From 8d9d55356c06bbea2400c045b2f3ebc0ade8121b Mon Sep 17 00:00:00 2001 From: Antoine Date: Mon, 9 Feb 2026 02:48:35 +0000 Subject: [PATCH] docs: Archive stale docs and create Atomizer-HQ agent documentation Archive Management: - Moved RALPH_LOOP, CANVAS, and dashboard implementation plans to archive/review/ for CEO review - Moved completed restructuring plan and protocol v1 to archive/historical/ - Moved old session summaries to archive/review/ New HQ Documentation (docs/hq/): - README.md: Overview of Atomizer-HQ multi-agent optimization team - PROJECT_STRUCTURE.md: Standard KB-integrated project layout with Hydrotech reference - KB_CONVENTIONS.md: Knowledge Base accumulation principles with generation tracking - AGENT_WORKFLOWS.md: Project lifecycle phases and agent handoffs (OP_09 integration) - STUDY_CONVENTIONS.md: Technical study execution standards and atomizer_spec.json format Index Update: - Reorganized docs/00_INDEX.md with HQ docs prominent - Updated structure to reflect new agent-focused organization - Maintained core documentation access for engineers No files deleted, only moved to appropriate archive locations. --- docs/00_INDEX.md | 225 ++- .../PROTOCOL_V1_MONOLITHIC.md | 0 .../historical}/RESTRUCTURING_PLAN.md | 0 .../ATOMIZER_DASHBOARD_V2_MASTER_PLAN.md | 0 ...TUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN.md | 0 ...INTERVIEW_MODE_IMPLEMENTATION_PLAN_TODO.md | 0 .../review}/CANVAS_DEEP_FIX_INVESTIGATION.md | 0 .../review}/CANVAS_ROBUSTNESS_PLAN.md | 0 .../review}/CANVAS_UX_IMPROVEMENTS.md | 0 .../{plans => review}/CANVAS_V3_PLAN.md | 0 .../review}/CLAUDE_CANVAS_INTEGRATION_V2.md | 0 .../review}/CLAUDE_CANVAS_PROJECT.md | 0 .../review}/DASHBOARD_CHAT_ARCHITECTURE.md | 0 .../review}/DASHBOARD_CHAT_TASKS.md | 0 .../DASHBOARD_CLAUDE_CODE_INTEGRATION.md | 0 .../review}/DASHBOARD_IMPROVEMENT_PLAN.md | 0 ...SHBOARD_INTAKE_ATOMIZERSPEC_INTEGRATION.md | 0 .../review}/DASHBOARD_SESSION_SUMMARY.md | 0 .../DYNAMIC_RESPONSE_IMPLEMENTATION_PLAN.md | 0 .../OPTIMIZATION_ENGINE_MIGRATION_PLAN.md | 0 .../review}/RALPH_LOOP_CANVAS_FIX.md | 0 .../review}/RALPH_LOOP_CANVAS_STUDY_SYNC.md | 0 .../{plans => review}/RALPH_LOOP_CANVAS_V2.md | 0 .../{plans => review}/RALPH_LOOP_CANVAS_V3.md | 0 .../review}/RALPH_LOOP_CANVAS_V4.md | 0 .../review}/RALPH_LOOP_MASTER_PROMPT.md | 0 .../review}/UNIFIED_CONFIG_EXECUTION_PLAN.md | 0 .../review}/UNIFIED_CONFIG_RALPH_PROMPT.md | 0 docs/hq/AGENT_WORKFLOWS.md | 450 +++++ docs/hq/KB_CONVENTIONS.md | 476 +++++ docs/hq/PROJECT_STRUCTURE.md | 377 ++++ docs/hq/README.md | 117 ++ docs/hq/STUDY_CONVENTIONS.md | 549 ++++++ tools/generate_optical_report.py.backup | 1526 +++++++++++++++++ 34 files changed, 3651 insertions(+), 69 deletions(-) rename docs/archive/{ => historical}/PROTOCOL_V1_MONOLITHIC.md (100%) rename docs/{plans => archive/historical}/RESTRUCTURING_PLAN.md (100%) rename docs/{plans => archive/review}/ATOMIZER_DASHBOARD_V2_MASTER_PLAN.md (100%) rename docs/{plans => archive/review}/ATOMIZER_STUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN.md (100%) rename docs/{plans => archive/review}/ATOMIZER_STUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN_TODO.md (100%) rename docs/{plans => archive/review}/CANVAS_DEEP_FIX_INVESTIGATION.md (100%) rename docs/{plans => archive/review}/CANVAS_ROBUSTNESS_PLAN.md (100%) rename docs/{plans => archive/review}/CANVAS_UX_IMPROVEMENTS.md (100%) rename docs/archive/{plans => review}/CANVAS_V3_PLAN.md (100%) rename docs/{plans => archive/review}/CLAUDE_CANVAS_INTEGRATION_V2.md (100%) rename docs/{plans => archive/review}/CLAUDE_CANVAS_PROJECT.md (100%) rename docs/{plans => archive/review}/DASHBOARD_CHAT_ARCHITECTURE.md (100%) rename docs/{plans => archive/review}/DASHBOARD_CHAT_TASKS.md (100%) rename docs/{plans => archive/review}/DASHBOARD_CLAUDE_CODE_INTEGRATION.md (100%) rename docs/{plans => archive/review}/DASHBOARD_IMPROVEMENT_PLAN.md (100%) rename docs/{plans => archive/review}/DASHBOARD_INTAKE_ATOMIZERSPEC_INTEGRATION.md (100%) rename docs/{guides => archive/review}/DASHBOARD_SESSION_SUMMARY.md (100%) rename docs/{plans => archive/review}/DYNAMIC_RESPONSE_IMPLEMENTATION_PLAN.md (100%) rename docs/{plans => archive/review}/OPTIMIZATION_ENGINE_MIGRATION_PLAN.md (100%) rename docs/{plans => archive/review}/RALPH_LOOP_CANVAS_FIX.md (100%) rename docs/{plans => archive/review}/RALPH_LOOP_CANVAS_STUDY_SYNC.md (100%) rename docs/archive/{plans => review}/RALPH_LOOP_CANVAS_V2.md (100%) rename docs/archive/{plans => review}/RALPH_LOOP_CANVAS_V3.md (100%) rename docs/{plans => archive/review}/RALPH_LOOP_CANVAS_V4.md (100%) rename docs/{plans => archive/review}/RALPH_LOOP_MASTER_PROMPT.md (100%) rename docs/{plans => archive/review}/UNIFIED_CONFIG_EXECUTION_PLAN.md (100%) rename docs/{plans => archive/review}/UNIFIED_CONFIG_RALPH_PROMPT.md (100%) create mode 100644 docs/hq/AGENT_WORKFLOWS.md create mode 100644 docs/hq/KB_CONVENTIONS.md create mode 100644 docs/hq/PROJECT_STRUCTURE.md create mode 100644 docs/hq/README.md create mode 100644 docs/hq/STUDY_CONVENTIONS.md create mode 100644 tools/generate_optical_report.py.backup diff --git a/docs/00_INDEX.md b/docs/00_INDEX.md index 6b7928f3..9dd2c7af 100644 --- a/docs/00_INDEX.md +++ b/docs/00_INDEX.md @@ -1,34 +1,77 @@ # Atomizer Documentation Index -**Last Updated**: 2026-01-24 -**Project Version**: 0.5.0 (AtomizerSpec v2.0 - Canvas Builder) +**Last Updated**: February 9, 2026 +**Project Version**: 0.5.0 (AtomizerSpec v2.0 + Atomizer-HQ Multi-Agent Team) --- ## Quick Start -New to Atomizer? Start here: +### For AI Agents (Atomizer-HQ Team) +**Start here** if you're an AI agent working on client projects: -1. **[README.md](../README.md)** - Project overview and philosophy -2. **[Getting Started](GETTING_STARTED.md)** - Installation, first study, dashboard -3. **[Protocol System](protocols/README.md)** - How Atomizer is organized -4. **[Example Studies](../studies/)** - Working examples +1. **[HQ Overview](hq/README.md)** — What Atomizer-HQ is and how agents work together +2. **[Project Structure](hq/PROJECT_STRUCTURE.md)** — Standard project organization +3. **[Agent Workflows](hq/AGENT_WORKFLOWS.md)** — Who does what in the project lifecycle +4. **[Knowledge Base Conventions](hq/KB_CONVENTIONS.md)** — How to accumulate and share knowledge + +### For Engineers (Core Optimization) +**Start here** if you're using Atomizer for FEA optimization: + +1. **[README.md](../README.md)** - Project overview and philosophy +2. **[Getting Started](GETTING_STARTED.md)** - Installation, first study, dashboard +3. **[Protocol System](protocols/README.md)** - How Atomizer is organized +4. **[Example Studies](../studies/)** - Working examples --- -## Documentation Structure +## Atomizer-HQ Agent Documentation -### Core Documentation +The multi-agent optimization team that runs client FEA projects. + +### Essential HQ Docs + +| Document | Purpose | Target Agents | +|----------|---------|---------------| +| **[HQ Overview](hq/README.md)** | What Atomizer-HQ is, how to use these docs | All agents | +| **[Project Structure](hq/PROJECT_STRUCTURE.md)** | Standard KB-integrated project layout | Manager, Technical Lead | +| **[KB Conventions](hq/KB_CONVENTIONS.md)** | Knowledge Base accumulation principles | All agents | +| **[Agent Workflows](hq/AGENT_WORKFLOWS.md)** | Project lifecycle and agent handoffs | All agents | +| **[Study Conventions](hq/STUDY_CONVENTIONS.md)** | Technical study execution standards | Technical Lead, Optimizer | + +### Agent Roles Quick Reference + +| Agent | Role | Primary Phase | Key Responsibilities | +|-------|------|---------------|---------------------| +| 📋 **Secretary** | CEO interface | Intake | Client requirements, project initiation | +| 🏗️ **Manager** | Coordination | Breakdown | Project structure, team coordination | +| 🔧 **Technical Lead** | FEA expert | Introspection | Model setup, optimization planning | +| ⚡ **Optimizer** | Study execution | Study | FEA optimization execution | +| 📊 **Post-Processor** | Results analysis | Results | Performance analysis, insights | +| 📝 **Reporter** | Documentation | Deliverables | Client reports, final packages | + +### Living Examples +- **Reference Project**: [projects/hydrotech-beam/](../projects/hydrotech-beam/) — Complete project structure +- **Project Structure**: Demonstrates KB-integrated organization and study flow +- **Knowledge Accumulation**: Shows generation-tracked knowledge evolution + +--- + +## Core Documentation + +Essential reference for understanding Atomizer's optimization framework. + +### Foundation Documents | Document | Purpose | |----------|---------| | **[GETTING_STARTED.md](GETTING_STARTED.md)** | Setup, first study, dashboard basics | | **[ARCHITECTURE.md](ARCHITECTURE.md)** | System architecture, hooks, data flow | -| **[protocols/README.md](protocols/README.md)** | Protocol Operating System overview | +| **[QUICK_REF.md](../QUICK_REF.md)** | Active reference guide | ### Protocol System -The Protocol Operating System (POS) provides structured workflows: +The Protocol Operating System (POS) provides structured workflows for optimization: ``` protocols/ @@ -41,7 +84,8 @@ protocols/ │ ├── OP_05_EXPORT_TRAINING_DATA.md │ ├── OP_06_TROUBLESHOOT.md │ ├── OP_07_DISK_OPTIMIZATION.md -│ └── OP_08_GENERATE_REPORT.md +│ ├── OP_08_GENERATE_REPORT.md +│ └── OP_09_AGENT_COMMUNICATION.md ├── system/ # Technical specifications (SYS_10-18) │ ├── SYS_10_IMSO.md # Intelligent optimization │ ├── SYS_11_MULTI_OBJECTIVE.md @@ -59,22 +103,28 @@ protocols/ └── EXT_04_CREATE_SKILL.md ``` -### User Guides +--- -Located in `guides/`: +## User Guides -| Guide | Purpose | -|-------|---------| -| **[CANVAS.md](guides/CANVAS.md)** | Visual study builder (AtomizerSpec v2.0) | -| **[DASHBOARD.md](guides/DASHBOARD.md)** | Dashboard overview and features | -| **[NEURAL_FEATURES_COMPLETE.md](guides/NEURAL_FEATURES_COMPLETE.md)** | Neural acceleration guide | -| **[NEURAL_WORKFLOW_TUTORIAL.md](guides/NEURAL_WORKFLOW_TUTORIAL.md)** | Data → Training → Optimization | -| **[hybrid_mode.md](guides/hybrid_mode.md)** | Hybrid FEA/NN optimization | -| **[TRAINING_DATA_EXPORT_GUIDE.md](guides/TRAINING_DATA_EXPORT_GUIDE.md)** | Exporting data for neural training | +Practical guides for using Atomizer features (engineers + Claude Code era). -### API Reference +### Current User Guides -Located in `api/`: +| Guide | Purpose | Status | +|-------|---------|--------| +| **[CANVAS.md](guides/CANVAS.md)** | Visual study builder (AtomizerSpec v2.0) | Active | +| **[DASHBOARD.md](guides/DASHBOARD.md)** | Dashboard overview and features | Active | +| **[NEURAL_FEATURES_COMPLETE.md](guides/NEURAL_FEATURES_COMPLETE.md)** | Neural acceleration guide | Active | +| **[NEURAL_WORKFLOW_TUTORIAL.md](guides/NEURAL_WORKFLOW_TUTORIAL.md)** | Data → Training → Optimization | Active | +| **[hybrid_mode.md](guides/hybrid_mode.md)** | Hybrid FEA/NN optimization | Active | +| **[TRAINING_DATA_EXPORT_GUIDE.md](guides/TRAINING_DATA_EXPORT_GUIDE.md)** | Exporting data for neural training | Active | + +--- + +## API Reference + +Technical integration documentation for developers and advanced users. | Document | Purpose | |----------|---------| @@ -83,18 +133,43 @@ Located in `api/`: | **[GNN_ARCHITECTURE.md](api/GNN_ARCHITECTURE.md)** | Graph Neural Network details | | **[NXOPEN_RESOURCES.md](api/NXOPEN_RESOURCES.md)** | NX Open documentation resources | -### Physics Documentation +--- -Located in `physics/`: +## Domain Knowledge + +Physics and engineering domain documentation. + +### Physics Documentation | Document | Purpose | |----------|---------| | **[ZERNIKE_FUNDAMENTALS.md](physics/ZERNIKE_FUNDAMENTALS.md)** | Zernike polynomial basics | | **[ZERNIKE_OPD_METHOD.md](physics/ZERNIKE_OPD_METHOD.md)** | OPD method for mirror optimization | -### Development +--- -Located in `development/`: +## Workflows and Operations + +Operational workflows for common tasks. + +### Standard Workflows + +| Document | Purpose | +|----------|---------| +| **[CREATE.md](WORKFLOWS/CREATE.md)** | Study creation workflow | +| **[RUN.md](WORKFLOWS/RUN.md)** | Optimization execution workflow | +| **[ANALYZE.md](WORKFLOWS/ANALYZE.md)** | Results analysis workflow | +| **[DELIVER.md](WORKFLOWS/DELIVER.md)** | Deliverable creation workflow | +| **[VALIDATE.md](WORKFLOWS/VALIDATE.md)** | Validation and verification workflow | +| **[REPORT.md](WORKFLOWS/REPORT.md)** | Report generation workflow | + +--- + +## Development and Architecture + +Technical development documentation. + +### Development Guides | Document | Purpose | |----------|---------| @@ -102,9 +177,7 @@ Located in `development/`: | **[DEVELOPMENT_ROADMAP.md](development/DEVELOPMENT_ROADMAP.md)** | Future plans | | **[Philosophy.md](development/Philosophy.md)** | Design philosophy | -### Diagrams - -Located in `diagrams/`: +### Architecture Documentation | Document | Purpose | |----------|---------| @@ -113,35 +186,57 @@ Located in `diagrams/`: --- +## Archive + +Historical and review documents preserved for context and CEO review. + +### Archive Structure +- **[archive/review/](archive/review/)** — Documents flagged for CEO review + - RALPH_LOOP implementation plans + - Dashboard implementation iterations + - Superseded development plans + - Session summaries and old development notes +- **[archive/historical/](archive/historical/)** — Historical but valuable documents + - Original protocol v1 monolithic document + - Foundational design documents + - Completed restructuring plans + +### Key Historical Documents +- **[PROTOCOL_V1_MONOLITHIC.md](archive/historical/PROTOCOL_V1_MONOLITHIC.md)** — Original monolithic protocol (Nov 2025) +- Various implementation plans and session summaries in review directories + +--- + ## Documentation by Task -### Creating Studies +### For Agents: Project Execution +1. **[Agent Workflows](hq/AGENT_WORKFLOWS.md)** — Project lifecycle and handoffs +2. **[Project Structure](hq/PROJECT_STRUCTURE.md)** — How to organize projects +3. **[Study Conventions](hq/STUDY_CONVENTIONS.md)** — Technical execution standards +4. **[KB Conventions](hq/KB_CONVENTIONS.md)** — Knowledge accumulation -1. **[GETTING_STARTED.md](GETTING_STARTED.md)** - First study tutorial -2. **[OP_01_CREATE_STUDY.md](protocols/operations/OP_01_CREATE_STUDY.md)** - Detailed creation protocol -3. **[guides/CANVAS.md](guides/CANVAS.md)** - Visual study builder +### For Engineers: Creating Studies +1. **[GETTING_STARTED.md](GETTING_STARTED.md)** — First study tutorial +2. **[OP_01_CREATE_STUDY.md](protocols/operations/OP_01_CREATE_STUDY.md)** — Detailed creation protocol +3. **[guides/CANVAS.md](guides/CANVAS.md)** — Visual study builder -### Running Optimizations +### For Engineers: Running Optimizations +1. **[OP_02_RUN_OPTIMIZATION.md](protocols/operations/OP_02_RUN_OPTIMIZATION.md)** — Run protocol +2. **[SYS_10_IMSO.md](protocols/system/SYS_10_IMSO.md)** — Intelligent optimization +3. **[SYS_15_METHOD_SELECTOR.md](protocols/system/SYS_15_METHOD_SELECTOR.md)** — Method selection -1. **[OP_02_RUN_OPTIMIZATION.md](protocols/operations/OP_02_RUN_OPTIMIZATION.md)** - Run protocol -2. **[SYS_10_IMSO.md](protocols/system/SYS_10_IMSO.md)** - Intelligent optimization -3. **[SYS_15_METHOD_SELECTOR.md](protocols/system/SYS_15_METHOD_SELECTOR.md)** - Method selection +### For Engineers: Neural Acceleration +1. **[guides/NEURAL_FEATURES_COMPLETE.md](guides/NEURAL_FEATURES_COMPLETE.md)** — Overview +2. **[SYS_14_NEURAL_ACCELERATION.md](protocols/system/SYS_14_NEURAL_ACCELERATION.md)** — Technical spec +3. **[guides/NEURAL_WORKFLOW_TUTORIAL.md](guides/NEURAL_WORKFLOW_TUTORIAL.md)** — Step-by-step -### Neural Acceleration +### For Engineers: Analyzing Results +1. **[OP_04_ANALYZE_RESULTS.md](protocols/operations/OP_04_ANALYZE_RESULTS.md)** — Analysis protocol +2. **[SYS_17_STUDY_INSIGHTS.md](protocols/system/SYS_17_STUDY_INSIGHTS.md)** — Physics visualizations -1. **[guides/NEURAL_FEATURES_COMPLETE.md](guides/NEURAL_FEATURES_COMPLETE.md)** - Overview -2. **[SYS_14_NEURAL_ACCELERATION.md](protocols/system/SYS_14_NEURAL_ACCELERATION.md)** - Technical spec -3. **[guides/NEURAL_WORKFLOW_TUTORIAL.md](guides/NEURAL_WORKFLOW_TUTORIAL.md)** - Step-by-step - -### Analyzing Results - -1. **[OP_04_ANALYZE_RESULTS.md](protocols/operations/OP_04_ANALYZE_RESULTS.md)** - Analysis protocol -2. **[SYS_17_STUDY_INSIGHTS.md](protocols/system/SYS_17_STUDY_INSIGHTS.md)** - Physics visualizations - -### Troubleshooting - -1. **[OP_06_TROUBLESHOOT.md](protocols/operations/OP_06_TROUBLESHOOT.md)** - Troubleshooting guide -2. **[GETTING_STARTED.md#troubleshooting](GETTING_STARTED.md#troubleshooting)** - Common issues +### For Everyone: Troubleshooting +1. **[OP_06_TROUBLESHOOT.md](protocols/operations/OP_06_TROUBLESHOOT.md)** — Troubleshooting guide +2. **[GETTING_STARTED.md#troubleshooting](GETTING_STARTED.md#troubleshooting)** — Common issues --- @@ -156,6 +251,7 @@ Located in `diagrams/`: | **OP_03** | Monitor Progress | Real-time monitoring | | **OP_04** | Analyze Results | Results analysis | | **OP_06** | Troubleshoot | Debugging issues | +| **OP_09** | Agent Communication | HQ communication standards | | **SYS_10** | IMSO | Intelligent optimization | | **SYS_12** | Extractors | Physics extraction library | | **SYS_14** | Neural | Neural network acceleration | @@ -166,10 +262,10 @@ Located in `diagrams/`: # Activate environment conda activate atomizer -# Run optimization +# Run optimization (engineers) python run_optimization.py --start --trials 50 -# Resume interrupted run +# Resume interrupted run python run_optimization.py --start --resume # Start dashboard @@ -177,6 +273,9 @@ python launch_dashboard.py # Neural turbo mode python run_nn_optimization.py --turbo --nn-trials 5000 + +# KB status check (agents) +cad_kb.py status projects/[project]/kb ``` ### Key Extractors @@ -194,18 +293,6 @@ Full catalog: [SYS_12_EXTRACTOR_LIBRARY.md](protocols/system/SYS_12_EXTRACTOR_LI --- -## Archive - -Historical documents are preserved in `archive/`: - -- `archive/historical/` - Legacy documents, old protocols -- `archive/marketing/` - Briefings, presentations -- `archive/session_summaries/` - Past development sessions -- `archive/plans/` - Superseded plan documents (RALPH_LOOP V2/V3, CANVAS V3, etc.) -- `archive/PROTOCOL_V1_MONOLITHIC.md` - Original monolithic protocol (Nov 2025) - ---- - ## LLM Resources For Claude/AI integration: @@ -218,5 +305,5 @@ For Claude/AI integration: --- -**Last Updated**: 2026-01-24 -**Maintained By**: Antoine / Atomaste +**Last Updated**: February 9, 2026 +**Maintained By**: Atomizer-HQ Team (Manager, Technical Lead, Secretary) + Antoine \ No newline at end of file diff --git a/docs/archive/PROTOCOL_V1_MONOLITHIC.md b/docs/archive/historical/PROTOCOL_V1_MONOLITHIC.md similarity index 100% rename from docs/archive/PROTOCOL_V1_MONOLITHIC.md rename to docs/archive/historical/PROTOCOL_V1_MONOLITHIC.md diff --git a/docs/plans/RESTRUCTURING_PLAN.md b/docs/archive/historical/RESTRUCTURING_PLAN.md similarity index 100% rename from docs/plans/RESTRUCTURING_PLAN.md rename to docs/archive/historical/RESTRUCTURING_PLAN.md diff --git a/docs/plans/ATOMIZER_DASHBOARD_V2_MASTER_PLAN.md b/docs/archive/review/ATOMIZER_DASHBOARD_V2_MASTER_PLAN.md similarity index 100% rename from docs/plans/ATOMIZER_DASHBOARD_V2_MASTER_PLAN.md rename to docs/archive/review/ATOMIZER_DASHBOARD_V2_MASTER_PLAN.md diff --git a/docs/plans/ATOMIZER_STUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN.md b/docs/archive/review/ATOMIZER_STUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN.md similarity index 100% rename from docs/plans/ATOMIZER_STUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN.md rename to docs/archive/review/ATOMIZER_STUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN.md diff --git a/docs/plans/ATOMIZER_STUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN_TODO.md b/docs/archive/review/ATOMIZER_STUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN_TODO.md similarity index 100% rename from docs/plans/ATOMIZER_STUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN_TODO.md rename to docs/archive/review/ATOMIZER_STUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN_TODO.md diff --git a/docs/plans/CANVAS_DEEP_FIX_INVESTIGATION.md b/docs/archive/review/CANVAS_DEEP_FIX_INVESTIGATION.md similarity index 100% rename from docs/plans/CANVAS_DEEP_FIX_INVESTIGATION.md rename to docs/archive/review/CANVAS_DEEP_FIX_INVESTIGATION.md diff --git a/docs/plans/CANVAS_ROBUSTNESS_PLAN.md b/docs/archive/review/CANVAS_ROBUSTNESS_PLAN.md similarity index 100% rename from docs/plans/CANVAS_ROBUSTNESS_PLAN.md rename to docs/archive/review/CANVAS_ROBUSTNESS_PLAN.md diff --git a/docs/plans/CANVAS_UX_IMPROVEMENTS.md b/docs/archive/review/CANVAS_UX_IMPROVEMENTS.md similarity index 100% rename from docs/plans/CANVAS_UX_IMPROVEMENTS.md rename to docs/archive/review/CANVAS_UX_IMPROVEMENTS.md diff --git a/docs/archive/plans/CANVAS_V3_PLAN.md b/docs/archive/review/CANVAS_V3_PLAN.md similarity index 100% rename from docs/archive/plans/CANVAS_V3_PLAN.md rename to docs/archive/review/CANVAS_V3_PLAN.md diff --git a/docs/plans/CLAUDE_CANVAS_INTEGRATION_V2.md b/docs/archive/review/CLAUDE_CANVAS_INTEGRATION_V2.md similarity index 100% rename from docs/plans/CLAUDE_CANVAS_INTEGRATION_V2.md rename to docs/archive/review/CLAUDE_CANVAS_INTEGRATION_V2.md diff --git a/docs/plans/CLAUDE_CANVAS_PROJECT.md b/docs/archive/review/CLAUDE_CANVAS_PROJECT.md similarity index 100% rename from docs/plans/CLAUDE_CANVAS_PROJECT.md rename to docs/archive/review/CLAUDE_CANVAS_PROJECT.md diff --git a/docs/plans/DASHBOARD_CHAT_ARCHITECTURE.md b/docs/archive/review/DASHBOARD_CHAT_ARCHITECTURE.md similarity index 100% rename from docs/plans/DASHBOARD_CHAT_ARCHITECTURE.md rename to docs/archive/review/DASHBOARD_CHAT_ARCHITECTURE.md diff --git a/docs/plans/DASHBOARD_CHAT_TASKS.md b/docs/archive/review/DASHBOARD_CHAT_TASKS.md similarity index 100% rename from docs/plans/DASHBOARD_CHAT_TASKS.md rename to docs/archive/review/DASHBOARD_CHAT_TASKS.md diff --git a/docs/plans/DASHBOARD_CLAUDE_CODE_INTEGRATION.md b/docs/archive/review/DASHBOARD_CLAUDE_CODE_INTEGRATION.md similarity index 100% rename from docs/plans/DASHBOARD_CLAUDE_CODE_INTEGRATION.md rename to docs/archive/review/DASHBOARD_CLAUDE_CODE_INTEGRATION.md diff --git a/docs/plans/DASHBOARD_IMPROVEMENT_PLAN.md b/docs/archive/review/DASHBOARD_IMPROVEMENT_PLAN.md similarity index 100% rename from docs/plans/DASHBOARD_IMPROVEMENT_PLAN.md rename to docs/archive/review/DASHBOARD_IMPROVEMENT_PLAN.md diff --git a/docs/plans/DASHBOARD_INTAKE_ATOMIZERSPEC_INTEGRATION.md b/docs/archive/review/DASHBOARD_INTAKE_ATOMIZERSPEC_INTEGRATION.md similarity index 100% rename from docs/plans/DASHBOARD_INTAKE_ATOMIZERSPEC_INTEGRATION.md rename to docs/archive/review/DASHBOARD_INTAKE_ATOMIZERSPEC_INTEGRATION.md diff --git a/docs/guides/DASHBOARD_SESSION_SUMMARY.md b/docs/archive/review/DASHBOARD_SESSION_SUMMARY.md similarity index 100% rename from docs/guides/DASHBOARD_SESSION_SUMMARY.md rename to docs/archive/review/DASHBOARD_SESSION_SUMMARY.md diff --git a/docs/plans/DYNAMIC_RESPONSE_IMPLEMENTATION_PLAN.md b/docs/archive/review/DYNAMIC_RESPONSE_IMPLEMENTATION_PLAN.md similarity index 100% rename from docs/plans/DYNAMIC_RESPONSE_IMPLEMENTATION_PLAN.md rename to docs/archive/review/DYNAMIC_RESPONSE_IMPLEMENTATION_PLAN.md diff --git a/docs/plans/OPTIMIZATION_ENGINE_MIGRATION_PLAN.md b/docs/archive/review/OPTIMIZATION_ENGINE_MIGRATION_PLAN.md similarity index 100% rename from docs/plans/OPTIMIZATION_ENGINE_MIGRATION_PLAN.md rename to docs/archive/review/OPTIMIZATION_ENGINE_MIGRATION_PLAN.md diff --git a/docs/plans/RALPH_LOOP_CANVAS_FIX.md b/docs/archive/review/RALPH_LOOP_CANVAS_FIX.md similarity index 100% rename from docs/plans/RALPH_LOOP_CANVAS_FIX.md rename to docs/archive/review/RALPH_LOOP_CANVAS_FIX.md diff --git a/docs/plans/RALPH_LOOP_CANVAS_STUDY_SYNC.md b/docs/archive/review/RALPH_LOOP_CANVAS_STUDY_SYNC.md similarity index 100% rename from docs/plans/RALPH_LOOP_CANVAS_STUDY_SYNC.md rename to docs/archive/review/RALPH_LOOP_CANVAS_STUDY_SYNC.md diff --git a/docs/archive/plans/RALPH_LOOP_CANVAS_V2.md b/docs/archive/review/RALPH_LOOP_CANVAS_V2.md similarity index 100% rename from docs/archive/plans/RALPH_LOOP_CANVAS_V2.md rename to docs/archive/review/RALPH_LOOP_CANVAS_V2.md diff --git a/docs/archive/plans/RALPH_LOOP_CANVAS_V3.md b/docs/archive/review/RALPH_LOOP_CANVAS_V3.md similarity index 100% rename from docs/archive/plans/RALPH_LOOP_CANVAS_V3.md rename to docs/archive/review/RALPH_LOOP_CANVAS_V3.md diff --git a/docs/plans/RALPH_LOOP_CANVAS_V4.md b/docs/archive/review/RALPH_LOOP_CANVAS_V4.md similarity index 100% rename from docs/plans/RALPH_LOOP_CANVAS_V4.md rename to docs/archive/review/RALPH_LOOP_CANVAS_V4.md diff --git a/docs/plans/RALPH_LOOP_MASTER_PROMPT.md b/docs/archive/review/RALPH_LOOP_MASTER_PROMPT.md similarity index 100% rename from docs/plans/RALPH_LOOP_MASTER_PROMPT.md rename to docs/archive/review/RALPH_LOOP_MASTER_PROMPT.md diff --git a/docs/plans/UNIFIED_CONFIG_EXECUTION_PLAN.md b/docs/archive/review/UNIFIED_CONFIG_EXECUTION_PLAN.md similarity index 100% rename from docs/plans/UNIFIED_CONFIG_EXECUTION_PLAN.md rename to docs/archive/review/UNIFIED_CONFIG_EXECUTION_PLAN.md diff --git a/docs/plans/UNIFIED_CONFIG_RALPH_PROMPT.md b/docs/archive/review/UNIFIED_CONFIG_RALPH_PROMPT.md similarity index 100% rename from docs/plans/UNIFIED_CONFIG_RALPH_PROMPT.md rename to docs/archive/review/UNIFIED_CONFIG_RALPH_PROMPT.md diff --git a/docs/hq/AGENT_WORKFLOWS.md b/docs/hq/AGENT_WORKFLOWS.md new file mode 100644 index 00000000..e30d318e --- /dev/null +++ b/docs/hq/AGENT_WORKFLOWS.md @@ -0,0 +1,450 @@ +# Agent Workflows + +**Version**: 1.0 +**Created**: February 2026 +**Reference**: OP_09 Communication Protocols + +--- + +## Project Lifecycle Overview + +Every Atomizer-HQ project follows a structured workflow with clear phases and agent handoffs. Understanding who does what, when, and how ensures smooth project execution and quality deliverables. + +### Six-Phase Project Lifecycle + +``` +Intake → Breakdown → Introspection → Study → Results → Deliverables + ↓ ↓ ↓ ↓ ↓ ↓ +Secretary Manager Technical Lead Optimizer Post-Processor Reporter +``` + +--- + +## Phase 1: Intake (Secretary) + +**Responsibility**: Client interface, requirement capture, project initiation +**Duration**: 1-2 days +**Deliverable**: Project intake document + +### Secretary Tasks +1. **Client Communication** + - Receive and clarify project requirements + - Identify scope, timeline, budget constraints + - Gather technical specifications and constraints + - Establish client communication preferences + +2. **Initial Assessment** + - Assess project complexity and feasibility + - Estimate required resources and timeline + - Identify potential technical challenges + - Flag any special requirements or risks + +3. **Project Initiation** + - Create initial project folder structure + - Document client requirements in structured format + - Create `project_metadata.json` with basic info + - Schedule handoff meeting with Manager + +### Secretary Deliverables +- **Client Requirements Document** — Structured requirements capture +- **Project Metadata** — `project_metadata.json` with client info +- **Initial Risk Assessment** — Potential challenges identified +- **Resource Estimate** — Preliminary timeline and effort estimate + +### Handoff to Manager +**Communication**: Direct message with project summary +**Artifacts**: Requirements document, metadata file, risk assessment +**Meeting**: Handoff discussion to clarify any ambiguities + +--- + +## Phase 2: Breakdown (Manager) + +**Responsibility**: Project structuring, team coordination, workflow planning +**Duration**: 1-2 days +**Deliverable**: Complete project structure and execution plan + +### Manager Tasks +1. **Project Structure Setup** + - Complete directory structure per `PROJECT_STRUCTURE.md` + - Initialize Knowledge Base framework + - Set up study planning structure + - Establish project documentation standards + +2. **Team Coordination** + - Assign Technical Lead and other team members + - Define agent responsibilities and interfaces + - Establish communication channels and schedules + - Plan handoff points and review gates + +3. **Execution Planning** + - Break down project into specific technical tasks + - Estimate timeline for each phase + - Identify dependencies and critical path + - Plan quality gates and review checkpoints + +4. **Risk Management** + - Review and refine initial risk assessment + - Plan mitigation strategies + - Identify decision points and escalation paths + - Establish contingency plans + +### Manager Deliverables +- **Complete Project Structure** — Full directory hierarchy +- **Execution Plan** — Timeline, milestones, dependencies +- **Team Assignments** — Agent roles and responsibilities +- **Communication Plan** — Channels, schedules, reporting structure + +### Handoff to Technical Lead +**Communication**: Project kickoff meeting with full team +**Artifacts**: Complete project structure, execution plan, team assignments +**Review**: Executive summary of client requirements and constraints + +--- + +## Phase 3: Introspection (Technical Lead) + +**Responsibility**: Technical analysis, model setup, optimization planning +**Duration**: 2-5 days +**Deliverable**: Technical foundation and study plan + +### Technical Lead Tasks +1. **Technical Requirements Analysis** + - Review client requirements from engineering perspective + - Identify technical constraints and design criteria + - Establish performance metrics and success criteria + - Define technical scope and boundaries + +2. **Model Setup and Validation** + - Set up reference CAD and FEA models + - Validate baseline model performance + - Establish modeling conventions and assumptions + - Create model documentation and KB entries + +3. **Optimization Strategy Development** + - Define design variables and constraints + - Select optimization objectives and metrics + - Plan study sequence and progression + - Estimate computational requirements + +4. **Knowledge Base Initialization** + - Create initial component knowledge files + - Document material properties and constraints + - Establish FEA conventions and assumptions + - Initialize lessons learned framework + +### Technical Lead Deliverables +- **Technical Requirements** — Engineering interpretation of client needs +- **Reference Models** — Validated baseline CAD and FEA models +- **Study Plan** — Optimization strategy and study sequence +- **Initial KB** — Component, material, and FEA knowledge foundation + +### Handoff to Optimizer +**Communication**: Technical handoff meeting +**Artifacts**: Study plan, reference models, technical requirements +**Training**: Model setup, conventions, and optimization strategy + +--- + +## Phase 4: Study Execution (Optimizer) + +**Responsibility**: FEA optimization execution, results generation +**Duration**: 3-10 days (depends on complexity) +**Deliverable**: Optimization results and raw data + +### Optimizer Tasks +1. **Study Setup** + - Create study directories per `STUDY_CONVENTIONS.md` + - Copy reference models to study workspace + - Configure optimization parameters and settings + - Validate model functionality and convergence + +2. **Optimization Execution** + - Execute optimization studies per study plan + - Monitor progress and convergence + - Troubleshoot any model or solver issues + - Adjust parameters as needed for convergence + +3. **Results Collection** + - Extract optimization results and performance data + - Document any issues or unexpected behaviors + - Create result summaries and best trial identification + - Archive study data and intermediate results + +4. **Knowledge Contribution** + - Document optimization insights and findings + - Update component behavior knowledge + - Note any modeling issues or improvements + - Record algorithmic performance observations + +### Optimizer Deliverables +- **Study Results** — Complete optimization output data +- **Best Designs** — Optimized model files and parameters +- **Execution Log** — Study progression and issue documentation +- **KB Contributions** — Optimization insights and lessons learned + +### Handoff to Post-Processor +**Communication**: Results review meeting +**Artifacts**: Study results, best designs, execution documentation +**Context**: Any issues encountered, unexpected behaviors, recommendations + +--- + +## Phase 5: Results Analysis (Post-Processor) + +**Responsibility**: Results analysis, validation, insight generation +**Duration**: 2-4 days +**Deliverable**: Analyzed results and engineering insights + +### Post-Processor Tasks +1. **Results Validation** + - Verify optimization results for engineering reasonableness + - Validate best designs against technical requirements + - Check constraint satisfaction and safety margins + - Perform sensitivity analysis on key parameters + +2. **Performance Analysis** + - Quantify performance improvements achieved + - Analyze trade-offs between competing objectives + - Identify design trends and behavioral patterns + - Compare results to baseline and requirements + +3. **Insight Generation** + - Extract engineering insights and design principles + - Identify key parameters and sensitivities + - Document unexpected findings and behaviors + - Generate recommendations for future work + +4. **Visualization and Documentation** + - Create plots, charts, and visual summaries + - Generate technical analysis documentation + - Prepare result summaries for stakeholder review + - Update Knowledge Base with analysis insights + +### Post-Processor Deliverables +- **Results Analysis** — Comprehensive technical analysis +- **Performance Summary** — Quantified improvements and metrics +- **Engineering Insights** — Design principles and recommendations +- **Visual Documentation** — Plots, charts, and graphical summaries + +### Handoff to Reporter +**Communication**: Analysis review meeting +**Artifacts**: Analysis results, performance summary, visual documentation +**Focus**: Key findings, recommendations, and client-relevant insights + +--- + +## Phase 6: Deliverables (Reporter) + +**Responsibility**: Client-facing documentation, final report generation +**Duration**: 2-3 days +**Deliverable**: Complete client deliverable package + +### Reporter Tasks +1. **Technical Report Generation** + - Synthesize all project work into cohesive technical report + - Translate engineering insights into client-relevant language + - Structure report for client technical and management audiences + - Include methodology, results, and recommendations + +2. **Deliverable Package Assembly** + - Organize optimized models and supporting data + - Create executive summary for management audience + - Prepare technical appendices and detailed data + - Package files for client delivery + +3. **Quality Review and Finalization** + - Review all deliverables for completeness and quality + - Ensure consistency across all documentation + - Validate technical accuracy and clarity + - Prepare final delivery package + +4. **Client Communication Support** + - Prepare presentation materials if requested + - Support client Q&A and follow-up discussions + - Document any post-delivery support requirements + - Plan potential follow-on work identification + +### Reporter Deliverables +- **Technical Report** — Comprehensive project documentation +- **Executive Summary** — Management-focused summary +- **Optimized Models** — Final design files and supporting data +- **Delivery Package** — Complete client deliverable set + +### Final Handoff to CEO +**Communication**: Project completion review +**Artifacts**: Complete deliverable package, project summary +**Review**: Quality gate before CEO approval and client delivery + +--- + +## Communication Protocols + +### Standard Communication Channels + +**Primary Coordination**: `#hq` channel +**Agent-to-Agent**: Direct messages via `sessions_send` +**Complex Tasks**: `sessions_spawn` for sub-agent delegation +**CEO Interface**: Secretary handles all CEO coordination + +### OP_09 Communication Standards + +All agent communications follow OP_09 protocols for clarity and traceability. + +**Message Format**: +``` +TO: [Agent Name] +FROM: [Agent Name] +RE: [Project Name] - [Phase] - [Specific Topic] +PRIORITY: [High/Medium/Low] + +CONTEXT: +[Brief context of the communication] + +REQUEST/INFORMATION: +[Specific request or information being communicated] + +DELIVERABLES: +[Expected deliverables and timeline] + +HANDOFF ARTIFACTS: +[Specific files, data, or documentation being transferred] +``` + +### Handoff Protocols + +**Every Phase Transition**: +1. **Handoff Meeting** — Direct agent-to-agent discussion +2. **Artifact Transfer** — All relevant files and documentation +3. **Context Summary** — Key points, issues, decisions made +4. **Success Criteria** — Clear definition of phase completion +5. **Next Phase Kickoff** — Introduction and orientation for receiving agent + +--- + +## Decision Logging + +### Project Decision Log +Every project maintains a decision log tracking key decisions, rationale, and implications. + +**Decision Entry Format**: +```markdown +## Decision [ID]: [Title] ([Date]) +**Phase**: [Project Phase] +**Decision Maker**: [Agent Name] +**Participants**: [Other agents involved] + +### Context +[Situation requiring decision] + +### Options Considered +[Alternative approaches evaluated] + +### Decision +[What was decided] + +### Rationale +[Why this decision was made] + +### Implications +[Impact on project timeline, scope, approach] + +### Approval +[Who approved this decision] +``` + +### Decision Categories +- **Technical Approach** — Modeling, analysis methods +- **Scope Changes** — Requirement modifications +- **Resource Allocation** — Timeline, effort adjustments +- **Quality Standards** — Acceptance criteria, review gates +- **Client Interface** — Communication, expectation management + +--- + +## Quality Gates and Reviews + +### Phase Review Gates +Each phase includes a quality gate before handoff to the next agent. + +**Standard Review Criteria**: +1. **Deliverable Completeness** — All required outputs produced +2. **Quality Standards** — Meet technical and documentation standards +3. **Success Criteria** — Phase objectives achieved +4. **Knowledge Capture** — Insights documented in KB +5. **Handoff Readiness** — Clear artifacts and communication for next phase + +### CEO Approval Gates +Certain milestones require CEO (Antoine) approval before proceeding: + +**Required CEO Approvals**: +- Project scope changes exceeding 20% effort increase +- Technical approach changes affecting timeline or deliverables +- Client communication regarding scope, timeline, or budget +- Final deliverable package before client delivery +- Project closure and lessons learned summary + +--- + +## Agent Coordination Patterns + +### Daily Standups (When Active) +**Format**: Brief status in `#hq` channel +**Frequency**: Daily during active project phases +**Content**: Yesterday's progress, today's plan, any blockers + +### Weekly Coordination +**Format**: Project status meeting +**Participants**: Active project agents + Manager +**Agenda**: Progress review, issue resolution, next week planning + +### Cross-Project Learning +**Format**: Lessons learned sharing +**Frequency**: Project completion + monthly review +**Purpose**: Share insights across projects, improve processes + +--- + +## Escalation Procedures + +### Technical Issues +1. **Agent-to-Agent** — Direct problem-solving collaboration +2. **Technical Lead** — Complex technical decisions +3. **Manager** — Resource or timeline impacts +4. **CEO** — Client impact or scope changes + +### Process Issues +1. **Manager** — Workflow or coordination problems +2. **Team Discussion** — Process improvement needs +3. **CEO** — Systematic issues requiring policy changes + +### Client Issues +1. **Secretary** — All client communication coordination +2. **Manager** — Scope or expectation management +3. **CEO** — Contract or relationship issues + +--- + +## Continuous Improvement + +### Process Refinement +- Document lessons learned in project KB +- Identify workflow bottlenecks and inefficiencies +- Propose process improvements based on experience +- Update workflows based on successful patterns + +### Knowledge Sharing +- Cross-pollinate insights between projects +- Share successful techniques and approaches +- Document common problems and solutions +- Build institutional memory through KB accumulation + +### Team Development +- Identify skill development opportunities +- Share expertise across agents +- Improve collaboration effectiveness +- Enhance communication protocols + +--- + +Last updated: February 2026 \ No newline at end of file diff --git a/docs/hq/KB_CONVENTIONS.md b/docs/hq/KB_CONVENTIONS.md new file mode 100644 index 00000000..63d51f04 --- /dev/null +++ b/docs/hq/KB_CONVENTIONS.md @@ -0,0 +1,476 @@ +# Knowledge Base Conventions + +**Version**: 1.0 +**Created**: February 2026 +**Scope**: Atomizer-HQ Knowledge Base Usage + +--- + +## Core Principle: Accumulation, Never Replacement + +The Knowledge Base (KB) is the memory of Atomizer-HQ. Every insight, result, and lesson learned gets added to the KB. **Never replace or delete existing knowledge** — only append and refine. + +### Why Accumulation Matters +- **Prevents re-work** — Don't rediscover the same constraints +- **Tracks evolution** — See how understanding developed over time +- **Maintains context** — Know why decisions were made +- **Enables learning** — Pattern recognition across projects + +--- + +## Knowledge Base Structure + +### Two-Level KB System + +**1. Global KB** (`knowledge_base/`) +- Cross-project insights +- General FEA principles +- Reusable component knowledge +- Shared lessons learned + +**2. Project-Specific KB** (`projects/[project]/kb/`) +- Project-specific findings +- Component behavior in this application +- Client-specific constraints +- Study-specific insights + +### KB Directory Structure +``` +kb/ +├── README.md # Navigation and conventions +├── components/ # Component-specific knowledge +│ ├── [component-name].md # Accumulated component insights +│ └── manufacturing-constraints.md +├── materials/ # Material property knowledge +├── fea/ # FEA-specific knowledge +│ ├── models/ # Modeling conventions +│ ├── load-cases/ # Load case documentation +│ └── results/ # Results interpretation +├── dev/ # Development knowledge +│ ├── lessons-learned.md # Process insights +│ ├── optimization-insights.md # What works/doesn't work +│ └── process-improvements.md # Workflow refinements +└── [domain-specific]/ # Custom categories as needed +``` + +--- + +## Generation Tracking System + +Every KB entry must track **when** and **why** knowledge was added. This creates a timeline of understanding evolution. + +### Generation Format +```markdown +## Generation N: [Descriptive Title] ([Date]) +**Context**: [What study/analysis led to this] +**Agent**: [Who contributed this knowledge] +**Confidence**: [High/Medium/Low] + +[Knowledge content...] + +### Key Insights +- [Insight 1] +- [Insight 2] + +### Implications +- [How this affects future work] +- [What should be investigated next] +``` + +### Example: Component Knowledge Evolution +```markdown +# hydraulic-cylinder-mount.md + +## Generation 1: Initial CAD Analysis (2026-02-01) +**Context**: Baseline model review +**Agent**: Technical Lead +**Confidence**: High + +### Component Overview +- Function: Mount hydraulic cylinder to main frame +- Critical loads: 15kN axial, 5kN lateral +- Material: Steel A36 (client requirement) +- Manufacturing: Welded fabrication + +### Key Features +- 4 bolt mounting pattern +- Integrated gusset plates for lateral stability +- Access clearance for maintenance + +## Generation 2: First FEA Results (2026-02-03) +**Context**: Baseline validation study +**Agent**: Optimizer +**Confidence**: High + +### Stress Analysis Results +- Maximum stress: 185 MPa at bolt interface +- Critical location: Upper bolt hole edge +- Safety factor: 1.45 (acceptable but tight) + +### Key Insights +- Bolt pattern creates stress concentration +- Current design marginal for peak loads +- Fillet radius at gusset transition critical + +### Implications +- Consider larger fillet radii in optimization +- Investigate bolt pattern alternatives +- Monitor fatigue potential at stress concentration + +## Generation 3: Optimization Insights (2026-02-05) +**Context**: Stress minimization study results +**Agent**: Post-Processor +**Confidence**: Medium + +### Optimization Findings +- Fillet radius optimization: 5mm → 8mm reduced stress 18% +- Gusset thickness optimization: 12mm → 15mm reduced stress 12% +- Combined effect: 28% stress reduction (185 → 133 MPa) + +### Unexpected Behaviors +- Material redistribution created new stress concentration at base +- Larger fillets improved stress but increased mass significantly +- Sweet spot: 7mm fillet radius for stress-mass balance + +### Key Insights +- Component responds well to local geometry changes +- Global stiffness less important than local stress concentrators +- Mass penalty acceptable for stress improvement + +### Implications +- 7mm fillet radius recommended for similar mounts +- Always check for new stress concentrations after optimization +- Consider this component pattern for future hydraulic mounts +``` + +--- + +## Component File Format + +Each component gets its own KB file with standardized sections. + +### Standard Component Template +```markdown +# [component-name].md + +## Component Overview +**Function**: [Primary purpose] +**Critical Loads**: [Key loading conditions] +**Material**: [Current material choice] +**Manufacturing**: [Fabrication method] + +## Behavioral Characteristics +[How this component behaves under various conditions] + +## Design Sensitivities +[What design parameters most affect performance] + +## Optimization Insights +[What works well, what doesn't, from studies] + +## Constraints and Limitations +[Manufacturing, geometric, material constraints] + +## Lessons Learned +[Key insights that affect future designs] + +## Related Components +[Links to other components that interact with this one] + +--- +[Then generations as above...] +``` + +--- + +## FEA KB Structure + +FEA knowledge is organized by simulation aspect, not by study. + +### FEA Knowledge Categories + +**Models** (`fea/models/`): +- Meshing conventions and best practices +- Boundary condition approaches +- Material model selection +- Modeling assumptions and simplifications + +**Load Cases** (`fea/load-cases/`): +- Operating condition definitions +- Load magnitudes and distributions +- Safety factors and design criteria +- Dynamic vs. static considerations + +**Results** (`fea/results/`): +- Stress criteria and failure modes +- Results interpretation guidelines +- Post-processing best practices +- Validation methods + +### Example: FEA Models Knowledge +```markdown +# meshing-conventions.md + +## Generation 1: Initial Meshing Approach (2026-02-01) +**Context**: Project setup +**Agent**: Technical Lead +**Confidence**: High + +### Standard Mesh Settings +- Element type: Quadratic tetrahedral (10-node) +- Element size: 5mm global, 2mm at stress concentrations +- Mesh quality: Aspect ratio < 3, Jacobian > 0.6 + +### Refinement Criteria +- Refine at fillets, holes, geometric transitions +- Use mesh convergence study for critical components +- Target: <5% stress change with 50% size reduction + +## Generation 2: Mesh Sensitivity Findings (2026-02-03) +**Context**: Baseline validation convergence study +**Agent**: Technical Lead +**Confidence**: High + +### Key Findings +- Current mesh adequate for global stress (2% error vs. fine mesh) +- Local stress concentrations require 1mm elements for convergence +- Contact regions need special attention (0.5mm elements) + +### Updated Guidelines +- Global: 5mm remains adequate +- Stress concentrations: 1mm elements +- Contact zones: 0.5mm elements +- Always run convergence check on critical locations + +### Implications +- Computational cost manageable with selective refinement +- Focus refinement efforts on actual critical locations +- Standard mesh appropriate for optimization studies +``` + +--- + +## Material Knowledge Format + +Material knowledge tracks property validation and selection criteria. + +### Material Template +```markdown +# [material-type]-properties.md + +## Material Overview +**Designation**: [Standard designation] +**Grade**: [Specific grade if applicable] +**Condition**: [Heat treatment, condition] + +## Validated Properties +[Properties confirmed through testing or analysis] + +## Design Allowables +[Properties used for design criteria] + +## Application History +[Where and how this material has been used successfully] + +## Limitations and Considerations +[When this material should/shouldn't be used] + +--- +[Then generations with specific validation results] +``` + +--- + +## Agent Contribution Guidelines + +### All Agents: Basic KB Responsibilities +1. **Read existing KB** before starting work (avoid duplicate effort) +2. **Add findings** immediately after analysis (don't wait) +3. **Use generation format** for all contributions +4. **Link to source studies** when relevant + +### Specific Agent Roles + +**Technical Lead**: +- Component characterization +- FEA modeling conventions +- Material property validation +- Engineering judgment and trade-offs + +**Optimizer**: +- Optimization results and insights +- Parameter sensitivity findings +- Algorithm performance notes +- Convergence characteristics + +**Post-Processor**: +- Results interpretation +- Visualization insights +- Analysis methodology +- Validation approaches + +**Manager**: +- Process lessons learned +- Project management insights +- Resource allocation learnings +- Timeline and coordination notes + +--- + +## Mario's Shared KB Skill Integration + +### Relationship to Global System +The Atomizer KB system extends Mario's global Knowledge Base skill with domain-specific conventions. + +**Global KB Skill** (`/home/papa/clawd/skills/knowledge-base/SKILL.md`): +- Core KB processing algorithms +- CDR (Critical Design Review) generation +- Knowledge extraction and summarization +- Cross-project insight correlation + +**Atomizer Extension** (`/home/papa/atomizer/shared/skills/knowledge-base-atomizer-ext.md`): +- FEA-specific knowledge patterns +- Component behavior tracking +- Optimization insight accumulation +- Agent workflow integration + +### Extension File Format +```markdown +# knowledge-base-atomizer-ext.md + +## FEA Knowledge Patterns +[Specific patterns for FEA knowledge organization] + +## Component Tracking Extensions +[How to track component behavior across projects] + +## Optimization Insight Formats +[Standardized formats for optimization results] + +## Agent Integration Points +[How different agents contribute to KB] +``` + +### Using the Global KB CLI +```bash +# Check KB status for project +cad_kb.py status projects/hydrotech-beam/kb + +# Generate project context summary +cad_kb.py context projects/hydrotech-beam/kb --output summary.md + +# Create CDR content from accumulated knowledge +cad_kb.py cdr projects/hydrotech-beam/kb --milestone "Design Optimization Complete" +``` + +--- + +## Quality Standards + +### Knowledge Quality Criteria +1. **Specific and Actionable** — "Increase fillet radius to 7mm" not "Make fillets bigger" +2. **Context-Rich** — Explain why, not just what +3. **Traceable** — Link to source studies, analyses, decisions +4. **Timestamped** — Generation tracking for all entries +5. **Validated** — Distinguish between hypothesis and confirmed results + +### Common Quality Issues +❌ **Vague**: "Design performed well" +✅ **Specific**: "Stress reduced from 185 MPa to 133 MPa with 7mm fillet radius" + +❌ **No context**: "Use steel for this part" +✅ **Context**: "Steel A36 selected for cost; aluminum would reduce mass but exceed budget" + +❌ **Missing generation**: Old content with no timestamp +✅ **Generation tracked**: "Generation 3: Optimization Results (2026-02-05)" + +--- + +## KB Maintenance and Review + +### Regular Maintenance Tasks + +**Weekly** (Manager): +- Review new KB contributions for quality +- Identify missing knowledge gaps +- Ensure generation tracking compliance + +**Per Project** (Technical Lead): +- Consolidate project-specific insights +- Promote reusable knowledge to global KB +- Archive completed project KB + +**Per Study** (All agents): +- Document study-specific insights immediately +- Update relevant component/material knowledge +- Note any contradictions with existing knowledge + +### Knowledge Conflict Resolution +When new knowledge contradicts existing knowledge: + +1. **Don't delete** the conflicting knowledge +2. **Add new generation** with updated understanding +3. **Explain the difference** — why did understanding change? +4. **Flag for review** — may indicate systematic issue + +Example: +```markdown +## Generation 4: Revised Load Understanding (2026-02-10) +**Context**: Additional client requirements revealed higher loads +**Agent**: Technical Lead +**Confidence**: High + +**NOTE**: This generation revises Generation 2 load assumptions. + +### Updated Load Requirements +- Previous: 15kN axial (Generation 2) +- Revised: 22kN axial (new client requirement) +- Impact: Safety factor drops from 1.45 to 0.98 (inadequate) + +### Implications +- Current design no longer adequate +- Need significant reinforcement or redesign +- All stress calculations in Generation 2-3 need updating +``` + +--- + +## Examples and Templates + +### Component Knowledge Example +See `projects/hydrotech-beam/kb/components/beam-support-bracket.md` for full example + +### Material Knowledge Example +See `projects/hydrotech-beam/kb/materials/steel-a36-properties.md` for full example + +### FEA Knowledge Example +See `projects/hydrotech-beam/kb/fea/models/meshing-conventions.md` for full example + +--- + +## Best Practices Summary + +### Writing Effective KB Entries +1. **Write immediately** — Don't accumulate for later +2. **Be specific** — Quantitative when possible +3. **Include context** — Why was this learned? +4. **Link studies** — Reference source analysis +5. **Use generations** — Track knowledge evolution +6. **Update implications** — How does this affect future work? + +### Using Existing KB +1. **Read before starting** — Don't duplicate effort +2. **Search across projects** — Similar components may exist +3. **Follow patterns** — Use established insights +4. **Build on previous work** — Reference and extend +5. **Question contradictions** — Flag inconsistencies + +### Maintaining KB Quality +1. **Review contributions** — Ensure quality standards +2. **Consolidate related entries** — Avoid fragmentation +3. **Update implications** — Keep forward-looking guidance current +4. **Archive completed projects** — Promote reusable insights to global + +--- + +Last updated: February 2026 \ No newline at end of file diff --git a/docs/hq/PROJECT_STRUCTURE.md b/docs/hq/PROJECT_STRUCTURE.md new file mode 100644 index 00000000..38d410ac --- /dev/null +++ b/docs/hq/PROJECT_STRUCTURE.md @@ -0,0 +1,377 @@ +# Standard Project Structure + +**Version**: 1.0 +**Created**: February 2026 +**Reference Implementation**: `projects/hydrotech-beam/` + +--- + +## Overview + +All Atomizer-HQ projects follow a standardized Knowledge Base-integrated structure. This ensures consistent organization, efficient handoffs between agents, and proper accumulation of domain knowledge. + +**Key Principles**: +- **Single Source of Truth** — Each project has one authoritative structure +- **KB Integration** — Knowledge accumulates in structured format +- **Study-Project Separation** — Studies are execution units, projects are business units +- **Reference → Copy Flow** — Models flow from reference to study-specific copies + +--- + +## Full Project Directory Structure + +``` +projects/[project-name]/ +│ +├── README.md # Project overview, status, contacts +├── project_metadata.json # Structured project info +│ +├── deliverables/ # Client-facing outputs +│ ├── reports/ # Technical reports, presentations +│ ├── models/ # Final optimized models +│ └── data/ # Results datasets, exports +│ +├── images/ # Visual assets (organized by type) +│ ├── components/ # Part/assembly images +│ ├── studies/ # Study result visualizations +│ ├── analysis/ # Analysis plots, graphs +│ └── deliverables/ # Client presentation images +│ +├── kb/ # Knowledge Base (THE CORE) +│ ├── README.md # KB navigation and conventions +│ ├── components/ # Component-specific knowledge +│ │ ├── [component-name].md # Per-component accumulation +│ │ └── manufacturing-constraints.md +│ ├── materials/ # Material property knowledge +│ │ ├── steel-properties.md +│ │ └── material-selection-criteria.md +│ ├── fea/ # FEA-specific knowledge +│ │ ├── models/ # Model setup knowledge +│ │ │ ├── meshing-conventions.md +│ │ │ ├── boundary-conditions.md +│ │ │ └── modeling-assumptions.md +│ │ ├── load-cases/ # Load case documentation +│ │ │ ├── operational-loads.md +│ │ │ └── safety-factors.md +│ │ └── results/ # Results interpretation +│ │ ├── stress-criteria.md +│ │ └── failure-modes.md +│ ├── dev/ # Development knowledge +│ │ ├── lessons-learned.md # Project-specific lessons +│ │ ├── optimization-insights.md # What worked, what didn't +│ │ └── process-improvements.md # Workflow refinements +│ └── client/ # Client-specific knowledge (optional) +│ ├── requirements.md # Client requirements evolution +│ └── preferences.md # Client preferences and constraints +│ +├── models/ # Reference models (READ-ONLY for studies) +│ ├── reference/ # Original/baseline models +│ │ ├── [component].prt # CAD models +│ │ ├── [component].sim # NX simulation setups +│ │ └── [component].fem # FEM files +│ ├── variations/ # Design variations +│ └── optimized/ # Final optimized models +│ +└── studies/ # Links to actual studies directory + ├── 01_baseline_validation/ # → ../../../studies/project_01_baseline/ + ├── 02_stress_optimization/ # → ../../../studies/project_02_stress/ + └── README.md # Study execution log +``` + +--- + +## Directory Responsibilities + +### Core Directories + +| Directory | Owner | Purpose | Frequency | +|-----------|-------|---------|-----------| +| `README.md` | Manager | Project status, contacts | Updated weekly | +| `project_metadata.json` | Secretary | Structured project data | Updated on changes | +| `deliverables/` | Reporter | Client-facing outputs | End of phases | +| `kb/` | **Everyone** | Accumulated knowledge | **Continuous** | +| `models/reference/` | Technical Lead | Baseline models | Setup phase | +| `studies/` | Optimizer | Study execution links | Per study | + +### KB Subdirectories + +| KB Directory | Primary Owner | Content | +|--------------|---------------|---------| +| `components/` | Technical Lead | Component behavior, constraints | +| `materials/` | Technical Lead | Material properties, selection | +| `fea/models/` | Technical Lead | Modeling conventions, assumptions | +| `fea/load-cases/` | Technical Lead | Load cases, boundary conditions | +| `fea/results/` | Post-Processor | Results interpretation, criteria | +| `dev/` | All Agents | Process lessons, optimization insights | + +--- + +## File Naming Conventions + +### General Rules +- **Lowercase with hyphens**: `component-analysis.md`, not `Component_Analysis.md` +- **Descriptive names**: `steel-yield-strength.md`, not `steel.md` +- **No spaces**: Use hyphens, not spaces +- **Consistent extensions**: `.md` for documentation, `.json` for data + +### Specific Conventions + +**Components**: `[component-type]-[specific-name].md` +``` +beam-support-bracket.md +hydraulic-cylinder-mount.md +``` + +**Materials**: `[material-type]-[property].md` +``` +steel-properties.md +aluminum-6061-characteristics.md +``` + +**Studies**: `[number]_[descriptive-name]` +``` +01_baseline_validation +02_stress_minimization +03_mass_reduction_study +``` + +--- + +## Model Flow Conventions + +### Reference → Study Copy Pattern + +1. **Reference Models** (`models/reference/`) + - Original/baseline models + - **READ-ONLY** for studies + - Version controlled + - Maintained by Technical Lead + +2. **Study Copies** (`studies/[study-name]/model/`) + - **Copied from reference** at study creation + - Modified during optimization + - Study-specific versions + - Managed by Optimizer + +3. **Optimized Models** (`models/optimized/`) + - Best results from studies + - **Copied from study results** + - Final deliverable candidates + - Curated by Technical Lead + +### Model Versioning +``` +models/reference/bracket-v1.0.prt # Initial design +models/reference/bracket-v1.1.prt # Design revision +studies/stress-opt/model/bracket.prt # Study working copy +models/optimized/bracket-optimized-v2.0.prt # Final optimized +``` + +--- + +## Project Creation Workflow + +### 1. Secretary: Project Intake +```bash +# Create project directory +mkdir -p projects/[project-name]/{deliverables,images,kb,models,studies} + +# Create metadata +# (See project_metadata.json template) +``` + +### 2. Manager: Structure Setup +```bash +# Copy template structure +cp -r templates/project-template/* projects/[project-name]/ + +# Create README from template +# Update with project specifics +``` + +### 3. Technical Lead: KB Initialization +```bash +# Create component files +touch projects/[project-name]/kb/components/[component].md + +# Initialize FEA knowledge structure +mkdir -p projects/[project-name]/kb/fea/{models,load-cases,results} + +# Create reference models directory +mkdir -p projects/[project-name]/models/reference +``` + +--- + +## Study Integration + +### Study-Project Relationship +- **Projects** = Business/client organizing unit +- **Studies** = Technical execution unit +- Studies reference project KB and models +- Results flow back to project KB + +### Creating Project Studies +```bash +# Create study linked to project +mkdir studies/project_01_baseline +ln -s ../../../projects/[project]/studies studies/project_01_baseline/project_link + +# Copy reference models to study +cp projects/[project]/models/reference/* studies/project_01_baseline/model/ + +# Study inherits project KB context +``` + +### Results Flow Back +1. **Study completes** → Results in `studies/[study]/results/` +2. **Post-Processor analyzes** → Insights documented +3. **KB accumulation** → Knowledge flows to `projects/[project]/kb/` +4. **Model archival** → Best models to `projects/[project]/models/optimized/` + +--- + +## KB Accumulation Principles + +### The Golden Rule: Add, Never Replace +- **DO**: Append new insights, learnings, results +- **DO NOT**: Overwrite existing knowledge +- **Timestamp entries**: Generation tracking for all additions +- **Version knowledge**: Track what was learned when + +### Component Knowledge Evolution +```markdown +# beam-support-analysis.md + +## Generation 1: Initial Analysis (2026-02-01) +- Material: Steel A36 +- Critical stress location: Root of bracket +- Baseline performance: 180 MPa max stress + +## Generation 2: First Optimization (2026-02-05) +- Discovered: Fillet radius critical to stress concentration +- Optimized radius from 5mm → 8mm reduced stress by 15% +- New critical location: Mounting bolt interface + +## Generation 3: Load Case Refinement (2026-02-08) +- Added dynamic loading consideration +- Peak stress now 220 MPa under dynamic conditions +- Recommendation: Consider fatigue analysis +``` + +--- + +## Templates + +### project_metadata.json Template +```json +{ + "project_name": "project-name", + "client": "Client Name", + "project_manager": "agent-name", + "technical_lead": "agent-name", + "created": "2026-02-01", + "status": "active", + "phase": "introspection", + "description": "Brief project description", + "components": ["component1", "component2"], + "objectives": ["minimize stress", "reduce mass"], + "constraints": ["manufacturing feasibility"], + "studies": [ + { + "name": "01_baseline_validation", + "status": "completed", + "study_link": "../../../studies/project_01_baseline" + } + ], + "deliverables": { + "interim_report": "deliverables/reports/interim-report.pdf", + "final_report": "deliverables/reports/final-report.pdf", + "optimized_models": "models/optimized/" + } +} +``` + +### Project README Template +```markdown +# [Project Name] + +**Client**: [Client Name] +**Status**: [Active/Completed/On Hold] +**Phase**: [Intake/Breakdown/Introspection/Study/Results/Deliverables] +**Manager**: [Agent Name] +**Technical Lead**: [Agent Name] + +## Objective +[Brief description of what we're optimizing] + +## Components +- [Component 1] — [Brief description] +- [Component 2] — [Brief description] + +## Current Status +[What's happening now, next steps] + +## Studies +- [Study 1] — [Status] — [Brief outcome] +- [Study 2] — [Status] — [Brief outcome] + +## Key Findings +[Major insights, recommendations] + +## Deliverables +- [X] Baseline analysis +- [ ] Optimization study +- [ ] Final report +``` + +--- + +## Best Practices + +### Project Organization +1. **One project per client deliverable** +2. **Clear phase progression** (don't skip phases) +3. **Regular KB updates** (not just at end) +4. **Study naming consistency** (01_, 02_, etc.) + +### Knowledge Base Maintenance +1. **Write as you work** — Don't accumulate at the end +2. **Be specific** — "Fillet radius affects stress concentration" not "Design matters" +3. **Include context** — Why was this learned? What led to this insight? +4. **Link studies** — Reference which study generated the knowledge + +### Model Management +1. **Protect reference models** — No direct modification +2. **Study isolation** — Each study gets its own model copies +3. **Version final models** — Clear naming for optimized versions +4. **Archive intermediate** — Keep best intermediate results + +--- + +## Living Example: Hydrotech Beam Project + +**Reference**: `projects/hydrotech-beam/` + +This project demonstrates the full structure in practice: +- Complete KB with component, material, and FEA knowledge +- Multiple studies linked and executed +- Results flowing back to project KB +- Deliverables organized for client handoff + +**Key Learnings from Hydrotech**: +- KB accumulation prevented re-discovering constraints +- Study-project linking maintained context +- Reference model protection avoided corruption +- Generation tracking showed knowledge evolution + +--- + +## Questions and Updates + +- **Structure Questions**: Ask Manager or Technical Lead +- **KB Conventions**: See `KB_CONVENTIONS.md` +- **Study Execution**: See `STUDY_CONVENTIONS.md` +- **Process Issues**: Document in project `kb/dev/lessons-learned.md` + +Last updated: February 2026 \ No newline at end of file diff --git a/docs/hq/README.md b/docs/hq/README.md new file mode 100644 index 00000000..49ab40d1 --- /dev/null +++ b/docs/hq/README.md @@ -0,0 +1,117 @@ +# Atomizer-HQ Agent Documentation + +**Version**: 1.0 +**Created**: February 2026 +**Target Audience**: AI Agents (Manager, Secretary, Technical Lead, etc.) + +--- + +## What is Atomizer-HQ? + +Atomizer-HQ is a multi-agent optimization team that runs FEA optimization projects for clients. Built on top of the Atomizer optimization framework, it provides a structured workflow from client intake through project delivery. + +**The Team**: +- 📋 **Secretary** — CEO interface, admin, client intake +- 🏗️ **Manager** — Project coordination, workflow orchestration +- 🔧 **Technical Lead** — FEA expertise, R&D leadership +- ⚡ **Optimizer** — Study execution, optimization runs +- 🔍 **Auditor** — Quality assurance, deliverable review +- 📊 **Post-Processor** — Results analysis, visualization +- 📝 **Reporter** — Technical documentation, client reports + +--- + +## How to Use These Docs + +This documentation provides agent-specific guidance for: + +1. **Project Structure** — How projects are organized +2. **Knowledge Base Usage** — Accumulating and sharing domain knowledge +3. **Agent Workflows** — Who does what, when, and how +4. **Study Conventions** — Technical study execution standards + +### Essential Reading for All Agents + +| Document | Purpose | +|----------|---------| +| **[PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)** | Standard project layout and conventions | +| **[KB_CONVENTIONS.md](KB_CONVENTIONS.md)** | Knowledge base usage and accumulation | +| **[AGENT_WORKFLOWS.md](AGENT_WORKFLOWS.md)** | Project lifecycle and agent handoffs | + +### Role-Specific Guides + +| Document | Target Agents | +|----------|---------------| +| **[STUDY_CONVENTIONS.md](STUDY_CONVENTIONS.md)** | Technical Lead, Optimizer, Study Builder | + +--- + +## Quick Reference + +### Project Phases +1. **Intake** → Secretary handles client requirements +2. **Breakdown** → Manager coordinates project setup +3. **Introspection** → Technical Lead analyzes requirements +4. **Study** → Optimizer executes FEA optimization +5. **Results** → Post-Processor analyzes outcomes +6. **Deliverables** → Reporter generates client materials + +### Key Principles +- **KB Accumulation**: Add knowledge, never replace +- **Single Source of Truth**: Projects have one authoritative structure +- **Quality Gates**: No deliverable goes to CEO without review +- **Clear Handoffs**: Use OP_09 communication protocols + +### Living Examples +- **Reference Project**: `projects/hydrotech-beam/` — Complete project structure +- **Active Studies**: `studies/` — Study execution examples +- **Knowledge Base**: `knowledge_base/` — Accumulated domain expertise + +--- + +## Getting Started + +### New Agent Onboarding +1. Read your role in `context-docs/01-AGENT-ROSTER.md` +2. Review the project structure in `PROJECT_STRUCTURE.md` +3. Understand KB conventions in `KB_CONVENTIONS.md` +4. Check active projects in `projects/` for context + +### Starting a New Project +1. Secretary creates project intake +2. Manager sets up project structure (see `PROJECT_STRUCTURE.md`) +3. Technical Lead performs introspection +4. Follow workflows in `AGENT_WORKFLOWS.md` + +### Contributing to Documentation +- These docs evolve based on agent experience +- Update conventions when patterns emerge +- Flag inconsistencies or missing guidance +- CEO (Antoine) approves major changes + +--- + +## Integration with Core Atomizer + +Atomizer-HQ builds on the core optimization framework: + +**Core Framework** (engineers + Claude Code): +- `protocols/` — Operational and system protocols +- `api/` — NX integration and technical APIs +- `optimization_engine/` — Core FEA optimization algorithms + +**HQ Layer** (multi-agent team): +- `projects/` — Client project workspaces +- `knowledge_base/` — Accumulated domain expertise +- Agent-specific workflows and conventions + +--- + +## Support and Evolution + +- **Questions**: Ask in #hq channel or direct agent messages +- **Issues**: Flag problems in daily coordination +- **Updates**: Documentation evolves with team experience +- **Approval**: CEO (Antoine) reviews major changes + +Last updated: February 2026 \ No newline at end of file diff --git a/docs/hq/STUDY_CONVENTIONS.md b/docs/hq/STUDY_CONVENTIONS.md new file mode 100644 index 00000000..829b10ca --- /dev/null +++ b/docs/hq/STUDY_CONVENTIONS.md @@ -0,0 +1,549 @@ +# Study Conventions + +**Version**: 1.0 +**Created**: February 2026 +**Target Audience**: Technical Lead, Optimizer, Study Builder +**References**: `studies/README.md`, `templates/HOW_TO_CREATE_A_STUDY.md` + +--- + +## Overview + +Studies are the technical execution units of Atomizer-HQ. They represent specific FEA optimization runs that generate data, insights, and optimized designs. This document defines how studies are structured, executed, and integrated with the broader project workflow. + +### Study vs. Project Distinction +- **Project** = Business/client organizing unit (`projects/[name]/`) +- **Study** = Technical execution unit (`studies/[name]/`) +- **Relationship**: Studies contribute results back to project KB and deliverables + +--- + +## Study Directory Structure + +Every study follows a standardized structure for consistency and tool compatibility. + +### Standard Study Layout +``` +studies/[study-name]/ +│ +├── README.md # Study purpose, configuration, results +├── atomizer_spec.json # Study configuration (AtomizerSpec v2.0) +├── run_optimization.py # Study execution script +│ +├── model/ # Study-specific model files +│ ├── [component].prt # NX CAD model (copied from project reference) +│ ├── [component].sim # NX simulation setup +│ ├── [component].fem # FEM file +│ └── baseline_results/ # Initial validation results +│ +├── introspection/ # Pre-study analysis +│ ├── model_analysis.md # Model validation and setup notes +│ ├── parameter_sensitivity.md # Initial parameter studies +│ └── optimization_plan.md # Study-specific optimization strategy +│ +├── results/ # Generated by Atomizer (DO NOT COMMIT) +│ ├── optimization.log # High-level progress log +│ ├── trial_logs/ # Detailed per-trial logs +│ ├── history.json # Complete trial history +│ ├── history.csv # CSV format for analysis +│ ├── best_trial.json # Best design summary +│ ├── plots/ # Auto-generated visualizations +│ └── study_*.db # Optuna database files +│ +└── project_link # Link to parent project (optional) +``` + +--- + +## Study Naming Conventions + +Studies use a consistent naming pattern for organization and traceability. + +### Naming Pattern: `[project]_[number]_[descriptive_name]` + +**Examples**: +- `hydrotech_01_baseline_validation` +- `hydrotech_02_stress_optimization` +- `bracket_03_mass_reduction` +- `mount_04_fatigue_analysis` + +### Naming Rules +1. **Project prefix** — Links study to project context +2. **Sequential numbering** — `01`, `02`, `03`, etc. (always two digits) +3. **Descriptive name** — Clear purpose in underscore format +4. **No spaces** — Use underscores throughout +5. **Lowercase** — Consistent case convention + +--- + +## atomizer_spec.json Format + +Studies use AtomizerSpec v2.0 as the single source of truth for configuration. + +### Complete atomizer_spec.json Example +```json +{ + "study_name": "hydrotech_02_stress_optimization", + "description": "Minimize maximum stress in hydraulic cylinder mount", + "created": "2026-02-05T14:30:00Z", + "version": "2.0", + + "model": { + "sim_file": "model/cylinder_mount.sim", + "prt_file": "model/cylinder_mount.prt", + "fem_file": "model/cylinder_mount.fem", + "description": "Hydraulic cylinder mounting bracket with 4-bolt pattern" + }, + + "design_variables": { + "bracket_thickness": { + "type": "continuous", + "min": 8.0, + "max": 20.0, + "initial": 12.0, + "units": "mm", + "description": "Main bracket plate thickness" + }, + "fillet_radius": { + "type": "continuous", + "min": 3.0, + "max": 12.0, + "initial": 5.0, + "units": "mm", + "description": "Fillet radius at gusset-bracket intersection" + }, + "gusset_thickness": { + "type": "continuous", + "min": 6.0, + "max": 15.0, + "initial": 10.0, + "units": "mm", + "description": "Gusset plate thickness" + } + }, + + "extractors": [ + { + "name": "max_stress", + "function": "extract_stress", + "parameters": { + "result_type": "von_mises", + "metric": "max", + "units": "MPa" + }, + "description": "Maximum von Mises stress in structure" + }, + { + "name": "max_displacement", + "function": "extract_displacement", + "parameters": { + "metric": "max", + "units": "mm" + }, + "description": "Maximum displacement magnitude" + }, + { + "name": "total_mass", + "function": "extract_mass", + "parameters": { + "units": "kg" + }, + "description": "Total structural mass" + } + ], + + "objectives": [ + { + "name": "minimize_stress", + "extractor": "max_stress", + "direction": "minimize", + "weight": 1.0, + "target": 150.0, + "units": "MPa" + } + ], + + "constraints": [ + { + "name": "displacement_limit", + "extractor": "max_displacement", + "type": "upper_bound", + "limit": 2.0, + "units": "mm", + "description": "Maximum allowable displacement" + }, + { + "name": "mass_limit", + "extractor": "total_mass", + "type": "upper_bound", + "limit": 5.0, + "units": "kg", + "description": "Maximum allowable mass" + } + ], + + "optimization_settings": { + "n_trials": 50, + "sampler": "TPE", + "n_startup_trials": 10, + "timeout": 7200, + "pruning": { + "enabled": true, + "patience": 5 + } + }, + + "post_processing": { + "generate_plots": true, + "plot_formats": ["png", "pdf"], + "cleanup_models": false, + "keep_top_n_models": 10 + }, + + "project": { + "name": "hydrotech-beam", + "phase": "stress_optimization", + "kb_path": "../projects/hydrotech-beam/kb", + "deliverable_path": "../projects/hydrotech-beam/deliverables" + } +} +``` + +--- + +## Study Setup Process + +### 1. Technical Lead: Study Planning +Before creating the study, the Technical Lead defines the optimization strategy. + +**Planning Tasks**: +- Define study objectives and success criteria +- Select design variables and ranges +- Choose optimization strategy and settings +- Plan model setup and validation approach + +**Planning Documentation** (`introspection/optimization_plan.md`): +```markdown +# Study Optimization Plan + +## Objective +Minimize maximum stress while maintaining displacement and mass constraints + +## Design Variables +- bracket_thickness: Primary structural parameter (8-20mm) +- fillet_radius: Local stress concentrator (3-12mm) +- gusset_thickness: Secondary support (6-15mm) + +## Strategy +1. Initial exploration: 20 trials to map design space +2. Focused optimization: 30 additional trials on promising regions +3. Validation: Verify best designs with mesh convergence + +## Expected Outcomes +- Target: Reduce max stress from 185 MPa to <150 MPa +- Maintain: Displacement <2mm, mass <5kg +- Timeline: 2-3 days execution +``` + +### 2. Optimizer: Study Creation +The Optimizer creates the study structure and configuration. + +**Creation Steps**: +```bash +# Create study directory +mkdir -p studies/hydrotech_02_stress_optimization/{model,introspection,results} + +# Copy reference models from project +cp projects/hydrotech-beam/models/reference/* \ + studies/hydrotech_02_stress_optimization/model/ + +# Create atomizer_spec.json from template +# (Use existing study as template or create from scratch) + +# Create study README.md +cp templates/study_README_template.md \ + studies/hydrotech_02_stress_optimization/README.md +``` + +### 3. Optimizer: Model Validation +Validate the model setup before optimization begins. + +**Validation Checklist**: +- [ ] Model loads and runs successfully in NX +- [ ] Design variables update model geometry correctly +- [ ] Extractors return valid results +- [ ] Baseline results match expectations +- [ ] Convergence criteria are met + +**Validation Documentation** (`introspection/model_analysis.md`): +```markdown +# Model Validation Results + +## Baseline Analysis +- Max stress: 185.3 MPa at upper bolt interface +- Max displacement: 1.42 mm at bracket tip +- Total mass: 3.8 kg + +## Parameter Sensitivity +- Thickness: 10% increase → 8% stress reduction +- Fillet radius: 2mm increase → 12% stress reduction +- Gusset thickness: Minimal effect on global stress + +## Model Quality +- Mesh convergence: <5% change with 50% refinement +- Solver convergence: 6 iterations typical +- Extractor validation: Results consistent with NX postprocessor +``` + +--- + +## Study Execution + +### Optimization Execution Workflow + +**1. Pre-Execution Check**: +```bash +# Validate configuration +python optimization_engine/validate_spec.py studies/hydrotech_02_stress_optimization/atomizer_spec.json + +# Test model functionality +python optimization_engine/test_model.py studies/hydrotech_02_stress_optimization/ +``` + +**2. Execute Study**: +```bash +# Navigate to Atomizer root +cd /path/to/Atomizer + +# Run optimization +python run_study.py --study studies/hydrotech_02_stress_optimization +``` + +**3. Monitor Progress**: +```bash +# Follow optimization log +tail -f studies/hydrotech_02_stress_optimization/results/optimization.log + +# Check current status +python optimization_engine/check_status.py studies/hydrotech_02_stress_optimization +``` + +### Progress Monitoring + +**Optimization Log Format**: +``` +[14:35:22] Study START | Design variables: 3, Objectives: 1, Constraints: 2 +[14:35:22] Trial 0 START | bracket_thickness=12.0, fillet_radius=5.0, gusset_thickness=10.0 +[14:35:48] Trial 0 COMPLETE | max_stress=185.3, max_displacement=1.42, total_mass=3.8 +[14:35:51] Trial 1 START | bracket_thickness=15.2, fillet_radius=7.8, gusset_thickness=11.5 +[14:36:15] Trial 1 COMPLETE | max_stress=158.7, max_displacement=1.18, total_mass=4.2 +``` + +--- + +## Results Processing + +### Automatic Results Generation +The optimization engine automatically generates: + +**Core Results**: +- `history.json` — Complete trial data +- `history.csv` — Analysis-friendly format +- `best_trial.json` — Optimal design summary +- `optimization.log` — Human-readable progress + +**Visualizations** (if enabled): +- Parameter correlation plots +- Objective history plots +- Constraint violation plots +- Pareto front plots (multi-objective) + +### Manual Results Analysis +The Optimizer should create additional analysis as needed: + +**Custom Analysis** (`results/custom_analysis.md`): +```markdown +# Study Results Analysis + +## Best Design Summary +- Optimal parameters: bracket_thickness=16.5mm, fillet_radius=9.2mm, gusset_thickness=12.1mm +- Performance: max_stress=142.8 MPa (23% reduction from baseline) +- Constraints: displacement=1.58mm (OK), mass=4.3kg (OK) + +## Key Insights +- Fillet radius most influential parameter (40% of improvement) +- Diminishing returns above 17mm bracket thickness +- Gusset thickness has minimal effect within tested range + +## Validation Required +- Mesh convergence check on optimal design +- Fatigue analysis at reduced stress levels +- Manufacturing feasibility of 9.2mm fillet radius +``` + +--- + +## Results Integration with Projects + +### Knowledge Base Updates +Study results flow back to the project KB immediately after completion. + +**KB Update Process**: +1. **Component Knowledge** — Update component behavior insights +2. **FEA Knowledge** — Document modeling insights and lessons +3. **Optimization Knowledge** — Record algorithm performance and sensitivities +4. **Lessons Learned** — Process improvements and unexpected findings + +**Example KB Update** (`projects/hydrotech-beam/kb/components/cylinder-mount.md`): +```markdown +## Generation 3: Stress Optimization Study (2026-02-05) +**Context**: hydrotech_02_stress_optimization results +**Agent**: Optimizer +**Confidence**: High + +### Optimization Results +- Achieved 23% stress reduction (185.3 → 142.8 MPa) +- Optimal design: 16.5mm thickness, 9.2mm fillet, 12.1mm gusset +- All constraints satisfied with margin + +### Key Sensitivities +- Fillet radius: Most critical parameter (40% of improvement) +- Bracket thickness: Diminishing returns >17mm +- Gusset thickness: Minimal effect in tested range (6-15mm) + +### Design Insights +- Local geometry (fillet) more important than global (thickness) +- Current constraint limits not binding (could push further) +- Manufacturing implications: 9.2mm fillet requires machining + +### Implications +- Focus future optimization on fillet and local geometry +- Consider tighter mass constraints to drive efficiency +- Investigate manufacturing cost of optimal fillet radius +``` + +### Model Archival +Best study models are promoted to project optimized models. + +**Model Promotion Process**: +```bash +# Copy optimal model to project +cp studies/hydrotech_02_stress_optimization/results/best_trial/cylinder_mount_optimal.prt \ + projects/hydrotech-beam/models/optimized/cylinder_mount_stress_optimized_v1.0.prt + +# Update model registry +# (Document in project metadata and KB) +``` + +--- + +## Study Quality Standards + +### Technical Quality Criteria +1. **Model Validation** — Baseline results verified +2. **Convergence** — Optimization converged appropriately +3. **Constraint Satisfaction** — All constraints respected +4. **Result Validation** — Best designs verified for engineering reasonableness +5. **Documentation** — Complete introspection and results documentation + +### Process Quality Criteria +1. **Planning** — Clear optimization strategy documented +2. **Execution** — Followed standard execution workflow +3. **Monitoring** — Progress tracked and issues documented +4. **Integration** — Results properly integrated with project KB +5. **Handoff** — Clear communication to Post-Processor + +### Documentation Standards +Every study must include: + +**Required Documentation**: +- [ ] `README.md` with study purpose and summary +- [ ] `introspection/optimization_plan.md` with strategy +- [ ] `introspection/model_analysis.md` with validation +- [ ] `results/custom_analysis.md` with insights (if applicable) +- [ ] KB updates with generation-tracked knowledge + +--- + +## Common Study Patterns + +### 1. Baseline Validation Studies +**Purpose**: Validate model setup and establish baseline performance +**Trials**: 3-5 (minimal optimization, focus on validation) +**Documentation**: Extensive model validation, minimal optimization insights + +### 2. Exploration Studies +**Purpose**: Map design space and identify promising regions +**Trials**: 20-50 (broad parameter ranges) +**Documentation**: Parameter sensitivities, design space characteristics + +### 3. Optimization Studies +**Purpose**: Find optimal designs within known promising regions +**Trials**: 30-100 (focused parameter ranges) +**Documentation**: Convergence analysis, optimal design validation + +### 4. Validation Studies +**Purpose**: Verify optimal designs and perform additional analysis +**Trials**: 5-10 (focused around optimal points) +**Documentation**: Mesh convergence, robustness analysis, manufacturing assessment + +--- + +## Integration with Templates + +### Reference Documents +- **`studies/README.md`** — Complete study directory overview +- **`templates/HOW_TO_CREATE_A_STUDY.md`** — Detailed study creation guide +- **`templates/study_template/`** — Template directory structure + +### Template Usage +```bash +# Create study from template +cp -r templates/study_template studies/new_study_name + +# Customize for specific project +# - Update atomizer_spec.json +# - Copy reference models +# - Update README.md +# - Create optimization plan +``` + +--- + +## Troubleshooting Common Issues + +### Model Execution Problems +**Symptoms**: Trials fail with model errors +**Solutions**: +- Verify NX installation and licensing +- Check model file paths in atomizer_spec.json +- Validate design variable expressions exist in model +- Test model manually in NX with parameter changes + +### Optimization Not Converging +**Symptoms**: No improvement over many trials +**Solutions**: +- Check parameter ranges (too narrow/too wide?) +- Verify objective scaling (similar magnitudes?) +- Try different sampler (Random for exploration) +- Increase trial count or adjust convergence criteria + +### Constraint Violations +**Symptoms**: All or most trials violate constraints +**Solutions**: +- Relax constraint limits (may be too tight) +- Expand design variable bounds +- Adjust objective weights (prioritize feasibility) +- Consider multi-stage optimization (feasibility first) + +### Results Don't Make Sense +**Symptoms**: Optimal designs seem wrong or unrealistic +**Solutions**: +- Verify extractor functions return correct values +- Check units consistency across specification +- Validate optimal design manually in NX +- Review optimization log for anomalies + +--- + +Last updated: February 2026 \ No newline at end of file diff --git a/tools/generate_optical_report.py.backup b/tools/generate_optical_report.py.backup new file mode 100644 index 00000000..957fbce6 --- /dev/null +++ b/tools/generate_optical_report.py.backup @@ -0,0 +1,1526 @@ +#!/usr/bin/env python3 +""" +Atomizer Optical Performance Report Generator +=============================================== + +Generates a comprehensive, CDR-ready HTML report for the optical +performance of an M1 mirror design from FEA results (OP2 file). + +The report combines: +1. Executive Summary with pass/fail vs design targets +2. Per-Angle Wavefront Error Analysis (3D surface plots) +3. Zernike Trajectory Analysis (mode-specific metrics across elevation) +4. Sensitivity Matrix (axial vs lateral load response) +5. Manufacturing Analysis (90° correction metrics) +6. Full Zernike coefficient tables + +Usage: + conda activate atomizer + python generate_optical_report.py "path/to/solution.op2" + + # With annular aperture + python generate_optical_report.py "path/to/solution.op2" --inner-radius 135.75 + + # Custom targets + python generate_optical_report.py "path/to/solution.op2" --target-40 4.0 --target-60 10.0 --target-mfg 20.0 + + # Include design parameters from study database + python generate_optical_report.py "path/to/solution.op2" --study-db "path/to/study.db" --trial 725 + +Output: + Creates a single comprehensive HTML file: + {basename}_OPTICAL_REPORT_{timestamp}.html + +Author: Atomizer / Atomaste +Created: 2026-01-29 +""" + +import sys +import os +import argparse +import json +from pathlib import Path +from math import factorial +from datetime import datetime +import numpy as np +from numpy.linalg import LinAlgError + +# Add Atomizer root to path +ATOMIZER_ROOT = Path(__file__).parent.parent +if str(ATOMIZER_ROOT) not in sys.path: + sys.path.insert(0, str(ATOMIZER_ROOT)) + +try: + import plotly.graph_objects as go + from plotly.subplots import make_subplots + from matplotlib.tri import Triangulation + from pyNastran.op2.op2 import OP2 + from pyNastran.bdf.bdf import BDF +except ImportError as e: + print(f"ERROR: Missing dependency: {e}") + print("Run: conda activate atomizer") + sys.exit(1) + +# Import Atomizer extractors +from optimization_engine.extractors.extract_zernike import ( + compute_zernike_coefficients, + compute_rms_metrics, + compute_aberration_magnitudes, + compute_rms_with_custom_filter, + zernike_noll, + zernike_label, + zernike_name, + noll_indices, + read_node_geometry, + find_geometry_file, + extract_displacements_by_subcase, + UNIT_TO_NM, + DEFAULT_N_MODES, + DEFAULT_FILTER_ORDERS, +) + +from optimization_engine.extractors.extract_zernike_trajectory import ( + ZernikeTrajectoryExtractor, + MODE_GROUPS, + MODE_NAMES, + compute_trajectory_params, +) + + +# ============================================================================ +# Configuration +# ============================================================================ + +N_MODES = 50 +FILTER_LOW_ORDERS = 4 +PLOT_DOWNSAMPLE = 12000 +COLORSCALE = 'Turbo' + +# Default design targets (nm) +DEFAULT_TARGETS = { + 'wfe_40_20': 4.0, + 'wfe_60_20': 10.0, + 'mfg_90': 20.0, +} + +# Default annular aperture for M1 (271.5mm central hole diameter) +DEFAULT_INNER_RADIUS = 135.75 # mm + +DISP_UNIT = 'mm' +NM_SCALE = UNIT_TO_NM[DISP_UNIT] + +# Subcase mapping: subcase_id -> angle +SUBCASE_ANGLE_MAP = { + '1': 90, '2': 20, '3': 40, '4': 60, + '90': 90, '20': 20, '40': 40, '60': 60, +} + +# ── Professional light-theme Plotly layout defaults ── +_PLOTLY_LIGHT_LAYOUT = dict( + paper_bgcolor='#ffffff', + plot_bgcolor='#f8fafc', + font=dict(family="Inter, system-ui, sans-serif", color='#1e293b', size=12), +) + +# Professional blue palette for charts +_BLUE_PALETTE = ['#2563eb', '#3b82f6', '#60a5fa', '#93c5fd', '#1d4ed8', '#1e40af'] +_MODE_COLORS = ['#2563eb', '#dc2626', '#16a34a', '#9333ea', '#ea580c', '#0891b2', '#4f46e5'] +_MODE_DASHES = ['solid', 'dash', 'dot', 'dashdot', 'longdash', 'longdashdot', 'solid'] + + +# ============================================================================ +# Data Extraction Helpers +# ============================================================================ + +def load_study_params(db_path: str, trial_id: int = None) -> dict: + """Load design parameters from study database.""" + import sqlite3 + conn = sqlite3.connect(db_path) + c = conn.cursor() + + if trial_id is None: + # Find best trial by weighted sum + c.execute(''' + SELECT t.trial_id, tua.key, tua.value_json + FROM trials t + JOIN trial_user_attributes tua ON t.trial_id = tua.trial_id + WHERE t.state = 'COMPLETE' AND tua.key = 'weighted_sum' + ORDER BY CAST(tua.value_json AS REAL) ASC + LIMIT 1 + ''') + row = c.fetchone() + if row: + trial_id = row[0] + else: + conn.close() + return {} + + # Get all attributes for the trial + c.execute(''' + SELECT key, value_json + FROM trial_user_attributes + WHERE trial_id = ? + ''', (trial_id,)) + attrs = {row[0]: json.loads(row[1]) for row in c.fetchall()} + + # Get parameters + c.execute(''' + SELECT tp.key, tp.value_json + FROM trial_params tp + WHERE tp.trial_id = ? + ''', (trial_id,)) + params = {row[0]: json.loads(row[1]) for row in c.fetchall()} + + conn.close() + + return { + 'trial_id': trial_id, + 'attributes': attrs, + 'parameters': params, + } + + +def build_wfe_arrays(node_ids, disp, node_geo): + """Build X, Y, WFE arrays from displacement data.""" + X, Y, WFE = [], [], [] + for nid, vec in zip(node_ids, disp): + geo = node_geo.get(int(nid)) + if geo is None: + continue + X.append(geo[0]) + Y.append(geo[1]) + WFE.append(vec[2] * 2.0 * NM_SCALE) + return np.array(X), np.array(Y), np.array(WFE) + + +def compute_relative_wfe(X1, Y1, WFE1, nids1, X2, Y2, WFE2, nids2): + """Compute WFE1 - WFE2 for common nodes.""" + ref_map = {int(n): w for n, w in zip(nids2, WFE2)} + Xr, Yr, Wr = [], [], [] + for nid, x, y, w in zip(nids1, X1, Y1, WFE1): + nid = int(nid) + if nid in ref_map: + Xr.append(x) + Yr.append(y) + Wr.append(w - ref_map[nid]) + return np.array(Xr), np.array(Yr), np.array(Wr) + + +def zernike_fit(X, Y, W, n_modes=N_MODES, inner_radius=None): + """Compute Zernike fit with optional annular masking.""" + Xc = X - np.mean(X) + Yc = Y - np.mean(Y) + R_outer = float(np.max(np.hypot(Xc, Yc))) + r = np.hypot(Xc, Yc) / R_outer + th = np.arctan2(Yc, Xc) + + # Annular mask + if inner_radius is not None: + r_inner_norm = inner_radius / R_outer + mask = (r >= r_inner_norm) & (r <= 1.0) & ~np.isnan(W) + else: + mask = (r <= 1.0) & ~np.isnan(W) + + idx = np.nonzero(mask)[0] + m = int(n_modes) + G = np.zeros((m, m), dtype=np.float64) + h = np.zeros((m,), dtype=np.float64) + v = W.astype(np.float64) + + for start in range(0, len(idx), 100000): + sl = idx[start:start+100000] + Zb = np.column_stack([zernike_noll(j, r[sl].astype(np.float32), th[sl].astype(np.float32)).astype(np.float32) + for j in range(1, m+1)]) + G += (Zb.T @ Zb).astype(np.float64) + h += (Zb.T @ v[sl]).astype(np.float64) + + try: + coeffs = np.linalg.solve(G, h) + except LinAlgError: + coeffs = np.linalg.lstsq(G, h, rcond=None)[0] + + # Compute residuals + Z_all = np.column_stack([zernike_noll(j, r.astype(np.float32), th.astype(np.float32)) + for j in range(1, m+1)]) + W_low4 = Z_all[:, :FILTER_LOW_ORDERS].dot(coeffs[:FILTER_LOW_ORDERS]) + W_low3 = Z_all[:, :3].dot(coeffs[:3]) + W_res_j4 = W - W_low4 # J1-J4 removed + W_res_j3 = W - W_low3 # J1-J3 removed + + global_rms = float(np.sqrt(np.mean(W[mask]**2))) + filtered_rms = float(np.sqrt(np.mean(W_res_j4[mask]**2))) + rms_j1to3 = float(np.sqrt(np.mean(W_res_j3[mask]**2))) + + return { + 'coefficients': coeffs, + 'R_outer': R_outer, + 'global_rms': global_rms, + 'filtered_rms': filtered_rms, + 'rms_j1to3': rms_j1to3, + 'W_res_filt': W_res_j4, + 'mask': mask, + 'n_masked': int(np.sum(mask)), + 'n_total': len(W), + } + + +def aberration_magnitudes(coeffs): + """Get individual aberration magnitudes from Zernike coefficients.""" + defocus = float(abs(coeffs[3])) + astig = float(np.sqrt(coeffs[4]**2 + coeffs[5]**2)) + coma = float(np.sqrt(coeffs[6]**2 + coeffs[7]**2)) + trefoil = float(np.sqrt(coeffs[8]**2 + coeffs[9]**2)) + spherical = float(abs(coeffs[10])) if len(coeffs) > 10 else 0.0 + return { + 'defocus': defocus, 'astigmatism': astig, 'coma': coma, + 'trefoil': trefoil, 'spherical': spherical, + } + + +def compute_spatial_freq_metrics(coefficients): + """Compute spatial frequency band metrics from Zernike coefficients. + + Decomposes the Zernike spectrum into Low Spatial Frequency (form/figure) + and Mid Spatial Frequency (ripple) bands based on radial order. + + Args: + coefficients: array of Zernike coefficients (50 modes, Noll convention) + + Returns: + dict with band RMS values and per-radial-order breakdown + """ + n_modes = min(len(coefficients), 50) + coeffs = np.array(coefficients[:n_modes]) + + # Build radial order mapping using noll_indices + order_map = {} # n -> list of coeff values + for j in range(1, n_modes + 1): + n, m = noll_indices(j) + if n not in order_map: + order_map[n] = [] + order_map[n].append(coeffs[j - 1]) + + # Band definitions (by Noll index, 1-based) + # LSF: J4-J15 (n=2..4) — Low Spatial Frequency (form/figure) + # MSF: J16-J50 (n=5..9) — Mid Spatial Frequency (ripple) + lsf_coeffs = coeffs[3:15] # indices 3..14 → J4..J15 + msf_coeffs = coeffs[15:n_modes] # indices 15..49 → J16..J50 + total_coeffs = coeffs[3:n_modes] # J4..J50 (excluding piston/tilt) + + lsf_rms = float(np.sqrt(np.sum(lsf_coeffs**2))) + msf_rms = float(np.sqrt(np.sum(msf_coeffs**2))) + total_filtered_rms = float(np.sqrt(np.sum(total_coeffs**2))) + lsf_msf_ratio = lsf_rms / msf_rms if msf_rms > 0 else float('inf') + + # Per-radial-order RMS + per_order = {} + for n in sorted(order_map.keys()): + order_coeffs = np.array(order_map[n]) + per_order[n] = float(np.sqrt(np.sum(order_coeffs**2))) + + return { + 'lsf_rms': lsf_rms, + 'msf_rms': msf_rms, + 'total_filtered_rms': total_filtered_rms, + 'lsf_msf_ratio': lsf_msf_ratio, + 'per_order': per_order, + } + + +def _spatial_freq_html(metrics): + """Generate HTML card for spatial frequency band metrics.""" + m = metrics + + # Per-order breakdown for n=2..9 + order_items = "" + for n in range(2, 10): + val = m['per_order'].get(n, 0.0) + order_items += ( + f'
' + f'n={n}:' + f'{val:.2f}' + f'
\n' + ) + + ratio_str = ( + f"{m['lsf_msf_ratio']:.1f}\u00d7" + if m['lsf_msf_ratio'] < 1000 + else "\u221e" + ) + + return f""" +
+

Spatial Frequency Breakdown

+
+
+
LSF (Form)
+
J4\u2013J15   n\u22644
+
{m['lsf_rms']:.2f} nm
+
+
+
MSF (Ripple)
+
J16\u2013J50   n\u22655
+
{m['msf_rms']:.2f} nm
+
+
+
LSF / MSF
+
Ratio
+
{ratio_str}
+
+
+
+
Per-Order RMS (nm)
+
{order_items}
+
+
+ """ + + +# ============================================================================ +# HTML Report Generation +# ============================================================================ + +def _metric_color(value, target): + """Return a CSS color class based on value vs target.""" + if value <= target: + return 'color: #16a34a; font-weight: 700;' # green + ratio = value / target + if ratio < 1.5: + return 'color: #d97706; font-weight: 700;' # amber + return 'color: #dc2626; font-weight: 700;' # red + + +def make_surface_plot(X, Y, W_res, mask, inner_radius=None, title="", amp=0.5, downsample=PLOT_DOWNSAMPLE): + """Create a 3D surface plot of residual WFE.""" + Xm, Ym, Wm = X[mask], Y[mask], W_res[mask] + + n = len(Xm) + if n > downsample: + rng = np.random.default_rng(42) + sel = rng.choice(n, size=downsample, replace=False) + Xp, Yp, Wp = Xm[sel], Ym[sel], Wm[sel] + else: + Xp, Yp, Wp = Xm, Ym, Wm + + res_amp = amp * Wp + max_amp = float(np.max(np.abs(res_amp))) if res_amp.size else 1.0 + + traces = [] + try: + tri = Triangulation(Xp, Yp) + if tri.triangles is not None and len(tri.triangles) > 0: + # Filter triangles spanning central hole + if inner_radius is not None: + cx, cy = np.mean(X), np.mean(Y) + valid = [] + for t in tri.triangles: + vx = Xp[t] - cx + vy = Yp[t] - cy + vr = np.hypot(vx, vy) + if np.any(vr < inner_radius * 0.9): + continue + p0, p1, p2 = Xp[t] + 1j*Yp[t] + if max(abs(p1-p0), abs(p2-p1), abs(p0-p2)) > 2*inner_radius: + continue + valid.append(t) + if valid: + tri_arr = np.array(valid) + else: + tri_arr = tri.triangles + else: + tri_arr = tri.triangles + + i, j, k = tri_arr.T + traces.append(go.Mesh3d( + x=Xp, y=Yp, z=res_amp, + i=i, j=j, k=k, + intensity=res_amp, + colorscale=COLORSCALE, + opacity=1.0, + flatshading=False, + lighting=dict(ambient=0.4, diffuse=0.8, specular=0.3, roughness=0.5, fresnel=0.2), + lightposition=dict(x=100, y=200, z=300), + showscale=True, + colorbar=dict(title=dict(text="nm", side="right", font=dict(color='#1e293b')), thickness=12, len=0.5, tickformat=".1f", + tickfont=dict(color='#1e293b')), + hovertemplate="X: %{x:.1f}
Y: %{y:.1f}
Residual: %{z:.2f} nm" + )) + + # Inner hole circle + if inner_radius: + theta_c = np.linspace(0, 2*np.pi, 80) + traces.append(go.Scatter3d( + x=cx + inner_radius*np.cos(theta_c), + y=cy + inner_radius*np.sin(theta_c), + z=np.zeros(80), + mode='lines', line=dict(color='#64748b', width=2), + name='Central Hole', showlegend=False, hoverinfo='name' + )) + except Exception: + traces.append(go.Scatter3d( + x=Xp, y=Yp, z=res_amp, + mode='markers', marker=dict(size=2, color=res_amp, colorscale=COLORSCALE, showscale=True), + showlegend=False + )) + + fig = go.Figure(data=traces) + fig.update_layout( + scene=dict( + camera=dict(eye=dict(x=1.2, y=1.2, z=0.8), up=dict(x=0, y=0, z=1)), + xaxis=dict(title=dict(text="X (mm)", font=dict(color='#1e293b')), showgrid=True, gridcolor='#e2e8f0', + showbackground=True, backgroundcolor='#f1f5f9', + tickfont=dict(color='#475569')), + yaxis=dict(title=dict(text="Y (mm)", font=dict(color='#1e293b')), showgrid=True, gridcolor='#e2e8f0', + showbackground=True, backgroundcolor='#f1f5f9', + tickfont=dict(color='#475569')), + zaxis=dict(title=dict(text="Residual (nm)", font=dict(color='#1e293b')), range=[-max_amp*3.0, max_amp*3.0], + showgrid=True, gridcolor='#e2e8f0', + showbackground=True, backgroundcolor='#eff6ff', + tickfont=dict(color='#475569')), + aspectmode='manual', + aspectratio=dict(x=1, y=1, z=0.4), + ), + margin=dict(t=30, b=10, l=10, r=10), + **_PLOTLY_LIGHT_LAYOUT, + height=650, + width=1200, + ) + return fig.to_html(include_plotlyjs=False, full_html=False, div_id=f"surface_{title.replace(' ','_')}") + + +def make_bar_chart(coeffs, title="Zernike Coefficients", max_modes=50): + """Create horizontal bar chart of Zernike coefficient magnitudes.""" + n = min(len(coeffs), max_modes) + labels = [str(zernike_label(j))[:40] for j in range(1, n+1)] + vals = np.abs(coeffs[:n]) + text_vals = [f"{v:.3f}" for v in vals] + + fig = go.Figure(go.Bar( + x=vals, y=labels, orientation='h', + marker_color=_BLUE_PALETTE[0], + text=text_vals, + textposition='outside', + textfont=dict(size=9, color='#475569'), + hovertemplate="%{y}
|c| = %{x:.3f} nm", + )) + fig.update_layout( + height=max(400, n*22), + margin=dict(t=30, b=10, l=220, r=60), + **_PLOTLY_LIGHT_LAYOUT, + xaxis=dict(title=dict(text="|Coefficient| (nm)", font=dict(color='#1e293b')), + gridcolor='#e2e8f0', zeroline=True, + zerolinecolor='#cbd5e1', + tickfont=dict(color='#475569')), + yaxis=dict(autorange='reversed', tickfont=dict(size=10, color='#1e293b')), + ) + return fig.to_html(include_plotlyjs=False, full_html=False, div_id=f"bar_{title.replace(' ','_')}") + + +def make_trajectory_plot(angles, coefficients_relative, mode_groups, sensitivity, title=""): + """Create trajectory visualization: Zernike modes vs elevation angle.""" + fig = go.Figure() + + color_idx = 0 + + for group_name, noll_indices in mode_groups.items(): + indices = [n - 5 for n in noll_indices if 5 <= n < 5 + coefficients_relative.shape[1]] + if not indices: + continue + + color = _MODE_COLORS[color_idx % len(_MODE_COLORS)] + dash = _MODE_DASHES[color_idx % len(_MODE_DASHES)] + + # RSS of modes in this group at each angle + rss = np.sqrt(np.sum(coefficients_relative[:, indices]**2, axis=1)) + display_name = MODE_NAMES.get(group_name, group_name) + + # Group RSS trace (thick) + fig.add_trace(go.Scatter( + x=angles, y=rss, + mode='lines+markers', + name=f"{display_name} (RSS)", + line=dict(color=color, width=3, dash=dash), + marker=dict(size=10, symbol='circle'), + hovertemplate=f"{display_name} RSS
%{{x:.1f}}°: %{{y:.3f}} nm", + legendgroup=group_name, + )) + + # Individual mode traces (thin, same color, lighter) + for idx_i, noll_idx in enumerate(noll_indices): + col_idx = noll_idx - 5 + if col_idx < 0 or col_idx >= coefficients_relative.shape[1]: + continue + mode_vals = np.abs(coefficients_relative[:, col_idx]) + mode_label = f"J{noll_idx}" + fig.add_trace(go.Scatter( + x=angles, y=mode_vals, + mode='lines+markers', + name=f" {mode_label}", + line=dict(color=color, width=1, dash='dot'), + marker=dict(size=5, symbol='diamond'), + opacity=0.5, + hovertemplate=f"{mode_label}
%{{x:.1f}}°: %{{y:.3f}} nm", + legendgroup=group_name, + showlegend=True, + )) + + color_idx += 1 + + # Check if log scale would help (values span >2 orders of magnitude) + all_y = [] + for trace in fig.data: + all_y.extend([v for v in trace.y if v > 0]) + use_log = False + if all_y: + y_min, y_max = min(all_y), max(all_y) + if y_max > 0 and y_min > 0 and (y_max / y_min) > 100: + use_log = True + + yaxis_cfg = dict( + title=dict(text="RMS (nm)", font=dict(color='#1e293b')), + gridcolor='#e2e8f0', + zeroline=True, zerolinecolor='#cbd5e1', + tickfont=dict(color='#475569'), + ) + if use_log: + yaxis_cfg['type'] = 'log' + yaxis_cfg['title'] = dict(text="RMS (nm) — log scale", font=dict(color='#1e293b')) + + fig.update_layout( + height=450, + margin=dict(t=30, b=50, l=70, r=20), + **_PLOTLY_LIGHT_LAYOUT, + xaxis=dict(title=dict(text="Elevation Angle (°)", font=dict(color='#1e293b')), + gridcolor='#e2e8f0', + tickvals=list(angles), dtick=10, + tickfont=dict(color='#475569')), + yaxis=yaxis_cfg, + legend=dict(x=0.01, y=0.99, bgcolor='rgba(255,255,255,0.9)', + bordercolor='#e2e8f0', borderwidth=1, + font=dict(size=10, color='#1e293b')), + ) + return fig.to_html(include_plotlyjs=False, full_html=False, div_id="trajectory_plot") + + +def make_sensitivity_bar(sensitivity_dict): + """Create stacked bar chart of axial vs lateral sensitivity per mode.""" + modes = list(sensitivity_dict.keys()) + axial = [sensitivity_dict[m]['axial'] for m in modes] + lateral = [sensitivity_dict[m]['lateral'] for m in modes] + labels = [str(MODE_NAMES.get(m, m)) for m in modes] + + fig = go.Figure() + fig.add_trace(go.Bar( + y=labels, x=axial, orientation='h', + name='Axial (sin \u03b8)', marker_color='#2563eb', + text=[f"{v:.3f}" for v in axial], textposition='outside', + textfont=dict(size=9, color='#475569'), + hovertemplate="%{y}
Axial: %{x:.3f} nm/unit" + )) + fig.add_trace(go.Bar( + y=labels, x=lateral, orientation='h', + name='Lateral (cos \u03b8)', marker_color='#7c3aed', + text=[f"{v:.3f}" for v in lateral], textposition='outside', + textfont=dict(size=9, color='#475569'), + hovertemplate="%{y}
Lateral: %{x:.3f} nm/unit" + )) + fig.update_layout( + barmode='group', + height=max(300, len(modes)*45), + margin=dict(t=30, b=40, l=180, r=60), + **_PLOTLY_LIGHT_LAYOUT, + xaxis=dict(title=dict(text="Sensitivity (nm per load fraction)", font=dict(color='#1e293b')), + gridcolor='#e2e8f0', + zeroline=True, zerolinecolor='#cbd5e1', + tickfont=dict(color='#475569')), + yaxis=dict(autorange='reversed', tickfont=dict(size=11, color='#1e293b')), + legend=dict(x=0.55, y=0.99, bgcolor='rgba(255,255,255,0.9)', + bordercolor='#e2e8f0', borderwidth=1, + font=dict(color='#1e293b')), + ) + return fig.to_html(include_plotlyjs=False, full_html=False, div_id="sensitivity_bar") + + +def make_per_angle_rms_plot(angle_rms_data, ref_angle=20): + """Create bar chart of per-angle RMS relative to reference.""" + angles = sorted(angle_rms_data.keys()) + rms_vals = [angle_rms_data[a] for a in angles] + labels = [f"{a}\u00b0 vs {ref_angle}\u00b0" for a in angles] + + fig = go.Figure(go.Bar( + x=labels, y=rms_vals, + marker_color=_BLUE_PALETTE[0], + text=[f"{v:.2f} nm" for v in rms_vals], + textposition='outside', + textfont=dict(size=11, color='#1e293b'), + hovertemplate="%{x}: %{y:.2f} nm" + )) + fig.update_layout( + height=350, + margin=dict(t=30, b=40, l=60, r=20), + **_PLOTLY_LIGHT_LAYOUT, + yaxis=dict(title=dict(text="Filtered RMS WFE (nm)", font=dict(color='#1e293b')), + gridcolor='#e2e8f0', + zeroline=True, zerolinecolor='#cbd5e1', + tickfont=dict(color='#475569')), + xaxis=dict(tickfont=dict(color='#1e293b', size=12)), + ) + return fig.to_html(include_plotlyjs=False, full_html=False, div_id="per_angle_rms") + + +# ============================================================================ +# Main Report Builder +# ============================================================================ + +def generate_report( + op2_path: Path, + inner_radius: float = None, + targets: dict = None, + study_db: str = None, + trial_id: int = None, + title: str = "M1 Mirror Optical Performance Report", + study_name: str = None, +) -> Path: + """Generate comprehensive optical performance HTML report.""" + + targets = targets or DEFAULT_TARGETS + timestamp = datetime.now().strftime("%Y-%m-%d %H:%M") + ts_file = datetime.now().strftime("%Y%m%d_%H%M%S") + + print("=" * 70) + print(" ATOMIZER OPTICAL PERFORMANCE REPORT GENERATOR") + print("=" * 70) + print(f"\nOP2 File: {op2_path.name}") + print(f"Inner Radius: {inner_radius} mm" if inner_radius else "Aperture: Full disk") + + # ------------------------------------------------------------------ + # 1. Load geometry & displacement data + # ------------------------------------------------------------------ + print("\n[1/5] Loading data...") + geo_path = find_geometry_file(op2_path) + node_geo = read_node_geometry(geo_path) + print(f" Geometry: {geo_path.name} ({len(node_geo)} nodes)") + + op2 = OP2() + op2.read_op2(str(op2_path)) + displacements = extract_displacements_by_subcase(op2_path) + print(f" Subcases: {list(displacements.keys())}") + + # Map subcases to angles + subcase_map = {} + for angle in ['90', '20', '40', '60']: + if angle in displacements: + subcase_map[angle] = angle + if len(subcase_map) < 4: + if all(str(i) in displacements for i in range(1, 5)): + subcase_map = {'90': '1', '20': '2', '40': '3', '60': '4'} + print(f" Subcase map: {subcase_map}") + + # Also detect intermediate angles (30, 50) if present + extra_angles = [] + for a in ['30', '50']: + if a in displacements: + extra_angles.append(a) + if extra_angles: + print(f" Extra angles detected: {extra_angles}") + + # ------------------------------------------------------------------ + # 2. Per-angle Zernike analysis + # ------------------------------------------------------------------ + print("\n[2/5] Per-angle Zernike analysis...") + + ref_label = subcase_map['20'] + ref_data = displacements[ref_label] + X_ref, Y_ref, WFE_ref = build_wfe_arrays(ref_data['node_ids'], ref_data['disp'], node_geo) + + # Analysis results storage + angle_results = {} # angle -> {rms_data, X, Y, WFE, ...} + + for angle_name, label in subcase_map.items(): + data = displacements[label] + X, Y, WFE = build_wfe_arrays(data['node_ids'], data['disp'], node_geo) + + # Absolute fit + rms_abs = zernike_fit(X, Y, WFE, inner_radius=inner_radius) + + # Relative fit (vs 20 deg reference) + if angle_name != '20': + Xr, Yr, Wr = compute_relative_wfe( + X, Y, WFE, data['node_ids'], + X_ref, Y_ref, WFE_ref, ref_data['node_ids'] + ) + rms_rel = zernike_fit(Xr, Yr, Wr, inner_radius=inner_radius) + else: + Xr, Yr, Wr = X, Y, np.zeros_like(WFE) + rms_rel = {'filtered_rms': 0.0, 'rms_j1to3': 0.0, 'coefficients': np.zeros(N_MODES)} + + angle_results[int(angle_name)] = { + 'X': X, 'Y': Y, 'WFE': WFE, + 'X_rel': Xr, 'Y_rel': Yr, 'WFE_rel': Wr, + 'rms_abs': rms_abs, + 'rms_rel': rms_rel, + 'aberrations_abs': aberration_magnitudes(rms_abs['coefficients']), + 'aberrations_rel': aberration_magnitudes(rms_rel['coefficients']) if angle_name != '20' else None, + } + print(f" {angle_name}° - Abs Filt: {rms_abs['filtered_rms']:.2f} nm, " + f"Rel Filt: {rms_rel['filtered_rms']:.2f} nm") + + # Extra angles (30, 50) + for ea in extra_angles: + data = displacements[ea] + X, Y, WFE = build_wfe_arrays(data['node_ids'], data['disp'], node_geo) + Xr, Yr, Wr = compute_relative_wfe( + X, Y, WFE, data['node_ids'], + X_ref, Y_ref, WFE_ref, ref_data['node_ids'] + ) + rms_abs = zernike_fit(X, Y, WFE, inner_radius=inner_radius) + rms_rel = zernike_fit(Xr, Yr, Wr, inner_radius=inner_radius) + angle_results[int(ea)] = { + 'X': X, 'Y': Y, 'WFE': WFE, + 'X_rel': Xr, 'Y_rel': Yr, 'WFE_rel': Wr, + 'rms_abs': rms_abs, + 'rms_rel': rms_rel, + 'aberrations_abs': aberration_magnitudes(rms_abs['coefficients']), + 'aberrations_rel': aberration_magnitudes(rms_rel['coefficients']), + } + print(f" {ea}° - Abs Filt: {rms_abs['filtered_rms']:.2f} nm, " + f"Rel Filt: {rms_rel['filtered_rms']:.2f} nm") + + # ------------------------------------------------------------------ + # 3. Trajectory analysis + # ------------------------------------------------------------------ + print("\n[3/5] Trajectory analysis...") + traj_result = None + try: + traj_extractor = ZernikeTrajectoryExtractor( + op2_file=op2_path, + bdf_file=geo_path, + reference_angle=20.0, + unit=DISP_UNIT, + n_modes=N_MODES, + inner_radius=inner_radius, + ) + traj_result = traj_extractor.extract_trajectory(exclude_angles=[90.0]) + print(f" R² fit: {traj_result['linear_fit_r2']:.4f}") + print(f" Dominant mode: {traj_result['dominant_mode']}") + print(f" Total filtered RMS: {traj_result['total_filtered_rms_nm']:.2f} nm") + except Exception as e: + print(f" [WARN] Trajectory analysis failed: {e}") + + # ------------------------------------------------------------------ + # 4. Manufacturing analysis + # ------------------------------------------------------------------ + print("\n[4/5] Manufacturing analysis...") + r90 = angle_results[90] + mfg_abs_aberr = r90['aberrations_abs'] + mfg_correction = aberration_magnitudes(angle_results[90]['rms_rel']['coefficients']) + mfg_rms_j1to3 = r90['rms_rel']['rms_j1to3'] + print(f" MFG 90 (J1-J3 filtered): {mfg_rms_j1to3:.2f} nm") + print(f" Correction - Astigmatism: {mfg_correction['astigmatism']:.2f} nm, " + f"Coma: {mfg_correction['coma']:.2f} nm") + + # ------------------------------------------------------------------ + # 5. Load study params (optional) + # ------------------------------------------------------------------ + study_params = None + if study_db: + print("\n[5/5] Loading study parameters...") + try: + study_params = load_study_params(study_db, trial_id) + print(f" Trial #{study_params.get('trial_id', '?')}") + except Exception as e: + print(f" [WARN] Could not load study params: {e}") + else: + print("\n[5/5] No study database provided (skipping design parameters)") + + # ------------------------------------------------------------------ + # Key metrics for executive summary + # ------------------------------------------------------------------ + wfe_40_20 = angle_results[40]['rms_rel']['filtered_rms'] + wfe_60_20 = angle_results[60]['rms_rel']['filtered_rms'] + mfg_90 = mfg_rms_j1to3 + + # Weighted sum + ws = 6*wfe_40_20 + 5*wfe_60_20 + 3*mfg_90 + + # ------------------------------------------------------------------ + # Generate HTML + # ------------------------------------------------------------------ + print("\nGenerating HTML report...") + + # Surface plots + surf_40 = make_surface_plot( + angle_results[40]['X_rel'], angle_results[40]['Y_rel'], + angle_results[40]['rms_rel']['W_res_filt'], angle_results[40]['rms_rel']['mask'], + inner_radius=inner_radius, title="40 vs 20" + ) + surf_60 = make_surface_plot( + angle_results[60]['X_rel'], angle_results[60]['Y_rel'], + angle_results[60]['rms_rel']['W_res_filt'], angle_results[60]['rms_rel']['mask'], + inner_radius=inner_radius, title="60 vs 20" + ) + surf_90 = make_surface_plot( + angle_results[90]['X'], angle_results[90]['Y'], + angle_results[90]['rms_abs']['W_res_filt'], angle_results[90]['rms_abs']['mask'], + inner_radius=inner_radius, title="90 abs" + ) + + # Bar charts + bar_40 = make_bar_chart(angle_results[40]['rms_rel']['coefficients'], title="40v20 coeffs") + bar_60 = make_bar_chart(angle_results[60]['rms_rel']['coefficients'], title="60v20 coeffs") + bar_90 = make_bar_chart(angle_results[90]['rms_abs']['coefficients'], title="90abs coeffs") + + # Spatial frequency band metrics + sfm_40 = _spatial_freq_html(compute_spatial_freq_metrics(angle_results[40]['rms_rel']['coefficients'])) + sfm_60 = _spatial_freq_html(compute_spatial_freq_metrics(angle_results[60]['rms_rel']['coefficients'])) + sfm_90 = _spatial_freq_html(compute_spatial_freq_metrics(angle_results[90]['rms_abs']['coefficients'])) + + # Per-angle RMS plot + angle_rms_data = {} + for ang in sorted(angle_results.keys()): + if ang != 20: + angle_rms_data[ang] = angle_results[ang]['rms_rel']['filtered_rms'] + per_angle_plot = make_per_angle_rms_plot(angle_rms_data) + + # Trajectory & sensitivity plots + traj_plot_html = "" + sens_plot_html = "" + if traj_result: + coeffs_rel = np.array(traj_result['coefficients_relative']) + traj_plot_html = make_trajectory_plot( + traj_result['angles_deg'], coeffs_rel, MODE_GROUPS, + traj_result['sensitivity_matrix'] + ) + sens_plot_html = make_sensitivity_bar(traj_result['sensitivity_matrix']) + + # Design parameters table + params_html = "" + if study_params and study_params.get('parameters'): + params = study_params['parameters'] + rows = "" + for k, v in sorted(params.items()): + unit = "\u00b0" if "angle" in k else "mm" + rows += f"{k}{v:.4f} {unit}\n" + params_html = f""" +
+

7. Design Parameters (Trial #{study_params.get('trial_id', '?')})

+ + {rows}
ParameterValue
+
+ """ + + # Per-angle detail table + angle_detail_rows = "" + for ang in sorted(angle_results.keys()): + r = angle_results[ang] + rel_filt = r['rms_rel']['filtered_rms'] + abs_filt = r['rms_abs']['filtered_rms'] + abs_glob = r['rms_abs']['global_rms'] + ab = r['aberrations_abs'] + angle_detail_rows += f""" + {ang}\u00b0 + {abs_glob:.2f}{abs_filt:.2f} + {rel_filt:.2f} + {ab['astigmatism']:.2f}{ab['coma']:.2f} + {ab['trefoil']:.2f}{ab['spherical']:.2f} + """ + + # Trajectory metrics table + traj_metrics_html = "" + if traj_result: + traj_metrics_html = f""" +
+
+
Coma RMS
+
{traj_result['coma_rms_nm']:.2f} nm
+
+
+
Astigmatism RMS
+
{traj_result['astigmatism_rms_nm']:.2f} nm
+
+
+
Trefoil RMS
+
{traj_result['trefoil_rms_nm']:.2f} nm
+
+
+
Spherical RMS
+
{traj_result['spherical_rms_nm']:.2f} nm
+
+
+
Total Filtered RMS
+
{traj_result['total_filtered_rms_nm']:.2f} nm
+
+
+
Linear Fit R\u00b2
+
{traj_result['linear_fit_r2']:.4f}
+
+
+

Dominant aberration mode: {MODE_NAMES.get(traj_result['dominant_mode'], traj_result['dominant_mode'])}

+

Mode ranking: {' \u2192 '.join(traj_result['mode_ranking'][:5])}

+ """ + + # Manufacturing details + mfg_html = f""" + + + + + + + + + + +
MetricAbsolute 90\u00b0Correction (90\u00b0\u221220\u00b0)
Defocus (J4){mfg_abs_aberr['defocus']:.2f} nm{mfg_correction['defocus']:.2f} nm
Astigmatism (J5+J6){mfg_abs_aberr['astigmatism']:.2f} nm{mfg_correction['astigmatism']:.2f} nm
Coma (J7+J8){mfg_abs_aberr['coma']:.2f} nm{mfg_correction['coma']:.2f} nm
Trefoil (J9+J10){mfg_abs_aberr['trefoil']:.2f} nm{mfg_correction['trefoil']:.2f} nm
Spherical (J11){mfg_abs_aberr['spherical']:.2f} nm{mfg_correction['spherical']:.2f} nm
J1\u2212J3 Filtered RMS{r90['rms_abs']['rms_j1to3']:.2f} nm{mfg_rms_j1to3:.2f} nm
+ """ + + # Executive summary metric styling + style_40 = _metric_color(wfe_40_20, targets['wfe_40_20']) + style_60 = _metric_color(wfe_60_20, targets['wfe_60_20']) + style_mfg = _metric_color(mfg_90, targets['mfg_90']) + + # Section numbering: adjust if trajectory present + sec_surface = 3 + sec_traj = 4 + sec_mfg = 5 if traj_result else 4 + sec_params = sec_mfg + 1 + sec_zernike = sec_params + 1 if (study_params and study_params.get('parameters')) else sec_mfg + 1 + sec_method = sec_zernike + 1 + + # Assemble full HTML + html = f""" + + + + +{title} + + + + +
+ + +
+
+

{title}

+
Generated {timestamp}  |  OP2: {op2_path.name}
+ {'
Study: ' + study_name + '
' if study_name else ''} +
+
+ + ATOMIZER + +
by Atomaste
+
FEA Optimization Platform
+
+
+ + +
+

1. Executive Summary

+
+
+
WFE 40\u00b0 vs 20\u00b0 (Tracking)
+
{wfe_40_20:.2f} nm
+
+
+
WFE 60\u00b0 vs 20\u00b0 (Tracking)
+
{wfe_60_20:.2f} nm
+
+
+
MFG 90\u00b0 (J1\u2212J3 Filtered)
+
{mfg_90:.2f} nm
+
+
+
Weighted Sum (6\u00b7W40 + 5\u00b7W60 + 3\u00b7MFG)
+
{ws:.1f}
+
+
+
+ Design targets — + WFE 40\u00b0\u221220\u00b0 \u2264 {targets['wfe_40_20']:.1f} nm  |  + WFE 60\u00b0\u221220\u00b0 \u2264 {targets['wfe_60_20']:.1f} nm  |  + MFG 90\u00b0 \u2264 {targets['mfg_90']:.1f} nm  |  + Weighted sum: lower is better. + {'
Annular aperture: inner radius = ' + f'{inner_radius:.1f} mm (\u00f8{2*inner_radius:.1f} mm central hole)' if inner_radius else ''} +
+
+ + +
+

2. Per-Angle RMS Summary

+ {per_angle_plot} + + + + + + + + + {angle_detail_rows} +
AngleAbs Global RMSAbs Filtered RMSRel Filtered RMSAstigmatismComaTrefoilSpherical
+

All values in nm. Filtered = J1\u2212J4 removed. Relative = vs 20\u00b0 reference. Aberrations are absolute.

+
+ + +
+

{sec_surface}. Wavefront Error Surface Maps

+

3D residual surfaces after removing piston, tip, tilt, and defocus (J1\u2212J4). Interactive \u2014 drag to rotate.

+
+
+

40\u00b0 vs 20\u00b0 (Relative)

+ {surf_40} +
+
+

60\u00b0 vs 20\u00b0 (Relative)

+ {surf_60} +
+
+
+

90\u00b0 Manufacturing (Absolute)

+ {surf_90} +
+
+ + +{'

' + str(sec_traj) + '. Zernike Trajectory Analysis

' + + '

Mode-specific integrated RMS across the operating elevation range. ' + + 'The linear model cj(\u03b8) = aj\u00b7\u0394sin\u03b8 + bj\u00b7\u0394cos\u03b8 decomposes gravity into axial and lateral components.

' + + traj_metrics_html + + '
' + + '

Mode RMS vs Elevation Angle

' + traj_plot_html + '
' + + '

Axial vs Lateral Sensitivity

' + sens_plot_html + '
' + + '
' if traj_result else ''} + + +
+

{sec_mfg}. Manufacturing Analysis (90\u00b0 Orientation)

+

+ The mirror is manufactured (polished) at 90\u00b0 orientation. The "Correction" column shows the + aberrations that must be polished out to achieve the 20\u00b0 operational figure. +

+ {mfg_html} +
+ + +{params_html} + + +
+

{sec_zernike}. Zernike Coefficient Details

+
+ 40\u00b0 vs 20\u00b0 \u2014 Relative Coefficients +
{sfm_40}{bar_40}
+
+
+ 60\u00b0 vs 20\u00b0 \u2014 Relative Coefficients +
{sfm_60}{bar_60}
+
+
+ 90\u00b0 \u2014 Absolute Coefficients +
{sfm_90}{bar_90}
+
+
+ + +
+

{sec_method}. Methodology

+ + + + + + + + + + + {'' if traj_result else ''} + +
Zernike Modes{N_MODES} (Noll convention)
Filtered ModesJ1\u2212J4 (Piston, Tip, Tilt, Defocus)
WFE CalculationWFE = 2 \u00d7 Surface Error (reflective)
Displacement Unit{DISP_UNIT} \u2192 nm ({NM_SCALE:.0e}\u00d7)
Aperture{'Annular (inner R = ' + f'{inner_radius:.1f} mm)' if inner_radius else 'Full disk'}
Reference Angle20\u00b0 (polishing/measurement orientation)
MFG Objective90\u00b0\u221220\u00b0 relative, J1\u2212J3 filtered (optician workload)
Weighted Sum6\u00d7WFE(40\u221220) + 5\u00d7WFE(60\u221220) + 3\u00d7MFG(90)
Trajectory R\u00b2' + f'{traj_result["linear_fit_r2"]:.6f}' + '
+
+ + +
+ Generated by Atomizer Optical Report Generator  |  {timestamp}
+ \u00a9 Atomaste  |  atomaste.ca +
+ +
+ +""" + + # Write output + output_path = op2_path.parent / f"{op2_path.stem}_OPTICAL_REPORT_{ts_file}.html" + output_path.write_text(html, encoding='utf-8') + + print(f"\n{'=' * 70}") + print(f"REPORT GENERATED: {output_path.name}") + print(f"{'=' * 70}") + print(f"\nLocation: {output_path}") + print(f"Size: {output_path.stat().st_size / 1024:.0f} KB") + + return output_path + + +# ============================================================================ +# CLI +# ============================================================================ + +def main(): + parser = argparse.ArgumentParser( + description='Atomizer Optical Performance Report Generator', + epilog='Generates a comprehensive CDR-ready HTML report from FEA results.' + ) + parser.add_argument('op2_file', nargs='?', help='Path to OP2 results file') + parser.add_argument('--inner-radius', '-r', type=float, default=None, + help=f'Inner radius of central hole in mm (default: {DEFAULT_INNER_RADIUS}mm for M1)') + parser.add_argument('--inner-diameter', '-d', type=float, default=None, + help='Inner diameter of central hole in mm') + parser.add_argument('--no-annular', action='store_true', + help='Disable annular aperture (treat as full disk)') + parser.add_argument('--target-40', type=float, default=DEFAULT_TARGETS['wfe_40_20'], + help=f'WFE 40-20 target in nm (default: {DEFAULT_TARGETS["wfe_40_20"]})') + parser.add_argument('--target-60', type=float, default=DEFAULT_TARGETS['wfe_60_20'], + help=f'WFE 60-20 target in nm (default: {DEFAULT_TARGETS["wfe_60_20"]})') + parser.add_argument('--target-mfg', type=float, default=DEFAULT_TARGETS['mfg_90'], + help=f'MFG 90 target in nm (default: {DEFAULT_TARGETS["mfg_90"]})') + parser.add_argument('--study-db', type=str, default=None, + help='Path to study.db for design parameters') + parser.add_argument('--trial', type=int, default=None, + help='Trial ID (default: best trial)') + parser.add_argument('--title', type=str, default="M1 Mirror Optical Performance Report", + help='Report title') + parser.add_argument('--study-name', type=str, default=None, + help='Study name for report header') + + args = parser.parse_args() + + # Find OP2 file + if args.op2_file: + op2_path = Path(args.op2_file) + if not op2_path.exists(): + print(f"ERROR: File not found: {op2_path}") + sys.exit(1) + else: + # Search current directory + cwd = Path.cwd() + candidates = list(cwd.glob("*solution*.op2")) + list(cwd.glob("*.op2")) + if not candidates: + print("ERROR: No OP2 file found. Specify path as argument.") + sys.exit(1) + op2_path = max(candidates, key=lambda p: p.stat().st_mtime) + print(f"Found: {op2_path}") + + # Handle inner radius + inner_radius = DEFAULT_INNER_RADIUS # Default to M1 annular + if args.no_annular: + inner_radius = None + elif args.inner_diameter is not None: + inner_radius = args.inner_diameter / 2.0 + elif args.inner_radius is not None: + inner_radius = args.inner_radius + + targets = { + 'wfe_40_20': args.target_40, + 'wfe_60_20': args.target_60, + 'mfg_90': args.target_mfg, + } + + try: + generate_report( + op2_path=op2_path, + inner_radius=inner_radius, + targets=targets, + study_db=args.study_db, + trial_id=args.trial, + title=args.title, + study_name=args.study_name, + ) + except Exception as e: + print(f"\nERROR: {e}") + import traceback + traceback.print_exc() + sys.exit(1) + + +if __name__ == '__main__': + main()