docs: Archive stale docs and create Atomizer-HQ agent documentation
Archive Management: - Moved RALPH_LOOP, CANVAS, and dashboard implementation plans to archive/review/ for CEO review - Moved completed restructuring plan and protocol v1 to archive/historical/ - Moved old session summaries to archive/review/ New HQ Documentation (docs/hq/): - README.md: Overview of Atomizer-HQ multi-agent optimization team - PROJECT_STRUCTURE.md: Standard KB-integrated project layout with Hydrotech reference - KB_CONVENTIONS.md: Knowledge Base accumulation principles with generation tracking - AGENT_WORKFLOWS.md: Project lifecycle phases and agent handoffs (OP_09 integration) - STUDY_CONVENTIONS.md: Technical study execution standards and atomizer_spec.json format Index Update: - Reorganized docs/00_INDEX.md with HQ docs prominent - Updated structure to reflect new agent-focused organization - Maintained core documentation access for engineers No files deleted, only moved to appropriate archive locations.
This commit is contained in:
225
docs/00_INDEX.md
225
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
|
||||
450
docs/hq/AGENT_WORKFLOWS.md
Normal file
450
docs/hq/AGENT_WORKFLOWS.md
Normal file
@@ -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
|
||||
476
docs/hq/KB_CONVENTIONS.md
Normal file
476
docs/hq/KB_CONVENTIONS.md
Normal file
@@ -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
|
||||
377
docs/hq/PROJECT_STRUCTURE.md
Normal file
377
docs/hq/PROJECT_STRUCTURE.md
Normal file
@@ -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
|
||||
117
docs/hq/README.md
Normal file
117
docs/hq/README.md
Normal file
@@ -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
|
||||
549
docs/hq/STUDY_CONVENTIONS.md
Normal file
549
docs/hq/STUDY_CONVENTIONS.md
Normal file
@@ -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
|
||||
1526
tools/generate_optical_report.py.backup
Normal file
1526
tools/generate_optical_report.py.backup
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user