Atomizer/docs/protocols/system/SYS_13_DASHBOARD_TRACKING.md

SYS_13: Real-Time Dashboard Tracking

Overview

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

Key Feature: Every trial completion writes state to JSON, enabling live browser updates.

---

When to Use

Trigger	Action
"dashboard", "visualization" mentioned	Load this protocol
"real-time", "monitoring" requested	Enable dashboard tracking
Multi-objective study	Dashboard shows Pareto front
Want to see progress visually	Point to localhost:3000

---

Quick Reference

Dashboard URLs:

Service	URL	Purpose
Frontend	http://localhost:3000	Main dashboard
Backend API	http://localhost:8000	REST API
Optuna Dashboard	http://localhost:8080	Alternative viewer

Start Commands:

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

# Frontend
cd atomizer-dashboard/frontend
npm run dev

---

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.

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

Data Structure (optimizer_state.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"]
}

2. REST API Endpoints

Base: /api/optimization/studies/{study_id}/

Endpoint	Method	Returns
/metadata	GET	Objectives, design vars, constraints with units
/optimizer-state	GET	Current phase, strategy, progress
/pareto-front	GET	Pareto-optimal solutions (multi-objective)
/history	GET	All trial history
/	GET	List all studies

Unit Inference:

def _infer_objective_unit(objective: Dict) -> str:
    name = objective.get("name", "").lower()
    desc = objective.get("description", "").lower()

    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 (components/OptimizerPanel.tsx)

Displays:

• Current phase (Characterization, Exploration, Exploitation, Adaptive)
• Current strategy (TPE, GP, NSGA-II, etc.)
• Progress bar with trial count
• Multi-objective indicator

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

2. ParetoPlot (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]
  • Z-Score: Standardizes to mean=0, std=1
• Tooltip shows raw values regardless of normalization
• Color-coded: green=feasible, red=infeasible

3. ParallelCoordinatesPlot (components/ParallelCoordinatesPlot.tsx)

Features:

• High-dimensional visualization (objectives + design variables)
• Interactive trial selection
• Normalized [0, 1] axes
• Color coding: green (feasible), red (infeasible), yellow (selected)

Stiffness    Mass    support_angle    tip_thickness
   │          │            │                │
   │    ╱─────╲           ╱                 │
   │   ╱       ╲─────────╱                  │
   │  ╱                  ╲                  │

4. Dashboard Layout

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

---

Configuration

In optimization_config.json:

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

Study Requirements:

• Must use Protocol 10 (IntelligentOptimizer) for optimizer state
• Must have optimization_config.json with objectives and design_variables
• Real-time tracking enabled automatically with Protocol 10

---

Usage Workflow

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
conda activate atomizer
python run_optimization.py --n-trials 50

3. View Dashboard

• Open browser to http://localhost:3000
• 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

Metric	Value
Backend endpoint latency	~10ms
Frontend polling interval	2 seconds
Real-time write overhead	<5ms per trial
Dashboard initial load	<500ms

---

Integration with Other 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
• Uses Optuna's study.best_trials for Pareto front

---

Troubleshooting

Symptom	Cause	Solution
"No Pareto front data yet"	Single-objective or no trials	Wait for trials, check objectives
OptimizerPanel shows "Not available"	Not using Protocol 10	Enable IntelligentOptimizer
Units not showing	Missing unit in config	Add unit field or use pattern in description
Dashboard not updating	Backend not running	Start backend with uvicorn
CORS errors	Backend/frontend mismatch	Check ports, restart both

---

Cross-References

• Depends On: SYS_10_IMSO, SYS_11_MULTI_OBJECTIVE
• Used By: OP_03_MONITOR_PROGRESS
• See Also: Optuna Dashboard for alternative visualization

---

Implementation Files

Backend:

• atomizer-dashboard/backend/api/main.py - FastAPI app
• atomizer-dashboard/backend/api/routes/optimization.py - Endpoints
• optimization_engine/realtime_tracking.py - Callback system

Frontend:

• atomizer-dashboard/frontend/src/pages/Dashboard.tsx - Main page
• atomizer-dashboard/frontend/src/components/OptimizerPanel.tsx
• atomizer-dashboard/frontend/src/components/ParetoPlot.tsx
• atomizer-dashboard/frontend/src/components/ParallelCoordinatesPlot.tsx

---

Implementation Details

Backend API Example (FastAPI)

@router.get("/studies/{study_id}/pareto-front")
async def get_pareto_front(study_id: str):
    """Get Pareto-optimal solutions for multi-objective studies."""
    study = optuna.load_study(study_name=study_id, storage=storage)

    if len(study.directions) == 1:
        return {"is_multi_objective": False}

    return {
        "is_multi_objective": True,
        "pareto_front": [
            {
                "trial_number": t.number,
                "values": t.values,
                "params": t.params,
                "user_attrs": dict(t.user_attrs)
            }
            for t in study.best_trials
        ]
    }

Frontend OptimizerPanel (React/TypeScript)

export function OptimizerPanel({ studyId }: { studyId: string }) {
  const [state, setState] = useState<OptimizerState | null>(null);

  useEffect(() => {
    const fetchState = async () => {
      const res = await fetch(`/api/optimization/studies/${studyId}/optimizer-state`);
      setState(await res.json());
    };
    fetchState();
    const interval = setInterval(fetchState, 1000);
    return () => clearInterval(interval);
  }, [studyId]);

  return (
    <Card title="Optimizer Status">
      <div>Phase: {state?.current_phase}</div>
      <div>Strategy: {state?.current_strategy}</div>
      <ProgressBar value={state?.trial_number} max={state?.total_trials} />
    </Card>
  );
}

Callback Integration

CRITICAL: Every study.optimize() call must include the realtime callback:

# In IntelligentOptimizer
self.realtime_callback = create_realtime_callback(
    tracking_dir=self.tracking_dir,
    optimizer_ref=self,
    verbose=self.verbose
)

# Register with ALL optimize calls
self.study.optimize(
    objective_function,
    n_trials=check_interval,
    callbacks=[self.realtime_callback]  # Required for real-time updates
)

---

Chart Library Options

The dashboard supports two chart libraries:

Feature	Recharts	Plotly
Load Speed	Fast	Slower (lazy loaded)
Interactivity	Basic	Advanced
Export	Screenshot	PNG/SVG native
3D Support	No	Yes
Real-time Updates	Better	Good

Recommendation: Use Recharts during active optimization, Plotly for post-analysis.

Quick Start

# Both backend and frontend
python start_dashboard.py

# Or manually:
cd atomizer-dashboard/backend && python -m uvicorn main:app --port 8000
cd atomizer-dashboard/frontend && npm run dev

Access at: http://localhost:3003

---

Version History

Version	Date	Changes
1.2	2025-12-05	Added chart library options
1.1	2025-12-05	Added implementation code snippets
1.0	2025-11-21	Initial release with real-time tracking