feat: Add MLP surrogate with Turbo Mode for 100x faster optimization
Neural Acceleration (MLP Surrogate): - Add run_nn_optimization.py with hybrid FEA/NN workflow - MLP architecture: 4-layer (64->128->128->64) with BatchNorm/Dropout - Three workflow modes: - --all: Sequential export->train->optimize->validate - --hybrid-loop: Iterative Train->NN->Validate->Retrain cycle - --turbo: Aggressive single-best validation (RECOMMENDED) - Turbo mode: 5000 NN trials + 50 FEA validations in ~12 minutes - Separate nn_study.db to avoid overloading dashboard Performance Results (bracket_pareto_3obj study): - NN prediction errors: mass 1-5%, stress 1-4%, stiffness 5-15% - Found minimum mass designs at boundary (angle~30deg, thick~30mm) - 100x speedup vs pure FEA exploration Protocol Operating System: - Add .claude/skills/ with Bootstrap, Cheatsheet, Context Loader - Add docs/protocols/ with operations (OP_01-06) and system (SYS_10-14) - Update SYS_14_NEURAL_ACCELERATION.md with MLP Turbo Mode docs NX Automation: - Add optimization_engine/hooks/ for NX CAD/CAE automation - Add study_wizard.py for guided study creation - Fix FEM mesh update: load idealized part before UpdateFemodel() New Study: - bracket_pareto_3obj: 3-objective Pareto (mass, stress, stiffness) - 167 FEA trials + 5000 NN trials completed - Demonstrates full hybrid workflow 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Antoine
398
.claude/skills/DEV_DOCUMENTATION.md
Normal file
398
.claude/skills/DEV_DOCUMENTATION.md
Normal file
@@ -0,0 +1,398 @@
|
||||
# Developer Documentation Skill
|
||||
|
||||
**Version**: 1.0
|
||||
**Purpose**: Self-documenting system for Atomizer development. Use this skill to systematically document new features, protocols, extractors, and changes.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This skill enables **automatic documentation maintenance** during development. When you develop new features, use these commands to keep documentation in sync with code.
|
||||
|
||||
---
|
||||
|
||||
## Quick Commands for Developers
|
||||
|
||||
### Document New Feature
|
||||
|
||||
**Tell Claude**:
|
||||
```
|
||||
"Document the new {feature} I just added"
|
||||
```
|
||||
|
||||
Claude will:
|
||||
1. Analyze the code changes
|
||||
2. Determine which docs need updating
|
||||
3. Update protocol files
|
||||
4. Update CLAUDE.md if needed
|
||||
5. Bump version numbers
|
||||
6. Create changelog entry
|
||||
|
||||
### Document New Extractor
|
||||
|
||||
**Tell Claude**:
|
||||
```
|
||||
"I created a new extractor: extract_thermal.py. Document it."
|
||||
```
|
||||
|
||||
Claude will:
|
||||
1. Read the extractor code
|
||||
2. Add entry to SYS_12_EXTRACTOR_LIBRARY.md
|
||||
3. Add to extractors-catalog.md module
|
||||
4. Update __init__.py exports
|
||||
5. Create test file template
|
||||
|
||||
### Document Protocol Change
|
||||
|
||||
**Tell Claude**:
|
||||
```
|
||||
"I modified Protocol 10 to add {feature}. Update docs."
|
||||
```
|
||||
|
||||
Claude will:
|
||||
1. Read the code changes
|
||||
2. Update SYS_10_IMSO.md
|
||||
3. Bump version number
|
||||
4. Add to Version History
|
||||
5. Update cross-references
|
||||
|
||||
### Full Documentation Audit
|
||||
|
||||
**Tell Claude**:
|
||||
```
|
||||
"Audit documentation for {component/study/protocol}"
|
||||
```
|
||||
|
||||
Claude will:
|
||||
1. Check all related docs
|
||||
2. Identify stale content
|
||||
3. Flag missing documentation
|
||||
4. Suggest updates
|
||||
|
||||
---
|
||||
|
||||
## Documentation Workflow
|
||||
|
||||
### When You Add Code
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ 1. WRITE CODE │
|
||||
│ - New extractor, hook, or feature │
|
||||
└─────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ 2. TELL CLAUDE │
|
||||
│ "Document the new {feature} I added" │
|
||||
└─────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ 3. CLAUDE UPDATES │
|
||||
│ - Protocol files │
|
||||
│ - Skill modules │
|
||||
│ - Version numbers │
|
||||
│ - Cross-references │
|
||||
└─────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ 4. REVIEW & COMMIT │
|
||||
│ - Review changes │
|
||||
│ - Commit code + docs together │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Update Rules
|
||||
|
||||
### File → Document Mapping
|
||||
|
||||
| If You Change... | Update These Docs |
|
||||
|------------------|-------------------|
|
||||
| `optimization_engine/extractors/*` | SYS_12, extractors-catalog.md |
|
||||
| `optimization_engine/intelligent_optimizer.py` | SYS_10_IMSO.md |
|
||||
| `optimization_engine/plugins/*` | EXT_02_CREATE_HOOK.md |
|
||||
| `atomizer-dashboard/*` | SYS_13_DASHBOARD_TRACKING.md |
|
||||
| `atomizer-field/*` | SYS_14_NEURAL_ACCELERATION.md |
|
||||
| Any multi-objective code | SYS_11_MULTI_OBJECTIVE.md |
|
||||
| Study creation workflow | OP_01_CREATE_STUDY.md |
|
||||
| Run workflow | OP_02_RUN_OPTIMIZATION.md |
|
||||
|
||||
### Version Bumping Rules
|
||||
|
||||
| Change Type | Version Bump | Example |
|
||||
|-------------|--------------|---------|
|
||||
| Bug fix | Patch (+0.0.1) | 1.0.0 → 1.0.1 |
|
||||
| New feature (backwards compatible) | Minor (+0.1.0) | 1.0.0 → 1.1.0 |
|
||||
| Breaking change | Major (+1.0.0) | 1.0.0 → 2.0.0 |
|
||||
|
||||
### Required Updates for New Extractor
|
||||
|
||||
1. **SYS_12_EXTRACTOR_LIBRARY.md**:
|
||||
- Add to Quick Reference table (assign E{N} ID)
|
||||
- Add detailed section with code example
|
||||
|
||||
2. **skills/modules/extractors-catalog.md** (when created):
|
||||
- Add entry with copy-paste code snippet
|
||||
|
||||
3. **optimization_engine/extractors/__init__.py**:
|
||||
- Add import and export
|
||||
|
||||
4. **Tests**:
|
||||
- Create `tests/test_extract_{name}.py`
|
||||
|
||||
### Required Updates for New Protocol
|
||||
|
||||
1. **docs/protocols/system/SYS_{N}_{NAME}.md**:
|
||||
- Create full protocol document
|
||||
|
||||
2. **docs/protocols/README.md**:
|
||||
- Add to navigation tables
|
||||
|
||||
3. **.claude/skills/01_CHEATSHEET.md**:
|
||||
- Add to quick lookup table
|
||||
|
||||
4. **.claude/skills/02_CONTEXT_LOADER.md**:
|
||||
- Add loading rules
|
||||
|
||||
5. **CLAUDE.md**:
|
||||
- Add reference if major feature
|
||||
|
||||
---
|
||||
|
||||
## Self-Documentation Commands
|
||||
|
||||
### "Document this change"
|
||||
|
||||
Claude analyzes recent changes and updates relevant docs.
|
||||
|
||||
**Input**: Description of what you changed
|
||||
**Output**: Updated protocol files, version bumps, changelog
|
||||
|
||||
### "Create protocol for {feature}"
|
||||
|
||||
Claude creates a new protocol document following the template.
|
||||
|
||||
**Input**: Feature name and description
|
||||
**Output**: New SYS_* or EXT_* document
|
||||
|
||||
### "Verify documentation for {component}"
|
||||
|
||||
Claude checks that docs match code.
|
||||
|
||||
**Input**: Component name
|
||||
**Output**: List of discrepancies and suggested fixes
|
||||
|
||||
### "Generate changelog since {date/commit}"
|
||||
|
||||
Claude creates a changelog from git history.
|
||||
|
||||
**Input**: Date or commit reference
|
||||
**Output**: Formatted changelog
|
||||
|
||||
---
|
||||
|
||||
## Protocol Document Template
|
||||
|
||||
When creating new protocols, use this structure:
|
||||
|
||||
```markdown
|
||||
# {LAYER}_{NUMBER}_{NAME}.md
|
||||
|
||||
<!--
|
||||
PROTOCOL: {Full Name}
|
||||
LAYER: {Operations|System|Extensions}
|
||||
VERSION: 1.0
|
||||
STATUS: Active
|
||||
LAST_UPDATED: {YYYY-MM-DD}
|
||||
PRIVILEGE: {user|power_user|admin}
|
||||
LOAD_WITH: [{dependencies}]
|
||||
-->
|
||||
|
||||
## Overview
|
||||
{1-3 sentence description}
|
||||
|
||||
## When to Use
|
||||
| Trigger | Action |
|
||||
|---------|--------|
|
||||
|
||||
## Quick Reference
|
||||
{Tables, key parameters}
|
||||
|
||||
## Detailed Specification
|
||||
{Full content}
|
||||
|
||||
## Examples
|
||||
{Working examples}
|
||||
|
||||
## Troubleshooting
|
||||
| Symptom | Cause | Solution |
|
||||
|
||||
## Cross-References
|
||||
- Depends On: []
|
||||
- Used By: []
|
||||
|
||||
## Version History
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 1.0 | {DATE} | Initial release |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Changelog Format
|
||||
|
||||
When updating protocols, add to Version History:
|
||||
|
||||
```markdown
|
||||
## Version History
|
||||
|
||||
| Version | Date | Changes |
|
||||
|---------|------|---------|
|
||||
| 1.2.0 | 2025-12-05 | Added thermal gradient support |
|
||||
| 1.1.0 | 2025-12-01 | Improved error handling |
|
||||
| 1.0.0 | 2025-11-20 | Initial release |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Git
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
When documenting:
|
||||
```
|
||||
docs: Update SYS_12 with thermal extractor
|
||||
|
||||
- Added E11 thermal gradient extractor
|
||||
- Updated Quick Reference table
|
||||
- Added code example in Detailed section
|
||||
- Bumped version to 1.1.0
|
||||
```
|
||||
|
||||
### Pre-Commit Checklist
|
||||
|
||||
Before committing code changes:
|
||||
- [ ] Related docs updated
|
||||
- [ ] Version numbers bumped
|
||||
- [ ] Cross-references valid
|
||||
- [ ] Examples tested
|
||||
- [ ] CLAUDE.md updated if major feature
|
||||
|
||||
---
|
||||
|
||||
## Example: Document New Extractor
|
||||
|
||||
**You say**:
|
||||
```
|
||||
"I just created extract_thermal_gradient.py in optimization_engine/extractors/.
|
||||
It extracts thermal gradients from temperature fields. Document it."
|
||||
```
|
||||
|
||||
**Claude does**:
|
||||
|
||||
1. Reads `extract_thermal_gradient.py`
|
||||
2. Updates `SYS_12_EXTRACTOR_LIBRARY.md`:
|
||||
```markdown
|
||||
| E11 | Thermal Gradient | `extract_thermal_gradient()` | .op2 | K/mm |
|
||||
```
|
||||
3. Adds detailed section with code example
|
||||
4. Updates `__init__.py`:
|
||||
```python
|
||||
from .extract_thermal_gradient import extract_thermal_gradient
|
||||
__all__ = [..., 'extract_thermal_gradient']
|
||||
```
|
||||
5. Bumps SYS_12 version: 1.0 → 1.1
|
||||
6. Reports what was updated
|
||||
|
||||
---
|
||||
|
||||
## Example: Document Protocol Change
|
||||
|
||||
**You say**:
|
||||
```
|
||||
"I added a new stopping criterion to Protocol 10 based on improvement rate.
|
||||
Update the documentation."
|
||||
```
|
||||
|
||||
**Claude does**:
|
||||
|
||||
1. Reads relevant code changes
|
||||
2. Updates `SYS_10_IMSO.md`:
|
||||
- Adds to Configuration section
|
||||
- Updates Architecture diagram if needed
|
||||
- Adds to Quick Reference
|
||||
3. Bumps version: 2.1 → 2.2
|
||||
4. Adds Version History entry:
|
||||
```markdown
|
||||
| 2.2 | 2025-12-05 | Added improvement rate stopping criterion |
|
||||
```
|
||||
5. Updates cross-references if needed
|
||||
|
||||
---
|
||||
|
||||
## Keeping Docs in Sync
|
||||
|
||||
### Daily Development
|
||||
|
||||
```
|
||||
Morning: Start coding
|
||||
│
|
||||
├─► Write new feature
|
||||
│
|
||||
├─► Test feature
|
||||
│
|
||||
├─► "Claude, document the {feature} I just added"
|
||||
│
|
||||
└─► Commit code + docs together
|
||||
```
|
||||
|
||||
### Weekly Audit
|
||||
|
||||
```
|
||||
Friday:
|
||||
│
|
||||
├─► "Claude, audit documentation for recent changes"
|
||||
│
|
||||
├─► Review flagged issues
|
||||
│
|
||||
└─► Fix any stale documentation
|
||||
```
|
||||
|
||||
### Release Preparation
|
||||
|
||||
```
|
||||
Before release:
|
||||
│
|
||||
├─► "Claude, generate changelog since last release"
|
||||
│
|
||||
├─► "Claude, verify all protocol versions are consistent"
|
||||
│
|
||||
└─► Final review and version bump
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**To keep documentation in sync**:
|
||||
|
||||
1. **After coding**: Tell Claude what you changed
|
||||
2. **Be specific**: "I added X to Y" works better than "update docs"
|
||||
3. **Commit together**: Code and docs in same commit
|
||||
4. **Regular audits**: Weekly check for stale docs
|
||||
|
||||
**Claude handles**:
|
||||
- Finding which docs need updates
|
||||
- Following the template structure
|
||||
- Version bumping
|
||||
- Cross-reference updates
|
||||
- Changelog generation
|
||||
|
||||
**You handle**:
|
||||
- Telling Claude what changed
|
||||
- Reviewing Claude's updates
|
||||
- Final commit
|
||||
Reference in New Issue
Block a user