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
2. Protocol 10: Intelligent Multi-Strategy Optimization (IMSO)
3. Protocol 11: Multi-Objective Support
4. Protocol 13: Real-Time Dashboard Tracking
5. Protocol Integration
6. Quick Reference
7. 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:

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:

# 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:

{
  "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

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:

study.best_trial    # Returns single Trial object
study.best_params   # Returns dict of parameters
study.best_value    # Returns float

Multi-Objective:

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

is_multi_objective = len(study.directions) > 1

2. Use Conditional Access Patterns

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:

{
    '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

  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

   directions=None  # or ['minimize']
   # Should complete without errors
   

2. Multi-Objective Test

   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

{
  "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:

{
  "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):

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:

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:

// 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):

cd atomizer-dashboard/backend
python -m uvicorn api.main:app --reload --port 8000

Frontend (atomizer-dashboard/frontend):

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:

   # 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:

   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:

{
  "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:

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

Protocol 11:

{
  "objectives": [
    {"name": "obj1", "type": "minimize"},
    {"name": "obj2", "type": "maximize"}
  ]
}

Protocol 13:

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

Common Commands

Start Dashboard:

# Backend
cd atomizer-dashboard/backend && python -m uvicorn api.main:app --port 8000

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

Run Optimization:

cd studies/my_study && python run_optimization.py --trials 50

Check Protocol 10 Reports:

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):

   ## 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:

# [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:

# [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:

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:

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:

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:

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:

# 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:

# ✅ 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:

# ✅ 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:

### 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:

{
  "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

# 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.