@@ -0,0 +1,982 @@
# TECHNICAL REVIEW: Atomizer Project Standard Specification v1.0
**Reviewer: ** Technical Lead (Subagent)
**Date: ** 2026-02-18
**Specification Version: ** 1.0 (Draft)
**Review Scope: ** Compatibility, feasibility, implementation complexity
---
## Executive Summary
The proposed Atomizer Project Standard is **ambitious and well-designed ** but requires **significant code changes ** to be fully compatible with the existing optimization engine. The core concepts are sound, but several assumptions about auto-extraction and file organization need technical amendments.
**Overall Assessment: **
- ✅ **Philosophy ** : Excellent — self-contained, LLM-native, rationale-first
- ⚠️ **AtomizerSpec v2.0 Integration ** : Requires path refactoring in optimization engine
- ⚠️ **Auto-Extraction Claims ** : Overstated — some extraction needs manual intervention
- ✅ **Study Lifecycle ** : Good mapping to existing protocols, but gaps exist
- ⚠️ **Schema Alignment ** : `.atomizer/project.json` creates redundancy
- ⚠️ **Model Organization ** : Dual-location pattern is confusing
- ✅ **Report Generation ** : Feasible with existing tooling
- ⚠️ **Playbooks ** : Redundant with Protocol Operating System
**Recommendation: ** Adopt with amendments. Priority order: Path compatibility → Auto-extraction → Schema consolidation → Documentation.
---
## 1. AtomizerSpec v2.0 Compatibility
### Current State
**File Paths in AtomizerSpec v2.0: **
``` json
{
"model" : {
"sim" : {
"path" : "Model_sim1.sim" // Relative to study root
}
}
}
```
**Optimization Engine Assumptions: **
``` python
# optimization_engine/core/runner.py (line ~30)
self . config_path = Path ( config_path ) # Expects config in study root or 1_setup/
# optimization_engine/nx/solver.py
# Expects model files in study_dir/1_setup/model/
```
**Current Study Structure: **
```
├── 1_setup/
│ ├── model/ # NX files here
│ └── atomizer_spec.json # Config here (or optimization_config.json)
├── 2_iterations/
└── 3_results/
```
### Proposed Structure
```
├── 01-models/
│ ├── cad/Model.prt
│ ├── fem/Model_fem1.fem
│ └── sim/Model_sim1.sim
├── 03-studies/
│ └── {NN}_{slug}/
│ ├── atomizer_spec.json
│ └── 1_setup/
│ └── model/ # Study-specific model copy (if modified)
```
### Compatibility Issues
| Issue | Severity | Impact |
|-------|----------|--------|
| `atomizer_spec.json` path references assume study-relative paths | **HIGH ** | Path resolution breaks if models are in `../../01-models/` |
| `OptimizationRunner.__init__()` expects config in study dir | **MEDIUM ** | Need `--project-root` flag |
| Study archival assumes `1_setup/model/` is the source | **MEDIUM ** | Backup/restore logic needs project-aware path |
| `TrialManager` trial numbering is study-scoped, not project-scoped | **LOW ** | Multiple studies in a project can have overlapping trial numbers |
### Code Changes Required
#### Change 1: Add Project Root Awareness
`optimization_engine/core/runner.py`
**Complexity: ** Medium (2-4 hours)
``` python
class OptimizationRunner :
def __init__ (
self ,
config_path : Path ,
project_root : Optional [ Path ] = None , # NEW
model_updater : Callable ,
simulation_runner : Callable ,
result_extractors : Dict [ str , Callable ]
) :
self . config_path = Path ( config_path )
self . project_root = Path ( project_root ) if project_root else self . config_path . parent . parent # NEW
# Resolve model paths relative to project root
if self . project_root :
self . model_dir = self . project_root / " 01-models "
else :
self . model_dir = self . config_path . parent / " 1_setup " / " model "
```
**Priority: ** P0 — Blocking for project-standard adoption
#### Change 2: Update AtomizerSpec Path Resolution
`optimization_engine/config/spec_models.py`
**Complexity: ** Low (1-2 hours)
Add `resolve_paths()` method to `AtomizerSpec` :
``` python
class AtomizerSpec ( BaseModel ) :
# ... existing fields ...
def resolve_paths ( self , project_root : Path ) - > None :
""" Resolve all relative paths against project root. """
if self . model . sim . path :
self . model . sim . path = str ( project_root / " 01-models " / " sim " / Path ( self . model . sim . path ) . name )
if self . model . fem and self . model . fem . path :
self . model . fem . path = str ( project_root / " 01-models " / " fem " / Path ( self . model . fem . path ) . name )
# ... etc
```
**Priority: ** P0 — Blocking
#### Change 3: Add `--project-root` CLI Flag
`run_optimization.py` (template)
**Complexity: ** Trivial (<1 hour)
``` python
parser . add_argument (
" --project-root " ,
type = Path ,
default = None ,
help = " Path to project root (for Atomizer Project Standard layout) "
)
```
**Priority: ** P1 — Nice-to-have
### Recommendation
**Option A: Hybrid Mode (Recommended) **
Support BOTH layouts:
- **Legacy mode** (default): `studies/{study}/1_setup/model/`
- **Project mode**: `projects/{name}/03-studies/{study}/` + `--project-root` flag
Detect automatically:
``` python
def detect_layout ( study_dir : Path ) - > str :
if ( study_dir . parent . parent / " 01-models " ) . exists ( ) :
return " project-standard "
return " legacy "
```
**Option B: Migration Tool **
Create `migrate_to_project_standard.py` that:
1. Creates `01-models/` and copies baseline model
2. Moves studies to `03-studies/{NN}_{slug}/`
3. Updates all `atomizer_spec.json` paths
4. Creates `.atomizer/project.json`
**Estimated Implementation: ** 12-16 hours total
---
## 2. Study Lifecycle vs Real Workflow
### Proposed Lifecycle (Spec §6.1)
```
```
### Actual Atomizer Operations (Protocol Operating System)
| Operation | POS Protocol | Coverage in Spec |
|-----------|--------------|------------------|
| **OP_01: Create Study ** | Bootstrap + study creation | ✅ PLAN + CONFIGURE |
| **OP_02: Run Optimization ** | Execute trials | ✅ RUN |
| **OP_03: Monitor Progress ** | Real-time tracking | ❌ Missing in lifecycle |
| **OP_04: Analyze Results ** | Post-processing | ✅ ANALYZE |
| **OP_05: Export Training Data ** | Neural acceleration | ❌ Missing |
| **OP_06: Troubleshoot ** | Debug failures | ❌ Missing |
| **OP_07: Disk Optimization ** | Free space | ❌ Missing |
| **OP_08: Generate Report ** | Deliverables | ✅ REPORT |
### Gaps Identified
| Gap | Impact | Recommendation |
|-----|--------|----------------|
| No **MONITOR ** stage | Real-time progress tracking is critical | Add between RUN and ANALYZE |
| No **EXPORT ** stage | Neural surrogate training needs data | Add parallel to FEED-BACK |
| No **TROUBLESHOOT ** stage | Optimization failures are common | Add decision tree in playbooks |
| No **DISK-OPTIMIZE ** stage | `.op2` files fill disk quickly | Add to tools/ or playbooks |
### Recommended Lifecycle (Revised)
```
↓ ↓
EXPORT (optional) TROUBLESHOOT (if needed)
```
### Mapping to Spec Sections
| Lifecycle Stage | Spec Section | Protocol | Deliverable |
|-----------------|--------------|----------|-------------|
| PLAN | §6.2 Stage 1 | User-driven | `README.md` hypothesis |
| CONFIGURE | §6.2 Stage 2 | OP_01 | `atomizer_spec.json` |
| VALIDATE | §6.2 Stage 3 | OP_01 preflight | Validation report |
| RUN | §6.2 Stage 4 | OP_02 | `study.db` , `2_iterations/` |
| **MONITOR ** | * Missing * | OP_03 | Real-time logs |
| ANALYZE | §6.2 Stage 5 | OP_04 | Plots, sensitivity |
| REPORT | §6.2 Stage 6 | OP_08 | `STUDY_REPORT.md` |
| FEED-BACK | §6.2 Stage 7 | Manual | KB updates |
| **EXPORT ** | * Missing * | OP_05 | `training_data/` |
| **TROUBLESHOOT ** | * Missing * | OP_06 | Fix + log |
**Estimated Amendment Effort: ** 2-4 hours (documentation)
---
## 3. Auto-Extraction Feasibility
### Spec Claims (§7.2)
> "The Atomizer intake workflow already extracts:"
| Data | Claimed Source | Reality Check |
|------|---------------|---------------|
| All NX expressions | ✅ `introspect_part.py` | **VERIFIED ** — works |
| Mass properties | ✅ NXOpen MeasureManager | **VERIFIED ** — works |
| Material assignments | ❓ `.fem` material cards | **PARTIAL ** — needs parser |
| Mesh statistics | ❓ `.fem` element/node counts | **PARTIAL ** — needs parser |
| Boundary conditions | ❓ `.sim` constraint definitions | **NO ** — not implemented |
| Load cases | ❓ `.sim` load definitions | **NO ** — not implemented |
| Baseline solve results | ✅ `.op2` / `.f06` parsing | **VERIFIED ** — pyNastran |
| Design variable candidates | ✅ Expression analysis | **VERIFIED ** — confidence scoring exists |
### Actual Extraction Capabilities (E12 Introspector)
**File: ** `optimization_engine/extractors/introspect_part.py`
**WORKS: **
``` python
result = introspect_part ( " Model.prt " )
# Returns:
{
' expressions ' : { ' user ' : [ . . . ] , ' user_count ' : 47 } ,
' mass_properties ' : { ' mass_kg ' : 1133.01 , ' volume_mm3 ' : . . . } ,
' materials ' : { ' assigned ' : [ . . . ] } , # Material NAME only
' bodies ' : { ' solid_bodies ' : [ . . . ] , ' counts ' : { . . . } } ,
' features ' : { ' total_count ' : 152 , ' by_type ' : { . . . } } ,
}
```
**DOES NOT WORK: **
- **Material properties** (E, ν ρ `physicalmateriallibrary.xml` parsing (not implemented)
- **Boundary conditions** — `.sim` file is XML, no parser exists
- **Load cases** — Same issue
- **Mesh statistics** — `.fem` is BDF format, would need pyNastran `read_bdf()`
### Missing Extractors
| Missing Capability | File Format | Difficulty | Estimated Effort |
|--------------------|-------------|------------|------------------|
| Material property extraction | `.xml` | Low | 4-6 hours |
| Mesh statistics | `.fem` (BDF) | Low | 2-4 hours (use pyNastran) |
| BC extraction | `.sim` (XML) | Medium | 8-12 hours |
| Load extraction | `.sim` (XML) | Medium | 8-12 hours |
### Recommendations
#### Immediate Actions
1. **Update spec §7.2 ** to reflect reality:
- ✅ Expression extraction: Fully automatic
- ✅ Mass properties: Fully automatic
- ⚠️ Material assignments: Name only (properties require manual entry or XML parser)
- ⚠️ Mesh statistics: Requires BDF parser (pyNastran — 2 hours to implement)
- ❌ Boundary conditions: Not automatic — manual KB entry or 8-12 hour XML parser
- ❌ Load cases: Not automatic — manual KB entry
2. **Create roadmap ** for missing extractors (§7.2 becomes aspirational):
- Phase 1: Expression + Mass (DONE)
- Phase 2: Mesh stats (2-4 hours)
- Phase 3: Material properties (4-6 hours)
- Phase 4: BCs + Loads (16-24 hours)
3. **Add to KB population protocol ** (§7.3):
- Auto-extraction runs what's available TODAY
- User fills gaps via structured interview
- KB entries flag: `source: auto|manual|mixed`
**Estimated Total Effort for Full Auto-Extraction: ** 30-46 hours
---
## 4. Schema Alignment: `.atomizer/project.json` vs `atomizer_spec.json`
### Redundancy Analysis
* * `.atomizer/project.json` (Spec §9.3):**
``` json
{
"project" : {
"slug" : "thermoshield-bracket" ,
"display_name" : "ThermoShield Bracket" ,
"created" : "2026-02-15T..." ,
"template_version" : "1.0" ,
"status" : "active" ,
"client" : "SpaceCo" ,
"model" : {
"cad_system" : "NX" ,
"solver" : "NX_Nastran" ,
"solution_type" : "SOL101"
} ,
"studies_count" : 3 ,
"active_study" : "03_cmaes_refinement" ,
"tags" : [ "thermal" , "satellite" ]
}
}
```
* * `atomizer_spec.json` (per study):**
``` json
{
"meta" : {
"version" : "2.0" ,
"study_name" : "03_cmaes_refinement" ,
"created" : "2026-02-16T..." ,
"description" : "..." ,
"status" : "running" ,
"tags" : [ "thermal" ]
} ,
"model" : {
"sim" : {
"path" : "Model_sim1.sim" ,
"solver" : "nastran" ,
"solution_type" : "SOL101"
}
}
}
```
### Overlap Map
| Data | `.atomizer/project.json` | `atomizer_spec.json` | Redundant? |
|------|-------------------------|---------------------|------------|
| Project slug | ✅ | ❌ | No |
| Study name | ❌ | ✅ | No |
| Client | ✅ | ❌ | No |
| CAD system | ✅ | ✅ | **YES ** |
| Solver | ✅ | ✅ | **YES ** |
| Solution type | ✅ | ✅ | **YES ** |
| Status | ✅ (project) | ✅ (study) | No (different scopes) |
| Tags | ✅ (project) | ✅ (study) | Partial (project vs study) |
| Created date | ✅ (project) | ✅ (study) | No (different events) |
### Issues
1. **Source of Truth Conflict: **
- If `project.json` says `"solver": "nastran"` but a study spec says `"solver": "abaqus"` , which wins?
- **Resolution:** Study spec ALWAYS wins (more specific). `project.json` is metadata only.
2. **Synchronization Burden: **
- Creating a study requires updating BOTH files
- Deleting a study requires updating `studies_count` , `active_study`
- **Resolution:** Make `project.json` auto-generated (never hand-edit)
3. **Discoverability: **
- `project.json` enables project-level queries ("show all NX projects")
- But `atomizer_spec.json` metadata fields (`meta.tags` ) already support this
- **Resolution:** Keep project-level aggregation but make it derived
### Recommendation
**Option 1: Generate `project.json` on-demand (Recommended) **
``` python
# optimization_engine/utils/project_manager.py (NEW)
def generate_project_json ( project_root : Path ) - > Dict [ str , Any ] :
""" Generate project.json from study specs + PROJECT.md frontmatter. """
studies = list ( ( project_root / " 03-studies " ) . glob ( " */atomizer_spec.json " ) )
# Aggregate from studies
solvers = set ( )
tags = set ( )
for study_spec in studies :
spec = AtomizerSpec . load ( study_spec )
solvers . add ( spec . model . sim . solver )
tags . update ( spec . meta . tags or [ ] )
# Read PROJECT.md frontmatter for client, display_name
frontmatter = parse_markdown_frontmatter ( project_root / " PROJECT.md " )
return {
" project " : {
" slug " : project_root . name ,
" display_name " : frontmatter . get ( " project " , project_root . name ) ,
" client " : frontmatter . get ( " client " ) ,
" created " : frontmatter . get ( " created " ) ,
" template_version " : frontmatter . get ( " template_version " , " 1.0 " ) ,
" status " : frontmatter . get ( " status " , " active " ) ,
" model " : {
" solvers " : list ( solvers ) , # List of solvers used across studies
} ,
" studies_count " : len ( studies ) ,
" tags " : list ( tags )
}
}
```
Call this on:
- Project creation (`atomizer project create` )
- Study creation/deletion
- Dashboard load
**Option 2: Eliminate `project.json` entirely **
Use `PROJECT.md` frontmatter as the source of truth for project metadata. Tools parse YAML frontmatter when needed.
**Pros: ** No redundancy
**Cons: ** Slower parsing (MD vs JSON)
**Verdict: ** Option 1. Keep `project.json` as a **cache ** , auto-generated.
**Estimated Effort: ** 4-6 hours
---
## 5. Model File Organization
### Proposed Dual-Location Pattern
**From Spec §2.1 and §10 (ThermoShield Bracket): **
```
├── 01-models/ # "Golden copies"
│ ├── cad/ThermoShield_Bracket.prt
│ ├── fem/ThermoShield_Bracket_fem1.fem
│ └── sim/ThermoShield_Bracket_sim1.sim
└── 03-studies/
└── 03_cmaes_refinement/
└── 1_setup/
└── model/ # "Study-specific model copy (if modified)"
```
### Confusion Points
| Question | Current Atomizer | Spec Proposal | Issue |
|----------|------------------|---------------|-------|
| Where is the source model? | `1_setup/model/` | `01-models/` | Two locations |
| Where does the solver look? | `1_setup/model/` | Depends on study | Path confusion |
| When do I copy to study? | Always | "if modified" | Unclear trigger |
| What if study modifies model? | Study owns it | Study copy diverges | Sync problem |
### Real-World Example: Hydrotech Beam
**Current (works): **
```
└── studies/
└── 01_doe_landscape/
└── 1_setup/
└── model/
├── Beam.prt # Study owns this
├── Beam_fem1.fem
└── Beam_sim1.sim
```
**Proposed (spec): **
```
├── 01-models/
│ ├── cad/Beam.prt # "Golden copy"
│ └── ...
└── 03-studies/
└── 01_doe_landscape/
└── 1_setup/
└── model/ # Copy if modified? Or symlink?
```
**Problem: ** Most optimization studies DO modify the model (that's the point). So "if modified" → "always".
### Alternative Interpretations
#### Interpretation A: `01-models/` is baseline, studies always copy
- `01-models/` = Baseline for comparison
- `03-studies/{NN}/1_setup/model/` = Working copy (always present)
- Pro: Clear separation
- Con: Disk waste (5+ studies ×
#### Interpretation B: `01-models/` is shared, studies symlink
- `01-models/` = Shared model files
- `03-studies/{NN}/1_setup/model/` = Symlinks to `../../../01-models/`
- Pro: No duplication
- Con: NX doesn't handle symlinks well on Windows
#### Interpretation C: Single source of truth (current Atomizer)
- `01-models/` = Documentation/reference only
- `03-studies/{NN}/1_setup/model/` = Actual working model
- Studies start from a baseline but own their model
- Pro: Simple, no sync issues
- Con: No "golden copy" for comparison
### Recommendation
**Adopt Interpretation C with amendments: **
1. * * `01-models/baseline/` ** contains:
- Baseline `.prt` , `.fem` , `.sim`
- `BASELINE.md` with documented metrics
- `results/` with baseline `.op2` , `.f06`
2. * * `03-studies/{NN}/1_setup/model/` ** contains:
- Working model for THIS study (copied from baseline at creation)
- Study owns this and can modify
3. **Study creation workflow: **
```python
def create_study(project_root, study_name):
baseline = project_root / "01-models" / "baseline"
study_model = project_root / "03-studies" / study_name / "1_setup" / "model"
# Copy baseline to study
shutil.copytree(baseline, study_model)
# Study README notes: "Started from baseline (mass=X, disp=Y)"
` ``
4. **Update spec §5 (Model File Organization):**
- Rename ` 01-models/` → ` 01-models/baseline/`
- Clarify: "Studies copy from baseline at creation and own their model thereafter"
- Add warning: "Do NOT modify ` 01-models/baseline/` during optimization"
**Estimated Effort:** 2 hours (documentation update)
---
## 6. Report Auto-Generation Feasibility
### Spec Claims (§8.2)
> "After a study completes, the following can be auto-generated from ` study.db` + ` iteration_history.csv` + ` atomizer_spec.json`"
**Template:**
` ``markdown
# Study Report: {study_name}
## Configuration
{Auto-extracted from atomizer_spec.json}
## Results Summary
| Metric | Best | Mean | Worst | Target |
## Convergence
{Auto-generated convergence plot reference}
## Parameter Analysis
{Top parameter importances from Optuna}
## Best Trial Details
...
` ``
### Existing Capabilities
**File:** ` optimization_engine/reporting/markdown_report.py`
` ``python
def generate_study_report(study_dir: Path, output_file: Path):
"""Generate markdown study report from Optuna database."""
# ✅ Loads study.db
# ✅ Extracts best trial, objectives, parameters
# ✅ Generates convergence plot (matplotlib → PNG)
# ✅ Computes parameter importance (Optuna fANOVA)
# ✅ Writes markdown with tables
` ``
**Example Output (M1 Mirror V14):**
` ``markdown
# Study Report: m1_mirror_adaptive_V14
## Study Information
- **Algorithm**: TPE
- **Budget**: 785 trials
- **Objectives**: wfe_40_20_nm, wfe_60_20_nm, mfg_90_nm, mass_kg
## Best Trial (#743)
| Objective | Value |
|-----------|-------|
| wfe_40_20_nm | 5.99 |
| Weighted Sum | 121.72 |
## Parameter Importance
| Parameter | Importance |
|-----------|-----------|
| whiffle_min | 0.45 |
| lateral_inner_angle | 0.23 |
...
` ``
### Gaps vs Spec Template
| Spec Feature | Exists? | Gap |
|--------------|---------|-----|
| Configuration summary | ✅ | Works |
| Results summary table | ✅ | Works |
| Convergence plot | ✅ | Works |
| Parameter importance | ✅ | Works (Optuna fANOVA) |
| Feasibility breakdown | ❌ | Missing — need to parse trial states |
| Best trial geometry export | ❌ | Missing — need NX journal to export ` .step` |
| Human annotation section | ✅ | Placeholder exists |
### Implementation Needs
#### Feature 1: Feasibility Breakdown
` ``python
def get_feasibility_stats(study: optuna.Study) -> Dict[str, int]:
"""Analyze trial feasibility."""
stats = {
'total': len(study.trials),
'complete': 0,
'failed': 0,
'pruned': 0,
'infeasible_geo': 0, # Geometric constraint violation
'infeasible_constraint': 0 # FEA constraint violation
}
for trial in study.trials:
if trial.state == optuna.trial.TrialState.COMPLETE:
stats['complete'] += 1
# Check user_attrs for infeasibility reason
if trial.user_attrs.get('infeasible_reason') == 'geometry':
stats['infeasible_geo'] += 1
elif trial.user_attrs.get('infeasible'):
stats['infeasible_constraint'] += 1
elif trial.state == optuna.trial.TrialState.FAIL:
stats['failed'] += 1
return stats
` ``
**Effort:** 2-4 hours
#### Feature 2: Best Trial Geometry Export
Requires NX journal to:
1. Load best trial model from ` 2_iterations/trial_{N}/`
2. Export as ` .step` or ` .x_t`
3. Save to ` 3_results/best_trial/geometry.step`
**Effort:** 4-6 hours (NX journal development)
### Recommendation
**Phase 1 (Immediate):** Use existing ` markdown_report.py`, add:
- Feasibility stats (2-4 hours)
- Template for human annotation (already exists)
**Phase 2 (Future):** Add:
- Best trial geometry export (4-6 hours)
- Automated plot embedding in markdown (2 hours)
**Update Spec §8.2:** Note that geometry export is manual for now.
**Total Estimated Effort:** 8-12 hours for full auto-generation
---
## 7. Playbooks vs Protocol Operating System
### Spec Proposal (§2.1, §10)
` ``
playbooks/
├── FIRST_RUN.md # How to run the first trial
└── MODAL_ANALYSIS.md # How to extract frequency results
` ``
### Existing Protocol Operating System
` ``
docs/protocols/
├── operations/
│ ├── OP_01_CREATE_STUDY.md
│ ├── OP_02_RUN_OPTIMIZATION.md
│ ├── OP_03_MONITOR_PROGRESS.md
│ ├── OP_04_ANALYZE_RESULTS.md
│ └── ...
└── system/
└── SYS_12_EXTRACTOR_LIBRARY.md
` ``
### Redundancy Analysis
| Playbook (Spec) | Protocol (Existing) | Overlap? |
|-----------------|---------------------|----------|
| ` FIRST_RUN.md` | ` OP_02_RUN_OPTIMIZATION.md` | **100%** — Same content |
| ` MODAL_ANALYSIS.md` | ` SYS_12_EXTRACTOR_LIBRARY.md` (E2: Frequency) | **90%** — Extractor docs cover this |
| ` DOE_SETUP.md` (implied) | ` OP_01_CREATE_STUDY.md` | **80%** — OP_01 includes sampler selection |
### Key Difference
**Protocols (POS):** Framework-level, generic, applies to all projects
**Playbooks (Spec):** Project-specific, tailored to this exact component/study
**Example:**
**OP_02 (Protocol):**
` ``markdown
# OP_02: Run Optimization
## Quick Start
` ``bash
python run_optimization.py --start
` ``
## Monitoring
Check progress: ` OP_03`
` ``
**FIRST_RUN.md (Playbook):**
` ``markdown
# First Run: ThermoShield Bracket
## Specific to THIS project
- Solver timeout: 600s (bracket solves fast)
- Watch for hole overlap infeasibility
- First 10 trials are DOE (LHS)
## Run
` ``bash
cd 03-studies/01_doe_landscape
python run_optimization.py --start
` ``
## Expected behavior
- Trial 1-10: ~30 seconds each (DOE)
- Trial 11+: TPE kicks in
- If mass > 0.8 kg → infeasible (auto-pruned)
` ``
### Recommendation
**Keep both, clarify distinction:**
1. **Playbooks** = Project-specific operational guides
- Location: ` {project}/playbooks/`
- Content: Project quirks, expected behavior, troubleshooting for THIS project
- Examples: "On this model, tip displacement is at node 5161"
2. **Protocols** = Generic framework operations
- Location: ` Atomizer/docs/protocols/`
- Content: How Atomizer works in general
- Examples: "To monitor, use OP_03"
3. **Update spec §2.1:**
- Rename ` playbooks/` → ` playbooks/` (keep name)
- Add description: "Project-specific operational notes. See ` docs/protocols/` for generic Atomizer operations."
4. **Create template playbooks:**
- ` playbooks/FIRST_RUN.md` → Template with placeholders
- ` playbooks/TROUBLESHOOTING.md` → Project-specific issues log
- ` playbooks/EXTRACTOR_NOTES.md` → Custom extractor usage for this project
**Estimated Effort:** 2 hours (documentation)
---
## Summary of Recommendations
### Priority 0: Blocking Issues (Must Fix Before Adoption)
| Issue | Change | Effort | Owner |
|-------|--------|--------|-------|
| Path compatibility | Add project root awareness to ` OptimizationRunner` | 2-4h | Dev |
| Path resolution | Update ` AtomizerSpec.resolve_paths()` | 1-2h | Dev |
| Auto-extraction claims | Revise §7.2 to reflect reality | 1h | Manager |
**Total P0 Effort:** 4-7 hours
### Priority 1: Important Improvements
| Issue | Change | Effort | Owner |
|-------|--------|--------|-------|
| Study lifecycle gaps | Add MONITOR, EXPORT, TROUBLESHOOT stages | 2-4h | Manager |
| Model organization clarity | Amend §5 to clarify baseline vs working copy | 2h | Manager |
| Schema redundancy | Make ` .atomizer/project.json` auto-generated | 4-6h | Dev |
| Report feasibility stats | Add feasibility breakdown to report generator | 2-4h | Dev |
**Total P1 Effort:** 10-16 hours
### Priority 2: Nice-to-Have
| Issue | Change | Effort | Owner |
|-------|--------|--------|-------|
| Full auto-extraction | Implement missing extractors (mesh, BC, loads) | 30-46h | Dev |
| Best trial geometry export | NX journal for ` .step` export | 4-6h | Dev |
| Playbook templates | Create template playbooks | 2h | Manager |
**Total P2 Effort:** 36-54 hours
---
## Implementation Roadmap
### Phase 1: Core Compatibility (Week 1)
- [ ] Add project root awareness to optimization engine (4-7h)
- [ ] Update spec §7.2 auto-extraction claims (1h)
- [ ] Amend spec §6 lifecycle to include missing stages (2h)
- [ ] Clarify spec §5 model organization (2h)
**Deliverable:** Spec v1.1 (compatible with existing Atomizer)
### Phase 2: Enhanced Integration (Week 2-3)
- [ ] Implement ` .atomizer/project.json` auto-generation (4-6h)
- [ ] Add feasibility stats to report generator (2-4h)
- [ ] Create playbook templates (2h)
- [ ] Test migration of Hydrotech Beam to project standard (4h)
**Deliverable:** Working project-standard template + migration tool
### Phase 3: Advanced Features (Future)
- [ ] Implement missing auto-extractors (30-46h)
- [ ] Best trial geometry export (4-6h)
- [ ] Dashboard integration for project view (TBD)
**Deliverable:** Full auto-population capability
---
## Technical Amendments to Specification
### Amendment 1: Section 1.2 Decision D3
**Current:**
> "Impact on Atomizer code: The optimization engine needs a ` --project-root` flag or config entry pointing to the project folder."
**Amend to:**
> "Impact on Atomizer code:
> 1. Add ` project_root` parameter to ` OptimizationRunner.__init__()`
> 2. Update ` AtomizerSpec.resolve_paths()` to handle ` ../../01-models/` references
> 3. Add ` --project-root` CLI flag to ` run_optimization.py` template
> 4. Maintain backward compatibility with legacy ` studies/{name}/1_setup/model/` layout
> **Estimated implementation:** 4-7 hours."
### Amendment 2: Section 5 (Model File Organization)
**Add new subsection §5.4: Model Location Decision Tree**
` ``markdown
### 5.4 Model Location Decision Tree
**Q: Where should I put the model files?**
| Scenario | Location | Rationale |
|----------|----------|-----------|
| Single study, no baseline comparison | ` 03-studies/01_study/1_setup/model/` | Simple, no duplication |
| Multiple studies from same baseline | ` 01-models/baseline/` + copy to studies | Baseline preserved for comparison |
| Studies modify model parametrically | ` 03-studies/{NN}/1_setup/model/` (copy) | Each study owns its model |
| Studies share exact same model | ` 01-models/` + symlink (advanced) | Disk savings — NX compatibility risk |
**Default recommendation:** Copy baseline to each study at creation.
` ``
### Amendment 3: Section 7.2 (Auto-Extraction Feasibility)
**Replace current table with:**
| Data | Auto-Extraction Status | Manual Fallback |
|------|----------------------|-----------------|
| All NX expressions | ✅ **Fully automatic** (` introspect_part.py`) | N/A |
| Mass properties | ✅ **Fully automatic** (NXOpen MeasureManager) | N/A |
| Material names | ✅ **Fully automatic** (part introspection) | N/A |
| Material properties (E, ν ρ physicalmateriallibrary.xml` parser (4-6h dev) | Manual entry in ` 02-kb/design/materials/{Material}.md` |
| Mesh statistics (element/node count) | ⚠️ **Requires implementation** — pyNastran BDF parser (2-4h dev) | Manual entry from NX Pre/Post |
| Boundary conditions | ❌ **Not implemented** — requires ` .sim` XML parser (8-12h dev) | Manual documentation in ` 02-kb/analysis/boundary-conditions/` |
| Load cases | ❌ **Not implemented** — requires ` .sim` XML parser (8-12h dev) | Manual documentation in ` 02-kb/analysis/loads/` |
| Baseline FEA results | ✅ **Fully automatic** (pyNastran ` .op2` parsing) | N/A |
| Design variable candidates | ✅ **Fully automatic** (expression analysis + confidence scoring) | N/A |
**Total implementation effort for missing extractors:** 22-34 hours
### Amendment 4: Section 6.1 (Study Lifecycle)
**Replace §6.1 lifecycle diagram with:**
` ``
PLAN → CONFIGURE → VALIDATE → RUN → MONITOR → ANALYZE → REPORT → FEED-BACK
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ └─ Update KB (OP_LAC)
│ │ │ │ │ │ └─ Generate STUDY_REPORT.md (OP_08)
│ │ │ │ │ └─ Post-process, visualize (OP_04)
│ │ │ │ └─ Real-time tracking (OP_03)
│ │ │ └─ Execute trials (OP_02)
│ │ └─ Preflight checks (OP_01)
│ └─ Write atomizer_spec.json
└─ Formulate hypothesis from previous study
Optional branches:
RUN ──→ EXPORT ──→ Train neural surrogate (OP_05)
Any stage ──→ TROUBLESHOOT ──→ Fix + resume (OP_06)
` ``
### Amendment 5: Section 4.1 (DECISIONS.md vs .atomizer/project.json)
**Add clarification:**
> **Note on ` .atomizer/project.json`:**
> This file is **auto-generated** from study specs and ` PROJECT.md` frontmatter. Do NOT hand-edit. If you need to update project metadata, edit ` PROJECT.md` frontmatter and regenerate via:
> ` ``bash
> atomizer project refresh-metadata
> ` ``
---
## Compatibility Assessment Matrix
| Component | Works As-Is | Needs Code | Needs Doc | Priority |
|-----------|------------|-----------|-----------|----------|
| Numbered folders (` 00-context/`, ` 01-models/`) | ✅ | ❌ | ❌ | - |
| ` PROJECT.md` / ` AGENT.md` entry points | ✅ | ❌ | ❌ | - |
| ` DECISIONS.md` format | ✅ | ❌ | ❌ | - |
| ` 02-kb/` structure | ✅ | ❌ | ⚠️ Minor | P1 |
| ` 03-studies/{NN}_{slug}/` naming | ✅ | ❌ | ❌ | - |
| ` atomizer_spec.json` in studies | ✅ | ⚠️ Path resolution | ❌ | **P0** |
| ` 01-models/` model source | ❌ | ✅ Path refactor | ✅ Clarify | **P0** |
| Auto-extraction claims | ❌ | ⚠️ Optional | ✅ Revise | **P0** |
| ` .atomizer/project.json` | ❌ | ✅ Auto-gen | ✅ Note | P1 |
| ` playbooks/` vs protocols | ⚠️ Overlap | ❌ | ✅ Clarify | P2 |
| Study lifecycle stages | ⚠️ Gaps | ❌ | ✅ Amend | P1 |
| ` STUDY_REPORT.md` auto-gen | ⚠️ Partial | ⚠️ Feasibility stats | ❌ | P1 |
**Legend:**
- ✅ Good to go
- ⚠️ Needs attention
- ❌ Blocking issue
---
## Final Verdict
**The Atomizer Project Standard v1.0 is APPROVED with amendments.**
**Technical Feasibility:** ✅ High — Core concepts are sound
**Implementation Complexity:** ⚠️ Medium — Requires 4-7 hours of core changes + 10-16 hours of improvements
**Backward Compatibility:** ✅ Maintainable — Can support both legacy and project-standard layouts
**Documentation Quality:** ✅ Excellent — Well-researched and thorough
**Auto-Extraction Claims:** ⚠️ Overstated — Revise to reflect current capabilities
**Recommended Action:**
1. Apply P0 amendments (path compatibility, auto-extraction reality check) → **Spec v1.1**
2. Implement P0 code changes (4-7 hours)
3. Test with Hydrotech Beam migration
4. Release project-standard template
5. Plan P1/P2 features for future sprints
**Risk Assessment:**
- **Low Risk:** Entry point design (` PROJECT.md`, ` AGENT.md`), KB structure, naming conventions
- **Medium Risk:** Path refactoring (backward compat required), schema redundancy (sync issues)
- **High Risk:** Auto-extraction promises (user disappointment if not delivered)
**Mitigation: ** Adopt hybrid mode (support both layouts), phase auto-extraction, clear documentation of what's automatic vs manual.
---
* End of Technical Review *
**Next Steps: ** Deliver to Manager for CEO review integration.
