feat: Add TrialManager and DashboardDB for unified trial management

- Add TrialManager (trial_manager.py) for consistent trial_NNNN naming
- Add DashboardDB (dashboard_db.py) for Optuna-compatible database schema
- Update CLAUDE.md with trial management documentation
- Update ATOMIZER_CONTEXT.md with v1.8 trial system
- Update cheatsheet v2.2 with new utilities
- Update SYS_14 protocol to v2.3 with TrialManager integration
- Add LAC learnings for trial management patterns
- Add archive/README.md for deprecated code policy

Key principles:
- Trial numbers NEVER reset (monotonic)
- Folders NEVER get overwritten
- Database always synced with filesystem
- Surrogate predictions are NOT trials (only FEA results)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2025-12-28 12:20:19 -05:00
parent f13563d7ab
commit cf454f6e40
10 changed files with 1402 additions and 9 deletions

View File

@@ -140,8 +140,10 @@ Atomizer/
│ └── extensions/ # EXT_01 - EXT_04
├── optimization_engine/ # Core Python modules
│ ├── extractors/ # Physics extraction library
── gnn/ # GNN surrogate module (Zernike)
── gnn/ # GNN surrogate module (Zernike)
│ └── utils/ # Utilities (dashboard_db, trial_manager)
├── studies/ # User studies
├── archive/ # Deprecated code (for reference)
└── atomizer-dashboard/ # React dashboard
```
@@ -170,6 +172,70 @@ python run_gnn_turbo.py --trials 5000
**Full documentation**: `docs/protocols/system/SYS_14_NEURAL_ACCELERATION.md`
## Trial Management & Dashboard Compatibility
### Trial Naming Convention
**CRITICAL**: Use `trial_NNNN/` folders (zero-padded, never reused, never overwritten).
```
2_iterations/
├── trial_0001/ # First FEA validation
│ ├── params.json # Input parameters
│ ├── results.json # Output objectives
│ ├── _meta.json # Metadata (source, timestamps, predictions)
│ └── *.op2, *.fem... # FEA files
├── trial_0002/
└── ...
```
**Key Principles:**
- Trial numbers are **global and monotonic** - never reset between runs
- Only **FEA-validated results** are trials (surrogate predictions are ephemeral)
- Each trial folder is **immutable** after completion
### Using TrialManager
```python
from optimization_engine.utils.trial_manager import TrialManager
tm = TrialManager(study_dir, "my_study_name")
# Create new trial (reserves folder + DB row)
trial = tm.new_trial(params={'rib_thickness': 10.5}, source="turbo")
# After FEA completes
tm.complete_trial(
trial_number=trial['trial_number'],
objectives={'wfe_40_20': 5.63, 'mass_kg': 118.67},
weighted_sum=175.87,
is_feasible=True
)
```
### Dashboard Database Compatibility
All studies must use Optuna-compatible SQLite schema for dashboard integration:
```python
from optimization_engine.utils.dashboard_db import DashboardDB
db = DashboardDB(study_dir / "3_results" / "study.db", "study_name")
db.log_trial(params={...}, objectives={...}, weighted_sum=175.87)
```
**Required Tables** (Optuna schema):
- `trials` - with `trial_id`, `number`, `study_id`, `state`
- `trial_values` - objective values
- `trial_params` - parameter values
- `trial_user_attributes` - custom metadata
**To convert legacy databases:**
```python
from optimization_engine.utils.dashboard_db import convert_custom_to_optuna
convert_custom_to_optuna(db_path, "study_name")
```
## CRITICAL: NX Open Development Protocol
### Always Use Official Documentation First