optimisation.design_space.factory module

Define factory and presets to handle variables, constraints, limits, etc..

Note

If you add your own DesignSpaceFactory preset, do not forget to add it to the list of supported presets in config.optimisation.design_space.

class AbsPhaseAmplitude(design_space_kw: dict[str, float | bool | str | Path])

Bases: DesignSpaceFactory

Optimise over \(\phi_{0,\,\mathrm{abs}}\) and \(k_e\).

__init__(design_space_kw: dict[str, float | bool | str | Path]) → None

_abc_impl = <_abc._abc_data object>

variables_names = ('phi_0_abs', 'k_e')

class AbsPhaseAmplitudeWithConstrainedSyncPhase(design_space_kw: dict[str, float | bool | str | Path])

Bases: DesignSpaceFactory

Optimise \(\phi_{0,\,\mathrm{abs}}\), \(k_e\). \(\phi_s\) is constrained.

Warning

The selected OptimisationAlgorithm must support the constraints.

__init__(design_space_kw: dict[str, float | bool | str | Path]) → None

_abc_impl = <_abc._abc_data object>

constraints_names = ('phi_s',)

variables_names = ('phi_0_abs', 'k_e')

class ConstrainedSyncPhase(design_space_kw: dict[str, float | bool | str | Path])

Bases: AbsPhaseAmplitudeWithConstrainedSyncPhase

Deprecated alias to AbsPhaseAmplitudeWithConstrainedSyncPhase.

Deprecated since version 0.6.16: Prefer AbsPhaseAmplitudeWithConstrainedSyncPhase.

__init__(design_space_kw: dict[str, float | bool | str | Path]) → None

_abc_impl = <_abc._abc_data object>

DESIGN_SPACE_FACTORY_PRESETS = {'abs_phase_amplitude': <class 'optimisation.design_space.factory.AbsPhaseAmplitude'>, 'abs_phase_amplitude_with_constrained_sync_phase': <class 'optimisation.design_space.factory.AbsPhaseAmplitudeWithConstrainedSyncPhase'>, 'constrained_sync_phase': <class 'optimisation.design_space.factory.AbsPhaseAmplitudeWithConstrainedSyncPhase'>, 'everything': <class 'optimisation.design_space.factory.Everything'>, 'rel_phase_amplitude': <class 'optimisation.design_space.factory.RelPhaseAmplitude'>, 'rel_phase_amplitude_with_constrained_sync_phase': <class 'optimisation.design_space.factory.RelPhaseAmplitudeWithConstrainedSyncPhase'>, 'sync_phase_amplitude': <class 'optimisation.design_space.factory.SyncPhaseAmplitude'>, 'sync_phase_as_variable': <class 'optimisation.design_space.factory.SyncPhaseAmplitude'>, 'unconstrained': <class 'optimisation.design_space.factory.AbsPhaseAmplitude'>, 'unconstrained_rel': <class 'optimisation.design_space.factory.RelPhaseAmplitude'>}

class DesignSpaceFactory(design_space_kw: dict[str, float | bool | str | Path])

Bases: ABC

Base class to handle Variable and Constraint creation.

reference_elements

All the elements with the reference setting.

Type:: list[Element]

compensating_elements

The elements from the linac under fixing that will be used for compensation.

Type:: list[Element]

design_space_kw

The entries of [design_space] in .ini file.

Type:: dict[str, float | bool

__init__(design_space_kw: dict[str, float | bool | str | Path]) → None

__post_init__(): Declare complementary variables.

_abc_impl = <_abc._abc_data object>

_check_can_be_retuned(compensating_elements: list[Element]) → None: Check that given elements can be retuned.

_get_initial_value_from_kw(variable: str, reference_element: Element) → float

Select initial value for given variable.

The default behavior is to return the value of variable from reference_element, which is a good starting point for optimisation.

Parameters:

variable ({'k_e', 'phi_0_rel', 'phi_0_abs', 'phi_s'}) – The variable from which you want the limits.
reference_element (Element) – The element in its nominal tuning.

Returns:

Initial value.

Return type:

float

_get_limits_from_kw(variable: str, reference_element: Element, reference_elements: list[Element]) → tuple[float, float]

Select limits for given variable.

Call this method for classic limits.

Parameters:

variable ({'k_e', 'phi_0_rel', 'phi_0_abs', 'phi_s'}) – The variable from which you want the limits.
reference_element (Element) – The element in its nominal tuning.
reference_elements (list[Element]) – List of reference elements.

Returns:

Lower and upper limit for current variable.

Return type:

tuple[float | None]

_run_constraints(compensating_elements: list[Element], reference_elements: list[Element]) → list[Constraint]: Set up all the required constraints.

_run_from_file(compensating_elements: list[Element], reference_elements: list[Element] | None = None) → DesignSpace

Use the DesignSpace.from_files() constructor.

Parameters:

variables_names (tuple[str, ...]) – Name of the variables to create.
constraints_names (tuple[str, ...] | None, optional) – Name of the constraints to create. The default is None.

Return type:

DesignSpace

_run_variables(compensating_elements: list[Element], reference_elements: list[Element]) → list[Variable]: Set up all the required variables.

design_space_kw: dict[str, float | bool | str | Path]

run(compensating_elements: list[Element], reference_elements: list[Element]) → DesignSpace: Set up variables and constraints.

use_files(variables_filepath: Path, constraints_filepath: Path | None = None, **design_space_kw: float | bool | str | Path) → None

Tell factory to generate design space from the provided files.

Parameters:

variables_filepath (Path) – Path to the variables.csv file.
constraints_filepath (Path | None) – Path to the constraints.csv file. The default is None.

class Everything(design_space_kw: dict[str, float | bool | str | Path])

Bases: DesignSpaceFactory

This class creates all possible variables and constraints.

This is not to be used in an optimisation problem, but rather to save in a .csv all the limits and initial values for every variable/constraint.

__init__(design_space_kw: dict[str, float | bool | str | Path]) → None

_abc_impl = <_abc._abc_data object>

constraints_names = ('phi_s',)

run(*args, **kwargs) → DesignSpace: Launch normal run but with an info message.

variables_names = ('k_e', 'phi_s', 'phi_0_abs', 'phi_0_rel')

class RelPhaseAmplitude(design_space_kw: dict[str, float | bool | str | Path])

Bases: DesignSpaceFactory

Optimise over \(\phi_{0,\,\mathrm{rel}}\) and \(k_e\).

The same as AbsPhaseAmplitude, but the phase variable is \(\phi_{0,\,\mathrm{rel}}\) instead of \(\phi_{0,\,\mathrm{abs}}\). It may be better for convergence, because it makes cavities more independent.

__init__(design_space_kw: dict[str, float | bool | str | Path]) → None

_abc_impl = <_abc._abc_data object>

variables_names = ('phi_0_rel', 'k_e')

class RelPhaseAmplitudeWithConstrainedSyncPhase(design_space_kw: dict[str, float | bool | str | Path])

Bases: DesignSpaceFactory

Optimise \(\phi_{0,\,\mathrm{rel}}\), \(k_e\). \(\phi_s\) is constrained.

Warning

The selected OptimisationAlgorithm must support the constraints.

__init__(design_space_kw: dict[str, float | bool | str | Path]) → None

_abc_impl = <_abc._abc_data object>

constraints_names = ('phi_s',)

variables_names = ('phi_0_rel', 'k_e')

class SyncPhaseAmplitude(design_space_kw: dict[str, float | bool | str | Path])

Bases: DesignSpaceFactory

Optimise over \(\phi_s\) and \(k_e\).

Synchronous phases outside of the bounds will not ocurr, without setting any Constraint. This kind of optimisation takes more time as we need, for every iteration of the OptimisationAlgorithm, to find the \(\phi_{0,\,\mathrm{rel}}\) that corresponds to the desired \(\phi_s\).

__init__(design_space_kw: dict[str, float | bool | str | Path]) → None

_abc_impl = <_abc._abc_data object>

variables_names = ('phi_s', 'k_e')

class SyncPhaseAsVariable(design_space_kw: dict[str, float | bool | str | Path])

Bases: SyncPhaseAmplitude

Deprecated alias to SyncPhaseAmplitude.

Deprecated since version 0.6.16: Prefer SyncPhaseAmplitude.

__init__(design_space_kw: dict[str, float | bool | str | Path]) → None

_abc_impl = <_abc._abc_data object>

class Unconstrained(design_space_kw: dict[str, float | bool | str | Path])

Bases: AbsPhaseAmplitude

Deprecated alias to AbsPhaseAmplitude.

Deprecated since version 0.6.16: Prefer AbsPhaseAmplitude.

__init__(design_space_kw: dict[str, float | bool | str | Path]) → None

_abc_impl = <_abc._abc_data object>

class UnconstrainedRel(design_space_kw: dict[str, float | bool | str | Path])

Bases: RelPhaseAmplitude

Deprecated alias to RelPhaseAmplitude.

Deprecated since version 0.6.16: Prefer RelPhaseAmplitude.

__init__(design_space_kw: dict[str, float | bool | str | Path]) → None

_abc_impl = <_abc._abc_data object>

get_design_space_factory(design_space_preset: str, **design_space_kw: float | bool) → DesignSpaceFactory

Select proper factory, instantiate it and return it.

Parameters:

design_space_preset (str) – design_space_preset
design_space_kw (float | bool) – design_space_kw

Return type:

DesignSpaceFactory