# Protocol Workflows
**Last Updated**: 2025-11-21
**Version**: 1.0
**Status**: ✅ Complete
---
## Overview
This document provides detailed workflow diagrams for each Atomizer protocol, showing exactly how the system processes optimizations from configuration to completion.
---
## Protocol 10: Intelligent Multi-Strategy Optimization (IMSO)
### Complete IMSO Workflow
```mermaid
flowchart TD
Start([User Starts Optimization]) --> LoadConfig[Load optimization_config.json]
LoadConfig --> CheckMultiObj{Multi-objective?}
%% Multi-objective path
CheckMultiObj -->|Yes| MultiObjPath[Protocol 11 Active]
MultiObjPath --> SkipChar[Skip Characterization
Protocol 10 Not Used]
SkipChar --> SetNSGAII[Set Sampler: NSGA-II]
SetNSGAII --> RunTrialsMulti[Run All Trials
NSGA-II Only]
%% Single-objective path
CheckMultiObj -->|No| SingleObjPath[Protocol 10 Active]
SingleObjPath --> InitChar[Initialize Characterization]
%% Characterization Phase
subgraph CharPhase["Characterization Phase (Protocol 10)"]
InitChar --> RandomSampling[Random/Sobol Sampling]
RandomSampling --> RunCharTrial[Run Trial]
RunCharTrial --> CharCount{Trial count ≥ min_trials?}
CharCount -->|No| RandomSampling
CharCount -->|Yes| CheckInterval{Check interval
reached?}
CheckInterval -->|No| RandomSampling
CheckInterval -->|Yes| CalcConfidence[Calculate Confidence Score]
CalcConfidence --> ConfCheck{Confidence ≥ 0.85?}
ConfCheck -->|No| MaxCheck{Reached max_trials?}
MaxCheck -->|No| RandomSampling
MaxCheck -->|Yes| ForceAnalysis[Force Landscape Analysis]
ConfCheck -->|Yes| ReadyForAnalysis[Ready for Analysis]
ForceAnalysis --> ReadyForAnalysis
end
%% Landscape Analysis
ReadyForAnalysis --> LandscapeAnalysis
subgraph Analysis["Landscape Analysis"]
LandscapeAnalysis[Analyze Landscape] --> Smoothness[Compute Smoothness]
Smoothness --> Multimodal[Detect Multimodality]
Multimodal --> Separability[Measure Separability]
Separability --> Noise[Estimate Noise Level]
Noise --> Classify{Landscape Type}
Classify -->|Smooth + Unimodal| RecommendTPE[Recommend: TPE]
Classify -->|Smooth + Multimodal| RecommendCMAES[Recommend: CMA-ES]
Classify -->|Noisy| RecommendGP[Recommend: GP]
Classify -->|Complex| RecommendNSGAII[Recommend: NSGA-II]
Classify -->|Unknown| RecommendRandom[Recommend: Random]
end
%% Strategy Selection
RecommendTPE --> SelectStrategy[Select Strategy]
RecommendCMAES --> SelectStrategy
RecommendGP --> SelectStrategy
RecommendNSGAII --> SelectStrategy
RecommendRandom --> SelectStrategy
SelectStrategy --> LogTransition[Log Strategy Transition
Protocol 13]
LogTransition --> RunOptimization
%% Optimization Phase
subgraph OptPhase["Optimization Phase"]
RunOptimization[Run Optimization] --> RunTrial[Execute Trial]
RunTrial --> CheckStagnation{Stagnation
detected?}
CheckStagnation -->|No| MoreTrials{More trials?}
CheckStagnation -->|Yes| SwitchStrategy[Switch Strategy]
SwitchStrategy --> LogSwitch[Log Transition]
LogSwitch --> RunTrial
MoreTrials -->|Yes| RunTrial
MoreTrials -->|No| OptComplete[Optimization Complete]
end
RunTrialsMulti --> Complete
OptComplete --> Complete
Complete[Generate Final Report] --> End([Optimization Complete])
%% Styling
classDef phaseClass fill:#E8F5E9,stroke:#2E7D32,stroke-width:3px
classDef decisionClass fill:#FFF9C4,stroke:#F57F17,stroke-width:2px
classDef protocolClass fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px
class CharPhase,OptPhase,Analysis phaseClass
class CheckMultiObj,CharCount,CheckInterval,ConfCheck,MaxCheck,Classify,CheckStagnation,MoreTrials decisionClass
class MultiObjPath,SingleObjPath,LogTransition,LogSwitch protocolClass
```
### Confidence Calculation Details
```mermaid
graph TB
subgraph ConfidenceCalc["Confidence Score Calculation"]
Start[Recent Trials
Last 10-20 trials] --> Convergence[Convergence Score
Improvement rate]
Start --> Coverage[Exploration Coverage
Design space sampling]
Start --> Stability[Prediction Stability
Surrogate variance]
Convergence --> Weight1[× 0.4]
Coverage --> Weight2[× 0.3]
Stability --> Weight3[× 0.3]
Weight1 --> Sum[Σ Weighted Scores]
Weight2 --> Sum
Weight3 --> Sum
Sum --> Overall[Overall Confidence
0.0 - 1.0]
Overall --> Threshold{≥ 0.85?}
Threshold -->|Yes| Ready[Ready for Exploitation]
Threshold -->|No| Continue[Continue Characterization]
end
subgraph Metrics["Individual Metrics"]
Conv[Convergence:
Recent improvement / Initial range]
Cov[Coverage:
Unique regions explored / Total regions]
Stab[Stability:
1 - (prediction_std / value_range)]
end
Convergence -.-> Conv
Coverage -.-> Cov
Stability -.-> Stab
```
### Landscape Analysis Algorithm
```mermaid
flowchart LR
subgraph LandscapeFeatures["Landscape Feature Extraction"]
direction TB
Trials[Completed Trials] --> BuildSurrogate[Build GP Surrogate]
BuildSurrogate --> F1[Feature 1:
Smoothness]
BuildSurrogate --> F2[Feature 2:
Multimodality]
BuildSurrogate --> F3[Feature 3:
Separability]
BuildSurrogate --> F4[Feature 4:
Noise Level]
F1 --> Smooth[Gradient Variance
Low = Smooth]
F2 --> Modes[Local Optima Count
High = Multimodal]
F3 --> Sep[Variable Interaction
Low = Separable]
F4 --> NoiseEst[Residual Variance
High = Noisy]
end
subgraph Classification["Strategy Classification"]
direction TB
Smooth --> C1{Smoothness
< 0.3?}
Modes --> C2{Modes > 3?}
Sep --> C3{Separability
< 0.5?}
NoiseEst --> C4{Noise > 0.2?}
C1 -->|Yes| TPEScore[TPE Score +2]
C1 -->|No| TPEScore
C2 -->|Yes| CMAScore[CMA-ES Score +2]
C2 -->|No| CMAScore
C3 -->|Yes| GPScore[GP Score +1]
C3 -->|No| GPScore
C4 -->|Yes| NSGAScore[NSGA-II Score +2]
C4 -->|No| NSGAScore
TPEScore --> MaxScore{Max score?}
CMAScore --> MaxScore
GPScore --> MaxScore
NSGAScore --> MaxScore
MaxScore --> Winner[Winning Strategy]
end
LandscapeFeatures --> Classification
```
---
## Protocol 11: Multi-Objective Support
### Multi-Objective Decision Tree
```mermaid
flowchart TD
Start[Component Initialization] --> CheckObj{Check Study
Objectives}
CheckObj -->|len == 1| SingleObj[Single-Objective Mode]
CheckObj -->|len > 1| MultiObj[Multi-Objective Mode]
%% Single-objective path
subgraph SinglePath["Single-Objective Operations"]
SingleObj --> API1[Use Singular API]
API1 --> UseBestValue[study.best_value]
API1 --> UseBestTrial[study.best_trial]
API1 --> UseTrialValue[trial.value]
API1 --> EnableChar[Enable Characterization]
API1 --> EnableStag[Enable Stagnation Detection]
end
%% Multi-objective path
subgraph MultiPath["Multi-Objective Operations"]
MultiObj --> API2[Use Plural API]
API2 --> UseBestTrials[study.best_trials
Pareto Front]
API2 --> UseTrialValues[trial.values
List of objectives]
API2 --> SkipChar[Skip Characterization
Return confidence=1.0]
API2 --> SkipStag[Skip Stagnation Detection
Return False]
API2 --> UseSampler[Force NSGA-II Sampler]
end
%% Component checks
subgraph Components["Component-Level Checks"]
Comp1[adaptive_surrogate.py] --> CompCheck1{Multi-obj?}
CompCheck1 -->|Yes| Return1[Return max confidence]
CompCheck1 -->|No| Calc1[Calculate confidence]
Comp2[strategy_portfolio.py] --> CompCheck2{Multi-obj?}
CompCheck2 -->|Yes| Return2[Skip stagnation]
CompCheck2 -->|No| Calc2[Detect stagnation]
Comp3[realtime_tracking.py] --> CompCheck3{Multi-obj?}
CompCheck3 -->|Yes| Write1[Write trial.values]
CompCheck3 -->|No| Write2[Write trial.value]
end
SinglePath --> Components
MultiPath --> Components
Components --> End[Component Execution]
%% Styling
classDef singleClass fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px
classDef multiClass fill:#BBDEFB,stroke:#1565C0,stroke-width:2px
classDef checkClass fill:#FFF9C4,stroke:#F57F17,stroke-width:2px
class SinglePath,API1,UseBestValue,UseBestTrial,UseTrialValue,EnableChar,EnableStag singleClass
class MultiPath,API2,UseBestTrials,UseTrialValues,SkipChar,SkipStag,UseSampler multiClass
class CheckObj,CompCheck1,CompCheck2,CompCheck3 checkClass
```
### Protocol 11 Compliance Checklist
```mermaid
flowchart TD
subgraph Detection["1. Detect Objective Count"]
D1[len study.directions] --> D2{Count?}
D2 -->|1| SetSingle[is_multi_objective = False]
D2 -->|>1| SetMulti[is_multi_objective = True]
end
subgraph APIUsage["2. Use Correct API"]
SetSingle --> API1[✓ study.best_value
✓ study.best_trial
✓ trial.value]
SetMulti --> API2[✓ study.best_trials
✓ trial.values
✗ trial.value = ERROR]
end
subgraph Features["3. Feature Compatibility"]
API1 --> F1[✓ Characterization
✓ Landscape Analysis
✓ Stagnation Detection
✓ All Strategies]
API2 --> F2[✗ Characterization Skipped
✗ Landscape Analysis Skipped
✗ Stagnation Detection Skipped
✓ NSGA-II Only]
end
subgraph Tracking["4. Tracking Compliance"]
F1 --> T1[Write trial.value
Write best_value]
F2 --> T2[Write trial.values
Write pareto_front_size]
end
subgraph Validation["5. Pre-deployment Validation"]
T1 --> V1{Test both modes}
T2 --> V1
V1 --> V2[✓ Single-obj test passes]
V1 --> V3[✓ Multi-obj test passes]
V2 --> Pass[Protocol 11 Compliant]
V3 --> Pass
end
classDef errorClass fill:#FFCDD2,stroke:#C62828,stroke-width:2px
classDef successClass fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px
class API2 errorClass
class Pass successClass
```
---
## Protocol 13: Real-Time Dashboard Tracking
### Tracking Workflow
```mermaid
sequenceDiagram
autonumber
participant Opt as IntelligentOptimizer
participant Optuna
participant Callback as RealtimeTracker
(Optuna Callback)
participant FS as File System
participant Dashboard
%% Study initialization
Opt->>Callback: Initialize Tracker
Callback->>FS: Create intelligent_optimizer/
directory
%% Trial execution
loop For each trial
Optuna->>Optuna: Sample Parameters
Optuna->>Opt: Execute Objective Function
Opt->>Opt: Run NX Solver
%% Trial completion
Optuna->>Callback: after_trial(study, trial)
activate Callback
%% Write trial log
Callback->>Callback: Extract trial data
Callback->>FS: Append to trial_log.json
Note over FS: {trial_number, params,
values, state, timestamp}
%% Write optimizer state
Callback->>Callback: Get current strategy/phase
Callback->>FS: Write optimizer_state.json
Note over FS: {current_strategy,
current_phase, trial_number}
%% Conditional writes
alt Characterization Phase
Callback->>Callback: Calculate progress
Callback->>FS: Write characterization_progress.json
Note over FS: {confidence, convergence,
exploration, trials_complete}
end
alt Landscape Analysis Complete
Callback->>Callback: Get analysis results
Callback->>FS: Write intelligence_report.json
Note over FS: {landscape_features,
strategy_recommendation,
confidence}
end
alt Strategy Transition
Callback->>Callback: Log transition
Callback->>FS: Write strategy_transitions.json
Note over FS: {from_strategy, to_strategy,
reason, trial_number}
end
deactivate Callback
%% Dashboard update
FS-->>Dashboard: File Watch Event
Dashboard->>FS: Read JSON Files
Dashboard->>Dashboard: Parse Data
Dashboard->>Dashboard: Update UI
Dashboard->>Dashboard: Render Charts
end
%% Finalization
Opt->>FS: Write optimization_summary.json
Opt->>FS: Write final_report.md
Dashboard->>Dashboard: Show Final Results
```
### File Write Patterns
```mermaid
graph TB
subgraph FileWrites["Protocol 13 File Writes"]
direction TB
subgraph EveryTrial["Every Trial (after_trial)"]
T1[trial_log.json
APPEND mode]
T2[optimizer_state.json
OVERWRITE mode]
end
subgraph Conditional["Conditional Writes"]
C1{In characterization?}
C1 -->|Yes| W1[characterization_progress.json]
C1 -->|No| Skip1[Skip]
C2{Landscape analyzed?}
C2 -->|Yes| W2[intelligence_report.json]
C2 -->|No| Skip2[Skip]
C3{Strategy changed?}
C3 -->|Yes| W3[strategy_transitions.json
APPEND mode]
C3 -->|No| Skip3[Skip]
end
subgraph OnComplete["On Completion"]
F1[optimization_summary.json]
F2[final_report.md]
end
end
subgraph Format["JSON Format Examples"]
direction LR
Ex1["trial_log.json:
[{trial: 0, ...},
{trial: 1, ...}]"]
Ex2["optimizer_state.json:
{strategy: 'TPE',
phase: 'optimization'}"]
Ex3["characterization_progress.json:
{confidence: 0.72,
trials: 15/30}"]
end
EveryTrial -.-> Ex1
EveryTrial -.-> Ex2
Conditional -.-> Ex3
```
---
## LLM-Assisted Workflow (Hybrid Mode)
### Complete LLM Workflow
```mermaid
flowchart TD
Start([User Provides Requirements]) --> LLMStart[LLM Receives Request]
LLMStart --> Parse[Parse Requirements]
Parse --> Extract[Extract Key Info:
- Objectives
- Design variables
- Constraints
- Preferences]
Extract --> DesignChoice{Design
Decisions
Needed?}
%% Interactive clarification
DesignChoice -->|Yes| AskUser[Ask User for Clarification]
AskUser --> UserResponse[User Provides Details]
UserResponse --> Extract
%% Generate configuration
DesignChoice -->|No| GenerateConfig[Generate Config]
subgraph ConfigGen["Configuration Generation"]
GenerateConfig --> SetObjectives[Define Objectives
with extractors]
SetObjectives --> SetDesignVars[Define Design Variables
with bounds]
SetDesignVars --> SetConstraints[Define Constraints]
SetConstraints --> SetProtocols[Configure Protocols]
SetProtocols --> P10Config{Enable
Protocol 10?}
P10Config -->|Yes| CharConfig[Set characterization params]
P10Config -->|No| SkipP10[Use default sampler]
CharConfig --> FinalConfig
SkipP10 --> FinalConfig[Assemble JSON]
end
FinalConfig --> ValidateConfig{Valid
Configuration?}
ValidateConfig -->|No| FixConfig[Fix Issues]
FixConfig --> FinalConfig
ValidateConfig -->|Yes| WriteConfig[Write optimization_config.json]
%% Create extractor if needed
WriteConfig --> NeedExtractor{Custom
Extractor
Needed?}
NeedExtractor -->|Yes| CreateExtractor
subgraph ExtractorGen["Extractor Generation"]
CreateExtractor[Generate Extractor Code] --> BaseClass[Inherit from BaseExtractor]
BaseClass --> ExtractMethod[Implement extract method]
ExtractMethod --> RegisterExt[Register in library]
end
RegisterExt --> WriteExtractor[Write extractor.py]
NeedExtractor -->|No| SkipExtractor[Use built-in extractors]
WriteExtractor --> SetupStudy
SkipExtractor --> SetupStudy
%% Study setup
subgraph StudySetup["Study Setup"]
SetupStudy[Create Study Directory] --> CreateFolders[Create 1_setup/ & 2_results/]
CreateFolders --> CopyModel[Copy CAD model to 1_setup/model/]
CopyModel --> CopyConfig[Copy config to 1_setup/]
CopyConfig --> CreateRunner[Create run_optimization.py]
end
CreateRunner --> ReadyToRun[Study Ready to Run]
ReadyToRun --> UserConfirm{User
Approves?}
UserConfirm -->|No| Revise[User Provides Feedback]
Revise --> Parse
UserConfirm -->|Yes| RunOptimization[Execute Optimization]
%% Optimization execution
RunOptimization --> Protocol10Flow[Follow Protocol 10 Workflow]
Protocol10Flow --> Protocol13Track[Protocol 13 Tracking Active]
Protocol13Track --> Monitor[LLM Can Monitor Progress]
Monitor --> Complete{Optimization
Complete?}
Complete -->|No| Monitor
Complete -->|Yes| Analyze[Analyze Results]
%% Result analysis
subgraph ResultAnalysis["Result Analysis"]
Analyze --> ReadDB[Read study.db]
ReadDB --> ReadReports[Read JSON reports]
ReadReports --> ExtractInsights[Extract Insights:
- Best solution
- Trade-offs
- Landscape type
- Convergence]
end
ExtractInsights --> PresentResults[Present Results to User]
PresentResults --> End([Workflow Complete])
%% Styling
classDef llmClass fill:#FFEBEE,stroke:#C62828,stroke-width:2px
classDef userClass fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
classDef processClass fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px
class LLMStart,Parse,Extract,GenerateConfig,CreateExtractor,Analyze,ExtractInsights,PresentResults llmClass
class Start,AskUser,UserResponse,UserConfirm,Revise,End userClass
class ConfigGen,ExtractorGen,StudySetup,ResultAnalysis processClass
```
### LLM Decision Points
```mermaid
flowchart LR
subgraph Decisions["LLM Decision Points During Setup"]
direction TB
D1[Objective Type]
D1 --> D1A{Minimize/Maximize?}
D1A --> D1B{Target value?}
D1B --> D1C{Single/Multi-objective?}
D2[Design Variables]
D2 --> D2A{Continuous/Integer/Categorical?}
D2A --> D2B{Physical bounds?}
D2B --> D2C{Engineering constraints?}
D3[Extractor Selection]
D3 --> D3A{Built-in available?}
D3A -->|No| D3B[Generate custom]
D3A -->|Yes| D3C[Use built-in]
D4[Protocol Configuration]
D4 --> D4A{Enable IMSO?}
D4A -->|Yes| D4B[Set characterization
min/max trials]
D4A -->|No| D4C[Use default sampler]
D5[Constraint Handling]
D5 --> D5A{Hard constraints?}
D5A -->|Yes| D5B[Pruning callbacks]
D5A -->|No| D5C[Soft penalties]
end
subgraph Clarification["When LLM Asks User"]
Q1[Ambiguous objective
'Optimize performance']
Q2[Unknown bounds
'What is max thickness?']
Q3[Missing constraints
'Any mass limits?']
Q4[Extractor uncertainty
'How to extract stress?']
end
D1C -.->|Unclear| Q1
D2B -.->|Unknown| Q2
D2C -.->|Unclear| Q3
D3A -.->|Unsure| Q4
```
---
## Integration: All Protocols Together
### Complete Optimization Flow
```mermaid
flowchart TD
Start([User Starts]) --> Config[Load Configuration]
Config --> DetectMode{LLM-assisted?}
%% LLM path
DetectMode -->|Yes| LLMSetup[LLM generates config
and extractors]
LLMSetup --> InitOpt
%% Manual path
DetectMode -->|No| ManualConfig[User-written config]
ManualConfig --> InitOpt
%% Initialization
InitOpt[Initialize IntelligentOptimizer] --> P13Init[Protocol 13: Initialize Tracking]
P13Init --> DetectObj{Multi-objective?}
%% Single-objective path
DetectObj -->|No| P10Start[Protocol 10: Start IMSO]
subgraph P10["Protocol 10 Execution"]
P10Start --> CharPhase[Characterization Phase
Random/Sobol sampling]
CharPhase --> CharProgress{Confidence ≥ 0.85?}
CharProgress -->|No| CharPhase
CharProgress -->|Yes| P13Char[P13: Write characterization_progress.json]
P13Char --> Landscape[Landscape Analysis]
Landscape --> P13Intel[P13: Write intelligence_report.json]
P13Intel --> SelectStrat[Select Strategy]
SelectStrat --> P13Trans[P13: Write strategy_transitions.json]
P13Trans --> OptPhase[Optimization Phase
Selected strategy]
OptPhase --> StagnCheck{Stagnation?}
StagnCheck -->|Yes| SwitchStrat[Switch Strategy]
SwitchStrat --> P13Trans
StagnCheck -->|No| OptPhase
end
%% Multi-objective path
DetectObj -->|Yes| P11Start[Protocol 11: Multi-Obj Mode]
subgraph P11["Protocol 11 Execution"]
P11Start --> SkipChar[Skip Characterization]
SkipChar --> SetNSGAII[Set NSGA-II Sampler]
SetNSGAII --> OptPhaseMulti[Optimization Phase
NSGA-II only]
end
%% Trial execution (common)
OptPhase --> RunTrial
OptPhaseMulti --> RunTrial
subgraph TrialExec["Trial Execution"]
RunTrial[Execute Trial] --> NXUpdate[Update NX Model]
NXUpdate --> NXSolve[Run FEA Solver]
NXSolve --> ExtractResults[Extract Results
Using Extractors]
ExtractResults --> CalcObj[Calculate Objectives]
CalcObj --> OptunaUpdate[Update Optuna Study]
end
%% Tracking after trial
OptunaUpdate --> P13Trial[P13: after_trial callback]
subgraph P13Track["Protocol 13 Tracking"]
P13Trial --> WriteLog[Append trial_log.json]
WriteLog --> WriteState[Write optimizer_state.json]
WriteState --> DashUpdate[Dashboard Auto-Updates]
end
DashUpdate --> MoreTrials{More trials?}
MoreTrials -->|Yes| RunTrial
MoreTrials -->|No| Finalize
%% Finalization
Finalize[Generate Final Report] --> P13Final[P13: Write optimization_summary.json]
P13Final --> End([Complete])
%% Styling
classDef p10Class fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px
classDef p11Class fill:#BBDEFB,stroke:#1565C0,stroke-width:2px
classDef p13Class fill:#FFE082,stroke:#F57F00,stroke-width:2px
class P10,P10Start,CharPhase,CharProgress,Landscape,SelectStrat,OptPhase,StagnCheck,SwitchStrat p10Class
class P11,P11Start,SkipChar,SetNSGAII,OptPhaseMulti p11Class
class P13Init,P13Char,P13Intel,P13Trans,P13Trial,P13Track,P13Final,DashUpdate p13Class
```
---
## Next Steps
For detailed architecture diagrams, see:
- [Architecture Overview](architecture_overview.md) - System components and data flow
For implementation details, see:
- [Protocol Specifications](../01_PROTOCOLS.md)
- [Documentation Index](../00_INDEX.md)