docs/WORKFLOW.md

# Development Workflow

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2026-06-10 | Initial release — full 5-tab Streamlit app deployed to HF Spaces |

## Architecture Decisions

### SDK Choice: Streamlit
- Chosen over Gradio for richer layout control (st.columns, st.tabs, custom CSS)
- Plotly for all visualizations — consistent dark theme, interactive tooltips
- st.components not needed — all 3D via Plotly native scatter3d
- No ZeroGPU needed — all computation is CPU-bound (numpy/scikit-learn)

### Data Strategy
- 8,000 synthetic DI-FCCVD reactor rows generated via physics-constrained numpy
- Bond order data computed from empirical ReaxFF scaling functions
- Cached via @st.cache_data to avoid re-computation on widget interaction
- CSV saved to data/ folder for persistence

### Visualization Choices
- Tab 1: Plotly Scatter3d for molecular visualization (no Three.js dependency)
- Tab 2: select_slider for frame-by-frame movie + Plotly line charts
- Tab 3: go.Indicator gauge + Plotly Heatmap for T vs cluster size
- Tab 4: go.Sankey for reaction pathway tree (replaces SVG tree)
- Tab 5: Histogram + correlation heatmap + styled dataframe

### ML Pipeline
- RandomForestRegressor (100 trees, max_depth=8) for all 5 pipeline models
- 5-fold cross-validation R² scores match expected domain physics
- Bayesian optimization approximated via weighted Pareto-front score on 8K runs
- No GPU required — all training < 5 seconds on CPU

## Change Log

### v2.0 — 2026-06-13 (Major Update)
**Based on AI Pipeline docx and ReaxFF paper (Nature Scientific Reports 2024)**

- **Multi-Catalyst Support**: Expanded from Fe to 6 catalyst types (Fe, Fe-C, Fe-S, Fe-Mo-C, Fe-Co-C, Fe-Ni-C)
- **Multi-Product CNT Types**: Added support for SWCNT, DWCNT, MWCNT with product type selector
- **Promoter Metal Tracking**: Added Mo, Co, Ni concentration tracking (ppm)
- **NEW Tab 6: ReaxFF Optimization**:
  - CMA-ES optimization simulation with loss function evolution (100 iterations)
  - Parameter subset optimization visualization (Bond → vdW)
  - Energy R² = 0.293, Force R² = 0.377 metrics
  - CNT nucleation probability calculator with catalyst comparison
  - Multi-catalyst Arrhenius plot (activation energies 1.6–2.1 eV)
  - DFT database statistics (300+ calculations, 3,000+ entries, 8 config types)
- **Enhanced AI Pipeline (Tab 5)**:
  - CNT product type distribution pie chart
  - Catalyst composition distribution pie chart
  - Expanded dataset from 14 to 21 columns
  - Added nucleation_barrier_eV, wall_layers tracking
- **New Modeling Functions**:
  - `simulate_reaxff_optimization()` — CMA-ES convergence simulation
  - `predict_nucleation_probability()` — Catalyst-aware nucleation prediction
  - Activation energy barriers by catalyst type from DFT/ReaxFF
- **Sidebar Enhancements**:
  - Target CNT Product selector (7 options)
  - Catalyst System selector (6 types)
- **Dataset Enhancements**: 8,000 rows × 21 columns with catalyst/product diversity
- Deployed to WellmatixGenAI HuggingFace Space
- Space URL: https://huggingface.co/spaces/WellmatixGenAI/cnt-ai-platform
- App URL: https://wellmatixgenai-cnt-ai-platform.hf.space

### v1.0 — 2026-06-10
- Built 5-tab Streamlit application from CNT AI Pipeline spec
- Implemented Digital Twin Reactor with 3D Plotly molecular viewer
- Implemented Decomposition Analysis with frame movie + bond order charts
- Implemented Catalyst & CNT Predictor with gauge and heatmap
- Implemented Pathways & Summary with Sankey diagram
- Implemented AI Pipeline tab with dataset overview + optimization
- Deployed to WellmatixGenAI HuggingFace Space as Docker container
- Space URL: https://huggingface.co/spaces/WellmatixGenAI/cnt-ai-platform
- App URL: https://wellmatixgenai-cnt-ai-platform.hf.space