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