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'
| Parameter | Value |
|---|
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""" +| Metric | Absolute 90\u00b0 | Correction (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 |
| Angle | Abs Global RMS | Abs Filtered RMS | +Rel Filtered RMS | +Astigmatism | Coma | Trefoil | Spherical | +
|---|
All values in nm. Filtered = J1\u2212J4 removed. Relative = vs 20\u00b0 reference. Aberrations are absolute.
+3D residual surfaces after removing piston, tip, tilt, and defocus (J1\u2212J4). Interactive \u2014 drag to rotate.
+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 + + '+ 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} +| Zernike Modes | {N_MODES} (Noll convention) |
| Filtered Modes | J1\u2212J4 (Piston, Tip, Tilt, Defocus) |
| WFE Calculation | WFE = 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 Angle | 20\u00b0 (polishing/measurement orientation) |
| MFG Objective | 90\u00b0\u221220\u00b0 relative, J1\u2212J3 filtered (optician workload) |
| Weighted Sum | 6\u00d7WFE(40\u221220) + 5\u00d7WFE(60\u221220) + 3\u00d7MFG(90) |
| Trajectory R\u00b2 | ' + f'{traj_result["linear_fit_r2"]:.6f}' + ' |