Skip to content

ropt Documentation

Configuration Classes

Configuration Classes

The ropt.config package contains the Pydantic models that define an optimization run. Each class corresponds to a top-level section of the configuration dictionary consumed by EnOptContext and the optimization functions.

For detailed descriptions of each field, including defaults, usage patterns, and examples, see the Configuration user-manual page.

ropt.config

Configuration classes for ensemble-based optimization.

The ropt.config module provides Pydantic-based configuration classes that collectively define a complete optimization setup. These classes are used to construct an EnOptContext object, which serves as the in-memory configuration for a single optimization run.

VariablesConfig

Configuration class for optimization variables.

VariablesConfig defines optimization variable settings for an EnOptContext object: bounds, types, mask, and perturbation settings.

See the Configuration guide for detailed descriptions and usage examples.

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`	`ArrayEnum`	Optional variable types.
`mask`	`Array1DBool`	Optional boolean mask indicating free variables.
`scales`	`Array1D`	Scale factors for the variables (default: 1.0).
`offsets`	`Array1D`	Offsets for the variables (default: 0.0).
`perturbation_magnitudes`	`Array1D`	Magnitudes of the perturbations for each variable (default: `DEFAULT_PERTURBATION_MAGNITUDE`).
`perturbation_types`	`ArrayEnum`	Type of perturbation for each variable (see `PerturbationType`, default: `DEFAULT_PERTURBATION_TYPE`).
`boundary_types`	`ArrayEnum`	How to handle perturbations that violate boundary conditions (see `BoundaryType`, default: `DEFAULT_PERTURBATION_BOUNDARY_TYPE`).
`samplers`	`Keys`	Sampler to apply to 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 for an EnOptContext object.

See the Configuration guide for detailed descriptions and usage examples.

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 to apply to each objective, by key, `None` to apply none (default: `None`).
`function_estimators`	`Keys`	Function estimator to apply to each objective, by key (default: `"0"`).

LinearConstraintsConfig

Configuration class for linear constraints.

LinearConstraintsConfig defines linear constraints used as the linear_constraints field of an EnOptContext object.

See the Configuration guide 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 used as the nonlinear_constraints field of an EnOptContext object.

See the Configuration guide 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 estimate an additional scale for, from the first batch (default: `False`).
`realization_filters`	`Keys`	Realization filter to apply to each constraint, by key, `None` to apply none (default: `None`).
`function_estimators`	`Keys`	Function estimator to apply to each constraint, by key (default: `"0"`).

RealizationsConfig

Configuration class for realizations.

RealizationsConfig defines realization ensemble settings for an EnOptContext object.

See the Configuration guide for detailed descriptions and usage examples.

Attributes:

Name	Type	Description
`weights`	`Array1D`	Weights for the realizations (default: 1.0).
`realization_min_success`	`NonNegativeInt \| None`	Minimum number of successful realizations (default: equal to the number of realizations).

OptimizerConfig

Configuration class for the optimization algorithm.

OptimizerConfig defines workflow-level settings for an optimization run, configured as the optimizer field of EnOptContext.

See the Configuration guide for detailed descriptions and usage examples.

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 the Configuration guide 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, compared against 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 used as the gradient field of EnOptContext.

See the Configuration guide for detailed descriptions and usage examples.

Attributes:

Name	Type	Description
`number_of_perturbations`	`PositiveInt`	Number of perturbations (default: `DEFAULT_NUMBER_OF_PERTURBATIONS`).
`perturbation_min_success`	`PositiveInt \| None`	Minimum number of successful function evaluations for perturbed variables (default: equal to `number_of_perturbations`).
`merge_realizations`	`bool`	Merge all realizations for the final gradient calculation (default: `False`).
`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 the Configuration guide 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 the Configuration guide 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 the Configuration guide 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 the Configuration guide 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_BOTH
)

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

This module defines utilities for validating plugin options.

This module provides classes and functions to define and validate options for plugins. It uses Pydantic to create models that represent the schema of plugin options, allowing for structured and type-safe configuration.

Classes:

Name	Description
`OptionsSchemaModel`	Represents the overall schema for plugin options.
`MethodSchemaModel`	Represents the schema for a specific method within a plugin, including its name and options.

OptionsSchemaModel

Bases: BaseModel

Represents the overall schema for plugin options.

This class defines the structure for describing the methods and options available for 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]]`	An optional list of method schemas that define common 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]

Creates a Pydantic model for validating options of a specific method.

This method dynamically generates a Pydantic model tailored to validate the options associated with a given method. The method is looked up by name, case-insensitively, and its options are combined with the common options that it does not exclude. The resulting model can then be used to validate dictionaries of options against the defined schema.

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 Pydantic model class capable of validating options for the specified method.

Raises:

Type	Description
`ValueError`	If the specified method is not found in the schema.

MethodSchemaModel

Bases: BaseModel, Generic[T]

Represents the schema for a specific method within a plugin.

This class defines the structure for describing one or more methods supported by a plugin. It contains a dictionary describing an option for this 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

Generates a Markdown table documenting plugin options.

This function takes a schema dictionary, validates it against the OptionsSchemaModel, and then generates a Markdown document that summarizes the available methods and their options. Common options are listed first, followed by a table of method-specific options. Each row in the table represents a method, and the columns list the method's name and its configurable options. If a URL is provided for a method, the method name will be hyperlinked to that URL in the table.

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.