Atomizer/optimization_engine/schemas/README.md

# Atomizer Configuration Schemas

This directory contains JSON Schema files for validating Atomizer optimization study configurations.

## Files

- **optimization_config_schema.json** - Schema for `optimization_config.json` files
  - Validates study configuration including objectives, constraints, design variables
  - Ensures consistency across all studies
  - Based on Protocol 10 (single-objective) and Protocol 11 (multi-objective) standards

## Usage

### Validate a Configuration

Use the ConfigManager CLI tool:

```bash
python optimization_engine/config_manager.py studies/your_study/1_setup/optimization_config.json
```

### In Python Code

```python
from pathlib import Path
from optimization_engine.config_manager import ConfigManager

config_path = Path("studies/my_study/1_setup/optimization_config.json")
manager = ConfigManager(config_path)
manager.load_config()

if manager.validate():
    print("Configuration is valid")
    design_vars = manager.get_design_variables()
    objectives = manager.get_objectives()
else:
    print(manager.get_validation_report())
```

## Schema Standards

### Standard Configuration Format

Based on the drone_gimbal_arm_optimization study, the standard format is:

```json
{
  "study_name": "study_name_lowercase_with_underscores",
  "description": "Brief description of optimization problem",
  "engineering_context": "Real-world scenario and requirements",

  "optimization_settings": {
    "protocol": "protocol_11_multi_objective",  // or protocol_10_single_objective
    "n_trials": 30,
    "sampler": "NSGAIISampler",  // or TPESampler, CmaEsSampler
    "pruner": null,
    "timeout_per_trial": 600
  },

  "design_variables": [
    {
      "parameter": "nx_expression_name",
      "bounds": [min, max],
      "description": "What this parameter controls"
    }
  ],

  "objectives": [
    {
      "name": "objective_name",
      "goal": "minimize",  // or "maximize"
      "weight": 1.0,
      "description": "What this measures",
      "target": 100.0,  // optional
      "extraction": {
        "action": "extract_mass",  // or extract_stress, extract_displacement, etc.
        "domain": "result_extraction",
        "params": {
          "result_type": "mass",
          "metric": "total"
        }
      }
    }
  ],

  "constraints": [
    {
      "name": "constraint_name",
      "type": "less_than",  // or "greater_than"
      "threshold": 100.0,
      "description": "Engineering justification",
      "extraction": {
        "action": "extract_displacement",
        "domain": "result_extraction",
        "params": {
          "result_type": "displacement",
          "metric": "max"
        }
      }
    }
  ],

  "simulation": {
    "model_file": "Model.prt",
    "sim_file": "Model_sim1.sim",
    "fem_file": "Model_fem1.fem",
    "solver": "nastran",
    "analysis_types": ["static", "modal"]
  },

  "reporting": {
    "generate_plots": true,
    "save_incremental": true,
    "llm_summary": false
  }
}
```

## Field Name Standards

**IMPORTANT**: Use these field names (not legacy alternatives):

| Field | Standard Name | Legacy (DON'T USE) |
|-------|--------------|-------------------|
| Objective direction | `"goal"` | `"type"` |
| Design var bounds | `"bounds": [min, max]` | `"min": X, "max": Y"` |
| Design var name | `"parameter"` | `"name"` |
| Constraint limit | `"threshold"` | `"value"` |

## File Location Standard

Configuration files **MUST** be in the `1_setup/` directory:

```
studies/your_study/
├── 1_setup/
│   ├── optimization_config.json  ← HERE
│   └── workflow_config.json
├── 2_results/
└── run_optimization.py
```

## Validation Rules

The schema enforces:

1. **Study Name**: Lowercase with underscores, 3-100 characters
2. **Design Variable Bounds**: min < max
3. **Multi-Objective Consistency**:
   - 2-3 objectives → protocol_11_multi_objective + NSGAIISampler
   - 1 objective → protocol_10_single_objective + TPESampler/CmaEsSampler
4. **Extraction Specs**: All objectives and constraints must have extraction blocks
5. **File Extensions**: .prt, .sim, .fem
6. **Analysis Types**: static, modal, thermal, or buckling

## Common Validation Errors

### Error: "min must be < max"
```json
// BAD
{"parameter": "thickness", "bounds": [10, 5]}

// GOOD
{"parameter": "thickness", "bounds": [5, 10]}
```

### Error: "Multi-objective should use NSGAIISampler"
```json
// BAD
{
  "objectives": [{...}, {...}],  // 2 objectives
  "optimization_settings": {"sampler": "TPESampler"}  // Wrong sampler!
}

// GOOD
{
  "objectives": [{...}, {...}],
  "optimization_settings": {"sampler": "NSGAIISampler"}
}
```

### Error: "Config should be in 1_setup/"
Move your configuration file from study root to `1_setup/` directory.

## Dependencies

The ConfigManager requires:
```bash
pip install jsonschema>=4.17.0
```

## Migration from Legacy Format

If you have old configuration files with:
- `"type"` instead of `"goal"` in objectives
- `"min"/"max"` instead of `"bounds"` in design variables
- `"name"` instead of `"parameter"` in design variables
- `"value"` instead of `"threshold"` in constraints

See the migration tool (coming in Phase 1.2.1):
```bash
python optimization_engine/config_migrator.py studies/old_study/optimization_config.json
```

## References

- [Phase 1.2 Implementation Plan](../../docs/07_DEVELOPMENT/Phase_1_2_Implementation_Plan.md)
- [create-study Claude Skill](../../.claude/skills/create-study.md)
- [drone_gimbal_arm Example](../../studies/drone_gimbal_arm_optimization/1_setup/optimization_config.json)

## Questions?

For MVP development questions, refer to [DEVELOPMENT.md](../../DEVELOPMENT.md) or the MVP plan in `docs/07_DEVELOPMENT/Today_Todo.md`.