algorithm module

Define the Abstract Base Class of optimisation algorithms.

Abstract methods are mandatory and a TypeError will be raised if you try to create your own algorithm and omit them.

When you add you own optimisation algorithm, do not forget to add it to the list of implemented algorithms in the algorithm module.

Todo

Check if it is necessary to pass out the whole elts to OptimisationAlgorithm?

Todo

Methods and flags to keep the optimisation history or not, and also to save it or not. See Explorator.

Todo

Better handling of the attribute folder. In particular, a correct value should be set at the OptimisationAlgorithm instanciation.

class OptiSol

Bases: TypedDict

Hold information on the solution.

var: ndarray | list[float]

cavity_settings: SetOfCavitySettings

fun: ndarray | list[float]

objectives: dict[str, float]

success: bool

class OptimisationAlgorithm(*, compensating_elements, elts, objectives, variables, compute_beam_propagation, compute_residuals, cavity_settings_factory, reference_simulation_output, constraints=None, compute_constraints=None, optimisation_algorithm_kwargs=None, history_kwargs=None, **kwargs)

Bases: ABC

Holds the optimization parameters, the methods to optimize.

Parameters:

• compensating_elements (list[Element]) – Cavity objects used to compensate for the faults.

• elts (ListOfElements) – Holds the whole compensation zone under study.

• objectives (list[Objective]) – Holds objectives, initial values, bounds.

• variables (list[Variable]) – Holds variables, their initial values, their limits.

• constraints (list[Constraint] | None, optional) – Holds constraints and their limits. The default is None.

• opti_sol (OptiSol) – Holds information on the solution that was found.

• supports_constraints (bool) – If the method handles constraints or not.

• compute_beam_propagation (ComputeBeamPropagationT) – Method to compute propagation of the beam with the given settings. Defined by a BeamCalculator.run_with_this() method, the positional argument elts being set by a functools.partial.

• compute_residuals (ComputeResidualsT) – Method to compute residuals from a SimulationOutput.

• compute_constraints (ComputeConstraintsT | None, optional) – Method to compute constraint violation. The default is None.

• cavity_settings_factory (CavitySettingsFactory) – A factory to easily create the cavity settings to try at each iteration of the optimisation algorithm.

• history_kwargs (dict | None, optional) – kwargs for the OptimizationHistory creation.

• reference_simulation_output (SimulationOutput) – Used for the OptimizationHistory.

• optimisation_algorithm_kwargs (dict[str, Any] | None, default: None)

__init__(*, compensating_elements, elts, objectives, variables, compute_beam_propagation, compute_residuals, cavity_settings_factory, reference_simulation_output, constraints=None, compute_constraints=None, optimisation_algorithm_kwargs=None, history_kwargs=None, **kwargs)

Instantiate the object.

Parameters:

• compensating_elements (Collection[Element])

• elts (ListOfElements)

• objectives (Collection[Objective])

• variables (Collection[Variable])

• compute_beam_propagation (Callable[[SetOfCavitySettings], SimulationOutput])

• compute_residuals (Callable[[SimulationOutput], Any])

• cavity_settings_factory (CavitySettingsFactory)

• reference_simulation_output (SimulationOutput)

• constraints (Collection[Constraint] | None, default: None)

• compute_constraints (Callable[[SimulationOutput], ndarray] | None, default: None)

• optimisation_algorithm_kwargs (dict[str, Any] | None, default: None)

• history_kwargs (dict[str, Any] | None, default: None)

supports_constraints: bool

property variable_names: list[str]

Give name of all variables.

property n_var: int

Give number of variables.

property n_obj: int

Give number of objectives.

property n_constr: int

Return number of (inequality) constraints.

property _default_kwargs: dict[str, Any]

Give the default optimisation algorithm kwargs.

abstract optimize()

Set up optimization parameters and solve the problem.

Returns:

info – Gives list of solutions, corresponding objective, convergence violation if applicable, etc.

Return type:

OptiSol

abstract _generate_opti_sol(*args, **kwargs)

Takes the results of the optimization in any form, returns dict.

Return type:

OptiSol

_format_variables()

Adapt all Variable to this optimisation algorithm.

Return type:

Any

_format_objectives()

Adapt all Objective to this optimisation algorithm.

Return type:

Any

_format_constraints()

Adapt all Constraint to this optimisation algorithm.

Return type:

Any

_wrapper_residuals(var)

Compute residuals from an array of variable values.

Parameters:

var (ndarray)

Return type:

ndarray

_norm_wrapper_residuals(var)

Compute norm of residuals vector from array of variable values.

Parameters:

var (ndarray)

Return type:

float

_finalize(opti_sol, *complementary_info)

End the optimization process.

Parameters:

• opti_sol (OptiSol)

• complementary_info (str)

Return type:

None

_create_set_of_cavity_settings(var, status='compensate (in progress)')

Transform var into generic SetOfCavitySettings.

Parameters:

• var (ndarray) – An array holding the variables to try.

• status (str, optional) – mmmh

Returns:

Object holding the settings of all the cavities.

Return type:

SetOfCavitySettings

_get_objective_values(var)

Save the full array of objective values.

Parameters:

var (ndarray)

Return type:

dict[str, float]

_output_some_info(opti_sol, *complementary_info)

Show the most useful data from optimization.

Parameters:

• opti_sol (OptiSol)

• complementary_info (str)

Return type:

None

_abc_impl = <_abc._abc_data object at 0x73df41ef2540>

class OptimizationHistory(reference_simulation_output, objectives_names, get_args=(), get_kwargs=None, folder=None, save_interval=100, **kwargs)

Bases: object

Keep all the settings that were tried.

Parameters:

• reference_simulation_output (SimulationOutput)

• objectives_names (Collection[str])

• get_args (tuple[str, ...], default: ())

• get_kwargs (dict[str, Any] | None, default: None)

• folder (Path | str | None, default: None)

• save_interval (int, default: 100)

_settings_filename = 'settings.csv'

_objectives_filename = 'objectives.csv'

_constraints_filename = 'constraints.csv'

__init__(reference_simulation_output, objectives_names, get_args=(), get_kwargs=None, folder=None, save_interval=100, **kwargs)

Instantiate the object.

Parameters:

• get_args (tuple[str, ...], dict[str, Any], optional) – args and kwargs passed to the SimulationOutput.get method. Used to add some values to the output files.

• get_kwargs (dict[str, Any] | None, optional) – args and kwargs passed to the SimulationOutput.get method. Used to add some values to the output files.

• get_kwargs – Keyword arguments for the SimulationOutput.get method.

• folder (pathlib.Path | str | None, optional) – Where the histories will be saved. If not provided or None is given, this class will not have any effect and every public method wil be overriden with dummy methods.

• save_interval (int, optional) – Files will be saved every save_interval iteration.

• reference_simulation_output (SimulationOutput)

• objectives_names (Collection[str])

_make_public_methods_useless()

Override some methods so that they do not do anything.

Return type:

None

add_settings(var)

Add a new set of cavity settings.

Parameters:

var (ndarray)

Return type:

None

_init_objective_hist(objectives_names, reference_simulation_output)

Create the objective history, with header and reference values.

Parameters:

• objectives_names (Collection[str])

• reference_simulation_output (SimulationOutput)

Return type:

tuple[list[str], list[None | float]]

_simulation_output_to_objectives(simulation_output)

Extract and format desired values from simulation_output.

Parameters:

simulation_output (SimulationOutput)

Return type:

list[float]

_objective_headers(objectives_names)

Get the objective headers.

Parameters:

objectives_names (Collection[str])

Return type:

tuple[list[str], list[str]]

add_objective_values(objectives, simulation_output)

Add some objective values.

Parameters:

• objectives (list)

• simulation_output (SimulationOutput)

Return type:

None

add_constraint_values(constraints)

Add some constraint values.

Parameters:

constraints (list | ndarray | None)

Return type:

None

save()

Save the three histories in their respective files.

All files will be in self.history_folder.

Return type:

None

_rename_previous_files()

Rename the previous history files.

Return type:

None

_empty_histories()

Empty the histories.

Return type:

None

checkpoint()

Save periodically based on the defined interval.

Return type:

None

_save_values(filepath, values)

Save the values to filepath (can be objectives or constraints).

Parameters:

• filepath (pathlib.Path) – Where to save the values.

• values (list[list[float] | numpy.ndarray | None]) – The list of values to save (objectives or constraints), starting in the third column. If a value is None, it is represented as ‘None’ in the file.

Return type:

None