docs: Major documentation overhaul - restructure folders, update tagline, add Getting Started guide

- Restructure docs/ folder (remove numeric prefixes): - 04_USER_GUIDES -> guides/ - 05_API_REFERENCE -> api/ - 06_PHYSICS -> physics/ - 07_DEVELOPMENT -> development/ - 08_ARCHIVE -> archive/ - 09_DIAGRAMS -> diagrams/ - Replace tagline 'Talk, don't click' with 'LLM-driven optimization framework' in 9 files - Create comprehensive docs/GETTING_STARTED.md: - Prerequisites and quick setup - Project structure overview - First study tutorial (Claude or manual) - Dashboard usage guide - Neural acceleration introduction - Rewrite docs/00_INDEX.md with correct paths and modern structure - Archive obsolete files: - 01_PROTOCOLS.md -> archive/historical/01_PROTOCOLS_legacy.md - 03_GETTING_STARTED.md -> archive/historical/ - ATOMIZER_PODCAST_BRIEFING.md -> archive/marketing/ - Update timestamps to 2026-01-20 across all key files - Update .gitignore to exclude docs/generated/ - Version bump: ATOMIZER_CONTEXT v1.8 -> v2.0
2026-01-20 10:03:45 -05:00
parent 37f73cc2be
commit ea437d360e
103 changed files with 8980 additions and 327 deletions
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@@ -0,0 +1,401 @@
+# Getting Started with Atomizer
+
+**Last Updated**: 2026-01-20
+
+This guide walks you through setting up Atomizer and running your first optimization study.
+
+---
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Quick Setup](#quick-setup)
+3. [Project Structure](#project-structure)
+4. [Your First Optimization Study](#your-first-optimization-study)
+5. [Using the Dashboard](#using-the-dashboard)
+6. [Neural Acceleration (Optional)](#neural-acceleration-optional)
+7. [Next Steps](#next-steps)
+
+---
+
+## Prerequisites
+
+### Required Software
+
+| Software | Version | Purpose |
+|----------|---------|---------|
+| **Siemens NX** | 2506+ | CAD/FEA modeling |
+| **NX Nastran** | Included with NX | FEA solver |
+| **Python** | 3.10+ | Core engine |
+| **Anaconda** | Latest | Environment management |
+| **Git** | Latest | Version control |
+
+### Hardware Recommendations
+
+- **RAM**: 16GB minimum, 32GB recommended
+- **Storage**: SSD with 50GB+ free space (FEA files are large)
+- **CPU**: Multi-core for parallel FEA runs
+
+---
+
+## Quick Setup
+
+### 1. Clone the Repository
+
+```bash
+git clone http://192.168.86.50:3000/Antoine/Atomizer.git
+cd Atomizer
+```
+
+### 2. Activate the Conda Environment
+
+The `atomizer` environment is pre-configured with all dependencies.
+
+```bash
+conda activate atomizer
+```
+
+**Important**: Always use this environment. Do not install additional packages.
+
+### 3. Verify Installation
+
+```bash
+# Check Python path
+python --version  # Should show Python 3.10+
+
+# Verify core imports
+python -c "from optimization_engine.core.runner import OptimizationRunner; print('OK')"
+```
+
+### 4. Configure NX Path (if needed)
+
+The default NX installation path is `C:\Program Files\Siemens\NX2506\`. If yours differs, update it in your study's `optimization_config.json`:
+
+```json
+{
+  "nx_settings": {
+    "nx_install_path": "C:\\Program Files\\Siemens\\NX2506"
+  }
+}
+```
+
+---
+
+## Project Structure
+
+```
+Atomizer/
+├── CLAUDE.md                    # AI assistant instructions
+├── README.md                    # Project overview
+├── .claude/                     # LLM configuration
+│   ├── ATOMIZER_CONTEXT.md      # Session context
+│   └── skills/                  # Claude skill modules
+├── optimization_engine/         # Core Python package
+│   ├── core/                    # Optimization runners
+│   ├── extractors/              # Physics extraction (20+)
+│   ├── nx/                      # NX/Nastran integration
+│   ├── gnn/                     # Neural network surrogates
+│   └── study/                   # Study management
+├── atomizer-dashboard/          # Web dashboard
+│   ├── backend/                 # FastAPI server
+│   └── frontend/                # React UI
+├── studies/                     # Your optimization studies
+│   ├── M1_Mirror/               # Mirror studies
+│   ├── Simple_Bracket/          # Bracket studies
+│   └── ...
+├── docs/                        # Documentation
+│   ├── protocols/               # Protocol Operating System
+│   ├── guides/                  # User guides
+│   └── physics/                 # Physics documentation
+└── knowledge_base/              # Learning system (LAC)
+```
+
+---
+
+## Your First Optimization Study
+
+### Option A: Using Claude (Recommended)
+
+The easiest way to create a study is through natural language:
+
+```
+You: "Create a new study to optimize my bracket for minimum mass 
+      with stress under 200 MPa. The model is at C:\Models\bracket.prt"
+
+Claude: [Analyzes model, creates study, generates configuration]
+```
+
+### Option B: Manual Creation
+
+#### Step 1: Create Study Directory
+
+```bash
+# Create study under appropriate geometry type
+mkdir -p studies/Simple_Bracket/my_first_study/1_setup/model
+mkdir -p studies/Simple_Bracket/my_first_study/2_iterations
+mkdir -p studies/Simple_Bracket/my_first_study/3_results
+```
+
+#### Step 2: Copy NX Files
+
+Copy your NX model files to the study:
+- `Model.prt` - Geometry part
+- `Model_fem1.fem` - FEM file
+- `Model_sim1.sim` - Simulation file
+- `Model_fem1_i.prt` - Idealized part (IMPORTANT!)
+
+```bash
+cp /path/to/your/model/* studies/Simple_Bracket/my_first_study/1_setup/model/
+```
+
+#### Step 3: Create Configuration
+
+Create `optimization_config.json` in your study root:
+
+```json
+{
+  "study_name": "my_first_study",
+  "description": "Bracket mass optimization with stress constraint",
+  
+  "design_variables": [
+    {
+      "name": "thickness",
+      "expression_name": "web_thickness",
+      "min": 2.0,
+      "max": 10.0,
+      "initial": 5.0
+    }
+  ],
+  
+  "objectives": [
+    {
+      "name": "mass",
+      "type": "minimize",
+      "extractor": "extract_mass_from_bdf"
+    }
+  ],
+  
+  "constraints": [
+    {
+      "name": "max_stress",
+      "type": "less_than",
+      "value": 200.0,
+      "extractor": "extract_solid_stress",
+      "extractor_args": {"element_type": "ctetra"}
+    }
+  ],
+  
+  "optimization": {
+    "method": "TPE",
+    "n_trials": 50
+  },
+  
+  "nx_settings": {
+    "nx_install_path": "C:\\Program Files\\Siemens\\NX2506",
+    "simulation_timeout_s": 600
+  }
+}
+```
+
+#### Step 4: Run the Optimization
+
+```bash
+cd studies/Simple_Bracket/my_first_study
+python run_optimization.py --start --trials 50
+```
+
+### Understanding the Output
+
+During optimization:
+- **Trial folders** are created in `2_iterations/` (trial_0001, trial_0002, ...)
+- **Results** are logged to `3_results/study.db` (Optuna database)
+- **Progress** is printed to console and logged to `optimization.log`
+
+```
+Trial 15/50: mass=2.34 kg, stress=185.2 MPa [FEASIBLE]
+  Best so far: mass=2.12 kg (trial #12)
+```
+
+---
+
+## Using the Dashboard
+
+### Starting the Dashboard
+
+```bash
+# From project root
+python launch_dashboard.py
+```
+
+This starts:
+- **Backend**: FastAPI at http://localhost:8000
+- **Frontend**: React at http://localhost:3003
+
+### Dashboard Features
+
+| Tab | Purpose |
+|-----|---------|
+| **Home** | Study selection, creation |
+| **Canvas** | Visual study builder (AtomizerSpec v2.0) |
+| **Dashboard** | Real-time monitoring, convergence plots |
+| **Analysis** | Pareto fronts, parallel coordinates |
+| **Insights** | Physics visualizations (Zernike, stress fields) |
+
+### Canvas Builder
+
+The Canvas provides a visual, node-based interface:
+
+1. **Add Model Node** - Select your .sim file
+2. **Add Design Variables** - Link to NX expressions
+3. **Add Extractors** - Choose physics to extract
+4. **Add Objectives** - Define what to optimize
+5. **Connect Nodes** - Create the optimization flow
+6. **Execute** - Generate and run the study
+
+---
+
+## Neural Acceleration (Optional)
+
+For studies with 50+ completed FEA trials, you can train a neural surrogate for 2000x+ speedup.
+
+### When to Use Neural Acceleration
+
+| Scenario | Use Neural? |
+|----------|-------------|
+| < 30 trials needed | No - FEA is fine |
+| 30-100 trials | Maybe - depends on FEA time |
+| > 100 trials | Yes - significant time savings |
+| Exploratory optimization | Yes - explore more designs |
+
+### Training a Surrogate
+
+```bash
+cd studies/M1_Mirror/m1_mirror_adaptive_V15
+
+# Train on existing FEA data
+python -m optimization_engine.gnn.train_zernike_gnn V15 --epochs 200
+```
+
+### Running Turbo Mode
+
+```bash
+# Run 5000 GNN predictions, validate top candidates with FEA
+python run_nn_optimization.py --turbo --nn-trials 5000
+```
+
+### Performance Comparison
+
+| Method | Time per Evaluation | 100 Trials |
+|--------|---------------------|------------|
+| FEA only | 10-30 minutes | 17-50 hours |
+| GNN Turbo | 4.5 milliseconds | ~30 seconds |
+
+---
+
+## Next Steps
+
+### Learn the Protocol System
+
+Atomizer uses a layered protocol system:
+
+| Layer | Location | Purpose |
+|-------|----------|---------|
+| **Operations** | `docs/protocols/operations/` | How to create, run, analyze |
+| **System** | `docs/protocols/system/` | Technical specifications |
+| **Extensions** | `docs/protocols/extensions/` | How to extend Atomizer |
+
+Key protocols to read:
+- **OP_01**: Creating studies
+- **OP_02**: Running optimizations
+- **SYS_12**: Available extractors
+- **SYS_14**: Neural acceleration
+
+### Explore Available Extractors
+
+Atomizer includes 20+ physics extractors:
+
+| Category | Examples |
+|----------|----------|
+| **Mechanical** | Displacement, stress, strain energy |
+| **Modal** | Frequency, mode shapes |
+| **Thermal** | Temperature, heat flux |
+| **Mass** | BDF mass, CAD mass |
+| **Optical** | Zernike wavefront error |
+
+Full catalog: `docs/protocols/system/SYS_12_EXTRACTOR_LIBRARY.md`
+
+### Use Claude for Complex Tasks
+
+For complex optimizations, describe your goals naturally:
+
+```
+"Set up a multi-objective optimization for my UAV arm:
+ - Minimize mass
+ - Maximize first natural frequency  
+ - Keep stress under 150 MPa
+ Use NSGA-II with 100 trials"
+```
+
+Claude will:
+1. Analyze your model
+2. Suggest appropriate extractors
+3. Configure the optimization
+4. Generate all necessary files
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| "NX not found" | Check `nx_install_path` in config |
+| "Mesh not updating" | Ensure `*_i.prt` (idealized part) is copied |
+| "Solver timeout" | Increase `simulation_timeout_s` |
+| "Import error" | Verify `conda activate atomizer` |
+
+### Getting Help
+
+1. Check `docs/protocols/operations/OP_06_TROUBLESHOOT.md`
+2. Ask Claude: "Why is my optimization failing?"
+3. Review `3_results/optimization.log`
+
+---
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Activate environment
+conda activate atomizer
+
+# Run optimization
+python run_optimization.py --start --trials 50
+
+# Resume interrupted run
+python run_optimization.py --start --resume
+
+# Test single trial
+python run_optimization.py --test
+
+# Start dashboard
+python launch_dashboard.py
+
+# Check study status
+python -c "from optimization_engine.study.state import get_study_status; print(get_study_status('.'))"
+```
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `optimization_config.json` | Study configuration |
+| `atomizer_spec.json` | AtomizerSpec v2.0 (Canvas) |
+| `run_optimization.py` | FEA optimization script |
+| `3_results/study.db` | Optuna database |
+
+---
+
+*Ready to optimize? Start with a simple study, then explore advanced features like neural acceleration and multi-objective optimization.*