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 BasicOptimizer.

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.
`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`	`Array1DInt`	Indices of the samplers to use for each variable.
`seed`	`ItemOrTuple[int]`	Seed for the random number generator used by the samplers.
`transforms`	`Array1DInt`	Indices of the variable transforms to apply for each variable.

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).
`realization_filters`	`Array1DInt`	Optional indices of realization filters.
`function_estimators`	`Array1DInt`	Optional indices of function estimators.
`transforms`	`Array1DInt`	Optional indices of objective transforms.

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.

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.
`realization_filters`	`Array1DInt`	Optional indices of realization filters.
`function_estimators`	`Array1DInt`	Optional indices of function estimators.
`transforms`	`Array1DInt`	Optional indices of constraint transforms.

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 (optional).
`parallel`	`bool`	Allow parallelized function evaluations (default: `False`).
`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`).

VariableTransformConfig

Configuration class for variable transforms.

VariableTransformConfig configures a VariableTransform plugin that transforms variables to the optimizer's domain.

See the Configuration guide for detailed descriptions and usage examples.

Attributes:

Name	Type	Description
`method`	`str`	Name of the variable transform method.
`options`	`dict[str, Any]`	Dictionary of options for the variable transform method.

ObjectiveTransformConfig

Configuration class for objective transforms.

ObjectiveTransformConfig configures an ObjectiveTransform plugin that transforms objective values.

See the Configuration guide for detailed descriptions and usage examples.

Attributes:

Name	Type	Description
`method`	`str`	Name of the objective transform method.
`options`	`dict[str, Any]`	Dictionary of options for the objective transform method.

NonlinearConstraintTransformConfig

Configuration class for nonlinear constraint transforms.

NonlinearConstraintTransformConfig configures a NonlinearConstraintTransform plugin that transforms constraint values.

See the Configuration guide for detailed descriptions and usage examples.

Attributes:

Name	Type	Description
`method`	`str`	Name of the nonlinear constraint transform method.
`options`	`dict[str, Any]`	Dictionary of options for the nonlinear constraint transform method.

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 in a list of [MethodSchemaModel][ropt.config.options.MethodSchemaModel] objects, each describing a method supported by the plugin.

Attributes:

Name	Type	Description
`methods`	`dict[str, MethodSchemaModel[Any]]`	A list of method 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": [
            {
                "options": {"a": float}
            },
            {
                "options": {"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. It iterates through the defined methods, collecting option schemas from those matching the specified method name. 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.