Atomizer/DEVELOPMENT_GUIDANCE.md

Atomizer Development Guidance

Living Document: Strategic direction, current status, and development priorities for Atomizer

Last Updated: 2025-11-17

Status: Alpha Development - 75-85% Complete, Integration Phase

---

Table of Contents

1. Executive Summary
2. Comprehensive Status Report
3. Development Strategy
4. Priority Initiatives
5. Foundation for Future
6. Technical Roadmap

---

Executive Summary

Current State

Status: Alpha Development - Significant Progress Made ✅ Readiness: Foundation solid, LLM features partially implemented, ready for integration phase Direction: ✅ Aligned with roadmap vision - moving toward LLM-native optimization platform

Quick Stats

• 110 Python files (~9,127 lines in core engine alone)
• 23 test files covering major components
• Phase 1 (Plugin System): ✅ 100% Complete & Production Ready
• Phases 2.5-3.1 (LLM Intelligence): ✅ 85% Complete - Components Built, Integration Needed
• Working Example Study: Bracket displacement optimization with substudy system

Key Insight

You've built more than the documentation suggests! The roadmap says "Phase 2: 0% Complete" but you've actually built sophisticated LLM components through Phase 3.1 (85% complete). The challenge now is integration, not development.

---

Comprehensive Status Report

🎯 What's Actually Working (Production Ready)

✅ Core Optimization Engine

Status: FULLY FUNCTIONAL

The foundation is rock solid:

• Optuna Integration: TPE, CMA-ES, GP samplers operational
• NX Solver Integration: Journal-based parameter updates and simulation execution
• OP2 Result Extraction: Stress and displacement extractors tested on real files
• Study Management: Complete folder structure with resume capability
• Precision Control: 4-decimal rounding for engineering units

Evidence:

• studies/bracket_displacement_maximizing/ has real optimization results
• 20 trials successfully completed with live history tracking
• Results: max_displacement: 0.611mm at trial 1, converging to 0.201mm at trial 20

✅ Plugin System (Phase 1)

Status: PRODUCTION READY

This is exemplary architecture:

• Hook Manager: Priority-based execution at 7 lifecycle points
  • pre_solve, post_solve, post_extraction, post_calculation, etc.
• Auto-discovery: Plugins load automatically from directories
• Context Passing: Full trial data available to hooks
• Logging Infrastructure:
  • Per-trial detailed logs (trial_logs/)
  • High-level optimization log (optimization.log)
  • Clean, parseable format

Evidence: Hook system tested in test_hooks_with_bracket.py - all passing ✅

✅ Substudy System

Status: WORKING & ELEGANT

NX-like hierarchical studies:

• Shared models, independent configurations
• Continuation support (fine-tuning builds on coarse exploration)
• Live incremental history tracking
• Clean separation of concerns

File: studies/bracket_displacement_maximizing/run_substudy.py

🚧 What's Built But Not Yet Integrated

🟡 Phase 2.5-3.1: LLM Intelligence Components

Status: 85% Complete - Individual Modules Working, Integration Pending

These are sophisticated, well-designed modules that are 90% ready but not yet connected to the main optimization loop:

✅ Built & Tested:

1. LLM Workflow Analyzer (llm_workflow_analyzer.py - 14.5KB)

   • Uses Claude API to analyze natural language optimization requests
   • Outputs structured JSON with engineering_features, inline_calculations, post_processing_hooks
   • Status: Fully functional standalone

2. Extractor Orchestrator (extractor_orchestrator.py - 12.7KB)

   • Processes LLM output and generates OP2 extractors
   • Dynamic loading and execution
   • Test: test_phase_3_1_integration.py - PASSING ✅
   • Evidence: Generated 3 working extractors in result_extractors/generated/

3. pyNastran Research Agent (pynastran_research_agent.py - 13.3KB)

   • Uses WebFetch to learn pyNastran API patterns
   • Knowledge base system stores learned patterns
   • 3 core extraction patterns: displacement, stress, force
   • Test: test_complete_research_workflow.py - PASSING ✅

4. Hook Generator (hook_generator.py - 27.8KB)

   • Auto-generates post-processing hook scripts
   • Weighted objectives, custom formulas, constraints, comparisons
   • Complete JSON I/O handling
   • Evidence: 4 working hooks in plugins/post_calculation/

5. Inline Code Generator (inline_code_generator.py - 17KB)

   • Generates Python code for simple math operations
   • Normalization, averaging, min/max calculations

6. Codebase Analyzer & Capability Matcher (Phase 2.5)

   • Scans existing code to detect gaps before requesting examples
   • 80-90% accuracy on complex optimization requests
   • Test: test_phase_2_5_intelligent_gap_detection.py - PASSING ✅

🟡 What's Missing:

Integration into main runner! The components exist but aren't connected to runner.py:

# Current runner.py (Line 29-76):
class OptimizationRunner:
    def __init__(self, config_path, model_updater, simulation_runner, result_extractors):
        # Uses MANUAL config.json
        # Uses MANUAL result_extractors dict
        # No LLM workflow integration ❌

New LLMOptimizationRunner exists (llm_optimization_runner.py) but:

• Not used in any production study
• Not tested end-to-end with real NX solves
• Missing integration with run_optimization.py scripts

📊 Architecture Assessment

🟢 Strengths

1. Clean Separation of Concerns

   • Each phase is a self-contained module
   • Dependencies flow in one direction (no circular imports)
   • Easy to test components independently

2. Excellent Documentation

   • Session summaries for each phase (docs/SESSION_SUMMARY_PHASE_*.md)
   • Comprehensive roadmap (DEVELOPMENT_ROADMAP.md)
   • Inline docstrings with examples

3. Feature Registry (feature_registry.json - 35KB)

   • Well-structured capability catalog
   • Each feature has: implementation, interface, usage examples, metadata
   • Perfect foundation for LLM navigation

4. Knowledge Base System

   • Research sessions stored with rationale
   • 9 markdown files documenting learned patterns
   • Enables "learn once, use forever" approach

5. Test Coverage

   • 23 test files covering major components
   • Tests for individual phases (2.5, 2.9, 3.1)
   • Integration tests passing

🟡 Areas for Improvement

1. Integration Gap

   • Critical: LLM components not connected to main runner
   • Two parallel runners exist (runner.py vs llm_optimization_runner.py)
   • Production studies still use manual JSON config

2. Documentation Drift

   • README.md says "Phase 2" is next priority
   • But Phases 2.5-3.1 are actually 85% complete
   • DEVELOPMENT.md shows "Phase 2: 0% Complete" - INCORRECT

3. Test vs Production Gap

   • LLM features tested in isolation
   • No end-to-end test: Natural language → LLM → Generated code → Real NX solve → Results
   • test_bracket_llm_runner.py exists but may not cover full pipeline

4. User Experience

   • No simple way to run LLM-enhanced optimization yet
   • User must manually edit JSON configs (old workflow)
   • Natural language interface exists but not exposed

5. Code Duplication Risk

   • runner.py and llm_optimization_runner.py share similar structure
   • Could consolidate into single runner with "LLM mode" flag

🎯 Gap Analysis: What's Missing for Complete Vision

Critical Gaps (Must-Have)

1. Phase 3.2: Runner Integration ⚠️

   • Connect LLMOptimizationRunner to production workflows
   • Update run_optimization.py to support both manual and LLM modes
   • End-to-end test: Natural language → Actual NX solve → Results

2. User-Facing Interface

   • CLI command: atomizer optimize --llm "minimize stress on bracket"
   • Or: Interactive session like examples/interactive_research_session.py
   • Currently: No easy way for users to leverage LLM features

3. Error Handling & Recovery

   • What happens if generated extractor fails?
   • Fallback to manual extractors?
   • User feedback loop for corrections?

Important Gaps (Should-Have)

1. Dashboard Integration

   • Dashboard exists (dashboard/) but may not show LLM-generated components
   • No visualization of generated code
   • No "LLM mode" toggle in UI

2. Performance Optimization

   • LLM calls in optimization loop could be slow
   • Caching for repeated patterns?
   • Batch code generation before optimization starts?

3. Validation & Safety

   • Generated code execution sandboxing?
   • Code review before running?
   • Unit tests for generated extractors?

Nice-to-Have Gaps

1. Phase 4: Advanced Code Generation

   • Complex FEA features (topology optimization, multi-physics)
   • NXOpen journal script generation

2. Phase 5: Analysis & Decision Support

   • Surrogate quality assessment (R², CV scores)
   • Sensitivity analysis
   • Engineering recommendations

3. Phase 6: Automated Reporting

   • HTML/PDF report generation
   • LLM-written narrative insights

🔍 Code Quality Assessment

Excellent:

• Modularity: Each component is self-contained (can be imported independently)
• Type Hints: Extensive use of Dict[str, Any], Path, Optional[...]
• Error Messages: Clear, actionable error messages
• Logging: Comprehensive logging at appropriate levels

Good:

• Naming: Clear, descriptive function/variable names
• Documentation: Most functions have docstrings with examples
• Testing: Core components have tests

Could Improve:

• Consolidation: Some code duplication between runners
• Configuration Validation: Some JSON configs lack schema validation
• Async Operations: No async/await for potential concurrency
• Type Checking: Not using mypy or similar (no mypy.ini found)

---

Development Strategy

Current Approach: Claude Code + Manual Development

Strategic Decision: We are NOT integrating LLM API calls into Atomizer right now for development purposes.

Why This Makes Sense:

1. Use What Works: Claude Code (your subscription) is already providing LLM assistance for development
2. Avoid Premature Optimization: Don't block on LLM API integration when you can develop without it
3. Focus on Foundation: Build the architecture first, add LLM API later
4. Keep Options Open: Architecture supports LLM API, but doesn't require it for development

Future LLM Integration Strategy:

• Near-term: Maybe test simple use cases to validate API integration works
• Medium-term: Integrate LLM API for production user features (not dev workflow)
• Long-term: Fully LLM-native optimization workflow for end users

Bottom Line: Continue using Claude Code for Atomizer development. LLM API integration is a "later" feature, not a blocker.

---

Priority Initiatives

🎯 TOP PRIORITY: Phase 3.2 Integration (2-4 Weeks)

Goal: Make LLM features actually usable in production

Critical: PAUSE new feature development. Focus 100% on connecting what you have.

Week 1-2: Integration Sprint

Day 1-3: Integrate LLMOptimizationRunner into run_optimization.py

• Add --llm flag to enable LLM mode
• Add --llm-request argument for natural language input
• Implement fallback to manual extractors if LLM generation fails
• Test with bracket study

Day 4-5: End-to-end validation

• Run full optimization with LLM-generated extractors
• Verify results match manual extractors
• Document any issues
• Create comparison report

Day 6-7: Error handling & polish

• Add graceful fallbacks for failed generation
• Improve error messages
• Add progress indicators
• Performance profiling

Week 3: Documentation & Examples

• Update DEVELOPMENT.md to show Phases 2.5-3.1 as 85% complete
• Update README.md to highlight LLM capabilities (currently underselling!)
• Add "Quick Start with LLM" section
• Create examples/llm_optimization_example.py with full workflow
• Write troubleshooting guide for LLM mode
• Create video/GIF demo for README

Week 4: User Testing & Refinement

• Internal testing with real use cases
• Gather feedback on LLM vs manual workflows
• Refine based on findings
• Performance optimization if needed

Expected Outcome: Users can run:

python run_optimization.py --llm "maximize displacement, ensure safety factor > 4"

🔬 HIGH PRIORITY: NXOpen Documentation Access

Goal: Enable LLM to reference NXOpen documentation when developing Atomizer features and generating NXOpen code

Options to Investigate:

1. Authenticated Web Fetching

   • Can we login to Siemens documentation portal?
   • Can WebFetch tool use authenticated sessions?
   • Explore Siemens PLM API access

2. Documentation Scraping

   • Ethical/legal considerations
   • Caching locally for offline use
   • Structured extraction of API signatures

3. Official API Access

   • Does Siemens provide API documentation in structured format?
   • JSON/XML schema files?
   • OpenAPI/Swagger specs?

4. Community Resources

   • TheScriptingEngineer blog content
   • NXOpen examples repository
   • Community-contributed documentation

Research Tasks:

• Investigate Siemens documentation portal login mechanism
• Test WebFetch with authentication headers
• Explore Siemens PLM API documentation access
• Review legal/ethical considerations for documentation access
• Create proof-of-concept: LLM + NXOpen docs → Generated code

Success Criteria: LLM can fetch NXOpen documentation on-demand when writing code

🔧 MEDIUM PRIORITY: NXOpen Intellisense Integration

Goal: Investigate if NXOpen Python stub files can improve Atomizer development workflow

Background:

From NX2406 onwards, Siemens provides stub files for Python intellisense:

• Location: UGII_BASE_DIR\ugopen\pythonStubs
• Purpose: Enable code completion, parameter info, member lists for NXOpen objects
• Integration: Works with VSCode Pylance extension

TheScriptingEngineer's Configuration:

// settings.json
"python.analysis.typeCheckingMode": "basic",
"python.analysis.stubPath": "path_to_NX/ugopen/pythonStubs/Release2023/"

Questions to Answer:

1. Development Workflow:

   • Does this improve Atomizer development speed?
   • Can Claude Code leverage intellisense information?
   • Does it reduce NXOpen API lookup time?

2. Code Generation:

   • Can generated code use these stubs for validation?
   • Can we type-check generated NXOpen scripts before execution?
   • Does it catch errors earlier?

3. Integration Points:

   • Should this be part of Atomizer setup process?
   • Can we distribute stubs with Atomizer?
   • Legal considerations for redistribution?

Implementation Plan:

• Locate stub files in NX2412 installation
• Configure VSCode with stub path
• Test intellisense with sample NXOpen code
• Evaluate impact on development workflow
• Document setup process for contributors
• Decide: Include in Atomizer or document as optional enhancement?

Success Criteria: Developers have working intellisense for NXOpen APIs

---

Foundation for Future

🏗️ Engineering Feature Documentation Pipeline

Purpose: Establish rigorous validation process for LLM-generated engineering features

Important: This is NOT for current software development. This is the foundation for future user-generated features.

Vision:

When a user asks Atomizer to create a new FEA feature (e.g., "calculate buckling safety factor"), the system should:

1. Generate Code: LLM creates the implementation
2. Generate Documentation: Auto-create comprehensive markdown explaining the feature
3. Human Review: Engineer reviews and approves before integration
4. Version Control: Documentation and code committed together

This ensures scientific rigor and traceability for production use.

Auto-Generated Documentation Format:

Each engineering feature should produce a markdown file with these sections:

# Feature Name: [e.g., Buckling Safety Factor Calculator]

## Goal
What problem does this feature solve?
- Engineering context
- Use cases
- Expected outcomes

## Engineering Rationale
Why this approach?
- Design decisions
- Alternative approaches considered
- Why this method was chosen

## Mathematical Foundation

### Equations
\```
σ_buckling = (π² × E × I) / (K × L)²
Safety Factor = σ_buckling / σ_applied
\```

### Sources
- Euler Buckling Theory (1744)
- AISC Steel Construction Manual, 15th Edition, Chapter E
- Timoshenko & Gere, "Theory of Elastic Stability" (1961)

### Assumptions & Limitations
- Elastic buckling only
- Slender columns (L/r > 100)
- Perfect geometry assumed
- Material isotropy

## Implementation

### Code Structure
\```python
def calculate_buckling_safety_factor(
    youngs_modulus: float,
    moment_of_inertia: float,
    effective_length: float,
    applied_stress: float,
    k_factor: float = 1.0
) -> float:
    """
    Calculate buckling safety factor using Euler formula.

    Parameters:
    ...
    """
\```

### Input Validation
- Positive values required
- Units: Pa, m⁴, m, Pa
- K-factor range: 0.5 to 2.0

### Error Handling
- Division by zero checks
- Physical validity checks
- Numerical stability considerations

## Testing & Validation

### Unit Tests
\```python
def test_euler_buckling_simple_case():
    # Steel column: E=200GPa, I=1e-6m⁴, L=3m, σ=100MPa
    sf = calculate_buckling_safety_factor(200e9, 1e-6, 3.0, 100e6)
    assert 2.0 < sf < 2.5  # Expected range
\```

### Validation Cases
1. **Benchmark Case 1**: AISC Manual Example 3.1 (page 45)
   - Input: [values]
   - Expected: [result]
   - Actual: [result]
   - Error: [%]

2. **Benchmark Case 2**: Timoshenko Example 2.3
   - ...

### Edge Cases Tested
- Very short columns (L/r < 50) - should warn/fail
- Very long columns - numerical stability
- Zero/negative inputs - should error gracefully

## Approval

- **Author**: [LLM Generated | Engineer Name]
- **Reviewer**: [Engineer Name]
- **Date Reviewed**: [YYYY-MM-DD]
- **Status**: [Pending | Approved | Rejected]
- **Notes**: [Reviewer comments]

## References

1. Euler, L. (1744). "Methodus inveniendi lineas curvas maximi minimive proprietate gaudentes"
2. American Institute of Steel Construction (2016). *Steel Construction Manual*, 15th Edition
3. Timoshenko, S.P. & Gere, J.M. (1961). *Theory of Elastic Stability*, 2nd Edition, McGraw-Hill

## Change Log

- **v1.0** (2025-11-17): Initial implementation
- **v1.1** (2025-11-20): Added K-factor validation per reviewer feedback

Implementation Requirements:

1. Template System:

   • Markdown template for each feature type
   • Auto-fill sections where possible
   • Highlight sections requiring human input

2. Generation Pipeline:

   User Request → LLM Analysis → Code Generation → Documentation Generation → Human Review → Approval → Integration
   

3. Storage Structure:

   atomizer/
   ├── engineering_features/
   │   ├── approved/
   │   │   ├── buckling_safety_factor/
   │   │   │   ├── implementation.py
   │   │   │   ├── tests.py
   │   │   │   └── FEATURE_DOCS.md
   │   │   └── ...
   │   └── pending_review/
   │       └── ...
   

4. Validation Checklist:

   • Equations match cited sources
   • Units are documented and validated
   • Edge cases are tested
   • Physical validity checks exist
   • Benchmarks pass within tolerance
   • Code matches documentation
   • References are credible and accessible

Who Uses This:

• NOT YOU (current development): You're building Atomizer's software foundation - different process
• FUTURE USERS: When users ask Atomizer to create custom FEA features
• PRODUCTION DEPLOYMENTS: Where engineering rigor and traceability matter

Development Now vs Foundation for Future:

Aspect	Development Now	Foundation for Future
Scope	Building Atomizer software	User-generated FEA features
Process	Agile, iterate fast	Rigorous validation pipeline
Documentation	Code comments, dev docs	Full engineering documentation
Review	You approve	Human engineer approves
Testing	Unit tests, integration tests	Benchmark validation required
Speed	Move fast	Move carefully

Bottom Line: Build the framework now, but don't use it yourself yet. It's for future credibility and production use.

🔐 Validation Pipeline Framework

Goal: Define the structure for rigorous validation of LLM-generated scientific tools

Pipeline Stages:

graph LR
    A[User Request] --> B[LLM Analysis]
    B --> C[Code Generation]
    C --> D[Documentation Generation]
    D --> E[Automated Tests]
    E --> F{Tests Pass?}
    F -->|No| G[Feedback Loop]
    G --> C
    F -->|Yes| H[Human Review Queue]
    H --> I{Approved?}
    I -->|No| J[Reject with Feedback]
    J --> G
    I -->|Yes| K[Integration]
    K --> L[Production Ready]

Components to Build:

1. Request Parser:

   • Natural language → Structured requirements
   • Identify required equations/standards
   • Classify feature type (stress, displacement, buckling, etc.)

2. Code Generator with Documentation:

   • Generate implementation code
   • Generate test cases
   • Generate markdown documentation
   • Link code ↔ docs bidirectionally

3. Automated Validation:

   • Run unit tests
   • Check benchmark cases
   • Validate equation implementations
   • Verify units consistency

4. Review Queue System:

   • Pending features awaiting approval
   • Review interface (CLI or web)
   • Approval/rejection workflow
   • Feedback mechanism to LLM

5. Integration Manager:

   • Move approved features to production
   • Update feature registry
   • Generate release notes
   • Version control integration

Current Status:

• Request parser - Not started
• Code generator with docs - Partially exists (hook_generator, extractor_orchestrator)
• Automated validation - Basic tests exist, need benchmark framework
• Review queue - Not started
• Integration manager - Not started

Priority: Build the structure and interfaces now, implement validation logic later.

Example Workflow (Future):

# User creates custom feature
$ atomizer create-feature --request "Calculate von Mises stress safety factor using Tresca criterion"

[LLM Analysis]
✓ Identified: Stress-based safety factor
✓ Standards: Tresca yield criterion
✓ Required inputs: stress_tensor, yield_strength
✓ Generating code...

[Code Generation]
✓ Created: engineering_features/pending_review/tresca_safety_factor/
  - implementation.py
  - tests.py
  - FEATURE_DOCS.md

[Automated Tests]
✓ Unit tests: 5/5 passed
✓ Benchmark cases: 3/3 passed
✓ Edge cases: 4/4 passed

[Status]
🟡 Pending human review
📋 Review with: atomizer review tresca_safety_factor

# Engineer reviews
$ atomizer review tresca_safety_factor

[Review Interface]
Feature: Tresca Safety Factor Calculator
Status: Automated tests PASSED

Documentation Preview:
[shows FEATURE_DOCS.md]

Code Preview:
[shows implementation.py]

Test Results:
[shows test output]

Approve? [y/N]: y
Review Notes: Looks good, equations match standard

[Approval]
✓ Feature approved
✓ Integrated into feature registry
✓ Available for use

# Now users can use it
$ atomizer optimize --objective "maximize displacement" --constraint "tresca_sf > 2.0"

This is the vision. Build the foundation now for future implementation.

---

Technical Roadmap

Revised Phase Timeline

Phase	Status	Description	Priority
Phase 1	✅ 100%	Plugin System	Complete
Phase 2.5	✅ 85%	Intelligent Gap Detection	Built, needs integration
Phase 2.6	✅ 85%	Workflow Decomposition	Built, needs integration
Phase 2.7	✅ 85%	Step Classification	Built, needs integration
Phase 2.9	✅ 85%	Hook Generation	Built, tested
Phase 3.0	✅ 85%	Research Agent	Built, tested
Phase 3.1	✅ 85%	Extractor Orchestration	Built, tested
Phase 3.2	🎯 0%	Runner Integration	TOP PRIORITY
Phase 3.3	🟡 50%	Optimization Setup Wizard	Partially built
Phase 3.4	🔵 0%	NXOpen Documentation Integration	Research phase
Phase 3.5	🔵 0%	Engineering Feature Pipeline	Foundation design
Phase 4+	🔵 0%	Advanced Features	Paused until 3.2 complete

Immediate Next Steps (Next 2 Weeks)

Week 1: Integration & Testing

Monday-Tuesday: Runner Integration

• Add --llm flag to run_optimization.py
• Connect LLMOptimizationRunner to production workflow
• Implement fallback to manual mode
• Test with bracket study

Wednesday-Thursday: End-to-End Testing

• Run complete LLM workflow: Request → Code → Solve → Results
• Compare LLM-generated vs manual extractors
• Performance profiling
• Fix any integration bugs

Friday: Polish & Documentation

• Improve error messages
• Add progress indicators
• Create example script
• Update inline documentation

Week 2: NXOpen Documentation Research

Monday-Tuesday: Investigation

• Research Siemens documentation portal
• Test authenticated WebFetch
• Explore PLM API access
• Review legal considerations

Wednesday: Intellisense Setup

• Locate NX2412 stub files
• Configure VSCode with Pylance
• Test intellisense with NXOpen code
• Document setup process

Thursday-Friday: Documentation Updates

• Update README.md with LLM capabilities
• Update DEVELOPMENT.md with accurate status
• Create NXOPEN_INTEGRATION.md guide
• Update this guidance document

Medium-Term Goals (1-3 Months)

1. Phase 3.4: NXOpen Documentation Integration

   • Implement authenticated documentation access
   • Create NXOpen knowledge base
   • Test LLM code generation with docs

2. Phase 3.5: Engineering Feature Pipeline

   • Build documentation template system
   • Create review queue interface
   • Implement validation framework

3. Dashboard Enhancement

   • Add LLM mode toggle
   • Visualize generated code
   • Show approval workflow

4. Performance Optimization

   • LLM response caching
   • Batch code generation
   • Async operations

Long-Term Vision (3-12 Months)

1. Phase 4: Advanced Code Generation

   • Complex FEA feature generation
   • Multi-physics setup automation
   • Topology optimization support

2. Phase 5: Intelligent Analysis

   • Surrogate quality assessment
   • Sensitivity analysis
   • Pareto front optimization

3. Phase 6: Automated Reporting

   • HTML/PDF generation
   • LLM-written insights
   • Executive summaries

4. Production Hardening

   • Security audits
   • Performance optimization
   • Enterprise features

---

Key Principles

Development Philosophy

1. Ship Before Perfecting: Integration is more valuable than new features
2. User Value First: Every feature must solve a real user problem
3. Scientific Rigor: Engineering features require validation and documentation
4. Progressive Enhancement: System works without LLM, better with LLM
5. Learn and Improve: Knowledge base grows with every use

Decision Framework

When prioritizing work, ask:

1. Does this unlock user value? If yes, prioritize
2. Does this require other work first? If yes, do dependencies first
3. Can we test this independently? If no, split into testable pieces
4. Will this create technical debt? If yes, document and plan to address
5. Does this align with long-term vision? If no, reconsider

Quality Standards

For Software Development (Atomizer itself):

• Unit tests for core components
• Integration tests for workflows
• Code review by you (main developer)
• Documentation for contributors
• Move fast, iterate

For Engineering Features (User-generated FEA):

• Comprehensive mathematical documentation
• Benchmark validation required
• Human engineer approval mandatory
• Traceability to standards/papers
• Move carefully, validate thoroughly

---

Success Metrics

Phase 3.2 Success Criteria

• Users can run: python run_optimization.py --llm "maximize displacement"
• End-to-end test passes: Natural language → NX solve → Results
• LLM-generated extractors produce same results as manual extractors
• Error handling works gracefully (fallback to manual mode)
• Documentation updated to reflect LLM capabilities
• Example workflow created and tested

NXOpen Integration Success Criteria

• LLM can fetch NXOpen documentation on-demand
• Generated code references correct NXOpen API methods
• Intellisense working in VSCode for NXOpen development
• Setup documented for contributors
• Legal/ethical review completed

Engineering Feature Pipeline Success Criteria

• Documentation template system implemented
• Example feature with full documentation created
• Review workflow interface built (CLI or web)
• Validation framework structure defined
• At least one feature goes through full pipeline (demo)

---

Communication & Collaboration

Stakeholders

• Antoine Letarte: Main developer, architect, decision maker
• Claude Code: Development assistant for Atomizer software
• Future Contributors: Will follow established patterns and documentation
• Future Users: Will use LLM features for optimization workflows

Documentation Strategy

1. DEVELOPMENT_GUIDANCE.md (this doc): Strategic direction, priorities, status
2. README.md: User-facing introduction, quick start, features
3. DEVELOPMENT.md: Detailed development status, todos, completed work
4. DEVELOPMENT_ROADMAP.md: Long-term vision, phases, future work
5. Session summaries: Detailed records of development sessions

Keep all documents synchronized and consistent.

Review Cadence

• Weekly: Review progress against priorities
• Monthly: Update roadmap and adjust course if needed
• Quarterly: Major strategic reviews and planning

---

Appendix: Quick Reference

File Locations

Core Engine:

• optimization_engine/runner.py - Current production runner
• optimization_engine/llm_optimization_runner.py - LLM-enhanced runner (needs integration)
• optimization_engine/nx_solver.py - NX Simcenter integration
• optimization_engine/nx_updater.py - Parameter update system

LLM Components:

• optimization_engine/llm_workflow_analyzer.py - Natural language parser
• optimization_engine/extractor_orchestrator.py - Extractor generation
• optimization_engine/pynastran_research_agent.py - Documentation learning
• optimization_engine/hook_generator.py - Hook code generation

Studies:

• studies/bracket_displacement_maximizing/ - Working example with substudies
• studies/bracket_displacement_maximizing/run_substudy.py - Substudy runner
• studies/bracket_displacement_maximizing/SUBSTUDIES_README.md - Substudy guide

Tests:

• tests/test_phase_2_5_intelligent_gap_detection.py - Gap detection tests
• tests/test_phase_3_1_integration.py - Extractor orchestration tests
• tests/test_complete_research_workflow.py - Research agent tests

Documentation:

• docs/SESSION_SUMMARY_PHASE_*.md - Development session records
• knowledge_base/ - Learned patterns and research sessions
• feature_registry.json - Complete capability catalog

Common Commands

# Run optimization (current manual mode)
cd studies/bracket_displacement_maximizing
python run_optimization.py

# Run substudy
python run_substudy.py coarse_exploration

# Run tests
python -m pytest tests/test_phase_3_1_integration.py -v

# Start dashboard
python dashboard/start_dashboard.py

Key Contacts & Resources

• Siemens NX Documentation: PLM Portal
• TheScriptingEngineer: Blog
• pyNastran Docs: GitHub
• Optuna Docs: optuna.org

---

Document Maintained By: Antoine Letarte (Main Developer) Last Review: 2025-11-17 Next Review: 2025-11-24