Warning, /AID2E-framework/docs/user-guide/configuration.md is written in an unsupported language. File is not indexed.
0001 # Configuration
0002
0003 ## Overview
0004
0005 The AID2E CLI recognizes four configuration types:
0006
0007 1. **DesignConfig** - Defines the parameter search space and constraints.
0008 2. **ProblemConfiguration** - Defines the design configuration, objectives, paths, and evaluation settings.
0009 3. **OptimizerConfiguration** - Defines optimizer selection and settings.
0010 4. **FullConfig** - Combines problem, optimizer, optional scheduler, and optional workflow configurations.
0011
0012 Although scheduler and workflow configurations are optional in `FullConfig`, both are required to run `aid2e optimize`.
0013
0014 ## Configuration Hierarchy
0015
0016 ```
0017 FullConfig (loaded via load_config())
0018 ├── problem: ProblemConfiguration
0019 │ ├── design_config: DesignConfig
0020 │ │ ├── DesignParameters (parameter groups)
0021 │ │ └── ParameterConstraint[] (optional)
0022 │ ├── objectives: ObjectiveDefinition[]
0023 │ ├── output_location and work_location
0024 │ ├── environment_config (optional)
0025 │ └── evaluation_config (optional)
0026 ├── optimizer: OptimizerConfiguration
0027 │ ├── name and type
0028 │ └── parameters (algorithm specific)
0029 ├── scheduler: SchedulerConfiguration (optional)
0030 └── workflows: WorkflowsConfiguration (optional)
0031 ```
0032
0033 ## Loading Configurations
0034
0035 ### Load a Problem and Design Configuration
0036
0037 ```python
0038 from aid2e.utilities.configurations import ProblemConfigLoader
0039
0040 cfg = ProblemConfigLoader.load("path/to/problem.config")
0041 print(cfg.design_config.get_parameter_names())
0042 ```
0043
0044 - The complete DTLZ2 example is defined in `examples/dtlz2/configurations/dtlz2_ax_joblib.yml`.
0045
0046 ### Load a Full Configuration
0047
0048 ```python
0049 from aid2e.utilities.configurations import load_config
0050
0051 # Load a full configuration
0052 `config = load_config("examples/dtlz2/configurations/dtlz2_ax_joblib.yml")`
0053
0054 # Access configuration components
0055 print(config.problem)
0056 print(config.problem.design_config)
0057 print(config.optimizer)
0058 print(config.scheduler)
0059 print(config.workflows)
0060 ```
0061
0062 The CLI detects configuration type from the top-level `problem`, `optimizer`, `design_space`, and `design_parameters` keys.
0063
0064 Relative problem paths, including design, output, and work paths, are resolved relative to the configuration file.
0065
0066 ## Problem Configuration
0067
0068 ```yaml
0069 problem:
0070 name: My Problem
0071 problem_type: toy
0072 output_location: ./output
0073 work_location: ./work
0074 design_parameters_file: ./design.params
0075 objectives:
0076 - name: f1
0077 direction: minimize
0078 ```
0079
0080 ### Objectives
0081
0082 Declare objectives once, under `problem.objectives`, with a unique name and a `minimize` or `maximize` direction. An objective can also define an optional objective plan. See the [workflow guide](workflows.md#objective-plans) for objective execution.
0083
0084 ### Design Configuration (`design.params`)
0085
0086 A problem defines its design space through exactly one of these fields:
0087
0088 - `design_parameters_file`: Load the design space from another file.
0089 - `inline_design`: Define the design space directly in the problem configuration.
0090
0091 ```yaml
0092 design_space:
0093 design_parameters:
0094 DTLZ2_variables:
0095 parameters:
0096 x1: {value: 0.5, bounds: [0.0, 1.0]}
0097 x2: {value: 0.0, bounds: [0.0, 1.0]}
0098 # ... x3-x10
0099
0100 parameter_constraints:
0101 - name: simple_constraint
0102 description: x1 must be less than 1.0
0103 rule: DTLZ2_variables.x1 < 1.0
0104 ```
0105
0106 ### Constraint Handling
0107
0108 Constraints are defined under `parameter_constraints` in the design space. `DesignConfig` validates their syntax and qualified parameter names when loading the configuration. `SearchSpace` stores them for optimizer use. This validation does not prove that an expression is supported by a particular optimizer.
0109
0110 Use fully qualified parameter names such as `DTLZ2_variables.x1`. Unknown qualified names and invalid Python syntax are rejected at configuration time.
0111
0112 #### Supported Ax Constraints
0113
0114 Ax supports sums or differences of distinct parameters with unit coefficients and a nonnegative numeric bound, using `<=`, `<`, `>=`, or `>`:
0115
0116 ```yaml
0117 rule: DTLZ2_variables.x1 + DTLZ2_variables.x2 <= 1.5
0118 ```
0119
0120 The current parser does not reliably support weighted terms, products, powers, or negative bounds. Such expressions may be skipped or translated incorrectly. Strict inequalities use a machine-epsilon adjustment; use explicit `<=` or `>=` bounds when a physical margin matters.
0121
0122 PyMOO does not currently enforce design constraints during candidate generation.
0123
0124 #### Checking Candidates
0125
0126 Use `SearchSpace.validate()` to check candidates against the original rules. This explicit check does not enable constraint enforcement in an optimizer.
0127
0128 ```python
0129 from aid2e.optimizers import SearchSpace
0130
0131 search_space = SearchSpace.from_design_config(config.problem.design_config)
0132
0133 # A candidate for the DTLZ2 configuration loaded above.
0134 candidate = {name: 0.5 for name in config.problem.design_config.get_parameter_names()}
0135 is_valid, errors = search_space.validate(candidate)
0136 ```
0137
0138 See [configuration notes](notes/configuration.md) for constraint methods and Ax conversion.
0139
0140 ## Optimizer Configuration
0141
0142 ```yaml
0143 optimizer:
0144 name: ax
0145 type: bayesian
0146 parameters:
0147 n_initial_samples: 4
0148 n_iterations: 8
0149 batch_size: 2
0150 ```
0151
0152 See the [optimizer guide](optimizers.md) for backend behavior and settings.
0153
0154 ## Scheduler Configuration
0155
0156 See the [scheduler guide](schedulers.md) for scheduler configuration and runner-specific settings.
0157
0158 ## Workflow Configuration
0159
0160 Use the `workflows: {workflows: [...]}` wrapper shown in the full example below. See the [workflow guide](workflows.md) for workflow structure, scheduler cascade, jobs, and objective plans.
0161
0162 ## Full Configuration
0163
0164 ### DTLZ2 Example
0165
0166 This abbreviated example follows the checked-in `examples/dtlz2/configurations/dtlz2_ax_constraints.yml` structure:
0167
0168 ```yaml
0169 problem:
0170 name: DTLZ2 Optimization
0171 problem_type: DTLZ2
0172 output_location: ./output/dtlz2
0173 work_location: ./work/dtlz2
0174
0175 inline_design:
0176 design_space:
0177 design_parameters:
0178 DTLZ2_variables:
0179 parameters:
0180 x1: {value: 0.5, bounds: [0.0, 1.0]}
0181 x2: {value: 0.5, bounds: [0.0, 1.0]}
0182 # ... x3-x10
0183 parameter_constraints:
0184 - name: x1_upper_bound
0185 rule: DTLZ2_variables.x1 < 1.0
0186 - name: sum_constraint
0187 rule: DTLZ2_variables.x1 + DTLZ2_variables.x2 < 1.5
0188
0189 objectives:
0190 - name: f1
0191 direction: minimize
0192 - name: f2
0193 direction: minimize
0194
0195 optimizer:
0196 name: ax
0197 type: bayesian
0198 parameters:
0199 initialization_strategy: sobol
0200 generator: BOTORCH_MODULAR
0201 n_initial_samples: 20
0202 n_iterations: 100
0203 batch_size: 4
0204 seed: 42
0205
0206 scheduler:
0207 runner_type: JobLibRunner
0208 parameters:
0209 n_jobs: 2
0210 backend: threading
0211
0212 workflows:
0213 workflows:
0214 - name: dtlz2_eval
0215 branches:
0216 - name: main
0217 stages:
0218 - name: evaluate
0219 objective_plan:
0220 steps:
0221 stages:
0222 - name: evaluate
0223 inline:
0224 entrypoint: examples.evaluators.dtlz2:objective_payload
0225 produces_objective: true
0226 ```
0227
0228 See the checked-in configuration for all ten design parameters and constraint descriptions.
0229
0230 ## See Also
0231
0232 - [Optimizer Guide](optimizers.md)
0233 - [Scheduler Guide](schedulers.md)
0234 - [Workflow Guide](workflows.md)
0235 - [DesignConfig API Documentation](../api-reference/utilities.md)
0236 - [SearchSpace API Documentation](../api-reference/optimizers.md)
0237 - [AxOptimizer API Documentation](../api-reference/optimizers.md)
