Everest Plan

ropt_everest.EverestPlan

Represents an execution plan for an Everest optimization workflow.

The EverestPlan class provides a high-level interface for defining and managing optimization workflows in Everest. It allows you to add various steps to the plan, such as optimizers and evaluators, that are then executed to achieve the desired optimization goal.

add_optimizer

add_optimizer() -> EverestOptimizerStep

Adds an optimizer to the execution plan.

This method integrates an optimization step into your Everest workflow. Invoking this method returns an EverestOptimizerStep object, which you can execute using its run method.

Returns:

Type	Description
`EverestOptimizerStep`	An `EverestOptimizerStep` object, representing the added optimizer.

add_ensemble_evaluator

add_ensemble_evaluator() -> EverestEnsembleEvaluatorStep

Adds an evaluator to the execution plan.

This method integrates an ensemble evaluator step into your Everest workflow. Invoking this method returns an EverestEnsembleEvaluatorStep object, which you can execute using its run method.

Returns:

Type	Description
`EverestEnsembleEvaluatorStep`	An `EverestEnsembleEvaluatorStep` object, representing the added evaluator.

add_cache

add_cache(
    steps: EverestStepBase
    | Sequence[EverestStepBase]
    | set[EverestStepBase],
    sources: EverestEventHandlerBase
    | Sequence[EverestEventHandlerBase]
    | set[EverestEventHandlerBase],
) -> EverestCachedEvaluator

Adds an cache to the execution plan.

This method integrates a caching mechanism into your Everest workflow. Invoking this method returns an EverestCachedEvaluator object, which will act as a cache.

The cache is only serving the steps specified in the steps argument. Cached values are retrieved from the specified source(s) and used to avoid redundant evaluations. The sources must be an event handler that stores the results produced by the optimization or evaluation steps.

Parameters:

Name	Type	Description	Default
`steps`	`EverestStepBase \| Sequence[EverestStepBase] \| set[EverestStepBase]`	The steps that will use the cache.	required
`sources`	`EverestEventHandlerBase \| Sequence[EverestEventHandlerBase] \| set[EverestEventHandlerBase]`	The source(s) of cached values.	required

Returns:

Type	Description
`EverestCachedEvaluator`	A cache object.

add_store

add_store(
    steps: EverestStepBase | Sequence[EverestStepBase],
) -> EverestStore

Adds a results store to the execution plan.

Stores the results of specified optimization or evaluation steps.

Invoking this method returns an EverestStore object, which provides various methods to access the stored results.

steps: This argument specifies which steps in the execution plan the store should monitor. You can provide either a single step object (such as an optimizer or evaluator) or a sequence of steps. The store object will record all the results generated by these steps.

Parameters:

Name	Type	Description	Default
`steps`	`EverestStepBase \| Sequence[EverestStepBase]`	The EverestStep(s) to monitor.	required

Returns:

Type	Description
`EverestStore`	An `EverestStore` object, which can be used to access the stored results.

add_tracker

add_tracker(
    steps: EverestStepBase | Sequence[EverestStepBase],
    *,
    what: Literal["best", "last"] = "best",
    constraint_tolerance: float | None = None,
) -> EverestTracker

Adds a tracker to the execution plan.

Trackers monitor the progress of specified optimization or evaluation steps and record relevant results. They provide a way to capture and analyze the outcomes of these steps during the execution of the plan. You can configure a tracker to save the best or the last results generated by the tracked steps.

Invoking this method returns an EverestTracker object, which provides various methods to access the tracked results.

A tracker is configured by three arguments:

steps: This argument specifies which steps in the execution plan the tracker should monitor. You can provide either a single step object (such as an optimizer or evaluator) or a sequence of steps. The tracker will record the results generated by these steps.

what: This argument determines which results the tracker should record. You can choose from the following options:

"best": Only the best result found so far is tracked.
"last": Only the most recently generated result is tracked.

The default value is "best".

constraint_tolerance: This optional argument specifies the tolerance for constraint satisfaction. It is used to determine whether a result is considered feasible, meaning it satisfies the defined constraints within the specified tolerance. Only feasible results will be recorded. If it is not set, constraints are not tested.

Parameters:

Name	Type	Description	Default
`steps`	`EverestStepBase \| Sequence[EverestStepBase]`	The EverestStep(s) to monitor.	required
`what`	`Literal['best', 'last']`	Which results to track ("best" or "last").	`'best'`
`constraint_tolerance`	`float \| None`	Tolerance for constraint satisfaction.	`None`

Returns:

Type	Description
`EverestTracker`	An `EverestTracker` object, which can be used to access the tracked results.

add_table

add_table(
    steps: EverestStepBase | Sequence[EverestStepBase],
) -> EverestTableHandler

Adds an event handler that create a table to the execution plan.

This event handler will monitor the progress of specified optimization or evaluation steps and record relevant results. A set of tables will then be generated and saved in the output directory.

Note

This requires that the everest-table plugin for ropt is installed. If it is not installed, this method will do nothing and return None. In this case, no tables will be generated.

Parameters:

Name	Type	Description	Default
`steps`	`EverestStepBase \| Sequence[EverestStepBase]`	The EverestStep(s) to monitor.	required

Returns:

Type	Description
`EverestTableHandler`	An `EverestTableHandler` object.

ropt_everest.EverestOptimizerStep

Bases: EverestStepBase

Represents an optimizer step in an Everest execution plan.

This class encapsulates an optimization step within an Everest workflow. It provides a method to execute the optimizer.

run

run(
    config: dict[str, Any],
    controls: ArrayLike | None = None,
    metadata: dict[str, Any] | None = None,
    output_dir: str | None = None,
) -> None

Runs the optimizer.

This method executes the underlying optimizer with the given parameters.

Configuration:

The config dictionary should be a dictionary that can be validated as an EverestConfig object.

Controls:

If no controls are provided, the optimizer will use the initial values from the configuration.

Metadata:

The metadata parameter allows you to associate arbitrary data with each result generated by the optimizer or ensemble evaluators.
This metadata is included in generated tables and data frames.
The keys in the metadata dictionary are used as column names in the output tables.

Optimizer output:

Normally, the optimizer's output is directed to the optimization_output subdirectory within the main output directory specified in the Everest configuration. When multiple optimization steps are executed, there's a risk of output files being overwritten. The output_dir argument provides a way to override the default output location for the optimizer. You can specify an absolute path, or a relative path, which will be interpreted as relative to the optimization_output directory.

Parameters:

Name	Type	Description	Default
`config`	`dict[str, Any]`	An optional dictionary containing the Everest configuration for the optimizer. If omitted, the default configuration is used.	required
`controls`	`ArrayLike \| None`	An array-like object containing the controls for the optimization.	`None`
`metadata`	`dict[str, Any] \| None`	An optional dictionary of metadata to associate with the results of the optimizer's results.	`None`
`output_dir`	`str \| None`	An optional output directory for the optimizer.	`None`

ropt_everest.EverestEnsembleEvaluatorStep

Bases: EverestStepBase

Represents an evaluator step in an Everest execution plan.

This class encapsulates an evaluation step within an Everest workflow. It provides a method to execute the evaluator .

run

run(
    config: dict[str, Any],
    controls: ArrayLike | None = None,
    metadata: dict[str, Any] | None = None,
) -> None

Runs the ensemble evaluator.

This method executes the underlying ensemble evaluator with the given parameters.

Configuration:

The config dictionary should be a dictionary that can be validated as an EverestConfig object.

Controls:

The controls parameter can be a single vector, a sequence of multiple vectors, or a 2D matrix where the control vectors are the rows. If no controls are provided, the evaluator will use its default the initial values from the configuration.

Metadata:

The metadata parameter allows you to associate arbitrary data with each result generated by the optimizer or evaluators.
This metadata is included in generated tables and data frames.
The keys in the metadata dictionary are used as column names in the output tables.

Parameters:

Name	Type	Description	Default
`config`	`dict[str, Any]`	An optional dictionary containing the Everest configuration for the optimizer. If omitted, the default configuration is used.	required
`controls`	`ArrayLike \| None`	An array-like object containing the controls for the optimization.	`None`
`metadata`	`dict[str, Any] \| None`	An optional dictionary of metadata to associate with the results of the optimizer's results.	`None`

ropt_everest.EverestStore

Bases: EverestEventHandlerBase

Provides access to the results stored by an Everest execution plan.

This class provides methods to retrieve and analyze the results produces within an Everest execution plan. It allows you to access the results. You can also convert the stored results into a Pandas DataFrame for easier analysis.

results `property`

results: list[Results] | None

Retrieves the stored results.

Returns:

Type	Description
`list[Results] \| None`	The stored results.

controls `property`

controls: NDArray[float64] | list[NDArray[float64]] | None

Retrieves the stored controls.

Returns:

Type	Description
`NDArray[float64] \| list[NDArray[float64]] \| None`	The stored controls.

reset

reset() -> None

Reset the store.

Clears any results accumulated so far.

dataframe

dataframe(kind: str) -> pd.DataFrame | None

Converts the stored results to a Pandas DataFrame.

This method converts the tracked results into a Pandas DataFrame, making it easier to analyze and visualize the data.

The kind argument supports the following options:

"results": For function results.
"gradients": For gradient results.
"simulations": For simulation results.
"perturbations": For perturbation results.
"constraints": For constraint information.

Note

The column names of the dataframe may be strings or tuples of strings. In the tuple form, the name is usually composed of a string indicating the type of column and one or more objective, constraint or control names. For instance, a column containing values of the control point.x may have the name: (controls, point.x). The gradient of an objective distance with respect to a control point.x may have the column name (objectives, distance, point.x.0).

Parameters:

Name	Type	Description	Default
`kind`	`str`	The type of table to create.	required

Returns:

Type	Description
`DataFrame \| None`	A Pandas DataFrame containing the store results, or None.

ropt_everest.EverestTracker

Bases: EverestEventHandlerBase

Provides access to the results generated by an Everest execution plan.

This class provides methods to retrieve and analyze the results tracked by a tracker within an Everest execution plan. It allows you to access the results. You can also convert the tracked results into a Pandas DataFrame for easier analysis.

The tracker can keep track of the best, the last, or all the results. The tracker can also be set to only keep track of the feasible results.

results `property`

results: FunctionResults | None

Retrieves the tracked results.

Returns:

Type	Description
`FunctionResults \| None`	The tracked results.

controls `property`

controls: NDArray[float64] | None

Retrieves the tracked controls.

Returns:

Type	Description
`NDArray[float64] \| None`	The tracked controls.

reset

reset() -> None

Reset the tracker.

Clears any results accumulated so far.

dataframe

dataframe(kind: str) -> pd.DataFrame | None

Converts the tracked results to a Pandas DataFrame.

This method converts the tracked results into a Pandas DataFrame, making it easier to analyze and visualize the data.

The kind argument supports the following options:

"results": For function results.
"gradients": For gradient results.
"simulations": For simulation results.
"perturbations": For perturbation results.
"constraints": For constraint information.

Note

The column names of the dataframe may be strings or tuples of strings. In the tuple form, the name is usually composed of a string indicating the type of column and one or more objective, constraint or control names. For instance, a column containing values of the control point.x may have the name: (controls, point.x). The gradient of an objective distance with respect to a control point.x may have the column name (objectives, distance, point.x.0).

Parameters:

Name	Type	Description	Default
`kind`	`str`	The type of table to create.	required

Returns:

Type	Description
`DataFrame \| None`	A Pandas DataFrame containing the tracked results, or None.

ropt_everest.EverestTableHandler

Bases: EverestEventHandlerBase

Represents a table event handler in an Everest execution plan.

ropt_everest.EverestCachedEvaluator

Bases: EverestEvaluatorBase

ropt_everest.load_config

load_config(config_file: str) -> dict[str, Any]

Loads an Everest configuration from a YAML file.

This function reads an Everest configuration specified by the config_file path, parses it, and returns it as a Python dictionary.

Parameters:

Name	Type	Description	Default
`config_file`	`str`	The path to the Everest configuration YAML file.	required

Returns:

Type	Description
`dict[str, Any]`	A dictionary representing the Everest configuration.

ropt_everest.run_everest

run_everest(
    config_file: str,
    *,
    script: Path | str | None = None,
    report_exit_code: bool = True,
) -> EverestExitCode

Runs an Everest optimization directly from a configuration file.

This function provides a convenient way to execute an Everest optimization plan without having to use the everest command. This method will run a full optimization, but it will not produce the usual monitoring output of Everest.

Using this method instead of the everest command-line tool offers several advantages, including:

Direct access to standard output (stdout): Unlike the everest command, this does not redirect standard output.
Error traces: If errors occur during the optimization, you'll get a full Python stack trace, making debugging easier.
Exceptional exit conditions, such as maximum number batch reached, or a user abort are reported, if report_exit_code is set.

The optional script argument is used to define a custom script that runs the optimization. If the file named by script does not exists, the argument is ignored and the default optimization workflow is run.

Parameters:

Name	Type	Description	Default
`config_file`	`str`	The path to the Everest configuration file (YAML).	required
`script`	`Path \| str \| None`	Optional script to replace the default optimization.	`None`
`report_exit_code`	`bool`	If `True`, report the exit code.	`True`

Returns:

Type	Description
`EverestExitCode`	The Everest exit code.

Everest Plan

ropt_everest.EverestPlan

add_optimizer

add_ensemble_evaluator

add_cache

add_store

add_tracker

add_table

ropt_everest.EverestOptimizerStep

run

ropt_everest.EverestEnsembleEvaluatorStep

run

ropt_everest.EverestStore

results property

controls property

reset

dataframe

ropt_everest.EverestTracker

results property

controls property

reset

dataframe

ropt_everest.EverestTableHandler

ropt_everest.EverestCachedEvaluator

ropt_everest.load_config

ropt_everest.run_everest

results `property`

controls `property`

results `property`

controls `property`