Atomizer/docs/04_USER_GUIDES/CANVAS.md

Atomizer Canvas - Visual Workflow Builder

Last Updated: January 16, 2026 Version: 3.0 Status: Production

---

Overview

The Atomizer Canvas is a visual, node-based workflow builder for designing optimization studies. It provides a drag-and-drop interface for configuring FEA optimizations that integrates with Claude to validate and execute workflows.

Key Features

• Visual Workflow Design: Drag-and-drop nodes to build optimization pipelines
• Professional Lucide Icons: Clean, consistent iconography throughout the interface
• Auto-Load from Studies: Import existing optimization_config.json files
• NX Model Introspection: Automatically extract expressions from .prt/.sim/.fem files
• File Browser: Browse and select model files with type filtering
• Expression Search: Searchable dropdown for design variable configuration
• One-Click Add: Add discovered expressions as design variables instantly
• Claude Integration: "Process with Claude" button for AI-assisted study creation
• Responsive Layout: Full-screen canvas that adapts to window size

What's New in V3

Feature	Description
File Browser	Browse studies directory for .sim/.prt/.fem/.afem files
Introspection Panel	View discovered expressions, extractors, and dependencies
One-Click Add	Add expressions as design variables with a single click
Claude Fixes	Fixed SQL errors, WebSocket reconnection issues
Health Check	/api/health endpoint for database monitoring

---

Architecture

Frontend Stack

Component	Technology	Purpose
Flow Engine	React Flow	Node-based graph rendering
State Management	Zustand	Canvas state (nodes, edges, selection)
Icons	Lucide React	Professional icon library
Styling	Tailwind CSS	Dark theme (Atomaster palette)
Chat	WebSocket	Real-time Claude communication

Node Types (8)

Node	Icon	Description	Color
Model	Cube	NX model file (.prt, .sim, .fem)	Blue
Solver	Cpu	Nastran solution type (SOL101, SOL103, etc.)	Violet
Design Variable	SlidersHorizontal	Parameter to optimize with bounds	Emerald
Extractor	FlaskConical	Physics result extraction (E1-E10)	Cyan
Objective	Target	Optimization goal (minimize/maximize)	Rose
Constraint	ShieldAlert	Design constraint (upper/lower bounds)	Amber
Algorithm	BrainCircuit	Optimization method (TPE, CMA-ES, NSGA-II)	Indigo
Surrogate	Rocket	Neural acceleration (optional)	Pink

File Structure

atomizer-dashboard/frontend/src/
├── components/canvas/
│   ├── AtomizerCanvas.tsx        # Main canvas component
│   ├── nodes/
│   │   ├── index.ts              # Node type registry
│   │   ├── BaseNode.tsx          # Base node with handles
│   │   ├── ModelNode.tsx         # Model file node
│   │   ├── SolverNode.tsx        # Solver type node
│   │   ├── DesignVarNode.tsx     # Design variable node
│   │   ├── ExtractorNode.tsx     # Extractor node
│   │   ├── ObjectiveNode.tsx     # Objective node
│   │   ├── ConstraintNode.tsx    # Constraint node
│   │   ├── AlgorithmNode.tsx     # Algorithm node
│   │   └── SurrogateNode.tsx     # Surrogate node
│   ├── panels/
│   │   ├── NodeConfigPanel.tsx   # Node configuration sidebar
│   │   ├── ValidationPanel.tsx   # Validation toast display
│   │   ├── ExecuteDialog.tsx     # Execute confirmation modal
│   │   ├── ChatPanel.tsx         # Claude chat sidebar
│   │   ├── ConfigImporter.tsx    # Study import dialog
│   │   ├── TemplateSelector.tsx  # Workflow template chooser
│   │   ├── FileBrowser.tsx       # File picker modal (V3)
│   │   ├── IntrospectionPanel.tsx # Model introspection results (V3)
│   │   └── ExpressionSelector.tsx # Expression search dropdown (V3)
│   └── palette/
│       └── NodePalette.tsx       # Draggable node palette
├── hooks/
│   ├── useCanvasStore.ts         # Zustand store for canvas state
│   └── useCanvasChat.ts          # Claude chat integration
├── lib/canvas/
│   ├── schema.ts                 # TypeScript type definitions
│   ├── intent.ts                 # Intent serialization (174 lines)
│   ├── validation.ts             # Graph validation logic
│   └── templates.ts              # Workflow templates
└── pages/
    └── CanvasView.tsx            # Canvas page (/canvas route)

---

User Interface

Layout

┌───────────────────────────────────────────────────────────────────┐
│  Canvas Builder                                    Templates Import│
├──────────┬────────────────────────────────────────────┬───────────┤
│          │                                            │           │
│  Node    │              Canvas Area                   │  Config   │
│  Palette │                                            │  Panel    │
│          │   ┌─────┐      ┌─────┐      ┌─────┐       │           │
│  [Model] │   │Model├──────│Solver├──────│Algo │       │  Label:   │
│  [Solver]│   └─────┘      └──┬──┘      └─────┘       │  [____]   │
│  [DVar]  │                   │                        │           │
│  [Extr]  │   ┌─────┐      ┌──┴──┐      ┌─────┐       │  Type:    │
│  [Obj]   │   │ DVar├──────│Extr ├──────│ Obj │       │  [____]   │
│  [Const] │   └─────┘      └─────┘      └─────┘       │           │
│  [Algo]  │                                            │           │
│  [Surr]  │                                            │           │
│          │                                            │           │
├──────────┴────────────────────────────────────────────┴───────────┤
│                     [Validate]  [Process with Claude]              │
└───────────────────────────────────────────────────────────────────┘

Dark Theme (Atomaster Palette)

Element	Color	Tailwind Class
Background	#050A12	bg-dark-900
Surface	#0A1525	bg-dark-850
Card	#0F1E32	bg-dark-800
Border	#1A2F4A	border-dark-700
Muted Text	#5A7A9A	text-dark-400
Primary	#00D4E6	text-primary-400

---

Core Workflows

1. Building a Workflow

1. Drag nodes from the left palette onto the canvas
2. Connect nodes by dragging from output handle to input handle
3. Configure nodes by clicking to open the config panel
4. Validate using the Validate button
5. Process with Claude to create the study

2. Importing from Existing Study

1. Click Import in the header
2. Select the Load Study tab
3. Search for your study by name
4. Select a study with an optimization_config.json
5. Click Load Study to populate the canvas

3. Using Templates

1. Click Templates in the header
2. Browse available workflow templates:
   • Mass Minimization: Single-objective mass reduction
   • Multi-Objective: Pareto optimization (mass + displacement)
   • Turbo Mode: Neural-accelerated optimization
   • Mirror WFE: Zernike wavefront error optimization
   • Frequency Target: Natural frequency optimization
3. Click a template to load it

4. Processing with Claude

1. Build and configure your workflow
2. Click Validate to check for errors
3. Click Process with Claude to:
   • Validate the configuration against Atomizer protocols
   • Receive recommendations (method selection, trial count)
   • Create the optimization study

---

Node Configuration

Model Node

Field	Description	Example
File Path	Path to NX model	models/bracket.sim
File Type	prt, sim, or fem	sim

When loading a .sim file, the system introspects to find:

• Linked .prt (geometry part)
• Linked .fem (FEM file)
• Solver type (SOL101, SOL103, etc.)
• Available expressions

Design Variable Node

Field	Description	Example
Expression Name	NX expression to vary	thickness
Min Value	Lower bound	5.0
Max Value	Upper bound	15.0
Unit	Engineering unit	mm

Expression Selector: Click the dropdown to:

• Search through available expressions
• Filter by name
• Refresh to reload from model
• Enter manually if expression not found

Extractor Node

Field	Description	Options
Extractor ID	Protocol E1-E10	E1 (Displacement), E2 (Frequency), etc.
Name	Display name	max_displacement
Config	Extractor-specific settings	Node ID, component, etc.

Available Extractors (SYS_12):

ID	Physics	Function
E1	Displacement	extract_displacement()
E2	Frequency	extract_frequency()
E3	Stress	extract_solid_stress()
E4	BDF Mass	extract_mass_from_bdf()
E5	CAD Mass	extract_mass_from_expression()
E8	Zernike	extract_zernike_coefficients()
E9	Zernike	extract_zernike_rms()
E10	Zernike	extract_zernike_wfe()

Objective Node

Field	Description	Options
Name	Objective identifier	mass, displacement
Direction	Optimization goal	minimize, maximize
Weight	Multi-objective weight	1.0 (0.0-10.0)

Constraint Node

Field	Description	Example
Name	Constraint identifier	max_stress
Operator	Comparison type	<=, >=, ==
Value	Threshold value	250.0

Algorithm Node

Field	Description	Options
Method	Optimization algorithm	TPE, CMA-ES, NSGA-II, GP-BO
Max Trials	Number of trials	100
Timeout	Optional time limit	3600 (seconds)

Method Selection (SYS_15):

Method	Best For	Design Vars	Objectives
TPE	General purpose	1-10	1
CMA-ES	Many variables	5-100	1
NSGA-II	Multi-objective	1-20	2-4
GP-BO	Expensive evaluations	1-10	1

Surrogate Node

Field	Description	Options
Enabled	Toggle acceleration	true/false
Model Type	Surrogate architecture	MLP, GNN, Auto
Min Trials	Trials before activation	20

---

File Browser (V3)

The File Browser allows you to navigate the studies directory to select model files.

Features

• Directory Navigation: Browse folder hierarchy with breadcrumbs
• Type Filtering: Filters to .sim, .prt, .fem, .afem by default
• Search: Quick search by file name
• Single-Click Select: Click a file to select and close

Usage

1. Click the Browse button (folder icon) next to the Model file path input
2. Navigate to your study folder
3. Click a model file to select it
4. The path is automatically populated in the Model node

---

Model Introspection (V3)

Model Introspection analyzes NX model files to discover expressions, solver type, and dependencies.

Features

• Expression Discovery: Lists all expressions found in the model
• Solver Detection: Infers solver type from file contents (SOL101, SOL103, etc.)
• Dependency Tracking: Shows related .prt, .fem, .afem files
• Extractor Suggestions: Recommends extractors based on solver type
• One-Click Add: Add expressions as Design Variables instantly

Usage

1. Configure a Model node with a valid file path
2. Click Introspect Model button
3. View discovered expressions, extractors, and files
4. Click + next to any expression to add as Design Variable
5. Click + next to any extractor to add to canvas

Discovered Information

Section	Contents
Solver Type	Detected solver (SOL101, SOL103, etc.)
Expressions	Name, current value, unit
Extractors	Available extractors for this solver
Dependent Files	Related .prt, .fem, .afem files

---

API Integration

Backend Endpoints

Study Configuration

GET  /api/studies/                    # List all studies
GET  /api/studies/{path}/config       # Get optimization_config.json

File Browser (V3)

GET  /api/files/list                 # List files in directory
  Query: path=subdir&types=.sim,.prt,.fem,.afem
  Returns: { files: [{name, path, isDirectory}], path }

NX Introspection (V3)

POST /api/nx/introspect              # Introspect NX model file
  Body: { file_path: string }
  Returns: {
    file_path, file_type, expressions, solver_type,
    dependent_files, extractors_available, warnings
  }

GET  /api/nx/expressions             # Get expressions from model
  Query: file_path=path/to/model.sim
  Returns: { expressions: [{name, value, unit, type}] }

Health Check (V3)

GET  /api/health                     # Check database and service health
  Returns: { status: "healthy", database: "connected" }

MCP Canvas Tools

The Canvas integrates with the MCP server for Claude tool use:

validate_canvas_intent

Validates an optimization intent from the Canvas.

{
  intent: OptimizationIntent  // The canvas workflow as JSON
}
// Returns: { valid, errors, warnings, recommendations }

execute_canvas_intent

Creates an optimization study from a validated intent.

{
  intent: OptimizationIntent,
  study_name: string,         // snake_case name
  auto_run?: boolean          // Start optimization immediately
}
// Returns: { study_path, config_path, status }

interpret_canvas_intent

Analyzes a Canvas intent and provides recommendations.

{
  intent: OptimizationIntent
}
// Returns: {
//   problem_type: "single-objective" | "multi-objective",
//   complexity: "low" | "medium" | "high",
//   recommended_method: string,
//   recommended_trials: number,
//   surrogate_recommended: boolean,
//   notes: string[]
// }

---

OptimizationIntent Schema

The Canvas serializes workflows to the OptimizationIntent JSON format:

interface OptimizationIntent {
  model: {
    path: string;
    type: 'prt' | 'sim' | 'fem';
  };
  solver: {
    type: string;  // SOL101, SOL103, etc.
  };
  design_variables: Array<{
    name: string;
    expression: string;
    min: number;
    max: number;
    unit?: string;
  }>;
  extractors: Array<{
    id: string;    // E1, E2, etc.
    name: string;
    config?: Record<string, unknown>;
  }>;
  objectives: Array<{
    name: string;
    extractor: string;
    direction: 'minimize' | 'maximize';
    weight?: number;
  }>;
  constraints?: Array<{
    name: string;
    extractor: string;
    operator: '<=' | '>=' | '==';
    value: number;
  }>;
  optimization: {
    method: string;
    max_trials: number;
    timeout?: number;
  };
  surrogate?: {
    enabled: boolean;
    model_type?: string;
    min_trials?: number;
  };
}

---

Validation Rules

The Canvas validates workflows against these rules:

Required Components

• At least 1 Model node
• At least 1 Solver node
• At least 1 Design Variable node
• At least 1 Objective node
• At least 1 Algorithm node

Configuration Rules

• All nodes must be configured (no empty fields)
• Design variable min < max
• Objective must connect to an Extractor
• Extractor ID must be valid (E1-E10)

Connection Rules

• Model → Solver (required)
• Solver → Extractor (required for each extractor)
• Extractor → Objective (required for each objective)
• Extractor → Constraint (optional)

Recommendations

• Multi-objective (2+ objectives) should use NSGA-II
• Many variables (5+) may benefit from surrogate
• High trial count (100+) should consider neural acceleration

---

Templates

Mass Minimization

Single-objective mass reduction with stress constraint.

• Nodes: 6 (Model, Solver, DVar, Extractor, Objective, Algorithm)
• Objective: Minimize mass
• Constraint: Max stress < limit
• Method: TPE (100 trials)

Multi-Objective

Pareto optimization for mass vs. displacement trade-off.

• Nodes: 7
• Objectives: Minimize mass, Minimize displacement
• Method: NSGA-II (150 trials)

Turbo Mode

Neural-accelerated optimization with surrogate.

• Nodes: 8 (includes Surrogate)
• Objective: User-defined
• Method: TPE + MLP Surrogate
• Trials: 50 FEA + 5000 surrogate

Mirror WFE

Zernike wavefront error optimization for optics.

• Nodes: 7
• Objective: Minimize WFE (E10)
• Method: CMA-ES (200 trials)

Frequency Target

Natural frequency optimization with modal analysis.

• Nodes: 6
• Objective: Target frequency (E2)
• Method: TPE (100 trials)

---

Keyboard Shortcuts

Key	Action
Delete / Backspace	Delete selected node
Escape	Deselect all
Ctrl+Z	Undo (future)
Ctrl+Shift+Z	Redo (future)
Space (hold)	Pan canvas
Scroll	Zoom in/out

---

Troubleshooting

Canvas Not Visible

• Ensure you're on the /canvas route
• Check for JavaScript errors in browser console
• Verify React Flow is properly initialized

Nodes Not Draggable

• Check that drag-and-drop events are being captured
• Ensure onDragStart sets the correct data type

Config Panel Not Updating

• Verify Zustand store is properly connected
• Check that updateNodeData is being called

Claude Chat Not Working

• Check WebSocket connection status (green indicator)
• Verify backend is running on port 8000
• Check /api/chat/ endpoint is accessible

Expression Dropdown Empty

• Ensure a Model node is configured with a file path
• Check /api/nx/expressions endpoint is working
• Try the "Refresh" button to reload expressions

---

Development

Running Locally

# Frontend
cd atomizer-dashboard/frontend
npm install
npm run dev

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

# MCP Server
cd mcp-server/atomizer-tools
npm run build
npm run dev

Building for Production

# Frontend
cd atomizer-dashboard/frontend
npm run build

# MCP Server
cd mcp-server/atomizer-tools
npm run build

Adding New Node Types

1. Create node component in components/canvas/nodes/
2. Add type to schema.ts
3. Register in nodes/index.ts
4. Add to NodePalette.tsx
5. Update validation rules in validation.ts
6. Add serialization logic to intent.ts

---

References

• React Flow Documentation: https://reactflow.dev/
• Lucide Icons: https://lucide.dev/icons/
• Zustand: https://github.com/pmndrs/zustand
• Atomizer Protocols: See docs/protocols/
• Extractor Library: See SYS_12_EXTRACTOR_LIBRARY.md
• Method Selector: See SYS_15_METHOD_SELECTOR.md

---

Canvas Builder: Design optimizations visually, execute with AI.