Atomizer/docs/01_PROTOCOLS.md

# Atomizer Protocol Specifications

**Last Updated**: 2025-11-21
**Status**: Active
**Applies To**: All Atomizer optimization systems

---

## Table of Contents

1. [Introduction](#introduction)
2. [Protocol 10: Intelligent Multi-Strategy Optimization (IMSO)](#protocol-10-intelligent-multi-strategy-optimization-imso)
3. [Protocol 11: Multi-Objective Support](#protocol-11-multi-objective-support)
4. [Protocol 13: Real-Time Dashboard Tracking](#protocol-13-real-time-dashboard-tracking)
5. [Protocol Integration](#protocol-integration)
6. [Quick Reference](#quick-reference)
7. [Documentation Standards and Practices](#documentation-standards-and-practices)

---

## Introduction

This document consolidates all active protocol specifications for the Atomizer optimization platform. Protocols define core architectural patterns, mandatory requirements, and implementation standards that ensure consistency, robustness, and extensibility across the system.

### What is a Protocol?

A **Protocol** in Atomizer is a numbered specification that defines:
- **Architecture**: Core components and their interactions
- **Requirements**: Mandatory behavior and API contracts
- **Implementation**: Reference code and usage patterns
- **Testing**: Validation procedures and success criteria
- **Integration**: How the protocol interacts with other systems

### Protocol Versioning

Protocols follow semantic versioning:
- **Major version** (e.g., Protocol 10 v2.0): Breaking changes or architectural redesign
- **Minor version** (e.g., Protocol 10 v2.1): Bug fixes and improvements
- **Status tags**: ✅ Complete, 🔨 Active Development, 📋 Planned

### Active Protocols

| Protocol | Name | Status | Priority | Version |
|----------|------|--------|----------|---------|
| 10 | Intelligent Multi-Strategy Optimization | ✅ Complete | P0 (Critical) | v2.1 |
| 11 | Multi-Objective Support | ✅ Complete | P0 (Mandatory) | v1.0 |
| 13 | Real-Time Dashboard Tracking | ✅ Complete | P1 (High) | v1.0 |

---

## Protocol 10: Intelligent Multi-Strategy Optimization (IMSO)

**Version**: 2.1
**Status**: ✅ Complete and Production-Ready
**Priority**: P0 (Critical for advanced optimization)

### Overview

Protocol 10 implements intelligent, adaptive optimization that automatically characterizes the problem landscape and selects the best optimization algorithm. This two-phase approach combines automated landscape analysis with algorithm-specific optimization to achieve superior performance compared to fixed-strategy approaches.

**Key Innovation**: Adaptive characterization phase that intelligently determines when enough exploration has been done, then seamlessly transitions to the optimal algorithm.

### Architecture

Protocol 10 uses a **two-study architecture** to overcome Optuna's fixed-sampler limitation:

```
┌─────────────────────────────────────────────────────────────┐
│  PHASE 1: ADAPTIVE CHARACTERIZATION STUDY                   │
│  ─────────────────────────────────────────────────────────  │
│  Sampler: Random/Sobol (unbiased exploration)               │
│  Trials: 10-30 (adapts to problem complexity)               │
│                                                              │
│  Every 5 trials:                                            │
│    → Analyze landscape metrics                              │
│    → Check metric convergence                               │
│    → Calculate characterization confidence                  │
│    → Decide if ready to stop                                │
│                                                              │
│  Stop when:                                                 │
│    ✓ Confidence ≥ 85%                                       │
│    ✓ OR max trials reached (30)                             │
│                                                              │
│  Simple problems (smooth, unimodal):                        │
│    Stop at ~10-15 trials                                    │
│                                                              │
│  Complex problems (multimodal, rugged):                     │
│    Continue to ~20-30 trials                                │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  TRANSITION: LANDSCAPE ANALYSIS & STRATEGY SELECTION        │
│  ─────────────────────────────────────────────────────────  │
│  Analyze final landscape:                                   │
│    - Smoothness (0-1)                                       │
│    - Multimodality (number of modes)                        │
│    - Parameter correlation                                  │
│    - Noise level                                            │
│                                                              │
│  Classify landscape:                                        │
│    → smooth_unimodal                                        │
│    → smooth_multimodal                                      │
│    → rugged_unimodal                                        │
│    → rugged_multimodal                                      │
│    → noisy                                                  │
│                                                              │
│  Recommend strategy:                                        │
│    smooth_unimodal    → GP-BO (best) or CMA-ES             │
│    smooth_multimodal  → GP-BO                               │
│    rugged_multimodal  → TPE                                 │
│    rugged_unimodal    → TPE or CMA-ES                       │
│    noisy              → TPE (most robust)                   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  PHASE 2: OPTIMIZATION STUDY                                │
│  ─────────────────────────────────────────────────────────  │
│  Sampler: Recommended from Phase 1                          │
│  Warm Start: Initialize from best characterization point    │
│  Trials: User-specified (default 50)                        │
│                                                              │
│  Optimizes efficiently using:                               │
│    - Right algorithm for the landscape                      │
│    - Knowledge from characterization phase                  │
│    - Focused exploitation around promising regions          │
└─────────────────────────────────────────────────────────────┘
```

### Core Components

#### 1. Adaptive Characterization (`adaptive_characterization.py`)

**Purpose**: Intelligently determine when sufficient landscape exploration has been performed.

**Confidence Calculation**:
```python
confidence = (
    0.40 * metric_stability_score +      # Are metrics converging?
    0.30 * parameter_coverage_score +    # Explored enough space?
    0.20 * sample_adequacy_score +       # Enough samples for complexity?
    0.10 * landscape_clarity_score       # Clear classification?
)
```

**Stopping Criteria**:
- **Minimum trials**: 10 (baseline data requirement)
- **Maximum trials**: 30 (prevent over-characterization)
- **Confidence threshold**: 85% (high confidence required)
- **Check interval**: Every 5 trials

**Adaptive Behavior**:
```python
# Simple problem (smooth, unimodal, low noise):
if smoothness > 0.6 and unimodal and noise < 0.3:
    required_samples = 10 + dimensionality
    # Stops at ~10-15 trials

# Complex problem (multimodal with N modes):
if multimodal and n_modes > 2:
    required_samples = 10 + 5 * n_modes + 2 * dimensionality
    # Continues to ~20-30 trials
```

#### 2. Landscape Analyzer (`landscape_analyzer.py`)

**Purpose**: Characterize the optimization landscape from trial history.

**Metrics Computed**:

1. **Smoothness** (0-1):
   - Method: Spearman correlation between parameter distance and objective difference
   - High (>0.6): Good for CMA-ES, GP-BO
   - Low (<0.4): Rugged landscape, good for TPE

2. **Multimodality**:
   - Method: DBSCAN clustering on good trials (bottom 30%)
   - Detects multiple distinct regions of good solutions
   - **False positive detection**: 2 modes + high smoothness + low noise → reclassified as unimodal

3. **Parameter Correlation**:
   - Method: Spearman correlation between parameters and objective
   - Identifies influential parameters

4. **Noise Level** (0-1):
   - Method: Local consistency check
   - Wide exploration ≠ noise; only true simulation instability detected

**Landscape Classifications**:
- `smooth_unimodal`: Single smooth bowl → GP-BO or CMA-ES
- `smooth_multimodal`: Multiple smooth regions → GP-BO
- `rugged_unimodal`: Single rugged region → TPE or CMA-ES
- `rugged_multimodal`: Multiple rugged regions → TPE
- `noisy`: High noise level → TPE (robust)

#### 3. Strategy Selector (`strategy_selector.py`)

**Purpose**: Recommend the optimal optimization algorithm based on landscape analysis.

**Algorithm Recommendations**:

| Landscape Type | Primary Strategy | Fallback | Rationale |
|----------------|------------------|----------|-----------|
| smooth_unimodal | GP-BO | CMA-ES | GP models smoothness explicitly |
| smooth_multimodal | GP-BO | TPE | GP handles multiple modes |
| rugged_unimodal | TPE | CMA-ES | TPE robust to ruggedness |
| rugged_multimodal | TPE | - | TPE excellent for complexity |
| noisy | TPE | - | TPE most robust to noise |

**Algorithm Characteristics**:

**GP-BO (Gaussian Process Bayesian Optimization)**:
- ✅ Best for: Smooth, expensive functions (like FEA)
- ✅ Explicit surrogate model with uncertainty quantification
- ✅ Acquisition function balances exploration/exploitation
- ❌ Less effective on highly rugged landscapes

**CMA-ES (Covariance Matrix Adaptation Evolution Strategy)**:
- ✅ Best for: Smooth unimodal problems
- ✅ Fast convergence to local optimum
- ✅ Adapts search distribution to landscape
- ❌ Can get stuck in local minima

**TPE (Tree-structured Parzen Estimator)**:
- ✅ Best for: Multimodal, rugged, or noisy problems
- ✅ Robust to noise and discontinuities
- ✅ Good global exploration
- ❌ Slower convergence on smooth problems

#### 4. Intelligent Optimizer (`intelligent_optimizer.py`)

**Purpose**: Orchestrate the entire Protocol 10 workflow.

**Workflow**:
1. Create characterization study (Random/Sobol sampler)
2. Run adaptive characterization with stopping criterion
3. Analyze final landscape
4. Select optimal strategy
5. Create optimization study with recommended sampler
6. Warm-start from best characterization point
7. Run optimization
8. Generate intelligence report

### Configuration

Add to `optimization_config.json`:

```json
{
  "intelligent_optimization": {
    "enabled": true,
    "characterization": {
      "min_trials": 10,
      "max_trials": 30,
      "confidence_threshold": 0.85,
      "check_interval": 5
    },
    "landscape_analysis": {
      "min_trials_for_analysis": 10
    },
    "strategy_selection": {
      "allow_cmaes": true,
      "allow_gpbo": true,
      "allow_tpe": true
    }
  },
  "trials": {
    "n_trials": 50
  }
}
```

### Usage Example

```python
from optimization_engine.intelligent_optimizer import IntelligentOptimizer

# Create optimizer
optimizer = IntelligentOptimizer(
    study_name="my_optimization",
    study_dir=results_dir,
    config=optimization_config,
    verbose=True
)

# Define design variables
design_vars = {
    'parameter1': (lower_bound, upper_bound),
    'parameter2': (lower_bound, upper_bound)
}

# Run Protocol 10
results = optimizer.optimize(
    objective_function=my_objective,
    design_variables=design_vars,
    n_trials=50,  # For optimization phase
    target_value=target,
    tolerance=0.1
)
```

### Performance Benefits

**Efficiency**:
- **Simple problems**: Early stop at ~10-15 trials (33% reduction)
- **Complex problems**: Extended characterization at ~20-30 trials (adequate coverage)
- **Right algorithm**: Uses optimal strategy for landscape type

**Example Performance** (Circular Plate Frequency Tuning):
- **TPE alone**: ~95 trials to target
- **Random search**: ~150+ trials
- **Protocol 10**: ~56 trials (**41% reduction**)

### Intelligence Reports

Protocol 10 generates comprehensive reports:

1. **Characterization Progress** (`characterization_progress.json`):
   - Metric evolution (smoothness, multimodality, noise)
   - Confidence progression
   - Stopping decision details

2. **Intelligence Report** (`intelligence_report.json`):
   - Final landscape classification
   - Parameter correlations
   - Recommended strategy with rationale

3. **Strategy Transitions** (`strategy_transitions.json`):
   - Phase transitions
   - Algorithm switches
   - Performance metrics

### Version History

**Version 2.1** (2025-11-20):
- Fixed strategy selector timing logic (use characterization trials, not total trials)
- Improved multimodality detection (detect false positives from smooth manifolds)
- Reduced pruning rate from 20% to ~5%

**Version 2.0** (2025-11-20):
- Added adaptive characterization with intelligent stopping
- Implemented two-study architecture
- Fixed noise detection algorithm
- Added GP-BO as primary recommendation for smooth problems

**Version 1.0** (2025-11-19):
- Initial implementation with dynamic strategy switching

### Related Files

- `optimization_engine/intelligent_optimizer.py` - Main orchestrator
- `optimization_engine/adaptive_characterization.py` - Stopping criterion
- `optimization_engine/landscape_analyzer.py` - Landscape metrics
- `optimization_engine/strategy_selector.py` - Algorithm recommendation
- `docs/PROTOCOL_10_V2_IMPLEMENTATION.md` - Detailed implementation notes
- `docs/PROTOCOL_10_V2_FIXES.md` - Bug fixes and improvements

---

## Protocol 11: Multi-Objective Support

**Version**: 1.0
**Status**: ✅ Complete and Mandatory
**Priority**: P0 (MANDATORY for ALL optimization engines)

### Overview

**ALL** optimization engines in Atomizer **MUST** support both single-objective and multi-objective optimization without requiring code changes. This is a **critical requirement** that prevents runtime failures and ensures system robustness.

### The Problem

Previously, optimization components only supported single-objective optimization. When used with multi-objective studies, they would:
1. Successfully run all trials
2. Save trials to the Optuna database
3. **CRASH** when compiling results, causing:
   - No tracking files generated
   - No summary reports
   - Silent failures difficult to debug

### Root Cause

Optuna has different APIs for single vs. multi-objective studies:

**Single-Objective**:
```python
study.best_trial    # Returns single Trial object
study.best_params   # Returns dict of parameters
study.best_value    # Returns float
```

**Multi-Objective**:
```python
study.best_trials   # Returns LIST of Pareto-optimal trials
study.best_params   # ❌ RAISES RuntimeError
study.best_value    # ❌ RAISES RuntimeError
study.best_trial    # ❌ RAISES RuntimeError
```

### Solution

#### 1. Always Check Study Type

```python
is_multi_objective = len(study.directions) > 1
```

#### 2. Use Conditional Access Patterns

```python
if is_multi_objective:
    best_trials = study.best_trials
    if best_trials:
        # Select representative trial (e.g., first Pareto solution)
        representative_trial = best_trials[0]
        best_params = representative_trial.params
        best_value = representative_trial.values  # Tuple
        best_trial_num = representative_trial.number
    else:
        best_params = {}
        best_value = None
        best_trial_num = None
else:
    # Single-objective: safe to use standard API
    best_params = study.best_params
    best_value = study.best_value
    best_trial_num = study.best_trial.number
```

#### 3. Return Rich Metadata

Always include in results:
```python
{
    'best_params': best_params,
    'best_value': best_value,  # float or tuple
    'best_trial': best_trial_num,
    'is_multi_objective': is_multi_objective,
    'pareto_front_size': len(study.best_trials) if is_multi_objective else 1,
    # ... other fields
}
```

### Implementation Checklist

When creating or modifying any optimization component:

- [ ] **Study Creation**: Support `directions` parameter
  ```python
  if directions:
      study = optuna.create_study(directions=directions, ...)
  else:
      study = optuna.create_study(direction='minimize', ...)
  ```

- [ ] **Result Compilation**: Check `len(study.directions) > 1`
- [ ] **Best Trial Access**: Use conditional logic (single vs. multi)
- [ ] **Logging**: Print Pareto front size for multi-objective
- [ ] **Reports**: Handle tuple objectives in visualization
- [ ] **Testing**: Test with BOTH single and multi-objective cases

### Design Principle

**"Write Once, Run Anywhere"**

Any optimization component should:
1. Accept both single and multi-objective problems
2. Automatically detect the study type
3. Handle result compilation appropriately
4. Never raise RuntimeError due to API misuse

### Testing Protocol

Before marking any optimization study as complete:

1. **Single-Objective Test**
   ```python
   directions=None  # or ['minimize']
   # Should complete without errors
   ```

2. **Multi-Objective Test**
   ```python
   directions=['minimize', 'minimize']
   # Should complete without errors
   # Should generate ALL tracking files
   ```

3. **Verify Outputs**
   - `2_results/study.db` exists
   - `2_results/intelligent_optimizer/` has tracking files
   - `2_results/optimization_summary.json` exists
   - No RuntimeError in logs

### Example: Multi-Objective Bracket Study

```json
{
  "objectives": [
    {
      "name": "stiffness",
      "type": "maximize",
      "description": "Structural stiffness (N/mm)"
    },
    {
      "name": "mass",
      "type": "minimize",
      "description": "Total mass (kg)"
    }
  ],
  "constraints": [
    {
      "name": "mass_limit",
      "type": "less_than",
      "value": 0.2
    }
  ]
}
```

This configuration creates a multi-objective study that:
- Finds Pareto-optimal trade-offs between stiffness and mass
- Enforces hard constraint on maximum mass
- Generates Pareto front visualization in dashboard

### Files Fixed

- ✅ `optimization_engine/intelligent_optimizer.py`
  - `_compile_results()` method
  - `_run_fallback_optimization()` method

### Files Requiring Review

Check these files for similar issues:
- [ ] `optimization_engine/study_continuation.py`
- [ ] `optimization_engine/hybrid_study_creator.py`
- [ ] `optimization_engine/intelligent_setup.py`
- [ ] `optimization_engine/llm_optimization_runner.py`

### Related Documentation

- `docs/PROTOCOL_11_MULTI_OBJECTIVE_SUPPORT.md` - Detailed specification
- `docs/FIX_SUMMARY_PROTOCOL_11.md` - Bug fixes

---

## Protocol 13: Real-Time Dashboard Tracking

**Version**: 1.0
**Status**: ✅ Complete and Production-Ready
**Priority**: P1 (High - enhances user experience)

### Overview

Protocol 13 implements a comprehensive real-time web dashboard for monitoring multi-objective optimization studies. It provides live visualization of optimizer state, Pareto fronts, parallel coordinates, and trial history with automatic updates every trial.

### Architecture

```
Trial Completion (Optuna)
         ↓
Realtime Callback (optimization_engine/realtime_tracking.py)
         ↓
Write optimizer_state.json
         ↓
Backend API /optimizer-state endpoint
         ↓
Frontend Components (2s polling)
         ↓
User sees live updates in browser
```

### Backend Components

#### 1. Real-Time Tracking System (`realtime_tracking.py`)

**Purpose**: Write JSON state files after every trial completion.

**Features**:
- Per-trial JSON writes to `optimizer_state.json`
- Captures current phase, strategy, and progress
- Multi-objective study detection
- Minimal overhead (<5ms per trial)

**Data Structure**:
```json
{
  "timestamp": "2025-11-21T15:27:28.828930",
  "trial_number": 29,
  "total_trials": 50,
  "current_phase": "adaptive_optimization",
  "current_strategy": "GP_UCB",
  "is_multi_objective": true,
  "study_directions": ["maximize", "minimize"]
}
```

**Integration** (in `intelligent_optimizer.py`):
```python
from optimization_engine.realtime_tracking import create_realtime_callback

# Create callback
callback = create_realtime_callback(
    tracking_dir=results_dir / "intelligent_optimizer",
    optimizer_ref=self,
    verbose=True
)

# Register with Optuna
study.optimize(objective, n_trials=n_trials, callbacks=[callback])
```

#### 2. REST API Endpoints (`atomizer-dashboard/backend/api/routes/optimization.py`)

**New Protocol 13 Endpoints**:

1. **GET `/api/optimization/studies/{study_id}/metadata`**
   - Returns objectives, design variables, constraints with units
   - Implements unit inference from descriptions
   - Supports Protocol 11 multi-objective format

2. **GET `/api/optimization/studies/{study_id}/optimizer-state`**
   - Returns real-time optimizer state from JSON
   - Shows current phase and strategy
   - Updates every trial

3. **GET `/api/optimization/studies/{study_id}/pareto-front`**
   - Returns Pareto-optimal solutions for multi-objective studies
   - Uses Optuna's `study.best_trials` API
   - Includes constraint satisfaction status

**Unit Inference**:
```python
def _infer_objective_unit(objective: Dict) -> str:
    """Infer unit from objective name and description"""
    name = objective.get("name", "").lower()
    desc = objective.get("description", "").lower()

    # Pattern matching
    if "frequency" in name or "hz" in desc:
        return "Hz"
    elif "stiffness" in name or "n/mm" in desc:
        return "N/mm"
    elif "mass" in name or "kg" in desc:
        return "kg"
    # ... more patterns
```

### Frontend Components

#### 1. OptimizerPanel Component (`components/OptimizerPanel.tsx`)

**Features**:
- Real-time phase display (Characterization, Exploration, Exploitation, Adaptive)
- Current strategy indicator (TPE, GP, NSGA-II, etc.)
- Progress bar with trial count
- Multi-objective study detection
- Auto-refresh every 2 seconds

**Visual Design**:
```
┌─────────────────────────────────┐
│ Intelligent Optimizer Status    │
├─────────────────────────────────┤
│ Phase: [Adaptive Optimization]  │
│ Strategy: [GP_UCB]              │
│ Progress: [████████░░] 29/50    │
│ Multi-Objective: ✓              │
└─────────────────────────────────┘
```

#### 2. ParetoPlot Component (`components/ParetoPlot.tsx`)

**Features**:
- Scatter plot of Pareto-optimal solutions
- Pareto front line connecting optimal points
- **3 Normalization Modes**:
  - **Raw**: Original engineering values
  - **Min-Max**: Scales to [0, 1] for equal comparison
  - **Z-Score**: Standardizes to mean=0, std=1
- Tooltip shows raw values regardless of normalization
- Color-coded feasibility (green=feasible, red=infeasible)
- Dynamic axis labels with units

**Normalization Math**:
```typescript
// Min-Max: (x - min) / (max - min) → [0, 1]
// Z-Score: (x - mean) / std → standardized
```

#### 3. ParallelCoordinatesPlot Component (`components/ParallelCoordinatesPlot.tsx`)

**Features**:
- High-dimensional visualization (objectives + design variables)
- Interactive trial selection (click to toggle, hover to highlight)
- Normalized [0, 1] axes for all dimensions
- Color coding: green (feasible), red (infeasible), yellow (selected)
- Opacity management: non-selected fade to 10% when selection active
- Clear selection button

**Visualization Structure**:
```
Stiffness    Mass    support_angle    tip_thickness
   |          |            |                |
   |    ╱─────╲           ╱                 |
   |   ╱       ╲─────────╱                  |
   |  ╱                  ╲                  |
```

#### 4. Dashboard Layout (`pages/Dashboard.tsx`)

**Structure**:
```
┌──────────────────────────────────────────────────┐
│ Study Selection                                  │
├──────────────────────────────────────────────────┤
│ Metrics Grid (Best, Avg, Trials, Pruned)       │
├──────────────────────────────────────────────────┤
│ [OptimizerPanel]  [ParetoPlot]                  │
├──────────────────────────────────────────────────┤
│ [ParallelCoordinatesPlot - Full Width]          │
├──────────────────────────────────────────────────┤
│ [Convergence]     [Parameter Space]             │
├──────────────────────────────────────────────────┤
│ [Recent Trials Table]                            │
└──────────────────────────────────────────────────┘
```

### Configuration

**Backend** (`atomizer-dashboard/backend`):
```bash
cd atomizer-dashboard/backend
python -m uvicorn api.main:app --reload --port 8000
```

**Frontend** (`atomizer-dashboard/frontend`):
```bash
cd atomizer-dashboard/frontend
npm run dev  # Runs on port 3001
```

**Study Requirements**:
- Must use Protocol 10 (IntelligentOptimizer)
- Must have `optimization_config.json` with objectives and design_variables
- Real-time tracking enabled automatically

### Usage

1. **Start Dashboard**:
   ```bash
   # Terminal 1: Backend
   cd atomizer-dashboard/backend
   python -m uvicorn api.main:app --reload --port 8000

   # Terminal 2: Frontend
   cd atomizer-dashboard/frontend
   npm run dev
   ```

2. **Start Optimization**:
   ```bash
   cd studies/my_study
   python run_optimization.py --trials 50
   ```

3. **View Dashboard**:
   - Open browser to `http://localhost:3001`
   - Select study from dropdown
   - Watch real-time updates every trial

4. **Interact with Plots**:
   - Toggle normalization on Pareto plot
   - Click lines in parallel coordinates to select trials
   - Hover for detailed trial information

### Performance

- **Backend**: ~10ms per endpoint (SQLite queries cached)
- **Frontend**: 2s polling interval (configurable)
- **Real-time writes**: <5ms per trial (JSON serialization)
- **Dashboard load time**: <500ms initial render

### Integration with Protocols

**Protocol 10 Integration**:
- Real-time callback integrated into `IntelligentOptimizer.optimize()`
- Tracks phase transitions (characterization → adaptive optimization)
- Reports strategy changes

**Protocol 11 Integration**:
- Pareto front endpoint checks `len(study.directions) > 1`
- Dashboard conditionally renders Pareto plots
- Handles both single and multi-objective studies
- Uses Optuna's `study.best_trials` for Pareto front

### Testing

**Tested With**:
- Study: `bracket_stiffness_optimization_V2`
- Trials: 50 (30 completed in testing)
- Objectives: 2 (stiffness maximize, mass minimize)
- Design Variables: 2 (support_angle, tip_thickness)
- Pareto Solutions: 20 identified
- Dashboard Port: 3001 (frontend) + 8000 (backend)

**Verified Features**:
- ✅ Real-time optimizer state updates
- ✅ Pareto front visualization with line
- ✅ Normalization toggle (Raw, Min-Max, Z-Score)
- ✅ Parallel coordinates with selection
- ✅ Dynamic units from config
- ✅ Multi-objective detection
- ✅ Constraint satisfaction coloring

### Troubleshooting

**Dashboard shows "No Pareto front data yet"**:
- Study must have multiple objectives
- At least 2 trials must complete
- Check `/api/optimization/studies/{id}/pareto-front` endpoint

**OptimizerPanel shows "Not available"**:
- Study must use IntelligentOptimizer (Protocol 10)
- Check `2_results/intelligent_optimizer/optimizer_state.json` exists
- Verify realtime_callback is registered

**Units not showing**:
- Add `unit` field to objectives in `optimization_config.json`
- Or ensure description contains unit pattern: "(N/mm)", "Hz", etc.
- Backend will infer from common patterns

### Related Documentation

- `docs/PROTOCOL_13_DASHBOARD.md` - Complete specification
- `docs/DASHBOARD_REACT_IMPLEMENTATION.md` - Frontend implementation details
- `docs/DASHBOARD_MASTER_PLAN.md` - Architecture overview

---

## Protocol Integration

### How Protocols Work Together

The protocols form a cohesive system where each addresses a specific concern:

```
┌─────────────────────────────────────────────────────────┐
│  USER REQUEST: "Optimize bracket for stiffness & mass"  │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│  Protocol 11: Multi-Objective Support                   │
│  ─────────────────────────────────────────────────────  │
│  • Detects 2 objectives from config                     │
│  • Creates multi-objective Optuna study                 │
│  • Ensures all components handle Pareto fronts          │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│  Protocol 10: Intelligent Optimization                  │
│  ─────────────────────────────────────────────────────  │
│  • Phase 1: Characterize landscape (10-30 trials)       │
│  • Analysis: Detect smooth_multimodal landscape         │
│  • Recommendation: Use NSGA-II for multi-objective      │
│  • Phase 2: Run NSGA-II optimization (50 trials)        │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│  Protocol 13: Real-Time Dashboard                       │
│  ─────────────────────────────────────────────────────  │
│  • Every trial: Write optimizer_state.json              │
│  • Display: Phase, strategy, progress                   │
│  • Visualize: Pareto front evolution                    │
│  • Interactive: Parallel coordinates exploration        │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│  RESULT: 20 Pareto-optimal solutions found              │
│  • Best stiffness: 1250 N/mm (mass: 0.198 kg)          │
│  • Lightest feasible: 892 N/mm (mass: 0.165 kg)        │
│  • User selects trade-off via dashboard                 │
└─────────────────────────────────────────────────────────┘
```

### Dependency Matrix

| Protocol | Depends On | Optional Dependencies |
|----------|------------|----------------------|
| Protocol 10 | None | - |
| Protocol 11 | None (Mandatory for all) | - |
| Protocol 13 | Protocol 10, Protocol 11 | - |

### Configuration Integration

**Complete Multi-Objective Setup**:

```json
{
  "study_name": "bracket_optimization",
  "description": "Multi-objective stiffness/mass optimization",

  "objectives": [
    {
      "name": "stiffness",
      "type": "maximize",
      "description": "Structural stiffness (N/mm)",
      "unit": "N/mm",
      "weight": 1.0
    },
    {
      "name": "mass",
      "type": "minimize",
      "description": "Total mass (kg)",
      "unit": "kg",
      "weight": 0.1
    }
  ],

  "constraints": [
    {
      "name": "mass_limit",
      "type": "less_than",
      "value": 0.2,
      "description": "Maximum allowable mass"
    }
  ],

  "design_variables": [
    {
      "name": "support_angle",
      "type": "continuous",
      "min": 20.0,
      "max": 70.0,
      "unit": "degrees"
    },
    {
      "name": "tip_thickness",
      "type": "continuous",
      "min": 30.0,
      "max": 60.0,
      "unit": "mm"
    }
  ],

  "optimization_settings": {
    "algorithm": "NSGA-II",
    "n_trials": 50
  },

  "intelligent_optimization": {
    "enabled": true,
    "characterization": {
      "min_trials": 10,
      "max_trials": 30,
      "confidence_threshold": 0.85
    }
  },

  "dashboard_settings": {
    "enabled": true,
    "port": 8000,
    "realtime_updates": true
  }
}
```

This configuration activates:
- ✅ Protocol 11: Multi-objective optimization with Pareto front
- ✅ Protocol 10: Intelligent algorithm selection
- ✅ Protocol 13: Real-time dashboard tracking

---

## Quick Reference

### Protocol Status Overview

| Protocol | Status | Files | Key Features |
|----------|--------|-------|--------------|
| **Protocol 10** | ✅ Production | 4 core + tests | Adaptive characterization, algorithm selection |
| **Protocol 11** | ✅ Mandatory | All optimizers | Single/multi-objective support |
| **Protocol 13** | ✅ Production | Backend + Frontend | Real-time dashboard, Pareto visualization |

### Key Configuration Parameters

**Protocol 10**:
```json
{
  "intelligent_optimization": {
    "characterization": {
      "min_trials": 10,
      "max_trials": 30,
      "confidence_threshold": 0.85
    }
  }
}
```

**Protocol 11**:
```json
{
  "objectives": [
    {"name": "obj1", "type": "minimize"},
    {"name": "obj2", "type": "maximize"}
  ]
}
```

**Protocol 13**:
```json
{
  "dashboard_settings": {
    "enabled": true,
    "port": 8000,
    "realtime_updates": true
  }
}
```

### Common Commands

**Start Dashboard**:
```bash
# Backend
cd atomizer-dashboard/backend && python -m uvicorn api.main:app --port 8000

# Frontend
cd atomizer-dashboard/frontend && npm run dev
```

**Run Optimization**:
```bash
cd studies/my_study && python run_optimization.py --trials 50
```

**Check Protocol 10 Reports**:
```bash
cat studies/my_study/2_results/intelligent_optimizer/intelligence_report.json
cat studies/my_study/2_results/intelligent_optimizer/characterization_progress.json
```

### API Endpoints

| Endpoint | Protocol | Purpose |
|----------|----------|---------|
| `/api/optimization/studies` | 13 | List all studies |
| `/api/optimization/studies/{id}/metadata` | 13 | Get objectives, design vars |
| `/api/optimization/studies/{id}/optimizer-state` | 13 | Get current optimizer phase |
| `/api/optimization/studies/{id}/pareto-front` | 13, 11 | Get Pareto-optimal solutions |
| `/api/optimization/studies/{id}/history` | 13 | Get all trials |

### Version Changelog

**2025-11-21**:
- Protocol 13 v1.0 released (Real-Time Dashboard)
- All protocols integrated and tested

**2025-11-20**:
- Protocol 10 v2.1 (Bug fixes)
- Protocol 11 v1.0 (Multi-objective support)
- Protocol 10 v2.0 (Adaptive characterization)

---

## Documentation Standards and Practices

**Version**: 1.0
**Status**: ✅ Active
**Priority**: P0 (Mandatory for all development)

### Overview

This section defines documentation standards and practices to ensure consistency, maintainability, and scalability throughout Atomizer development. All contributors must follow these guidelines when creating or modifying documentation.

### Documentation Structure

#### File Organization

Documentation uses a numbered prefix system for clear organization:

```
docs/
├── 00_INDEX.md                    # Main navigation hub (THIS IS THE START)
├── 01_PROTOCOLS.md                # This file - Master protocol specifications
├── 02_ARCHITECTURE.md             # System architecture overview
├── 03_GETTING_STARTED.md          # Quick start guide
├── 04_USER_GUIDES/                # End-user documentation
│   ├── dashboard_usage.md
│   ├── hybrid_mode.md
│   └── ...
├── 05_API_REFERENCE/              # API and integration documentation
│   ├── nx_integration.md
│   ├── system_configuration.md
│   └── ...
├── 06_PROTOCOLS_DETAILED/         # Individual protocol specifications
│   ├── protocol_10_imso.md
│   ├── protocol_11_multi_objective.md
│   ├── protocol_13_dashboard.md
│   └── ...
├── 07_DEVELOPMENT/                # Development guides and procedures
│   └── (future: contributing.md, testing.md, etc.)
└── 08_ARCHIVE/                    # Historical documents
    ├── session_summaries/
    ├── phase_documents/
    └── historical/
```

#### Naming Conventions

**Root-level files** (00-03):
- Use numbered prefixes: `00_`, `01_`, `02_`, `03_`
- Use UPPERCASE with underscores: `00_INDEX.md`, `01_PROTOCOLS.md`
- Purpose: Quick access to essential documents

**Subdirectory files** (04-08):
- Use lowercase with underscores: `dashboard_usage.md`, `nx_integration.md`
- Be descriptive: `protocol_10_imso.md` not just `p10.md`
- Purpose: Clear categorization within topics

**Archived files**:
- Preserve original names when moving to `08_ARCHIVE/`
- Use subdirectories: `session_summaries/`, `phase_documents/`, `historical/`
- Purpose: Historical context without root clutter

### Protocol Documentation Requirements

#### Creating a New Protocol

When introducing a new protocol (e.g., Protocol 14):

1. **Update Master Document** (`01_PROTOCOLS.md`):
   ```markdown
   ## Protocol 14: [Name]

   **Version**: 1.0
   **Status**: 🔨 In Development / ✅ Complete / 📋 Planned
   **Priority**: P0 (Critical) / P1 (High) / P2 (Normal) / P3 (Low)

   ### Overview
   [Brief description of the protocol's purpose]

   ### Architecture
   [System design, component interaction, data flow]

   ### Core Components
   [List and explain key components]

   ### Configuration
   [JSON configuration examples]

   ### Usage Example
   [Code snippets showing typical usage]

   ### Integration with Other Protocols
   [How this protocol interacts with existing protocols]

   ### Related Files
   [List of implementation files]
   ```

2. **Create Detailed Specification** (`06_PROTOCOLS_DETAILED/protocol_14_[name].md`):
   - In-depth implementation details
   - API reference
   - Testing procedures
   - Troubleshooting guide

3. **Update Navigation** (`00_INDEX.md`):
   - Add protocol to Quick Start section
   - Add to Protocol Quick Reference table
   - Update "Common Tasks" if applicable
   - Cross-reference with related documentation

4. **Update Root Documents**:
   - `README.md`: Add quick link if major feature
   - `DEVELOPMENT.md`: Update current phase status

#### Protocol Versioning

Follow semantic versioning:
- **Major version** (e.g., v2.0): Breaking changes, architectural redesign
- **Minor version** (e.g., v2.1): New features, backward compatible
- **Patch version** (e.g., v2.1.1): Bug fixes only

**Version Change Checklist**:
- [ ] Update version number in master document
- [ ] Add entry to "Version History" section
- [ ] Document breaking changes prominently
- [ ] Update code examples if API changed
- [ ] Test all examples in documentation
- [ ] Update cross-references to other protocols

### Documentation Types

#### 1. User Guides (`04_USER_GUIDES/`)

**Purpose**: Help users accomplish specific tasks

**Requirements**:
- Step-by-step instructions
- Code examples that run without modification
- Screenshots or diagrams where helpful
- "Common Issues" section
- Links to related API documentation

**Template**:
```markdown
# [Task Name]

**Last Updated**: YYYY-MM-DD
**Difficulty**: Beginner / Intermediate / Advanced

## Overview
[What this guide covers]

## Prerequisites
- Requirement 1
- Requirement 2

## Step 1: [Action]
[Detailed instructions with code]

## Step 2: [Action]
[Detailed instructions with code]

## Verification
[How to confirm success]

## Common Issues
[Troubleshooting steps]

## Next Steps
[Links to related guides]
```

#### 2. API Reference (`05_API_REFERENCE/`)

**Purpose**: Complete reference for APIs and integrations

**Requirements**:
- Function signatures with parameter types
- Return value specifications
- Example usage for each function
- Error conditions and exceptions
- Performance characteristics (if relevant)

**Template**:
```markdown
# [Component Name] API Reference

**Last Updated**: YYYY-MM-DD
**Status**: Stable / Experimental

## Overview
[Brief description]

## Classes

### ClassName

[Description]

**Constructor**:
```python
def __init__(self, param1: Type1, param2: Type2):
    """
    Brief description

    Args:
        param1: Description
        param2: Description
    """
```

**Methods**:

#### method_name(param1, param2)

[Description]

**Parameters**:
- `param1` (Type): Description
- `param2` (Type): Description

**Returns**:
- Type: Description

**Raises**:
- ExceptionType: When condition

**Example**:
```python
obj = ClassName(...)
result = obj.method_name(...)
```
```

#### 3. Architecture Documentation (`02_ARCHITECTURE.md`, detailed docs)

**Purpose**: Explain system design decisions and component interactions

**Requirements**:
- High-level diagrams (ASCII or embedded images)
- Component responsibility descriptions
- Data flow explanations
- Design rationale (why, not just what)
- Performance considerations

**Key Elements**:
```markdown
## System Architecture

### Component Diagram
[ASCII art or embedded diagram]

### Component Descriptions

#### Component Name
- **Responsibility**: What it does
- **Dependencies**: What it requires
- **Used By**: What uses it
- **Key Files**: Implementation files

### Design Decisions

#### Decision: [Name]
- **Context**: Problem being solved
- **Options Considered**: Alternative approaches
- **Decision**: What was chosen
- **Rationale**: Why this approach
- **Trade-offs**: What we gained/lost
```

### Cross-Referencing

#### Internal Links

Use relative paths for internal documentation:

```markdown
For more details, see [Protocol 10 specification](protocol_10_imso.md)
See the [Getting Started Guide](../03_GETTING_STARTED.md)
Check the [00_INDEX.md](../00_INDEX.md) for all documentation
```

#### Code References

Link to implementation files:

```markdown
Implemented in [optimization_engine/intelligent_optimizer.py](../optimization_engine/intelligent_optimizer.py)
See configuration format in [optimization_config.json](../examples/optimization_config.json)
```

#### Protocol References

When documenting a feature that uses multiple protocols:

```markdown
This feature integrates:
- **Protocol 10**: Adaptive characterization for landscape analysis
- **Protocol 11**: Multi-objective Pareto front handling
- **Protocol 13**: Real-time dashboard updates

See [Protocol Integration](01_PROTOCOLS.md#protocol-integration) for details.
```

### Documentation Maintenance

#### When to Update Documentation

Update documentation immediately when:
- [ ] API signatures change
- [ ] Configuration format changes
- [ ] New protocol features are added
- [ ] Bugs affect documented behavior
- [ ] Performance characteristics change significantly

#### Review Cycle

**After Each Protocol Update**:
1. Update master PROTOCOLS.md (this file)
2. Update detailed specification in 06_PROTOCOLS_DETAILED/
3. Update 00_INDEX.md if navigation changes
4. Update affected user guides
5. Test all code examples
6. Update DEVELOPMENT.md status

**Quarterly Reviews** (every 3 months):
1. Review all "Last Updated" dates
2. Test all code examples
3. Check for broken links
4. Update version numbers
5. Archive outdated documents to 08_ARCHIVE/

#### Documentation Testing

Before committing documentation changes:

```bash
# 1. Check for broken internal links
grep -r "\[.*\](.*\.md)" docs/ | check each link exists

# 2. Test all code examples (create temp script)
# Extract code blocks and run them

# 3. Verify cross-references
# Ensure referenced protocols/files exist

# 4. Check formatting
# Run markdown linter if available
```

### Writing Style Guide

#### Language

- **Concise**: Use short sentences and paragraphs
- **Active voice**: "Protocol 10 selects the algorithm" not "The algorithm is selected by Protocol 10"
- **Present tense**: "The system creates a study" not "The system will create a study"
- **Second person for tutorials**: "You can configure..." not "One can configure..."
- **Third person for specifications**: "The system performs..." not "We perform..."

#### Code Examples

**Always provide complete, runnable examples**:

```python
# ✅ GOOD: Complete, runnable example
from optimization_engine.intelligent_optimizer import IntelligentOptimizer

optimizer = IntelligentOptimizer(
    study_name="my_optimization",
    study_dir=Path("studies/my_study/2_results"),
    config=optimization_config,
    verbose=True
)

results = optimizer.optimize(
    objective_function=my_objective,
    design_variables={'param1': (0, 10)},
    n_trials=50
)

# ❌ BAD: Incomplete example
optimizer = IntelligentOptimizer(...)
results = optimizer.optimize(...)
```

**Include imports and context**:
```python
# ✅ GOOD: Shows all imports
from pathlib import Path
import json

from optimization_engine.intelligent_optimizer import IntelligentOptimizer

# Load config
with open('optimization_config.json', 'r') as f:
    config = json.load(f)

# ❌ BAD: Missing imports and setup
optimizer = IntelligentOptimizer(...)
```

#### Diagrams

Use ASCII art for simple diagrams (easier to maintain):

```
┌─────────────────────┐
│  Characterization   │
│  Phase (10-30)      │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Landscape Analysis │
│  (Strategy Select)  │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Optimization       │
│  Phase (50 trials)  │
└─────────────────────┘
```

For complex diagrams, use external tools and commit images to `docs/images/`.

#### Status Indicators

Use consistent emoji indicators:
- ✅ Complete - Fully implemented and tested
- 🔨 In Progress - Active development
- 📋 Planned - Design phase, not yet started
- ⏳ Pending - Waiting on dependencies
- ❌ Deprecated - No longer recommended
- ⚠️ Breaking Change - Backward incompatible

### Configuration Documentation

#### JSON Schema

Always document configuration options with:
- Parameter name
- Type (string, number, boolean, array, object)
- Default value
- Valid range or options
- Description
- Required/Optional indicator

**Example**:
```markdown
### Configuration Options

| Parameter | Type | Default | Valid Range | Required | Description |
|-----------|------|---------|-------------|----------|-------------|
| `min_trials` | integer | 10 | 5-50 | Yes | Minimum characterization trials |
| `max_trials` | integer | 30 | 10-100 | Yes | Maximum characterization trials |
| `confidence_threshold` | float | 0.85 | 0.0-1.0 | No | Stopping confidence level |
| `check_interval` | integer | 5 | 1-10 | No | Trials between checks |
```

#### Complete Configuration Examples

Provide full working configurations:

```json
{
  "study_name": "example_optimization",
  "description": "Complete working example",

  "objectives": [
    {
      "name": "frequency",
      "type": "minimize",
      "description": "Target frequency (Hz)",
      "unit": "Hz",
      "target": 1000.0,
      "tolerance": 10.0
    }
  ],

  "design_variables": [
    {
      "name": "thickness",
      "type": "continuous",
      "min": 1.0,
      "max": 10.0,
      "unit": "mm"
    }
  ],

  "intelligent_optimization": {
    "enabled": true,
    "characterization": {
      "min_trials": 10,
      "max_trials": 30,
      "confidence_threshold": 0.85,
      "check_interval": 5
    }
  },

  "trials": {
    "n_trials": 50
  }
}
```

### Session Summaries and Historical Documentation

#### When to Create Session Summaries

Create a session summary when:
- Major feature completed (Protocol implementation)
- Significant bug fix requiring architecture changes
- Multi-day development sprint concludes
- Important decisions made affecting future development

#### Session Summary Template

```markdown
# Session Summary: [Feature/Sprint Name]

**Date**: YYYY-MM-DD
**Duration**: X hours/days
**Contributors**: Names
**Status**: ✅ Complete / 🔨 In Progress

## Objectives

What we set out to accomplish:
- [ ] Objective 1
- [ ] Objective 2

## Accomplishments

### Feature 1: [Name]
- Implementation details
- Files changed
- Tests added

### Feature 2: [Name]
- Implementation details
- Files changed
- Tests added

## Technical Decisions

### Decision 1: [Name]
- **Problem**: What we were solving
- **Options**: What we considered
- **Decision**: What we chose
- **Rationale**: Why we chose it

## Known Issues

- Issue 1: Description and workaround
- Issue 2: Description and workaround

## Next Steps

1. Task 1
2. Task 2

## Files Changed

- `file1.py` - Description of changes
- `file2.py` - Description of changes

## References

- [Protocol XX](01_PROTOCOLS.md#protocol-xx)
- [Related Issue #123](link)
```

Save session summaries to `docs/08_ARCHIVE/session_summaries/`.

### Documentation Checklist

#### Before Committing

- [ ] All code examples tested and working
- [ ] Internal links verified (no 404s)
- [ ] Version numbers updated
- [ ] "Last Updated" date current
- [ ] Cross-references to related docs added
- [ ] Markdown formatting validated
- [ ] Spelling and grammar checked
- [ ] No confidential information included

#### For New Protocols

- [ ] Master PROTOCOLS.md updated
- [ ] Detailed spec in 06_PROTOCOLS_DETAILED/ created
- [ ] 00_INDEX.md navigation updated
- [ ] Protocol Quick Reference table updated
- [ ] Integration section added (how it works with other protocols)
- [ ] Configuration examples provided
- [ ] Usage examples tested
- [ ] Related files list complete

#### For Breaking Changes

- [ ] Version number incremented (major)
- [ ] "⚠️ Breaking Change" indicator added
- [ ] Migration guide written
- [ ] Old behavior documented for reference
- [ ] Deprecation timeline specified
- [ ] All affected code examples updated

### Tools and Automation

#### Recommended Tools

- **Markdown Editor**: VS Code with Markdown extensions
- **Diagram Tool**: draw.io, Mermaid, or ASCII art
- **Link Checker**: markdown-link-check
- **Spell Checker**: VS Code spell checker extension
- **Version Control**: Git with descriptive commit messages

#### Documentation Build (Future)

Consider implementing:
- Automated link checking in CI/CD
- Markdown linting for consistency
- Documentation site generator (MkDocs, Docusaurus)
- Automatic table of contents generation

### Contact and Contribution

**Documentation Maintainers**: Atomizer Development Team

**How to Contribute**:
1. Read this section thoroughly
2. Follow templates and style guide
3. Test all code examples
4. Submit pull request with documentation changes
5. Request review from maintainers

**Questions**:
- Open GitHub issue with "documentation" label
- Contact maintainers directly for urgent matters

---

**Document Maintained By**: Atomizer Development Team
**Last Review**: 2025-11-21
**Next Review**: When new protocols are added or existing protocols updated

For implementation details, see individual protocol documentation in `docs/06_PROTOCOLS_DETAILED/` files.