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:

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

In Python Code

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:

{
  "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"

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

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

Error: "Multi-objective should use NSGAIISampler"

// 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:

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):

python optimization_engine/config_migrator.py studies/old_study/optimization_config.json

References

• Phase 1.2 Implementation Plan
• create-study Claude Skill
• drone_gimbal_arm Example

Questions?

For MVP development questions, refer to DEVELOPMENT.md or the MVP plan in docs/07_DEVELOPMENT/Today_Todo.md.