Atomizer/docs/06_PROTOCOLS_DETAILED/DASHBOARD_VISUALIZATION.md

# Atomizer Dashboard Visualization Guide

## Overview

The Atomizer Dashboard provides real-time visualization of optimization studies with interactive charts, trial history, and study management. It supports two chart libraries:

- **Recharts** (default): Fast, lightweight, good for real-time updates
- **Plotly**: Interactive with zoom, pan, export - better for analysis

## Starting the Dashboard

```bash
# 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

## Chart Components

### 1. Pareto Front Plot

Visualizes the trade-off between objectives in multi-objective optimization.

**Features:**
- 2D scatter plot for 2 objectives
- 3D view for 3+ objectives (Plotly only)
- Color differentiation: FEA (blue), NN (orange), Pareto (green)
- Axis selector for choosing which objectives to display
- Hover tooltips with trial details

**Usage:**
- Click points to select trials
- Use axis dropdowns to switch objectives
- Toggle 2D/3D view (Plotly mode)

### 2. Parallel Coordinates Plot

Shows relationships between all design variables and objectives simultaneously.

**Features:**
- Each vertical axis represents a variable or objective
- Lines connect values for each trial
- Brush filtering: drag on any axis to filter
- Color coding by trial source (FEA/NN/Pareto)

**Usage:**
- Drag on axes to create filters
- Double-click to reset filters
- Hover for trial details

### 3. Convergence Plot

Tracks optimization progress over time.

**Features:**
- Scatter points for each trial's objective value
- Step line showing best-so-far
- Range slider for zooming (Plotly)
- FEA vs NN differentiation

**Metrics Displayed:**
- Best value achieved
- Current trial value
- Total trial count

### 4. Parameter Importance Chart

Shows which design variables most influence the objective.

**Features:**
- Horizontal bar chart of correlation coefficients
- Color coding: Red (positive), Green (negative)
- Sortable by importance or name
- Pearson correlation calculation

**Interpretation:**
- Positive correlation: Higher parameter → Higher objective
- Negative correlation: Higher parameter → Lower objective
- |r| > 0.5: Strong influence

### 5. Expandable Charts

All charts support full-screen modal view:

**Features:**
- Click expand icon to open modal
- Larger view for detailed analysis
- Maintains all interactivity
- Close with X or click outside

## Chart Library Toggle

Switch between Recharts and Plotly using the header buttons:

| 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 (real-time)
- Switch to Plotly for post-optimization analysis

## Study Management

### Study Selection

- Left sidebar shows all available studies
- Click to select and load data
- Badge shows study status (running/completed)

### Metrics Cards

Top row displays key metrics:
- **Trials**: Total completed trials
- **Best Value**: Best objective achieved
- **Pruned**: Trials pruned by sampler

### Trial History

Bottom section shows trial details:
- Trial number and objective value
- Parameter values (expandable)
- Source indicator (FEA/NN)
- Sort by performance or chronological

## Report Viewer

Access generated study reports:

1. Click "View Report" button
2. Markdown rendered with syntax highlighting
3. Supports tables, code blocks, math

## Console Output

Real-time log viewer:

- Shows optimization progress
- Error messages highlighted
- Auto-scroll to latest
- Collapsible panel

## API Endpoints

The dashboard uses these REST endpoints:

```
GET  /api/optimization/studies                    # List all studies
GET  /api/optimization/studies/{id}/status        # Study status
GET  /api/optimization/studies/{id}/history       # Trial history
GET  /api/optimization/studies/{id}/metadata      # Study config
GET  /api/optimization/studies/{id}/pareto        # Pareto front
GET  /api/optimization/studies/{id}/report        # Markdown report
GET  /api/optimization/studies/{id}/console       # Log output
```

## WebSocket Updates

Real-time updates via WebSocket:

```
ws://localhost:8000/api/ws/optimization/{study_id}
```

Events:
- `trial_completed`: New trial finished
- `trial_pruned`: Trial was pruned
- `new_best`: New best value found

## Performance Optimization

### For Large Studies (1000+ trials)

1. Use Recharts for real-time monitoring
2. Switch to Plotly for final analysis
3. Limit displayed trials in parallel coordinates

### Bundle Optimization

The dashboard uses:
- `plotly.js-basic-dist` (smaller bundle, ~1MB vs 3.5MB)
- Lazy loading for Plotly components
- Code splitting (vendor, recharts, plotly chunks)

## Troubleshooting

### Charts Not Loading

1. Check backend is running (port 8000)
2. Verify API proxy in vite.config.ts
3. Check browser console for errors

### Slow Performance

1. Switch to Recharts mode
2. Reduce trial history limit
3. Close unused browser tabs

### Missing Data

1. Verify study.db exists
2. Check study has completed trials
3. Refresh page after new trials

## Development

### Adding New Charts

1. Create component in `src/components/`
2. Add Plotly version in `src/components/plotly/`
3. Export from `src/components/plotly/index.ts`
4. Add to Dashboard.tsx with toggle logic

### Styling

Uses Tailwind CSS with dark theme:
- Background: `dark-800`, `dark-900`
- Text: `dark-100`, `dark-200`
- Accent: `primary-500`, `primary-600`