docs(canvas): Add comprehensive Canvas documentation
- Architecture overview and file structure - Node types reference table - Data flow diagram - Usage instructions for building workflows - Template and import documentation - Intent JSON schema reference - State management API - Validation rules - Chat integration details Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
177
atomizer-dashboard/frontend/src/components/canvas/README.md
Normal file
177
atomizer-dashboard/frontend/src/components/canvas/README.md
Normal file
@@ -0,0 +1,177 @@
|
|||||||
|
# Atomizer Canvas - Visual Optimization Workflow Builder
|
||||||
|
|
||||||
|
A React Flow-based node graph editor for building FEA optimization workflows visually.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The Canvas provides a visual interface for constructing optimization configurations. Users drag nodes from a palette, connect them to define data flow, configure parameters, and execute with Claude.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
Canvas System
|
||||||
|
├── lib/canvas/ # Core logic
|
||||||
|
│ ├── schema.ts # Node type definitions
|
||||||
|
│ ├── intent.ts # Graph → Intent JSON serialization
|
||||||
|
│ ├── validation.ts # Graph validation rules
|
||||||
|
│ ├── templates.ts # Pre-built workflow templates
|
||||||
|
│ └── index.ts # Exports
|
||||||
|
├── components/canvas/ # UI components
|
||||||
|
│ ├── nodes/ # 8 node type components
|
||||||
|
│ ├── palette/ # Drag source palette
|
||||||
|
│ ├── panels/ # Config, validation, chat panels
|
||||||
|
│ └── AtomizerCanvas.tsx # Main canvas component
|
||||||
|
├── hooks/ # State management
|
||||||
|
│ ├── useCanvasStore.ts # Zustand store
|
||||||
|
│ ├── useCanvasChat.ts # Chat bridge
|
||||||
|
│ └── useIntentParser.ts # Message parsing
|
||||||
|
└── pages/
|
||||||
|
└── CanvasView.tsx # Canvas page
|
||||||
|
```
|
||||||
|
|
||||||
|
## Node Types
|
||||||
|
|
||||||
|
| Node | Icon | Description | Inputs | Outputs |
|
||||||
|
|------|------|-------------|--------|---------|
|
||||||
|
| Model | 📦 | NX model file (.prt, .fem, .sim) | - | 1 |
|
||||||
|
| Solver | ⚙️ | Nastran solution type (SOL101-112) | 1 | 1 |
|
||||||
|
| DesignVar | 📐 | Parameter with min/max bounds | - | 1 |
|
||||||
|
| Extractor | 🔬 | Physics quantity extraction | 1 | 1 |
|
||||||
|
| Objective | 🎯 | Optimization goal (min/max) | 1 | 1 |
|
||||||
|
| Constraint | 🚧 | Limit condition (<=, >=) | 1 | 1 |
|
||||||
|
| Algorithm | 🧠 | Optimization method (TPE, CMA-ES, etc.) | 1+ | 1 |
|
||||||
|
| Surrogate | 🚀 | Neural network acceleration | 1 | - |
|
||||||
|
|
||||||
|
## Data Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
[DesignVar]──┐
|
||||||
|
├──▶[Model]──▶[Solver]──▶[Extractor]──┬──▶[Objective]──┬──▶[Algorithm]──▶[Surrogate]
|
||||||
|
[DesignVar]──┘ └──▶[Constraint]─┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### Building a Workflow
|
||||||
|
|
||||||
|
1. **Drag nodes** from the left palette onto the canvas
|
||||||
|
2. **Connect nodes** by dragging from output handles (right) to input handles (left)
|
||||||
|
3. **Configure nodes** by clicking to open the config panel
|
||||||
|
4. **Validate** to check for errors/warnings
|
||||||
|
5. **Execute** to send to Claude for processing
|
||||||
|
|
||||||
|
### Using Templates
|
||||||
|
|
||||||
|
Click "Templates" to load pre-configured workflows:
|
||||||
|
- **Mass Minimization** - Single-objective mass reduction
|
||||||
|
- **Multi-Objective Pareto** - Trade-off analysis with NSGA-II
|
||||||
|
- **Turbo Mode** - Accelerated optimization with MLP surrogate
|
||||||
|
- **Mirror Zernike** - Optical surface optimization
|
||||||
|
- **Frequency Optimization** - Modal analysis with SOL103
|
||||||
|
|
||||||
|
### Importing Configurations
|
||||||
|
|
||||||
|
Click "Import" to load existing configurations:
|
||||||
|
- **File Upload** - Select an `optimization_config.json` file
|
||||||
|
- **Paste JSON** - Paste configuration directly
|
||||||
|
- **Load Study** - Load from existing study by name
|
||||||
|
|
||||||
|
## Intent JSON Format
|
||||||
|
|
||||||
|
The canvas serializes to an Intent JSON for Claude:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": "1.0",
|
||||||
|
"source": "canvas",
|
||||||
|
"timestamp": "2026-01-14T...",
|
||||||
|
"model": {
|
||||||
|
"path": "path/to/model.prt",
|
||||||
|
"type": "prt"
|
||||||
|
},
|
||||||
|
"solver": {
|
||||||
|
"type": "SOL101"
|
||||||
|
},
|
||||||
|
"design_variables": [
|
||||||
|
{ "name": "thickness", "min": 1.0, "max": 10.0, "unit": "mm" }
|
||||||
|
],
|
||||||
|
"extractors": [
|
||||||
|
{ "id": "E4", "name": "BDF Mass", "config": {} }
|
||||||
|
],
|
||||||
|
"objectives": [
|
||||||
|
{ "name": "mass", "direction": "minimize", "weight": 1.0, "extractor": "E4" }
|
||||||
|
],
|
||||||
|
"constraints": [
|
||||||
|
{ "name": "max_disp", "operator": "<=", "value": 0.5, "extractor": "E1" }
|
||||||
|
],
|
||||||
|
"optimization": {
|
||||||
|
"method": "TPE",
|
||||||
|
"max_trials": 100
|
||||||
|
},
|
||||||
|
"surrogate": {
|
||||||
|
"enabled": true,
|
||||||
|
"type": "MLP",
|
||||||
|
"min_trials": 20
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## State Management
|
||||||
|
|
||||||
|
Uses Zustand for state management:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const {
|
||||||
|
nodes, // Current nodes
|
||||||
|
edges, // Current edges
|
||||||
|
selectedNode, // Currently selected node ID
|
||||||
|
validation, // Validation result
|
||||||
|
|
||||||
|
// Actions
|
||||||
|
addNode, // Add node at position
|
||||||
|
updateNodeData, // Update node configuration
|
||||||
|
onConnect, // Handle edge creation
|
||||||
|
validate, // Run validation
|
||||||
|
toIntent, // Serialize to Intent JSON
|
||||||
|
loadFromIntent, // Load graph from Intent
|
||||||
|
loadFromConfig, // Load from optimization_config.json
|
||||||
|
clear, // Clear canvas
|
||||||
|
} = useCanvasStore();
|
||||||
|
```
|
||||||
|
|
||||||
|
## Validation Rules
|
||||||
|
|
||||||
|
The canvas validates:
|
||||||
|
- **Required nodes**: Model, Solver, Objective, Algorithm
|
||||||
|
- **Minimum counts**: At least 1 design variable, 1 extractor
|
||||||
|
- **Valid connections**: Based on VALID_CONNECTIONS map
|
||||||
|
- **Node configuration**: All required fields filled
|
||||||
|
- **Connectivity**: Objectives must have connected extractors
|
||||||
|
|
||||||
|
## Chat Integration
|
||||||
|
|
||||||
|
The canvas integrates with Claude via:
|
||||||
|
- **Validate** - Get intelligent feedback on workflow
|
||||||
|
- **Analyze** - Get optimization recommendations
|
||||||
|
- **Execute with Claude** - Create study and optionally run optimization
|
||||||
|
|
||||||
|
## Files
|
||||||
|
|
||||||
|
### Core Schema
|
||||||
|
- `lib/canvas/schema.ts` - All node data types and connection rules
|
||||||
|
|
||||||
|
### Components
|
||||||
|
- `nodes/BaseNode.tsx` - Base node with handles, status, animations
|
||||||
|
- `nodes/*.tsx` - Specific node implementations
|
||||||
|
- `palette/NodePalette.tsx` - Draggable node list
|
||||||
|
- `panels/NodeConfigPanel.tsx` - Node configuration form
|
||||||
|
- `panels/ValidationPanel.tsx` - Error/warning display
|
||||||
|
- `panels/ChatPanel.tsx` - Claude response display
|
||||||
|
- `panels/ExecuteDialog.tsx` - Study name input
|
||||||
|
- `panels/ConfigImporter.tsx` - Import configuration dialog
|
||||||
|
- `panels/TemplateSelector.tsx` - Template selection dialog
|
||||||
|
|
||||||
|
### Hooks
|
||||||
|
- `useCanvasStore.ts` - Main state store
|
||||||
|
- `useCanvasChat.ts` - Chat bridge for Claude interaction
|
||||||
|
- `useIntentParser.ts` - Parse Claude messages for canvas updates
|
||||||
Reference in New Issue
Block a user