Atomizer/docs/DEV/ARSENAL-DEVELOPMENT-PLAN.md

# Arsenal Development Plan — Atomizer Multi-Solver Integration

> **Status:** DRAFT — pending CEO approval  
> **Date:** 2026-06-25  
> **Authors:** Technical Lead (architecture + feasibility), Auditor (risk + gates), Manager (orchestration)  
> **Source docs:** Arsenal V3 Final, Tool-Agnostic Architecture, Multi-Solver Roadmap, Arsenal Reference  

---

## 1. Executive Summary

**Goal:** Integrate the 80/20 highest-leverage open-source tools from the Atomizer Arsenal into V2, enabling fully scripted optimization without NX GUI dependency.

**What this unlocks:**
- Linux-headless optimization loops (no NX license bottleneck)
- 100s–1000s of trials per campaign (vs. current NX-constrained budgets)
- Multi-solver validation (CalculiX vs Nastran cross-checking)
- Path to CFD and multi-physics (expansion sprints)

**The 80/20 stack (6 sprints):**

| Priority | Tool | Category | Why |
|----------|------|----------|-----|
| 🔴 P1 | CalculiX | FEA solver | Free structural solver, covers 80% of use cases |
| 🔴 P1 | Gmsh | Meshing | Universal mesher, Python API, STEP import |
| 🔴 P1 | Build123d | CAD | Code-native geometry, LLM-perfect, headless |
| 🔴 P1 | meshio + pyNastran | Converters | Format glue between all tools |
| 🔴 P1 | PyVista + ParaView | Post-processing | Automated visualization pipeline |
| 🟡 P2 | pymoo | Optimization | Multi-objective (NSGA-II/III) |
| 🟡 P2 | OpenFOAM | CFD | Thermal/flow screening |
| 🟢 P3 | preCICE | Coupling | Thermo-structural coupling |
| 🟢 P3 | OpenMDAO | MDO | System-level optimization |

**Antoine's time commitment:** ~2–3 hours per sprint for validation gates.  
**HQ autonomous work:** days of implementation per sprint.

---

## 2. Architecture Overview

The Arsenal integrates through Atomizer's 3-layer tool-agnostic architecture:

```
┌─────────────────────────────────────────────────────────┐
│  Layer 3: OPTIMIZATION INTELLIGENCE                      │
│  AtomizerSpec v3.0 │ Optuna/pymoo │ LAC │ LLM Agents    │
│  ── never touches tool-specific formats ──               │
├─────────────────────────────────────────────────────────┤
│  Layer 2: TOOL PROCESSORS (deterministic Python)         │
│  Geometry:  nx_geometry │ build123d_geometry │ step_import│
│  Meshing:   gmsh_mesher │ nx_mesher                      │
│  Solvers:   nastran_solver │ calculix_solver │ openfoam   │
│  Convert:   meshio_converter │ pynastran_bridge          │
│  Post:      pyvista_post │ paraview_post                 │
├─────────────────────────────────────────────────────────┤
│  Layer 1: UNIVERSAL DATA CONTRACTS                       │
│  AtomizerGeometry │ AtomizerMesh │ AtomizerBCs           │
│  AtomizerMaterial │ AtomizerResults                      │
│  ── solver-agnostic dataclasses (the Rosetta Stone) ──  │
└─────────────────────────────────────────────────────────┘
```

**Key rule:** Adding a new tool = writing ONE processor file. Contracts never change per tool.

### 2.1 V2 Repository Target Layout

```
atomizer/
├── contracts/
│   ├── geometry.py              # AtomizerGeometry
│   ├── mesh.py                  # AtomizerMesh
│   ├── boundary_conditions.py   # AtomizerBCs
│   ├── material.py              # AtomizerMaterial
│   ├── results.py               # AtomizerResults
│   └── validators.py            # Cross-contract sanity checks
├── processors/
│   ├── base.py                  # Abstract base classes
│   ├── geometry/
│   │   ├── build123d_geometry.py
│   │   ├── nx_geometry.py
│   │   └── step_import.py
│   ├── meshing/
│   │   ├── gmsh_mesher.py
│   │   └── nx_mesher.py
│   ├── solvers/
│   │   ├── nastran_solver.py
│   │   ├── calculix_solver.py
│   │   └── openfoam_solver.py   # Sprint 4
│   ├── converters/
│   │   ├── meshio_converter.py
│   │   └── pynastran_bridge.py
│   └── postprocessing/
│       ├── pyvista_post.py
│       └── paraview_post.py
├── orchestrator/
│   ├── pipeline.py              # Solver-agnostic run sequencing
│   ├── auto_select.py           # Toolchain routing logic
│   └── coupling.py              # Sprint 5: preCICE
├── optimization/
│   ├── engine.py                # Core optimization loop
│   ├── optuna_backend.py
│   └── pymoo_backend.py         # Sprint 6
└── mcp_servers/                 # Sprint 2-3
    ├── calculix/
    ├── gmsh/
    ├── build123d/
    └── pynastran/
```

---

## 3. Current Environment Assessment

| Item | Status | Action Required |
|------|--------|----------------|
| V2 repo (`atomizer/` package) | ❌ Not yet created — still V1 flat layout | Sprint 0: scaffold package structure |
| pyNastran | ✅ Installed | None |
| CalculiX (ccx) | ❌ Not installed | `apt install calculix-ccx` or Docker |
| Gmsh | ❌ Not installed | `pip install gmsh pygmsh` |
| Build123d | ❌ Not installed | `pip install build123d` |
| meshio | ❌ Not installed | `pip install meshio` |
| PyVista | ❌ Not installed | `pip install pyvista` |
| ParaView/pvpython | ❌ Not installed | `apt install paraview` |
| pymoo | ❌ Not installed | `pip install pymoo` (Sprint 6) |
| OpenFOAM | ❌ Not installed | Docker recommended (Sprint 4) |

**First blocker:** Package installs on T420. Either direct install or Docker-based dev environment.

---

## 4. Sprint Plan

### Sprint 0: Environment + Scaffold (1–2 days)
**Goal:** Working dev environment and V2 package skeleton.

| Task | Owner | Autonomy | Deliverable |
|------|-------|----------|-------------|
| Install core Python packages (gmsh, build123d, meshio, pyvista) | Developer/IT | 🟢 Full | Working imports |
| Install CalculiX (`apt install calculix-ccx`) | Developer/IT | 🟢 Full | `ccx` on PATH |
| Scaffold `atomizer/` package with `__init__.py` stubs | Developer | 🟢 Full | Package importable |
| Create `tests/benchmarks/` with 3 analytical reference cases | Tech Lead | 🟢 Full | JSON expected-value files |

**Analytical benchmarks (known-answer problems):**
1. **Cantilever beam** — tip deflection = PL³/3EI (linear static)
2. **Plate with hole** — SCF ≈ 3.0 at hole edge (stress concentration)
3. **Simply supported beam** — first natural frequency = (π²/L²)√(EI/ρA) (modal)

**Antoine gate:** None — this is infrastructure.

---

### Sprint 1: Contracts + Structural Bridge Baseline (1 week)
**Goal:** Contract-driven NX/Nastran baseline with format conversion verification.

| Task | Owner | Autonomy | Deliverable |
|------|-------|----------|-------------|
| Implement 5 contract dataclasses | Developer | 🟢 95% | `contracts/*.py` with full type hints |
| Implement `validators.py` | Developer | 🟢 95% | Unit-consistent checks, BC physics checks |
| Implement `processors/base.py` abstract classes | Tech Lead → Developer | 🟢 95% | `GeometryProcessor`, `MeshProcessor`, `SolverProcessor` ABCs |
| Wrap existing NX/Nastran into `nastran_solver.py` | NX Expert → Developer | 🟡 70% | Existing workflow through new interface |
| Implement `meshio_converter.py` | Developer | 🟢 95% | BDF ↔ INP ↔ MSH ↔ VTK round-trip |
| Implement `pynastran_bridge.py` | Developer | 🟢 95% | BDF read/modify, OP2 parse → AtomizerResults |
| Implement `pipeline.py` skeleton | Tech Lead → Developer | 🟢 90% | Sequential pipeline runner |
| Unit tests for all contracts + converters | Developer | 🟢 95% | pytest suite passing |

**Success criterion:** Existing NX/Nastran workflow passes through new architecture with zero regression.

**Antoine gate:** Provide 3 trusted benchmark studies with known expected outputs for parity check.

**Risk:** Hidden assumptions in legacy NX/Nastran parsing may break when abstracted.  
**Mitigation:** Run full diff on old vs new output before declaring parity.

---

### Sprint 2: Open Structural Lane — CalculiX + Gmsh + Build123d (1–2 weeks)
**Goal:** Full Linux-headless structural optimization loop with zero NX dependency.

| Task | Owner | Autonomy | Deliverable |
|------|-------|----------|-------------|
| Implement `build123d_geometry.py` | Developer | 🟢 90% | DV dict → Build123d → STEP |
| Implement `step_import.py` | Developer | 🟢 95% | STEP → AtomizerGeometry |
| Implement `gmsh_mesher.py` | Developer | 🟢 90% | STEP → Gmsh → AtomizerMesh (with quality metrics) |
| Implement `calculix_solver.py` | Tech Lead → Developer | 🟡 80% | .inp generation + ccx exec + .frd parsing → AtomizerResults |
| Implement `pyvista_post.py` | Developer | 🟢 95% | AtomizerResults → contour plots (PNG/VTK) |
| Implement `optuna_backend.py` (adapted) | Optimizer → Developer | 🟢 90% | Contract-aware Optuna loop |
| Run 3 analytical benchmarks through full pipeline | Tech Lead | 🟢 90% | Pass/fail report vs known answers |
| CalculiX vs Nastran parity comparison | Tech Lead | 🟡 70% | Delta report on shared benchmark |

**Demo scenario:**
```
Parametric bracket (thickness, fillet_radius, rib_width)
→ Build123d generates STEP
→ Gmsh meshes
→ CalculiX solves (SOL 101 equivalent)
→ PyVista renders stress contour
→ Optuna optimizes for min mass @ stress constraint
→ Full loop on Linux, no NX
```

**Success criteria:**
- [ ] 3 analytical benchmarks pass within 2% of theory
- [ ] CalculiX vs Nastran delta < 5% on stress/displacement for shared benchmark
- [ ] Full optimization loop completes 50+ trials unattended

**Antoine gate:** 
1. Approve CalculiX vs Nastran parity tolerance (proposed: 5% on stress, 3% on displacement)
2. Validate one benchmark result manually
3. Review Build123d geometry quality for representative model

**Risks:**
- Gmsh mesh quality on sharp fillets → **Mitigation:** define mesh size presets, add Jacobian quality check
- CalculiX .frd parsing edge cases → **Mitigation:** test against multiple element types (CQUAD4 equivalent, CHEXA equivalent)
- Build123d geometry failures on complex shapes → **Mitigation:** start with simple parametric bracket, escalate complexity gradually

---

### Sprint 3: MVP Hardening + Client-Grade Post-Processing (1 week)
**Goal:** Production-quality outputs from both solver lanes, side-by-side comparison capability.

| Task | Owner | Autonomy | Deliverable |
|------|-------|----------|-------------|
| Implement `paraview_post.py` | Developer | 🟢 90% | Publication-quality figures (headless pvpython) |
| Implement `auto_select.py` | Tech Lead → Developer | 🟡 75% | Toolchain routing rules (NX lane vs open lane) |
| Implement `spec/validator.py` | Developer | 🟢 95% | AtomizerSpec v3.0 schema validation |
| Dual-lane comparison report | Post-Processor → Developer | 🟢 85% | Side-by-side Nastran vs CalculiX with pass/fail |
| Regression test suite | Auditor → Developer | 🟢 90% | Automated benchmark + parity checks |
| MCP-CalculiX server | MCP Engineer → Developer | 🟡 70% | Tool-call interface for CalculiX |
| MCP-Gmsh server | MCP Engineer → Developer | 🟡 70% | Tool-call interface for Gmsh |
| Documentation: Integration Guide | Secretary | 🟢 95% | `docs/DEV/INTEGRATION-GUIDE.md` |

**Success criteria:**
- [ ] Dual-lane comparison passes on all 3 benchmarks
- [ ] Automated regression suite runs in CI
- [ ] MCP servers pass basic smoke tests

**Antoine gate:**
1. Approve report template and required figure list
2. Define auto-select routing rules (when NX vs when open-source)
3. Sign off MVP as "usable for real studies"

**🏁 MVP EXIT — after Sprint 3, Atomizer can run full structural optimization on Linux without NX.**

---

### Sprint 4: CFD Lane — OpenFOAM (1–2 weeks)
**Goal:** Automated CFD/thermal screening within the same orchestration framework.

| Task | Owner | Autonomy | Deliverable |
|------|-------|----------|-------------|
| Install OpenFOAM (Docker recommended) | IT | 🟢 Full | Working `simpleFoam` / `buoyantSimpleFoam` |
| Implement `openfoam_solver.py` | Tech Lead → Developer | 🟡 65% | Case generation + execution + result parsing |
| Extend `gmsh_mesher.py` with CFD presets | Developer | 🟡 75% | Boundary layer meshing, inflation layers |
| Extend contracts for CFD quantities | Tech Lead → Developer | 🟡 70% | Pressure, velocity, temperature fields in AtomizerResults |
| 2 CFD validation cases | Tech Lead | 🟡 60% | Lid-driven cavity + pipe flow (known analytical/reference) |

**Demo scenario:**
```
Electronics enclosure airflow
→ STEP → Gmsh CFD mesh → OpenFOAM (buoyantSimpleFoam)
→ PyVista thermal map + pressure drop
→ Variant ranking by max temperature
```

**Antoine gate:**
1. Lock one validated starter case template before generalization
2. Define screening-fidelity defaults (mesh size, turbulence model)
3. Validate thermal results against engineering judgment

**Risk:** OpenFOAM setup complexity is high. Dictionary validation is error-prone.  
**Mitigation:** Start with one locked template, generalize only after it works.

---

### Sprint 5: Coupled Thermo-Structural — preCICE (1–2 weeks)
**Goal:** Two-way coupled OpenFOAM ↔ CalculiX simulations.

| Task | Owner | Autonomy | Deliverable |
|------|-------|----------|-------------|
| Install preCICE + adapters | IT | 🟢 Full | preCICE + CalculiX adapter + OpenFOAM adapter |
| Implement `coupling.py` | Tech Lead → Developer | 🟡 60% | Coupled orchestration with convergence monitoring |
| 1 coupled benchmark | Tech Lead | 🔴 50% | Heated plate with thermal expansion |

**Antoine gate:** Approve coupling parameters and convergence criteria.

**Risk:** Coupling divergence, debugging complexity.  
**Mitigation:** Conservative time-step, explicit convergence checks, one golden benchmark.

---

### Sprint 6: Multi-Objective + MDO — pymoo + OpenMDAO (1–2 weeks)
**Goal:** Pareto optimization across multiple objectives and disciplines.

| Task | Owner | Autonomy | Deliverable |
|------|-------|----------|-------------|
| Implement `pymoo_backend.py` | Optimizer → Developer | 🟢 85% | NSGA-II/III alongside Optuna |
| Pareto front visualization | Post-Processor → Developer | 🟢 90% | Interactive Pareto plots |
| OpenMDAO integration (if scope allows) | Tech Lead → Developer | 🟡 60% | MDO wiring for multi-discipline |
| 1 multi-objective demo | Optimizer + Tech Lead | 🟡 70% | Mass vs stress vs temperature Pareto |

**Antoine gate:** Define objective scaling and hard constraints.

---

## 5. Semi-Autonomous Workflow

```
┌─────────────────────────────────────────────────────────┐
│                  PER-SPRINT LOOP                         │
│                                                          │
│  1. Antoine picks sprint / approves scope        [YOU]   │
│  2. HQ researches + designs architecture         [AUTO]  │
│  3. Auditor reviews design for risks             [AUTO]  │
│  4. Antoine approves architecture (15 min)       [YOU]   │
│  5. Developer implements + writes tests          [AUTO]  │
│  6. Auditor reviews code against protocols       [AUTO]  │
│  7. Antoine validates one benchmark (2-3 hrs)    [YOU]   │
│  8. Merge → next sprint                          [AUTO]  │
│                                                          │
│  Your time: ~2-3 hours/sprint                            │
│  HQ time: days of implementation/sprint                  │
└─────────────────────────────────────────────────────────┘
```

**What runs fully autonomously (steps 2-3, 5-6):**
- Research tool capabilities, formats, Python bindings
- Design processor architecture and contract extensions
- Implement Python adapters, parsers, converters
- Write and run unit tests against analytical benchmarks
- Audit code against Atomizer protocols
- Generate regression reports

**What needs your engineering judgment (steps 1, 4, 7):**
- Tool priority sequencing (strategic call)
- Architecture approval (15-min review)
- Cross-solver parity acceptance (is 5% delta OK?)
- Benchmark validation (does this match physics?)
- Geometry quality assessment (does Build123d output look right?)

---

## 6. Quality Gates (Auditor-Defined)

### Per-Processor Gate
- [ ] Processor implements abstract base class correctly
- [ ] Round-trip test: contract → native format → solve → parse → contract
- [ ] At least 1 analytical benchmark passes within tolerance
- [ ] Unit test coverage ≥ 80% for parser logic
- [ ] Error handling for: missing files, solver crash, malformed output
- [ ] Documentation: input/output formats, known limitations

### Per-Sprint Gate
- [ ] All processor gates pass
- [ ] Integration test: full pipeline from AtomizerSpec → results
- [ ] Regression: no existing tests broken
- [ ] Parity check (if applicable): new solver vs reference solver
- [ ] Tech Lead sign-off on physics validity
- [ ] Auditor sign-off on code quality + protocol compliance

### MVP Gate (Sprint 3 Exit)
- [ ] 3 analytical benchmarks pass (cantilever, plate-hole, modal)
- [ ] CalculiX vs Nastran parity < 5% stress, < 3% displacement
- [ ] 50-trial optimization completes unattended
- [ ] Dual-lane comparison report generates automatically
- [ ] Antoine validates one real-world study through the new pipeline
- [ ] All regression tests pass in CI

---

## 7. Risk Register

| # | Risk | Impact | Likelihood | Mitigation | Owner |
|---|------|--------|------------|------------|-------|
| R1 | CalculiX vs Nastran parity exceeds tolerance | High | Medium | Start with simple geometries, document element type mapping, investigate mesh sensitivity | Tech Lead |
| R2 | Gmsh mesh quality on complex geometry | Medium | Medium | Define quality thresholds, add Jacobian/aspect-ratio checks, fallback presets | Tech Lead |
| R3 | Build123d limitations on complex parametric models | Medium | Low | Start simple, escalate complexity, keep NX lane as fallback | Developer |
| R4 | Contract design locks in wrong abstractions | High | Low | Freeze contracts only after Sprint 1 validation, allow minor evolution in Sprint 2 | Tech Lead + Auditor |
| R5 | Package dependency conflicts on T420 | Low | Medium | Use venv or Docker dev environment | IT |
| R6 | OpenFOAM setup complexity delays Sprint 4 | Medium | High | Docker-first approach, one locked template | IT + Tech Lead |
| R7 | Scope creep into expansion tools before MVP stable | High | Medium | Hard gate: no Sprint 4+ work until Sprint 3 exit criteria met | Manager + Auditor |
| R8 | MCP server maintenance burden | Low | Medium | MVP cap at 4 MCP servers, thin wrappers only | MCP Engineer |

---

## 8. Tool Installation Reference

### Sprint 0-2 (Core)
```bash
# Python packages
pip install gmsh pygmsh build123d meshio pyvista

# CalculiX solver
sudo apt install calculix-ccx

# ParaView (Sprint 3)
sudo apt install paraview
```

### Sprint 4+ (Expansion)
```bash
# OpenFOAM via Docker
docker pull openfoam/openfoam-dev

# preCICE
sudo apt install libprecice-dev python3-precice

# pymoo
pip install pymoo

# OpenMDAO
pip install openmdao
```

---

## 9. Success Metrics

| Metric | Sprint 3 Target | Sprint 6 Target |
|--------|----------------|----------------|
| Solver lanes operational | 2 (Nastran + CalculiX) | 4 (+OpenFOAM + coupled) |
| Optimization trials/hr (bracket-class) | 50+ | 100+ |
| Analytical benchmarks passing | 3 | 8+ |
| Cross-solver parity verified | Nastran ↔ CalculiX | + OpenFOAM thermal |
| Automation level (no human in loop) | 70% | 85% |
| MCP servers | 2 (CalculiX, Gmsh) | 4 |

---

## 10. Immediate Next Steps

1. **Antoine:** Approve this plan and Sprint 0-1 scope
2. **IT/Developer:** Run Sprint 0 package installs (est. 1-2 hours)
3. **Tech Lead:** Finalize contract dataclass specs with field-level detail
4. **Developer:** Scaffold `atomizer/` package structure
5. **Auditor:** Prepare benchmark expected-value files for 3 analytical cases
6. **Manager:** Create Mission Dashboard tasks for Sprint 0 + Sprint 1

---

*This plan is a living document. Update after each sprint retrospective.*