Skip to content

Configuration Classes

ropt.config

Configuration classes for ensemble-based optimization.

Pydantic models that together define a complete optimization setup. Each corresponds to a top-level section of the configuration dictionary that describes a single optimization. See Configuration Sections for the fields, their defaults and worked examples.

VariablesConfig

Configuration class for optimization variables.

VariablesConfig defines optimization variable settings: bounds, types, mask, and perturbation settings. It is the variables section of the configuration.

See Configuration Sections for detailed descriptions and usage examples.

The perturbation defaults are DEFAULT_PERTURBATION_MAGNITUDE, DEFAULT_PERTURBATION_TYPE (one of PerturbationType) and DEFAULT_PERTURBATION_BOUNDARY_TYPE (one of BoundaryType).

Variables reach the optimizer as \(y = (x - o)/s\) and are reported back as \(x = s\,y + o\), using scales and offsets. A scale is a change of units, so every entry must be positive. There is no auto_scale here: scales_and_offsets_from_bounds derives scales from the bounds when that is what is wanted.

Attributes:

Name Type Description
variable_count int

Number of variables.
lower_bounds Array1D

Lower bounds for the variables (default: \(-\infty\)).
upper_bounds Array1D

Upper bounds for the variables (default: \(+\infty\)).
types ItemOrTuple[VariableType]

The type of each variable (default: continuous).
mask Array1DBool

Which variables are free (default: all free).
scales Array1D

Scale factors for the variables (default: 1.0).
offsets Array1D

Offsets for the variables (default: 0.0).
perturbation_magnitudes Array1D

Magnitude of the perturbation of each variable.
perturbation_types ItemOrTuple[PerturbationType]

Type of perturbation for each variable.
boundary_types ItemOrTuple[BoundaryType]

Handling of perturbations that violate a bound.
samplers Keys

Sampler for each variable, by key (default: "0").
seed ItemOrTuple[int]

Seed for the random number generator used by the samplers.

ObjectiveFunctionsConfig

Configuration class for objective functions.

ObjectiveFunctionsConfig defines objective function settings. It is the objectives section of the configuration.

See Configuration Sections for detailed descriptions and usage examples.

The reported target_objective is divided by the estimated auto_scale factors, so optimizations that differ in that setting compare only through functions.objectives or their variables.

Attributes:

Name Type Description
weights Array1D

Weights for the objective functions (default: 1.0).
scales Array1D

Scale factors for the objective functions (default: 1.0).
offsets Array1D

Offsets for the objective functions (default: 0.0).
auto_scale bool

Estimate additional scales from the first batch.
maximize Array1DBool

Which objectives to maximize (default: False).
realization_filters Keys

Realization filter per objective, by key (default: none).
function_estimators Keys

Function estimator per objective, by key (default: "0").

LinearConstraintsConfig

Configuration class for linear constraints.

LinearConstraintsConfig defines linear constraints. It is the linear_constraints section of the configuration.

See Configuration Sections for detailed descriptions and usage examples.

Attributes:

Name Type Description
coefficients Array2D

Matrix of coefficients for the linear constraints.
lower_bounds Array1D

Lower bounds for the right-hand side of the constraint equations.
upper_bounds Array1D

Upper bounds for the right-hand side of the constraint equations.
scales Array1D

Scale factors for the constraint equations (default: 1.0).
auto_scale bool

Estimate an additional scale for each equation.

NonlinearConstraintsConfig

Configuration class for non-linear constraints.

NonlinearConstraintsConfig defines nonlinear constraints. It is the nonlinear_constraints section of the configuration.

See Configuration Sections for detailed descriptions and usage examples.

Attributes:

Name Type Description
lower_bounds Array1D

Lower bounds for the right-hand-side values.
upper_bounds Array1D

Upper bounds for the right-hand-side values.
scales Array1D

Scale factors for the constraint functions (default: 1.0).
auto_scale Array1DBool

Which constraints to auto-scale (default: False).
realization_filters Keys

Realization filter per constraint, by key (default: none).
function_estimators Keys

Function estimator per constraint, by key (default: "0").

RealizationsConfig

Configuration class for realizations.

RealizationsConfig defines realization ensemble settings. It is the realizations section of the configuration.

See Configuration Sections for detailed descriptions and usage examples.

realization_min_success defaults to the number of realizations, so a single failure ends the optimization.

Attributes:

Name Type Description
weights Array1D

Weights for the realizations (default: 1.0).
realization_min_success NonNegativeInt | None

Minimum number of successful realizations.

OptimizerConfig

Configuration class for the optimization algorithm.

OptimizerConfig defines the settings that control how an optimization is managed. It is the optimizer section of the configuration.

See Configuration Sections for detailed descriptions and usage examples.

Warning

Capturing output rewires process-global state, so one optimization at a time can do it. A second optimization that sets stdout or stderr while another holds the capture raises WorkflowError.

Attributes:

Name Type Description
max_batches PositiveInt | None

Maximum number of batch evaluations (optional).
max_functions PositiveInt | None

Maximum number of function evaluations (optional).
output_dir Path | None

Output directory for the optimizer (optional).
stdout Path | None

File to redirect optimizer standard output (optional).
stderr Path | None

File to redirect optimizer standard error (optional).

BackendConfig

Configuration class for the optimization backend.

BackendConfig defines the configuration for the optimization algorithm used by an optimization backend plugin.

See Configuration Sections for detailed descriptions and usage examples.

Attributes:

Name Type Description
method str

Name of the optimization method.
max_iterations PositiveInt | None

Maximum number of iterations (optional).
convergence_tolerance NonNegativeFloat | None

Convergence tolerance, on scaled quantities (optional).
parallel bool

Allow parallelized function evaluations (default: False).
verbose bool | NonNegativeInt | None

How much the optimizer reports (optional).
options dict[str, Any] | list[str] | None

Generic options for the optimizer (optional).

GradientConfig

Configuration class for gradient calculations.

GradientConfig specifies how gradients are estimated in gradient-based optimizers. It is the gradient section of the configuration.

See Configuration Sections for detailed descriptions and usage examples.

number_of_perturbations defaults to DEFAULT_NUMBER_OF_PERTURBATIONS, and perturbation_min_success to number_of_perturbations.

Attributes:

Name Type Description
number_of_perturbations PositiveInt

Number of perturbations.
perturbation_min_success PositiveInt | None

Minimum number of successful perturbations.
merge_realizations bool

Merge realizations for the final gradient.
evaluation_policy Literal['speculative', 'separate', 'auto']

How to evaluate functions and gradients.

FunctionEstimatorConfig

Configuration class for function estimators.

FunctionEstimatorConfig configures a function estimator plugin, which controls how objective and constraint function values (and their gradients) are combined across realizations.

See Configuration Sections for detailed descriptions and usage examples.

Attributes:

Name Type Description
method str

Name of the function estimator method.
options dict[str, Any]

Dictionary of options for the function estimator.

RealizationFilterConfig

Configuration class for realization filters.

RealizationFilterConfig configures a RealizationFilter plugin that adjusts per-realization weights.

See Configuration Sections for detailed descriptions and usage examples.

Attributes:

Name Type Description
method str

Name of the realization filter method.
options dict[str, Any]

Dictionary of options for the realization filter.

SamplerConfig

Configuration class for samplers.

SamplerConfig configures a Sampler plugin that generates variable perturbations for gradient estimation.

See Configuration Sections for detailed descriptions and usage examples.

Attributes:

Name Type Description
method str

Name of the sampler method.
options dict[str, Any]

Dictionary of options for the sampler.
shared bool

Whether to share perturbation values between realizations (default: False).

ropt.config.constants

Default values used by the configuration classes.

See Configuration Sections for detailed explanations of these defaults and their interactions.

DEFAULT_SEED module-attribute 

DEFAULT_SEED: Final = 1

Default seed for random number generators used by samplers.

DEFAULT_NUMBER_OF_PERTURBATIONS module-attribute 

DEFAULT_NUMBER_OF_PERTURBATIONS: Final = 5

Default number of perturbations for gradient estimation.

DEFAULT_PERTURBATION_MAGNITUDE module-attribute 

DEFAULT_PERTURBATION_MAGNITUDE: Final = 0.005

Default scaling factor applied to sampler-generated perturbation values.

DEFAULT_PERTURBATION_BOUNDARY_TYPE module-attribute 

DEFAULT_PERTURBATION_BOUNDARY_TYPE: Final = (
    BoundaryType.MIRROR
)

Default boundary handling for perturbations that violate variable bounds.

DEFAULT_PERTURBATION_TYPE module-attribute 

DEFAULT_PERTURBATION_TYPE: Final = PerturbationType.ABSOLUTE

Default interpretation of perturbation magnitudes.

ropt.config.options

Schema models for describing and validating plugin options.

A plugin declares the options that each of its methods accepts. The schema turns that declaration into a pydantic model that validates the options field of a configuration section, and into a Markdown table for the documentation.

OptionsSchemaModel

Bases: BaseModel

The schema for the options of every method of a plugin.

The methods are described by a mapping of method names to MethodSchemaModel objects, each describing a method supported by the plugin.

Attributes:

Name Type Description
methods dict[str, MethodSchemaModel[Any]]

A mapping of method names to their schemas.
common list[MethodSchemaModel[Any]]

Optional method schemas defining options shared by all methods.

Example: 

from ropt.config.options import OptionsSchemaModel

schema = OptionsSchemaModel.model_validate(
    {
        "methods": {
            "method": {"options": {"a": float, "b": int | str}},
        }
    }
)

options = schema.get_options_model("method")
print(options.model_validate({"a": 1.0, "b": 1}))  # a=1.0 b=1

get_options_model 

get_options_model(method: str) -> type[BaseModel]

Create a pydantic model for validating the options of one method.

The method is looked up by name, case-insensitively, and its options are combined with the common options that it does not exclude.

Parameters:

Name Type Description Default
method str

The name of the method for which to create the options model.

 required

Returns:

Type Description
type[BaseModel]

A model that validates the options of the given method.

Raises:

Type Description
ValueError

If the method is not found in the schema.

MethodSchemaModel

Bases: BaseModel

The schema for the options of a single method.

Attributes:

Name Type Description
options dict[str, T]

A dictionary of option names and their types.
url HttpUrl | None

An optional URL for the plugin.
exclude set[str]

A set of common options to exclude for this method.
title str | None

An optional title for common method sections.
doc str | None

An optional description of the common section.

gen_options_table 

gen_options_table(schema: dict[str, Any]) -> str

Generate a Markdown table documenting plugin options.

Common options are listed first, followed by a table of method-specific options, one row per method. A method whose schema provides a URL is hyperlinked to it.

Parameters:

Name Type Description Default
schema dict[str, Any]

A dictionary representing the schema of plugin options.

 required

Returns:

Type Description
str

A string containing the documented plugin options.