Atomizer/optimization_engine/feature_registry.json

{
  "feature_registry": {
    "version": "0.2.0",
    "last_updated": "2025-01-16",
    "description": "Comprehensive catalog of Atomizer capabilities for LLM-driven optimization",
    "architecture_doc": "docs/FEATURE_REGISTRY_ARCHITECTURE.md",
    "categories": {
      "engineering": {
        "description": "Physics-based operations for structural, thermal, and multi-physics analysis",
        "subcategories": {
          "extractors": {
            "stress_extractor": {
              "feature_id": "stress_extractor",
              "name": "Stress Extractor",
              "description": "Extracts von Mises stress from NX Nastran OP2 files",
              "category": "engineering",
              "subcategory": "extractors",
              "lifecycle_stage": "post_extraction",
              "abstraction_level": "primitive",
              "implementation": {
                "file_path": "optimization_engine/result_extractors/extractors.py",
                "function_name": "extract_stress_from_op2",
                "entry_point": "from optimization_engine.result_extractors.extractors import extract_stress_from_op2"
              },
              "interface": {
                "inputs": [
                  {
                    "name": "op2_file",
                    "type": "Path",
                    "required": true,
                    "description": "Path to OP2 file from NX solve",
                    "example": "bracket_sim1-solution_1.op2"
                  }
                ],
                "outputs": [
                  {
                    "name": "max_von_mises",
                    "type": "float",
                    "description": "Maximum von Mises stress across all elements",
                    "units": "MPa"
                  },
                  {
                    "name": "element_id_at_max",
                    "type": "int",
                    "description": "Element ID where max stress occurs"
                  }
                ]
              },
              "dependencies": {
                "features": [],
                "libraries": ["pyNastran"],
                "nx_version": "2412"
              },
              "usage_examples": [
                {
                  "description": "Minimize stress in bracket optimization",
                  "code": "result = extract_stress_from_op2(Path('bracket.op2'))\nmax_stress = result['max_von_mises']",
                  "natural_language": [
                    "minimize stress",
                    "reduce von Mises stress",
                    "find lowest stress configuration",
                    "optimize for minimum stress"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["displacement_extractor", "mass_extractor"],
                "typical_workflows": ["structural_optimization", "stress_minimization"],
                "prerequisites": ["nx_solver"]
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-10",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/stress_extractor.md"
              }
            },
            "displacement_extractor": {
              "feature_id": "displacement_extractor",
              "name": "Displacement Extractor",
              "description": "Extracts nodal displacements from NX Nastran OP2 files",
              "category": "engineering",
              "subcategory": "extractors",
              "lifecycle_stage": "post_extraction",
              "abstraction_level": "primitive",
              "implementation": {
                "file_path": "optimization_engine/result_extractors/extractors.py",
                "function_name": "extract_displacement_from_op2",
                "entry_point": "from optimization_engine.result_extractors.extractors import extract_displacement_from_op2"
              },
              "interface": {
                "inputs": [
                  {
                    "name": "op2_file",
                    "type": "Path",
                    "required": true,
                    "description": "Path to OP2 file from NX solve",
                    "example": "bracket_sim1-solution_1.op2"
                  }
                ],
                "outputs": [
                  {
                    "name": "max_displacement",
                    "type": "float",
                    "description": "Maximum displacement magnitude across all nodes",
                    "units": "mm"
                  },
                  {
                    "name": "node_id_at_max",
                    "type": "int",
                    "description": "Node ID where max displacement occurs"
                  }
                ]
              },
              "dependencies": {
                "features": [],
                "libraries": ["pyNastran"],
                "nx_version": "2412"
              },
              "usage_examples": [
                {
                  "description": "Minimize displacement in stiffness optimization",
                  "code": "result = extract_displacement_from_op2(Path('bracket.op2'))\nmax_disp = result['max_displacement']",
                  "natural_language": [
                    "minimize displacement",
                    "reduce deflection",
                    "maximize stiffness",
                    "limit deformation"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["stress_extractor", "mass_extractor"],
                "typical_workflows": ["stiffness_optimization", "multi_objective_optimization"],
                "prerequisites": ["nx_solver"]
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-10",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/displacement_extractor.md"
              }
            }
          },
          "metrics": {
            "description": "Advanced engineering metrics and composite measures"
          }
        }
      },
      "software": {
        "description": "Core algorithms and infrastructure for optimization and workflow management",
        "subcategories": {
          "optimization": {
            "optimization_runner": {
              "feature_id": "optimization_runner",
              "name": "Optimization Runner",
              "description": "Main optimization loop using Optuna TPE sampler with multi-objective support",
              "category": "software",
              "subcategory": "optimization",
              "lifecycle_stage": "all",
              "abstraction_level": "workflow",
              "implementation": {
                "file_path": "optimization_engine/runner.py",
                "function_name": "run_optimization",
                "entry_point": "from optimization_engine.runner import run_optimization"
              },
              "interface": {
                "inputs": [
                  {
                    "name": "config",
                    "type": "dict",
                    "required": true,
                    "description": "Optimization configuration with design variables, objectives, constraints",
                    "example": "{sim_file: 'bracket.sim', design_variables: [...], objectives: [...]}"
                  },
                  {
                    "name": "n_trials",
                    "type": "int",
                    "required": false,
                    "description": "Number of optimization trials",
                    "example": "50"
                  }
                ],
                "outputs": [
                  {
                    "name": "best_params",
                    "type": "dict",
                    "description": "Best design parameters found"
                  },
                  {
                    "name": "best_value",
                    "type": "float",
                    "description": "Best objective value achieved"
                  },
                  {
                    "name": "study",
                    "type": "optuna.Study",
                    "description": "Optuna study object with complete history"
                  }
                ]
              },
              "dependencies": {
                "features": ["nx_solver", "nx_updater", "hook_manager"],
                "libraries": ["optuna"],
                "nx_version": "2412"
              },
              "usage_examples": [
                {
                  "description": "Run bracket stress minimization",
                  "code": "best = run_optimization(config, n_trials=50)",
                  "natural_language": [
                    "run optimization",
                    "start optimization study",
                    "optimize my model",
                    "find best parameters"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["stress_extractor", "displacement_extractor", "report_generator"],
                "typical_workflows": ["complete_optimization_workflow"],
                "prerequisites": ["config_file", "sim_file"]
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-10",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/optimization_runner.md"
              }
            },
            "tpe_sampler": {
              "feature_id": "tpe_sampler",
              "name": "TPE Sampler",
              "description": "Tree-structured Parzen Estimator sampler for Bayesian optimization",
              "category": "software",
              "subcategory": "optimization",
              "lifecycle_stage": "optimization",
              "abstraction_level": "primitive",
              "implementation": {
                "file_path": "optimization_engine/runner.py",
                "function_name": "optuna.samplers.TPESampler",
                "entry_point": "import optuna.samplers.TPESampler"
              },
              "interface": {
                "inputs": [
                  {
                    "name": "n_startup_trials",
                    "type": "int",
                    "required": false,
                    "description": "Number of random trials before TPE kicks in",
                    "example": "20"
                  }
                ],
                "outputs": []
              },
              "dependencies": {
                "features": [],
                "libraries": ["optuna"],
                "nx_version": null
              },
              "usage_examples": [
                {
                  "description": "Use TPE for intelligent parameter sampling",
                  "natural_language": [
                    "use intelligent sampling",
                    "Bayesian optimization",
                    "TPE sampler"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["optimization_runner"],
                "typical_workflows": ["optimization_study"],
                "prerequisites": []
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-10",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/tpe_sampler.md"
              }
            }
          },
          "nx_integration": {
            "nx_solver": {
              "feature_id": "nx_solver",
              "name": "NX Solver",
              "description": "Executes NX Simcenter simulations via journal scripts",
              "category": "software",
              "subcategory": "nx_integration",
              "lifecycle_stage": "solve",
              "abstraction_level": "primitive",
              "implementation": {
                "file_path": "optimization_engine/nx_solver.py",
                "function_name": "run_nx_simulation",
                "entry_point": "from optimization_engine.nx_solver import run_nx_simulation"
              },
              "interface": {
                "inputs": [
                  {
                    "name": "sim_file",
                    "type": "Path",
                    "required": true,
                    "description": "Path to .sim file",
                    "example": "bracket_sim1.sim"
                  },
                  {
                    "name": "nastran_version",
                    "type": "str",
                    "required": false,
                    "description": "NX Nastran version",
                    "example": "2412"
                  },
                  {
                    "name": "timeout",
                    "type": "int",
                    "required": false,
                    "description": "Solve timeout in seconds",
                    "example": "300"
                  }
                ],
                "outputs": [
                  {
                    "name": "op2_file",
                    "type": "Path",
                    "description": "Path to generated OP2 file"
                  }
                ]
              },
              "dependencies": {
                "features": [],
                "libraries": [],
                "nx_version": "2412"
              },
              "usage_examples": [
                {
                  "description": "Run FEA solve for bracket",
                  "code": "op2_file = run_nx_simulation(sim_file=Path('bracket.sim'), nastran_version='2412')",
                  "natural_language": [
                    "run simulation",
                    "solve FEA",
                    "execute NX solve",
                    "run Nastran analysis"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["nx_updater", "stress_extractor"],
                "typical_workflows": ["optimization_loop"],
                "prerequisites": ["nx_updater"]
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-10",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/nx_solver.md"
              }
            },
            "nx_updater": {
              "feature_id": "nx_updater",
              "name": "NX Expression Updater",
              "description": "Updates NX model expressions (design variables) via journal scripts",
              "category": "software",
              "subcategory": "nx_integration",
              "lifecycle_stage": "pre_solve",
              "abstraction_level": "primitive",
              "implementation": {
                "file_path": "optimization_engine/nx_updater.py",
                "function_name": "update_nx_expressions",
                "entry_point": "from optimization_engine.nx_updater import update_nx_expressions"
              },
              "interface": {
                "inputs": [
                  {
                    "name": "prt_file",
                    "type": "Path",
                    "required": true,
                    "description": "Path to .prt file",
                    "example": "bracket.prt"
                  },
                  {
                    "name": "expressions",
                    "type": "dict",
                    "required": true,
                    "description": "Dictionary of expression names to values",
                    "example": "{wall_thickness: 4.5}"
                  }
                ],
                "outputs": [
                  {
                    "name": "success",
                    "type": "bool",
                    "description": "Whether update was successful"
                  }
                ]
              },
              "dependencies": {
                "features": [],
                "libraries": [],
                "nx_version": "2412"
              },
              "usage_examples": [
                {
                  "description": "Update wall thickness for optimization trial",
                  "code": "update_nx_expressions(prt_file=Path('bracket.prt'), expressions={'wall_thickness': 4.5})",
                  "natural_language": [
                    "update design variable",
                    "change parameter",
                    "set expression value",
                    "modify geometry"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["nx_solver"],
                "typical_workflows": ["optimization_loop"],
                "prerequisites": []
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-10",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/nx_updater.md"
              }
            }
          },
          "infrastructure": {
            "hook_manager": {
              "feature_id": "hook_manager",
              "name": "Hook Manager",
              "description": "Manages plugin lifecycle hooks for optimization workflow",
              "category": "software",
              "subcategory": "infrastructure",
              "lifecycle_stage": "all",
              "abstraction_level": "composite",
              "implementation": {
                "file_path": "optimization_engine/plugins/hook_manager.py",
                "function_name": "HookManager",
                "entry_point": "from optimization_engine.plugins.hook_manager import HookManager"
              },
              "interface": {
                "inputs": [
                  {
                    "name": "hook_type",
                    "type": "str",
                    "required": true,
                    "description": "Lifecycle point: pre_solve, post_solve, post_extraction",
                    "example": "pre_solve"
                  },
                  {
                    "name": "context",
                    "type": "dict",
                    "required": true,
                    "description": "Context data passed to hooks (trial_number, design_variables, etc.)"
                  }
                ],
                "outputs": [
                  {
                    "name": "execution_history",
                    "type": "list",
                    "description": "List of hooks executed with timestamps and success status"
                  }
                ]
              },
              "dependencies": {
                "features": [],
                "libraries": [],
                "nx_version": null
              },
              "usage_examples": [
                {
                  "description": "Execute pre-solve hooks before FEA",
                  "code": "hook_manager.execute_hooks('pre_solve', context={'trial': 1})",
                  "natural_language": [
                    "run pre-solve plugins",
                    "execute hooks before solving",
                    "trigger lifecycle events"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["detailed_logger", "optimization_logger"],
                "typical_workflows": ["optimization_runner"],
                "prerequisites": []
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-16",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/hook_manager.md"
              }
            },
            "path_resolver": {
              "feature_id": "path_resolver",
              "name": "Path Resolver",
              "description": "Intelligent project path resolution using marker files",
              "category": "software",
              "subcategory": "infrastructure",
              "lifecycle_stage": "all",
              "abstraction_level": "primitive",
              "implementation": {
                "file_path": "atomizer_paths.py",
                "function_name": "root, optimization_engine, studies, tests",
                "entry_point": "from atomizer_paths import root, optimization_engine, studies"
              },
              "interface": {
                "inputs": [],
                "outputs": [
                  {
                    "name": "root_path",
                    "type": "Path",
                    "description": "Project root directory path"
                  }
                ]
              },
              "dependencies": {
                "features": [],
                "libraries": ["pathlib"],
                "nx_version": null
              },
              "usage_examples": [
                {
                  "description": "Get project root from any script location",
                  "code": "from atomizer_paths import root\nproject_root = root()",
                  "natural_language": [
                    "find project root",
                    "get base directory",
                    "resolve paths"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["all features"],
                "typical_workflows": ["all workflows"],
                "prerequisites": []
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-16",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/path_resolver.md"
              }
            },
            "study_manager": {
              "feature_id": "study_manager",
              "name": "Study Manager",
              "description": "Creates and manages optimization study folders with standardized structure",
              "category": "software",
              "subcategory": "infrastructure",
              "lifecycle_stage": "pre_optimization",
              "abstraction_level": "composite",
              "implementation": {
                "file_path": "optimization_engine/runner.py",
                "function_name": "setup_study",
                "entry_point": "from optimization_engine.runner import setup_study"
              },
              "interface": {
                "inputs": [
                  {
                    "name": "study_name",
                    "type": "str",
                    "required": true,
                    "description": "Name of the study",
                    "example": "bracket_stress_minimization"
                  }
                ],
                "outputs": [
                  {
                    "name": "study_path",
                    "type": "Path",
                    "description": "Path to created study folder"
                  }
                ]
              },
              "dependencies": {
                "features": ["path_resolver"],
                "libraries": [],
                "nx_version": null
              },
              "usage_examples": [
                {
                  "description": "Create new optimization study",
                  "code": "study_path = setup_study('bracket_stress_minimization')",
                  "natural_language": [
                    "create new study",
                    "set up optimization",
                    "create study folder"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["optimization_runner"],
                "typical_workflows": ["study_creation"],
                "prerequisites": []
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-16",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/study_manager.md"
              }
            }
          },
          "logging": {
            "detailed_logger": {
              "feature_id": "detailed_logger",
              "name": "Detailed Trial Logger",
              "description": "Creates detailed per-trial logs with complete iteration trace",
              "category": "software",
              "subcategory": "logging",
              "lifecycle_stage": "pre_solve",
              "abstraction_level": "primitive",
              "implementation": {
                "file_path": "optimization_engine/plugins/pre_solve/detailed_logger.py",
                "function_name": "DetailedLogger",
                "entry_point": "from optimization_engine.plugins.pre_solve.detailed_logger import DetailedLogger"
              },
              "interface": {
                "inputs": [
                  {
                    "name": "context",
                    "type": "dict",
                    "required": true,
                    "description": "Hook context with trial data"
                  }
                ],
                "outputs": [
                  {
                    "name": "log_file",
                    "type": "Path",
                    "description": "Path to trial log file"
                  }
                ]
              },
              "dependencies": {
                "features": ["hook_manager"],
                "libraries": [],
                "nx_version": null
              },
              "usage_examples": [
                {
                  "description": "Log detailed trial information",
                  "natural_language": [
                    "create trial log",
                    "log trial details",
                    "track iteration"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["optimization_logger"],
                "typical_workflows": ["optimization_runner"],
                "prerequisites": ["hook_manager"]
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-16",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/detailed_logger.md"
              }
            },
            "optimization_logger": {
              "feature_id": "optimization_logger",
              "name": "Optimization Progress Logger",
              "description": "Creates high-level optimization.log with progress tracking",
              "category": "software",
              "subcategory": "logging",
              "lifecycle_stage": "pre_solve",
              "abstraction_level": "primitive",
              "implementation": {
                "file_path": "optimization_engine/plugins/pre_solve/optimization_logger.py",
                "function_name": "OptimizationLogger",
                "entry_point": "from optimization_engine.plugins.pre_solve.optimization_logger import OptimizationLogger"
              },
              "interface": {
                "inputs": [
                  {
                    "name": "context",
                    "type": "dict",
                    "required": true,
                    "description": "Hook context with trial data"
                  }
                ],
                "outputs": [
                  {
                    "name": "log_entry",
                    "type": "str",
                    "description": "Log entry appended to optimization.log"
                  }
                ]
              },
              "dependencies": {
                "features": ["hook_manager"],
                "libraries": [],
                "nx_version": null
              },
              "usage_examples": [
                {
                  "description": "Track optimization progress",
                  "natural_language": [
                    "log optimization progress",
                    "track trials",
                    "monitor optimization"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["detailed_logger"],
                "typical_workflows": ["optimization_runner"],
                "prerequisites": ["hook_manager"]
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-16",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/optimization_logger.md"
              }
            }
          }
        }
      },
      "ui": {
        "description": "User interface components for dashboard and visualization",
        "subcategories": {
          "dashboard_widgets": {
            "optimization_progress_chart": {
              "feature_id": "optimization_progress_chart",
              "name": "Optimization Progress Chart",
              "description": "Real-time chart showing optimization convergence",
              "category": "ui",
              "subcategory": "dashboard_widgets",
              "lifecycle_stage": "post_optimization",
              "abstraction_level": "composite",
              "implementation": {
                "file_path": "dashboard/frontend/components/ProgressChart.js",
                "function_name": "OptimizationProgressChart",
                "entry_point": "new OptimizationProgressChart(containerId)"
              },
              "interface": {
                "inputs": [
                  {
                    "name": "trial_data",
                    "type": "list[dict]",
                    "required": true,
                    "description": "List of trial results with objective values",
                    "example": "[{trial: 1, value: 45.3}, {trial: 2, value: 42.1}]"
                  }
                ],
                "outputs": [
                  {
                    "name": "chart_element",
                    "type": "HTMLElement",
                    "description": "Rendered chart DOM element"
                  }
                ]
              },
              "dependencies": {
                "features": [],
                "libraries": ["Chart.js"],
                "nx_version": null
              },
              "usage_examples": [
                {
                  "description": "Display optimization progress in dashboard",
                  "code": "chart = new OptimizationProgressChart('chart-container')\nchart.update(trial_data)",
                  "natural_language": [
                    "show optimization progress",
                    "display convergence chart",
                    "visualize trial results",
                    "plot optimization history"
                  ]
                }
              ],
              "composition_hints": {
                "combines_with": ["trial_history_table", "best_parameters_display"],
                "typical_workflows": ["dashboard_view", "result_monitoring"],
                "prerequisites": ["optimization_runner"]
              },
              "metadata": {
                "author": "Antoine Polvé",
                "created": "2025-01-10",
                "status": "stable",
                "tested": true,
                "documentation_url": "docs/features/dashboard_widgets.md"
              }
            }
          }
        }
      },
      "analysis": {
        "description": "Post-processing, decision support, and intelligent analysis features",
        "subcategories": {
          "decision_support": {
            "description": "Features for surrogate quality, sensitivity analysis, and recommendations"
          }
        }
      }
    },
    "feature_templates": {
      "description": "Templates for creating new features following established patterns",
      "extractor_template": {
        "description": "Template for creating new result extractors (thermal, modal, fatigue, etc.)",
        "pattern": "Read OP2/F06 file → Parse result data → Return dictionary with max/min/avg values",
        "example_features": ["stress_extractor", "displacement_extractor"],
        "required_fields": ["feature_id", "name", "description", "implementation", "interface", "usage_examples"]
      },
      "composite_metric_template": {
        "description": "Template for creating composite metrics (RSS, weighted objectives, etc.)",
        "pattern": "Accept multiple extractor outputs → Apply formula → Return single metric value",
        "example_features": [],
        "required_fields": ["feature_id", "dependencies.features", "composition_hints.composed_from"]
      },
      "hook_plugin_template": {
        "description": "Template for creating new lifecycle hooks",
        "pattern": "Register hook function → Execute at lifecycle point → Return context",
        "example_features": ["detailed_logger", "optimization_logger"],
        "required_fields": ["lifecycle_stage", "composition_hints.prerequisites"]
      }
    },
    "workflow_recipes": {
      "description": "Common feature compositions for typical use cases",
      "structural_optimization": {
        "description": "Complete workflow for structural stress minimization",
        "features": [
          "study_manager",
          "nx_updater",
          "nx_solver",
          "stress_extractor",
          "optimization_runner",
          "detailed_logger",
          "optimization_logger"
        ],
        "sequence": [
          "1. Create study folder (study_manager)",
          "2. Update design variables (nx_updater)",
          "3. Run FEA solve (nx_solver)",
          "4. Extract stress (stress_extractor)",
          "5. Evaluate objective (optimization_runner)",
          "6. Log results (detailed_logger, optimization_logger)",
          "7. Repeat for n_trials"
        ]
      },
      "multi_objective_optimization": {
        "description": "Workflow for multi-objective optimization (stress + displacement)",
        "features": [
          "study_manager",
          "nx_updater",
          "nx_solver",
          "stress_extractor",
          "displacement_extractor",
          "optimization_runner",
          "detailed_logger"
        ],
        "sequence": [
          "1. Create study folder",
          "2. Update design variables",
          "3. Run FEA solve",
          "4. Extract stress AND displacement",
          "5. Evaluate both objectives with weights",
          "6. Log results",
          "7. Repeat for n_trials"
        ]
      }
    }
  }
}