Atomizer/docs/development/DEVELOPMENT_GUIDANCE.md

Atomizer Development Guidance

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

Last Updated: 2025-11-17 (Evening - Phase 3.2 Integration Planning Complete)

Status: Alpha Development - 80-90% Complete, Integration Phase

🎯 NOW IN PROGRESS: Phase 3.2 Integration Sprint - Integration Plan

---

Table of Contents

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

---

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 (~10,000+ lines in core engine)
• 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
• Phase 3.3 (Visualization & Cleanup): ✅ 100% Complete & Production Ready
• Study Organization v2.0: ✅ 100% Complete with Templates
• Working Example Study: simple_beam_optimization (4 substudies, 56 trials, full documentation)

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/simple_beam_optimization/ - Complete 4D optimization study
  • 4 substudies (01-04) with numbered organization
  • 56 total trials across all substudies
  • 4 design variables (beam thickness, face thickness, hole diameter, hole count)
  • 3 objectives (displacement, stress, mass) + 1 constraint
  • Full documentation with substudy READMEs
• studies/bracket_displacement_maximizing/ - Earlier study (20 trials)

✅ 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/simple_beam_optimization/run_optimization.py

✅ Phase 3.3: Visualization & Model Cleanup

Status: PRODUCTION READY

Automated post-processing system for optimization results:

• 6 Plot Types:
  • Convergence (objective vs trial with running best)
  • Design space evolution (parameter changes over time)
  • Parallel coordinates (high-dimensional visualization)
  • Sensitivity heatmap (parameter correlation analysis)
  • Constraint violations tracking
  • Multi-objective breakdown
• Output Formats: PNG (300 DPI) + PDF (vector graphics)
• Model Cleanup: Selective deletion of large CAD/FEM files
  • Keeps top-N best trials (default: 10)
  • Preserves all results.json files
  • 50-90% disk space savings typical
• Configuration: JSON-based post_processing section

Evidence:

• Tested on 50-trial beam optimization
• Generated 12 plot files (6 types × 2 formats)
• Plots saved to studies/simple_beam_optimization/2_substudies/04_full_optimization_50trials/plots/
• Documentation: docs/PHASE_3_3_VISUALIZATION_AND_CLEANUP.md

Integration: Runs automatically after optimization completes (if enabled in config)

✅ Study Organization System v2.0

Status: PRODUCTION READY

Standardized directory structure for all optimization studies:

Structure:

studies/[study_name]/
├── 1_setup/              # Pre-optimization (model, benchmarking)
├── 2_substudies/         # Numbered runs (01_, 02_, 03_...)
└── 3_reports/            # Study-level analysis

Features:

• Numbered Substudies: Chronological ordering (01, 02, 03...)
• Self-Documenting: Each substudy has README.md with purpose/results
• Metadata Tracking: study_metadata.json with complete substudy registry
• Templates: Complete templates for new studies and substudies
• Migration Tool: reorganize_study.py for existing studies

Evidence:

• Applied to simple_beam_optimization study
• 4 substudy READMEs documenting progression
• Complete template system in templates/
• How-to guide: templates/HOW_TO_CREATE_A_STUDY.md
• Documentation: docs/STUDY_ORGANIZATION.md

File: studies/simple_beam_optimization/study_metadata.json

🚧 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

🎯 Phase 3.2 Integration Sprint - ACTIVE NOW

Status: 🟢 IN PROGRESS (2025-11-17)

Goal: Connect LLM components to production workflow - make LLM mode accessible

Detailed Plan: See docs/PHASE_3_2_INTEGRATION_PLAN.md

What's Being Built (4-Week Sprint)

Week 1: Make LLM Mode Accessible (16 hours)

• Create unified entry point with --llm flag
• Wire LLMOptimizationRunner to production
• Create minimal working example
• End-to-end integration test

Week 2: Robustness & Safety (16 hours)

• Code validation pipeline (syntax, security, test execution)
• Graceful fallback mechanisms
• LLM audit trail for transparency
• Failure scenario testing

Week 3: Learning System (12 hours)

• Knowledge base implementation
• Template extraction and reuse
• ResearchAgent integration

Week 4: Documentation & Discoverability (8 hours)

• Update README with LLM capabilities
• Create docs/LLM_MODE.md
• Demo video/GIF
• Update all planning docs

Success Metrics

• Natural language request → Optimization results (single command)
• Generated code validated before execution (no crashes)
• Successful workflows saved and reused (learning system operational)
• Documentation shows LLM mode prominently (users discover it)

Impact

Once complete:

• 100 lines of JSON config → 3 lines of natural language
• Users describe goals → LLM generates code automatically
• System learns from successful workflows → gets faster over time
• Complete audit trail for all LLM decisions

---

🎯 Gap Analysis: What's Missing for Complete Vision

Critical Gaps (Being Addressed in Phase 3.2)

1. Phase 3.2: Runner Integration ✅ IN PROGRESS

   • 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
   • Timeline: Week 1 of Phase 3.2 (2025-11-17 onwards)

2. User-Facing Interface ✅ IN PROGRESS

   • CLI command: python run_optimization.py --llm --request "minimize stress"
   • Dual-mode: LLM or traditional JSON config
   • Timeline: Week 1 of Phase 3.2

3. Error Handling & Recovery ✅ IN PROGRESS

   • Code validation before execution
   • Graceful fallback to manual mode
   • Complete audit trail
   • Timeline: Week 2 of Phase 3.2

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

✅ Phase 3.2 Integration - Framework Complete (2025-11-17)

Status: ✅ 75% Complete - Framework implemented, API integration pending

What's Done:

• ✅ Generic run_optimization.py CLI with --llm flag support
• ✅ Integration with LLMOptimizationRunner for automated extractor/hook generation
• ✅ Argument parsing and validation
• ✅ Comprehensive help message and examples
• ✅ Test suite verifying framework functionality
• ✅ Documentation of hybrid approach (Claude Code → JSON → LLMOptimizationRunner)

Current Limitation:

• ⚠️ LLMWorkflowAnalyzer requires Anthropic API key for natural language parsing
• --llm mode works but needs --api-key argument
• Without API key, use hybrid approach (pre-generated workflow JSON)

Working Approaches:

1. With API Key: --llm "request" --api-key "sk-ant-..."
2. Hybrid (Recommended): Claude Code → workflow JSON → LLMOptimizationRunner
3. Study-Specific: Hardcoded workflow (see bracket study example)

Files:

• optimization_engine/run_optimization.py - Generic CLI runner
• docs/PHASE_3_2_INTEGRATION_STATUS.md - Complete status report
• tests/test_phase_3_2_llm_mode.py - Integration tests

Next Steps (When API integration becomes priority):

• Implement true Claude Code integration in LLMWorkflowAnalyzer
• OR defer until Anthropic API integration is prioritized
• OR continue with hybrid approach (90% of value, 10% of complexity)

Recommendation: ✅ Framework Complete - Proceed to other priorities (NXOpen docs, Engineering pipeline)

🔬 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	✅ 75%	Runner Integration	Framework complete, API integration pending
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

---

Development Standards

Reference Hierarchy for Feature Implementation

When implementing new features or capabilities in Atomizer, follow this prioritized order for consulting documentation and APIs:

Tier 1: Primary References (ALWAYS CHECK FIRST)

These are the authoritative sources that define the actual APIs and behaviors we work with:

1. NXOpen Python Stub Files (C:\Program Files\Siemens\NX2412\UGOPEN\pythonStubs)

   • Why: Exact method signatures, parameter types, return values for all NXOpen APIs
   • When: Writing NX journal scripts, updating part parameters, CAE operations
   • Access: VSCode Pylance intellisense (configured in .vscode/settings.json)
   • Accuracy: ~95% - this is the actual API definition
   • Example: For updating expressions, check NXOpen/Part.pyi → ExpressionCollection class → see FindObject() and EditExpressionWithUnits() methods

2. Existing Atomizer Journals (optimization_engine/*.py, studies/*/)

   • Why: Working, tested code that already solves similar problems
   • When: Before writing new NX integration code
   • Files to Check:
     • optimization_engine/solve_simulation.py - NX journal for running simulations
     • optimization_engine/nx_updater.py - Parameter update patterns
     • Any study-specific journals in studies/*/
   • Pattern: Search for similar functionality first, adapt existing code

3. NXOpen API Patterns in Codebase (optimization_engine/, result_extractors/)

   • Why: Established patterns for NX API usage in Atomizer
   • When: Implementing new NX operations
   • What to Look For:
     • Session management patterns
     • Part update workflows
     • Expression handling
     • Save/load patterns

Tier 2: Specialized References (USE FOR SPECIFIC TASKS)

These are secondary sources for specialized tasks - use ONLY for their specific domains:

1. pyNastran (knowledge_base/, online docs)

   • ONLY FOR: OP2/F06 file post-processing (reading Nastran output files)
   • NOT FOR: NXOpen guidance, simulation setup, parameter updates
   • Why Limited: pyNastran is for reading results, not for NX API integration
   • When to Use: Creating result extractors, reading stress/displacement from OP2 files
   • Example Valid Use: result_extractors/stress_extractor.py - reads OP2 stress data
   • Example INVALID Use: ❌ Don't use pyNastran docs to learn how to update NX part expressions

2. TheScriptingEngineer Blog (https://thescriptingengineer.com)

   • When: Need working examples of NXOpen usage patterns
   • Why: High-quality, practical examples with explanations
   • Best For: Learning NXOpen workflow patterns, discovering API usage
   • Limitation: Blog may use different NX versions, verify against stub files

Tier 3: Last Resort References (USE SPARINGLY)

Use these only when Tier 1 and Tier 2 don't provide answers:

1. Web Search / External Documentation

   • When: Researching new concepts not covered by existing code
   • Caution: Verify information against stub files and existing code
   • Best For: Conceptual understanding, theory, background research

2. Siemens Official Documentation Portal (https://plm.sw.siemens.com)

   • When: Need detailed API documentation beyond stub files
   • Status: Authenticated access under investigation (see NXOpen Integration initiative)
   • Future: May become Tier 1 once integration is complete

Reference Hierarchy Decision Tree

Need to implement NXOpen functionality?
│
├─> Check NXOpen stub files (.pyi) - Do exact methods exist?
│   ├─> YES: Use those method signatures ✅
│   └─> NO: Continue ↓
│
├─> Search existing Atomizer journals - Has this been done before?
│   ├─> YES: Adapt existing code ✅
│   └─> NO: Continue ↓
│
├─> Check TheScriptingEngineer - Are there examples?
│   ├─> YES: Adapt pattern, verify against stub files ✅
│   └─> NO: Continue ↓
│
└─> Web search for concept - Understand theory, then implement using stub files
    └─> ALWAYS verify final code against stub files before using ✅

Need to extract results from OP2/F06?
│
└─> Use pyNastran ✅
    └─> Check knowledge_base/ for existing patterns first

Need to understand FEA theory/equations?
│
└─> Web search / textbooks ✅
    └─> Document sources in feature documentation

Why This Hierarchy Matters

Before (guessing/hallucinating):

# ❌ Guessed API - might not exist or have wrong signature
work_part.Expressions.Edit("tip_thickness", "5.0")  # Wrong method name!

After (checking stub files):

# ✅ Verified against NXOpen/Part.pyi stub file
expr = work_part.Expressions.FindObject("tip_thickness")  # Correct!
work_part.Expressions.EditExpressionWithUnits(expr, unit, "5.0")  # Correct!

Improvement: ~60% accuracy (guessing) → ~95% accuracy (stub files)

NXOpen Integration Status

✅ Completed (2025-11-17):

• NXOpen stub files located and configured in VSCode
• Python 3.11 environment setup for NXOpen compatibility
• NXOpen module import enabled via .pth file
• Intellisense working for all NXOpen APIs
• Documentation: NXOPEN_INTELLISENSE_SETUP.md

🔜 Future Work:

• Authenticated Siemens documentation access (research phase)
• Documentation scraping for LLM knowledge base
• LLM-generated journal scripts with validation

---

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