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 optimisation.design_space_specs.

class DesignSpaceFactory(*, variables_names, from_file, constraints_names=(), variables_filepath=None, constraints_filepath=None, **design_space_kw)[source]

Bases: ABC

Base class to handle Variable and Constraint creation.

Parameters:

design_space_kw (Any) – The entries of [design_space] in TOML configuration file.
variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']])
from_file (bool)
constraints_names (Collection[Literal['phi_s']], default: ())
variables_filepath (Path | None, default: None)
constraints_filepath (Path | None, default: None)

__init__(*, variables_names, from_file, constraints_names=(), variables_filepath=None, constraints_filepath=None, **design_space_kw)[source]

Init object.

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']])
from_file (bool)
constraints_names (Collection[Literal['phi_s']], default: ())
variables_filepath (Path | None, default: None)
constraints_filepath (Path | None, default: None)
design_space_kw (Any)

Return type:

None

create: Callable[[Sequence[Element], Sequence[Element]], DesignSpace]: Actual factory method

limits_from_design_space_kw: Stores additional kw to compute design space limits

_check_can_be_retuned(compensating_elements)[source]

Check that given elements can be retuned.

Parameters:: compensating_elements (Collection[Element])
Return type:: None

_instantiate_variables(compensating_elements, reference_elements)[source]

Set up all the required variables.

Parameters:

compensating_elements (Collection[FieldMap])
reference_elements (Collection[Element])

Return type:

list[Variable]

_instantiate_constraints(compensating_elements, reference_elements)[source]

Set up all the required constraints.

Parameters:

compensating_elements (Collection[Element])
reference_elements (Collection[Element])

Return type:

list[Constraint]

_create_from_kw(compensating_elements, reference_elements)[source]

Set up variables and constraints.

Limits are calculated from nominal values.

Parameters:

compensating_elements (Sequence[Element])
reference_elements (Sequence[Element])

Return type:

DesignSpace

_get_initial_value_from_kw(variable, reference_element)[source]

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 (Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']) – The variable from which you want the limits.
reference_element (FieldMap) – The element in its nominal tuning.

Return type:

float

Returns:

Initial value.

_get_limits_from_kw(variable, reference_element, reference_elements)[source]

Select limits for given variable.

Call this method for classic limits.

Parameters:

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

Return type:

tuple[float, float]

Returns:

Lower and upper limit for current variable.

_use_files(variables_filepath=None, constraints_filepath=None)[source]

Tell factory to generate design space from the provided files.

Parameters:

variables_filepath (Path | None, default: None)
constraints_filepath (Path | None, default: None)

Return type:

None

_create_from_file(compensating_elements, reference_elements=None)[source]

Use the DesignSpace.from_files() constructor.

Parameters:

variables_names – Name of the variables to create.
constraints_names – Name of the constraints to create. The default is None.
compensating_elements (Sequence[Element])
reference_elements (Sequence[Element] | None, default: None)

Return type:

DesignSpace

_abc_impl = <_abc._abc_data object at 0x7921a0b62500>

class UserDefinedDesignSpaceFactory(**design_space_kw)[source]

Bases: DesignSpaceFactory

Let user choose variables and constraints from TOML.

__init__(**design_space_kw)[source]

Init object.

Return type:: None

_abc_impl = <_abc._abc_data object at 0x7921a0c78b80>

class _Preset(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Bases: DesignSpaceFactory

Create design space with predefined keys variables/constraints.

Raise warning if variables/constraints were set in the TOML.

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

_preset_variables: tuple[Literal['k_e', 'phi_0_abs', 'phi_0_rel', 'phi_s'], ...]

_preset_constraints: tuple[Literal['phi_s'], ...] = ()

__init__(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Init object.

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

Return type:

None

_abc_impl = <_abc._abc_data object at 0x7921a0c798c0>

class AbsPhaseAmplitude(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Bases: _Preset

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

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

_preset_variables: tuple[Literal['k_e', 'phi_0_abs', 'phi_0_rel', 'phi_s'], ...] = ('phi_0_abs', 'k_e')

_preset_constraints: tuple[Literal['phi_s'], ...] = ()

_abc_impl = <_abc._abc_data object at 0x7921a0c78ac0>

class RelPhaseAmplitude(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Bases: _Preset

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.

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

_preset_variables: tuple[Literal['k_e', 'phi_0_abs', 'phi_0_rel', 'phi_s'], ...] = ('phi_0_rel', 'k_e')

_preset_constraints: tuple[Literal['phi_s'], ...] = ()

_abc_impl = <_abc._abc_data object at 0x7921a20b0e00>

class SyncPhaseAmplitude(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Bases: _Preset

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\).

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

_preset_variables: tuple[Literal['k_e', 'phi_0_abs', 'phi_0_rel', 'phi_s'], ...] = ('phi_s', 'k_e')

_preset_constraints: tuple[Literal['phi_s'], ...] = ()

_abc_impl = <_abc._abc_data object at 0x7921a20b3fc0>

class AbsPhaseAmplitudeWithConstrainedSyncPhase(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Bases: _Preset

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

Warning

The selected OptimisationAlgorithm must support the constraints.

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

_preset_variables: tuple[Literal['k_e', 'phi_0_abs', 'phi_0_rel', 'phi_s'], ...] = ('phi_0_abs', 'k_e')

_preset_constraints: tuple[Literal['phi_s'], ...] = ('phi_s',)

_abc_impl = <_abc._abc_data object at 0x7921a20b1840>

class RelPhaseAmplitudeWithConstrainedSyncPhase(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Bases: _Preset

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

Warning

The selected OptimisationAlgorithm must support the constraints.

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

_preset_variables: tuple[Literal['k_e', 'phi_0_abs', 'phi_0_rel', 'phi_s'], ...] = ('phi_0_rel', 'k_e')

_preset_constraints: tuple[Literal['phi_s'], ...] = ('phi_s',)

_abc_impl = <_abc._abc_data object at 0x7921a20b3500>

class Everything(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Bases: _Preset

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.

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

_preset_variables: tuple[Literal['k_e', 'phi_0_abs', 'phi_0_rel', 'phi_s'], ...] = ('k_e', 'phi_0_abs', 'phi_0_rel', 'phi_s')

_preset_constraints: tuple[Literal['phi_s'], ...] = ('phi_s',)

run(*args, **kwargs)[source]

Launch normal run but with an info message.

Return type:: DesignSpace

_abc_impl = <_abc._abc_data object at 0x7921a20b2400>

class Unconstrained(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Bases: AbsPhaseAmplitude

Deprecated alias to AbsPhaseAmplitude.

Deprecated since version 0.6.16: Prefer AbsPhaseAmplitude.

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

_abc_impl = <_abc._abc_data object at 0x7921a20b1280>

class UnconstrainedRel(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Bases: RelPhaseAmplitude

Deprecated alias to RelPhaseAmplitude.

Deprecated since version 0.6.16: Prefer RelPhaseAmplitude.

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

_abc_impl = <_abc._abc_data object at 0x7921a20b3800>

class SyncPhaseAsVariable(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Bases: SyncPhaseAmplitude

Deprecated alias to SyncPhaseAmplitude.

Deprecated since version 0.6.16: Prefer SyncPhaseAmplitude.

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

_abc_impl = <_abc._abc_data object at 0x7921a3aadd40>

class ConstrainedSyncPhase(*, variables_names=None, constraints_names=None, **design_space_kw)[source]

Bases: AbsPhaseAmplitudeWithConstrainedSyncPhase

Deprecated alias to AbsPhaseAmplitudeWithConstrainedSyncPhase.

Deprecated since version 0.6.16: Prefer AbsPhaseAmplitudeWithConstrainedSyncPhase.

Parameters:

variables_names (Collection[Literal['k_e'] | Literal['phi_0_abs', 'phi_0_rel', 'phi_s']] | None, default: None)
constraints_names (Collection[Literal['phi_s']] | None, default: None)

_abc_impl = <_abc._abc_data object at 0x7921a3aacb80>

DESIGN_SPACE_FACTORY_PRESETS: dict[Literal['AbsPhaseAmplitude', 'AbsPhaseAmplitudeWithConstrainedSyncPhase', 'Everything', 'RelPhaseAmplitude', 'RelPhaseAmplitudeWithConstrainedSyncPhase', 'SyncPhaseAmplitude', 'UserDefined', 'abs_phase_amplitude', 'abs_phase_amplitude_with_constrained_sync_phase', 'everything', 'rel_phase_amplitude', 'rel_phase_amplitude_with_constrained_sync_phase', 'sync_phase_amplitude', 'user_defined', 'unconstrained', 'unconstrained_rel', 'constrained_sync_phase', 'sync_phase_as_variable'], type[DesignSpaceFactory]] = { 'AbsPhaseAmplitude': <class 'lightwin.optimisation.design_space.factory.AbsPhaseAmplitude'>, 'AbsPhaseAmplitudeWithConstrainedSyncPhase': <class 'lightwin.optimisation.design_space.factory.AbsPhaseAmplitudeWithConstrainedSyncPhase'>, 'Everything': <class 'lightwin.optimisation.design_space.factory.Everything'>, 'RelPhaseAmplitude': <class 'lightwin.optimisation.design_space.factory.RelPhaseAmplitude'>, 'RelPhaseAmplitudeWithConstrainedSyncPhase': <class 'lightwin.optimisation.design_space.factory.RelPhaseAmplitudeWithConstrainedSyncPhase'>, 'SyncPhaseAmplitude': <class 'lightwin.optimisation.design_space.factory.SyncPhaseAmplitude'>, 'abs_phase_amplitude': <class 'lightwin.optimisation.design_space.factory.AbsPhaseAmplitude'>, 'abs_phase_amplitude_with_constrained_sync_phase': <class 'lightwin.optimisation.design_space.factory.AbsPhaseAmplitudeWithConstrainedSyncPhase'>, 'constrained_sync_phase': <class 'lightwin.optimisation.design_space.factory.AbsPhaseAmplitudeWithConstrainedSyncPhase'>, 'everything': <class 'lightwin.optimisation.design_space.factory.Everything'>, 'rel_phase_amplitude': <class 'lightwin.optimisation.design_space.factory.RelPhaseAmplitude'>, 'rel_phase_amplitude_with_constrained_sync_phase': <class 'lightwin.optimisation.design_space.factory.RelPhaseAmplitudeWithConstrainedSyncPhase'>, 'sync_phase_amplitude': <class 'lightwin.optimisation.design_space.factory.SyncPhaseAmplitude'>, 'sync_phase_as_variable': <class 'lightwin.optimisation.design_space.factory.SyncPhaseAmplitude'>, 'unconstrained': <class 'lightwin.optimisation.design_space.factory.AbsPhaseAmplitude'>, 'unconstrained_rel': <class 'lightwin.optimisation.design_space.factory.RelPhaseAmplitude'>}

get_design_space_factory(design_space_preset='SyncPhaseAmplitude', **design_space_kw)[source]

Select proper factory, instantiate it and return it.

Parameters:

design_space_preset (Literal['AbsPhaseAmplitude', 'AbsPhaseAmplitudeWithConstrainedSyncPhase', 'Everything', 'RelPhaseAmplitude', 'RelPhaseAmplitudeWithConstrainedSyncPhase', 'SyncPhaseAmplitude', 'UserDefined', 'abs_phase_amplitude', 'abs_phase_amplitude_with_constrained_sync_phase', 'everything', 'rel_phase_amplitude', 'rel_phase_amplitude_with_constrained_sync_phase', 'sync_phase_amplitude', 'user_defined', 'unconstrained', 'unconstrained_rel', 'constrained_sync_phase', 'sync_phase_as_variable'], default: 'SyncPhaseAmplitude') – design_space_preset
design_space_kw (Unpack[DesignSpaceKw]) – design_space_kw

Return type:

DesignSpaceFactory