# Atomizer Dashboard **Last Updated**: January 17, 2026 **Version**: 3.1 (AtomizerSpec v2.0) --- ## Overview The Atomizer Dashboard is a real-time web-based interface for monitoring and analyzing multi-objective optimization studies. Built with React, TypeScript, and Tailwind CSS, it provides comprehensive visualization and interaction capabilities for NSGA-II based structural optimization. **New in V3.1**: All studies now use **AtomizerSpec v2.0** as the unified configuration format. The `atomizer_spec.json` file serves as the single source of truth for Canvas, Backend, Claude, and the Optimization Engine. ### Major Features | Feature | Route | Description | |---------|-------|-------------| | **Canvas Builder** | `/canvas` | Visual node-based workflow designer (AtomizerSpec v2.0) | | **Live Dashboard** | `/dashboard` | Real-time optimization monitoring | | **Results Viewer** | `/results` | Markdown reports with charts | | **Analytics** | `/analytics` | Cross-study comparison | | **Claude Chat** | Global | AI-powered study creation with spec tools | > **New in V3.1**: The [Canvas Builder](CANVAS.md) now uses AtomizerSpec v2.0 as the unified configuration format, with support for custom extractors and real-time WebSocket synchronization. --- ## Architecture ### Frontend Stack - **Framework**: React 18 with TypeScript - **Build Tool**: Vite - **Styling**: Tailwind CSS with custom dark/light theme support - **Charts**: Recharts for data visualization - **State Management**: React hooks (useState, useEffect) - **WebSocket**: Real-time optimization updates ### Backend Stack - **Framework**: FastAPI (Python) - **Database**: Optuna SQLite studies - **API**: RESTful endpoints with WebSocket support - **CORS**: Configured for local development ### Ports - **Frontend**: `http://localhost:3003` (Vite dev server) - **Backend**: `http://localhost:8000` (FastAPI/Uvicorn) --- ## Key Features ### 1. Multi-Objective Visualization #### Pareto Front Plot - 2D scatter plot showing trade-offs between objectives - Color-coded by constraint satisfaction (green = feasible, red = infeasible) - Interactive hover tooltips with trial details - Automatically extracts Pareto-optimal solutions using NSGA-II #### Parallel Coordinates Plot **Research-Based Multi-Dimensional Visualization** Structure: **Design Variables → Objectives → Constraints** Features: - **Light Theme**: White background with high-visibility dark text and colors - **Color-Coded Axes**: - Blue background: Design variables - Green background: Objectives - Yellow background: Constraints - **Interactive Selection**: - Hover over lines to highlight individual trials - Click to select/deselect trials - Multi-select with visual feedback (orange highlight) - **Type Badges**: Labels showing DESIGN VAR, OBJECTIVE, or CONSTRAINT - **Units Display**: Automatic unit labeling (mm, MPa, Hz, g, etc.) - **Min/Max Labels**: Range values displayed on each axis - **Feasibility Coloring**: - Green: Feasible solutions - Red: Infeasible solutions (constraint violations) - Blue: Hover highlight - Orange: Selected trials **Implementation**: [ParallelCoordinatesPlot.tsx](atomizer-dashboard/frontend/src/components/ParallelCoordinatesPlot.tsx:1) **Line colors**: ```typescript if (isSelected) return '#FF6B00'; // Orange for selected if (!trial.feasible) return '#DC2626'; // Red for infeasible if (isHovered) return '#2563EB'; // Blue for hover return '#10B981'; // Green for feasible ``` ### 2. Optimizer Strategy Panel Displays algorithm information: - **Algorithm**: NSGA-II, TPE, or custom - **Type**: Single-objective or Multi-objective - **Objectives Count**: Number of optimization objectives - **Design Variables Count**: Number of design parameters ### 3. Convergence Plot (Enhanced) **File**: `atomizer-dashboard/frontend/src/components/ConvergencePlot.tsx` Advanced convergence visualization: - **Dual-line plot**: Individual trial values + running best trajectory - **Area fill**: Gradient under trial values curve - **Statistics panel**: Best value, improvement %, 90% convergence trial - **Summary footer**: First value, mean, std dev, total trials - **Step-after interpolation**: Running best shown as step function ### 4. Parameter Importance Chart **File**: `atomizer-dashboard/frontend/src/components/ParameterImportanceChart.tsx` Correlation-based parameter analysis: - **Pearson correlation**: Calculates correlation between each parameter and objective - **Horizontal bar chart**: Parameters ranked by absolute importance - **Color coding**: Green (negative correlation - helps minimize), Red (positive - hurts minimize) - **Tooltip**: Shows percentage importance and raw correlation coefficient (r) - **Minimum 3 trials**: Required for statistical significance ### 5. Study Report Viewer **File**: `atomizer-dashboard/frontend/src/components/StudyReportViewer.tsx` Full-featured markdown report viewer: - **Modal overlay**: Full-screen report viewing - **Math equations**: KaTeX support for LaTeX math (`$...$` inline, `$$...$$` block) - **GitHub-flavored markdown**: Tables, code blocks, task lists - **Custom styling**: Dark theme with proper typography - **Syntax highlighting**: Code blocks with language detection - **Refresh button**: Re-fetch report for live updates - **External link**: Open in system editor ### 6. Trial History Table - Comprehensive list of all trials - Sortable columns - Status indicators (COMPLETE, PRUNED, FAIL) - Parameter values and objective values - User attributes (constraints) ### 7. Pruned Trials Tracking - **Real-time count**: Fetched directly from Optuna database - **Pruning diagnostics**: Tracks pruned trial params and causes - **Database query**: Uses SQLite `state = 'PRUNED'` filter ### 8. Analytics Page (Cross-Study Comparisons) **File**: `atomizer-dashboard/frontend/src/pages/Analytics.tsx` Dedicated analytics page for comparing optimization studies: #### Aggregate Statistics - **Total Studies**: Count of all studies in the system - **Running/Paused/Completed**: Status distribution breakdown - **Total Trials**: Sum of trials across all studies - **Avg Trials/Study**: Average trial count per study - **Best Overall**: Best objective value across all studies with study ID #### Study Comparison Table - **Sortable columns**: Name, Status, Progress, Best Value - **Status indicators**: Color-coded badges (running=green, paused=orange, completed=blue) - **Progress bars**: Visual completion percentage with color coding - **Quick actions**: Open button to navigate directly to a study's dashboard - **Selected highlight**: Current study highlighted with "Selected" badge - **Click-to-expand**: Row expansion for additional details #### Status Distribution Chart - Visual breakdown of studies by status - Horizontal bar chart with percentage fill - Color-coded: Running (green), Paused (orange), Completed (blue), Not Started (gray) #### Top Performers Panel - Ranking of top 5 studies by best objective value (assumes minimization) - Medal-style numbering (gold, silver, bronze for top 3) - Clickable rows to navigate to study - Trial count display **Usage**: Navigate to `/analytics` when a study is selected. Provides aggregate view across all studies. ### 9. Global Claude Terminal **Files**: - `atomizer-dashboard/frontend/src/components/GlobalClaudeTerminal.tsx` - `atomizer-dashboard/frontend/src/components/ClaudeTerminal.tsx` - `atomizer-dashboard/frontend/src/context/ClaudeTerminalContext.tsx` Persistent AI assistant terminal: - **Global persistence**: Terminal persists across page navigation - **WebSocket connection**: Real-time communication with Claude Code backend - **Context awareness**: Automatically includes current study context when available - **New Study mode**: When no study selected, offers guided study creation wizard - **Visual indicators**: Connection status shown in sidebar footer - **Keyboard shortcut**: Open/close terminal from anywhere **Modes**: - **With Study Selected**: "Set Context" button loads study-specific context - **No Study Selected**: "New Study" button starts guided wizard from `.claude/skills/guided-study-wizard.md` ### 10. Shared Markdown Renderer **File**: `atomizer-dashboard/frontend/src/components/MarkdownRenderer.tsx` Reusable markdown rendering component: - **Syntax highlighting**: Prism-based code highlighting with `oneDark` theme - **GitHub-flavored markdown**: Tables, task lists, strikethrough - **LaTeX math support**: KaTeX rendering with `remark-math` and `rehype-katex` - **Custom styling**: Dark theme typography optimized for dashboard - **Used by**: Home page (README display), Results page (reports) --- ## Pages Structure ### Home Page (`/`) - Study navigator and selector - README.md display with full markdown rendering - New study creation via Claude terminal ### Canvas Page (`/canvas`) **NEW** - Visual node-based workflow builder - Drag-and-drop node palette with 8 node types - Claude integration for workflow processing - Auto-load from existing studies - Expression search for design variables - See [Canvas Documentation](CANVAS.md) for details ### Dashboard Page (`/dashboard`) - Real-time live tracker for selected study - Convergence plot, Pareto front, parameter importance - Trial history table ### Reports Page (`/results`) - AI-generated optimization report viewer - Full markdown rendering with syntax highlighting and math - Copy and download capabilities ### Analytics Page (`/analytics`) - Cross-study comparison and aggregate statistics - Study ranking and status distribution - Quick navigation to individual studies --- ## API Endpoints ### AtomizerSpec (V3.1) #### GET `/api/studies/{study_id}/spec` Get the full AtomizerSpec for a study. **Response**: ```json { "meta": { "version": "2.0", "study_name": "..." }, "model": { "sim": { "path": "...", "solver": "nastran" } }, "design_variables": [...], "extractors": [...], "objectives": [...], "constraints": [...], "optimization": { "algorithm": { "type": "TPE" }, "budget": { "max_trials": 100 } }, "canvas": { "edges": [...], "layout_version": "2.0" } } ``` #### PUT `/api/studies/{study_id}/spec` Replace the entire spec with validation. #### PATCH `/api/studies/{study_id}/spec` Partial update using JSONPath. Body: `{ "path": "design_variables[0].bounds.max", "value": 15.0 }` #### POST `/api/studies/{study_id}/spec/validate` Validate spec and return detailed report. Returns: `{ "valid": true, "errors": [], "warnings": [] }` #### POST `/api/studies/{study_id}/spec/nodes` Add a new node (design variable, extractor, objective, constraint). #### PATCH `/api/studies/{study_id}/spec/nodes/{node_id}` Update an existing node's properties. #### DELETE `/api/studies/{study_id}/spec/nodes/{node_id}` Remove a node and clean up related edges. ### Studies #### GET `/api/optimization/studies` List all available optimization studies. **Response**: ```json [ { "id": "drone_gimbal_arm_optimization", "name": "drone_gimbal_arm_optimization", "direction": ["minimize", "maximize"], "n_trials": 100, "best_value": [3245.67, 165.3], "sampler": "NSGAIISampler" } ] ``` #### GET `/api/optimization/studies/{study_id}/trials` Get all trials for a study. **Response**: ```json { "trials": [ { "number": 0, "values": [3456.2, 145.6], "params": { "beam_half_core_thickness": 7.5, "beam_face_thickness": 2.1, "holes_diameter": 30.0, "hole_count": 11 }, "state": "COMPLETE", "user_attrs": { "max_stress": 95.3, "max_displacement": 1.2, "frequency": 145.6, "mass": 3456.2, "constraint_satisfied": true } } ] } ``` #### GET `/api/optimization/studies/{study_id}/metadata` Get study metadata including objectives and design variables. **Response**: ```json { "objectives": [ { "name": "mass", "type": "minimize", "unit": "g" }, { "name": "frequency", "type": "maximize", "unit": "Hz" } ], "design_variables": [ { "name": "beam_half_core_thickness", "unit": "mm", "min": 5.0, "max": 10.0 } ], "sampler": "NSGAIISampler" } ``` #### GET `/api/optimization/studies/{study_id}/pareto-front` Get Pareto-optimal solutions for multi-objective studies. **Response**: ```json { "is_multi_objective": true, "pareto_front": [ { "trial_number": 0, "values": [3245.67, 165.3], "params": {...}, "user_attrs": {...}, "constraint_satisfied": true } ] } ``` ### WebSocket #### WS `/ws/optimization/{study_id}` Real-time trial updates during optimization. **Message Format**: ```json { "type": "trial_complete", "trial": { "number": 5, "values": [3456.2, 145.6], "params": {...} } } ``` --- ## Running the Dashboard ### Backend ```bash cd atomizer-dashboard/backend python -m uvicorn api.main:app --reload --port 8000 ``` ### Frontend ```bash cd atomizer-dashboard/frontend npm run dev ``` Access at: `http://localhost:3003` --- ## Configuration ### Vite Proxy ([vite.config.ts](atomizer-dashboard/frontend/vite.config.ts:1)) ```typescript export default defineConfig({ plugins: [react()], server: { host: '0.0.0.0', port: 3003, proxy: { '/api': { target: 'http://127.0.0.1:8000', changeOrigin: true, secure: false, ws: true, // WebSocket support } } } }) ``` ### CORS ([backend/api/main.py](atomizer-dashboard/backend/api/main.py:1)) ```python app.add_middleware( CORSMiddleware, allow_origins=["http://localhost:3003"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) ``` --- ## Component Structure ``` atomizer-dashboard/ ├── frontend/ │ ├── src/ │ │ ├── components/ │ │ │ ├── canvas/ # Canvas Builder V2 │ │ │ │ ├── AtomizerCanvas.tsx # Main canvas with React Flow │ │ │ │ ├── nodes/ # 8 node type components │ │ │ │ │ ├── BaseNode.tsx # Base with Lucide icons │ │ │ │ │ ├── ModelNode.tsx # Cube icon │ │ │ │ │ ├── SolverNode.tsx # Cpu icon │ │ │ │ │ ├── DesignVarNode.tsx # SlidersHorizontal icon │ │ │ │ │ ├── ExtractorNode.tsx # FlaskConical icon │ │ │ │ │ ├── ObjectiveNode.tsx # Target icon │ │ │ │ │ ├── ConstraintNode.tsx # ShieldAlert icon │ │ │ │ │ ├── AlgorithmNode.tsx # BrainCircuit icon │ │ │ │ │ └── SurrogateNode.tsx # Rocket icon │ │ │ │ ├── panels/ │ │ │ │ │ ├── NodeConfigPanel.tsx # Config sidebar │ │ │ │ │ ├── ValidationPanel.tsx # Validation toast │ │ │ │ │ ├── ChatPanel.tsx # Claude chat │ │ │ │ │ ├── ConfigImporter.tsx # Study browser │ │ │ │ │ └── TemplateSelector.tsx # Workflow templates │ │ │ │ └── palette/ │ │ │ │ └── NodePalette.tsx # Draggable palette │ │ │ ├── chat/ # Chat components │ │ │ │ ├── ChatMessage.tsx # Message display │ │ │ │ └── ThinkingIndicator.tsx # Loading indicator │ │ │ ├── ParallelCoordinatesPlot.tsx # Multi-objective viz │ │ │ ├── ParetoPlot.tsx # Pareto front scatter │ │ │ ├── OptimizerPanel.tsx # Strategy info │ │ │ ├── ConvergencePlot.tsx # Convergence chart │ │ │ ├── ParameterImportanceChart.tsx # Parameter importance │ │ │ ├── StudyReportViewer.tsx # Report viewer │ │ │ ├── MarkdownRenderer.tsx # Markdown renderer │ │ │ ├── ClaudeTerminal.tsx # Claude terminal │ │ │ ├── GlobalClaudeTerminal.tsx # Global terminal │ │ │ ├── common/ │ │ │ │ ├── Card.tsx # Card component │ │ │ │ └── Button.tsx # Button component │ │ │ ├── layout/ │ │ │ │ ├── Sidebar.tsx # Navigation │ │ │ │ └── MainLayout.tsx # Layout wrapper │ │ │ └── dashboard/ │ │ │ ├── MetricCard.tsx # KPI display │ │ │ └── StudyCard.tsx # Study selector │ │ ├── pages/ │ │ │ ├── Home.tsx # Study selection │ │ │ ├── CanvasView.tsx # Canvas builder │ │ │ ├── Dashboard.tsx # Live tracker │ │ │ ├── Results.tsx # Report viewer │ │ │ └── Analytics.tsx # Analytics │ │ ├── hooks/ │ │ │ ├── useCanvasStore.ts # Zustand canvas state │ │ │ ├── useCanvasChat.ts # Canvas chat │ │ │ ├── useChat.ts # WebSocket chat │ │ │ └── useWebSocket.ts # WebSocket base │ │ ├── lib/canvas/ │ │ │ ├── schema.ts # Type definitions │ │ │ ├── intent.ts # Intent serialization │ │ │ ├── validation.ts # Graph validation │ │ │ └── templates.ts # Workflow templates │ │ ├── context/ │ │ │ ├── StudyContext.tsx # Study state │ │ │ └── ClaudeTerminalContext.tsx # Terminal state │ │ ├── api/ │ │ │ └── client.ts # API client │ │ └── types/ │ │ └── index.ts # TypeScript types │ └── vite.config.ts ├── backend/ │ └── api/ │ ├── main.py # FastAPI app │ ├── services/ │ │ ├── claude_agent.py # Claude API integration │ │ ├── session_manager.py # Session lifecycle │ │ ├── context_builder.py # Context assembly │ │ └── conversation_store.py # SQLite persistence │ └── routes/ │ ├── optimization.py # Optimization endpoints │ ├── studies.py # Study config endpoints │ ├── nx.py # NX introspection │ └── terminal.py # Claude WebSocket └── mcp-server/atomizer-tools/ └── src/ ├── index.ts # MCP server entry └── tools/ ├── canvas.ts # Canvas tools ├── study.ts # Study management ├── optimization.ts # Optimization control └── analysis.ts # Analysis tools ``` ## NPM Dependencies The frontend uses these key packages: - `react-markdown` - Markdown rendering - `remark-gfm` - GitHub-flavored markdown support - `remark-math` - Math equation parsing - `rehype-katex` - KaTeX math rendering - `recharts` - Interactive charts --- ## Data Flow 1. **Optimization Engine** runs trials and stores results in Optuna SQLite database 2. **Backend API** reads from database and exposes REST endpoints 3. **Frontend** fetches data via `/api/optimization/*` endpoints 4. **WebSocket** pushes real-time updates to connected clients 5. **React Components** render visualizations based on fetched data --- ## Troubleshooting ### Dashboard Page Crashes **Issue**: `TypeError: Cannot read properties of undefined (reading 'split')` **Fix**: Ensure all data is validated before rendering. ParallelCoordinatesPlot now includes: ```typescript if (!paretoData || paretoData.length === 0) return ; if (!objectives || !designVariables) return ; ``` ### No Data Showing 1. Check backend is running: `curl http://localhost:8000/api/optimization/studies` 2. Verify study exists in Optuna database 3. Check browser console for API errors 4. Ensure WebSocket connection is established ### CORS Errors - Backend must allow origin `http://localhost:3003` - Frontend proxy must target `http://127.0.0.1:8000` (not `localhost`) --- ## Best Practices ### For Multi-Objective Studies 1. **Always use metadata endpoint** to get objective/variable definitions 2. **Extract constraints from user_attrs** for parallel coordinates 3. **Filter Pareto front** using `paretoData.pareto_front` array 4. **Validate constraint_satisfied** field before coloring ### For Real-Time Updates 1. **Use WebSocket** for live trial updates 2. **Debounce state updates** to avoid excessive re-renders 3. **Close WebSocket** connection on component unmount ### For Performance 1. **Limit displayed trials** for large studies (e.g., show last 1000) 2. **Use React.memo** for expensive components 3. **Virtualize large lists** if showing >100 trials in tables --- ## Recent Updates ### January 2026 (V3.1) - AtomizerSpec v2.0 - [x] **AtomizerSpec v2.0**: Unified configuration architecture - **Single Source of Truth**: One `atomizer_spec.json` file for Canvas, Backend, Claude, and Optimization Engine - **Spec REST API**: Full CRUD operations at `/api/studies/{id}/spec` - **Pydantic Validation**: Backend validation with detailed error messages - **Legacy Migration**: Automatic migration from `optimization_config.json` - **29 Studies Migrated**: All existing studies converted to v2.0 format - [x] **Custom Extractors**: Define custom Python extraction functions in the spec - **Security Validation**: Code checked for dangerous patterns - **Runtime Loading**: Functions executed during optimization - **Canvas UI**: Code editor panel for custom extractor nodes - [x] **WebSocket Sync**: Real-time spec synchronization - Multiple clients stay synchronized - Optimistic updates with rollback on error - Conflict detection with hash comparison - [x] **Comprehensive Testing**: Full test coverage for Phase 4 - Unit tests for SpecManager and Pydantic models - API integration tests for all spec endpoints - Migration tests for legacy config formats - E2E tests for complete workflow ### January 2026 (V3.0) - [x] **Canvas Builder V3**: Major upgrade with model introspection and Claude fixes - **File Browser**: Browse studies directory for .sim/.prt/.fem/.afem files - **Model Introspection**: Auto-discover expressions, solver type, and dependencies - **One-Click Add**: Add expressions as design variables, add suggested extractors - **Claude Bug Fixes**: Fixed SQL errors, WebSocket reconnection, chat integration - **Connection Flow Fix**: Design variables now correctly flow INTO model nodes - **Health Check Endpoint**: `/api/health` for database status monitoring - [x] **Canvas Builder V2**: Complete visual workflow designer with React Flow - 8 node types with professional Lucide icons - Drag-and-drop node palette - Expression search dropdown for design variables - Auto-load from existing optimization_config.json - "Process with Claude" button for AI-assisted study creation - MCP canvas tools (validate, execute, interpret) - Responsive full-screen layout - [x] **Backend Services**: - NX introspection service (`/api/nx/introspect`, `/api/nx/expressions`) - File browser API (`/api/files/list`) - Claude session management with SQLite persistence - Context builder for study-aware conversations - [x] **Optimization Engine v2.0**: Major code reorganization - New modular structure: `core/`, `nx/`, `study/`, `config/`, `reporting/`, `processors/` - Backwards-compatible imports with deprecation warnings - 120 files reorganized for better maintainability ### December 2025 - [x] **Convergence Plot**: Enhanced with running best, statistics, and gradient fill - [x] **Parameter Importance Chart**: Correlation analysis with color-coded bars - [x] **Study Report Viewer**: Full markdown rendering with KaTeX math support - [x] **Pruned Trials**: Real-time count from Optuna database (not JSON file) - [x] **Chart Data Transformation**: Fixed `values` array mapping for single/multi-objective - [x] **Analytics Page**: Dedicated cross-study comparison and aggregate statistics view - [x] **Global Claude Terminal**: Persistent AI terminal with study context awareness - [x] **Shared Markdown Renderer**: Reusable component with syntax highlighting and math support - [x] **Study Session Persistence**: localStorage-based study selection that survives page refresh - [x] **Paused Status Support**: Full support for paused optimization status throughout UI - [x] **Guided Study Wizard**: Interactive wizard skill for creating new studies via Claude ### Future Enhancements - [ ] 3D Pareto front visualization for 3+ objectives - [ ] Advanced filtering and search in trial history - [ ] Export results to CSV/JSON - [ ] Custom parallel coordinates brushing/filtering - [ ] Hypervolume indicator tracking - [ ] Interactive design variable sliders - [ ] Constraint importance analysis - [ ] Tauri desktop application (Phase 5) --- ## References - **Optuna Documentation**: https://optuna.readthedocs.io/ - **NSGA-II Algorithm**: Deb et al. (2002) - **Parallel Coordinates**: Inselberg & Dimsdale (1990) - **React Documentation**: https://react.dev/ - **FastAPI Documentation**: https://fastapi.tiangolo.com/