factory module

Define a factory to create Objective objects.

When you implement a new objective preset, also add it to the list of implemented presets in OBJECTIVE_PRESETS and optimisation.wtf_specs.

Todo

decorator to auto output the variables and constraints?

class ObjectiveFactory(reference_simulation_output, broken_elts, failed_elements, compensating_elements, limits_from_design_space_kw)[source]

Bases: ABC

A base class to create all the Objective of a Fault.

It is intended to be sub-classed to make presets. Look at EnergyPhaseMismatch or EnergySyncPhaseMismatch for examples.

Parameters:

  • objective_position_preset – List of keys to dynamically select where the objectives should be matched.

  • compensation_zone_override_settings – Keyword arguments that are passed to zone_to_recompute(). By default, the list of elements in which we propagate the beam is as small as possible, but you may want to override this behavior.

  • reference_simulation_output (SimulationOutput)

  • broken_elts (ListOfElements)

  • failed_elements (Collection[Element])

  • compensating_elements (Collection[Element])

  • limits_from_design_space_kw (dict[str, Any])

objective_position_preset: list[Literal['end of last altered lattice', 'one lattice after last altered lattice', 'end of last failed lattice', 'one lattice after last failed lattice', 'end of linac', 'end of every altered lattice']]

List of positions telling where objectives should be evaluated.

compensation_zone_override_settings = {   'full_lattices': False,     'full_linac': False,     'start_at_beginning_of_linac': False}
__init__(reference_simulation_output, broken_elts, failed_elements, compensating_elements, limits_from_design_space_kw)[source]

Create the object.

Parameters:

  • reference_simulation_output (SimulationOutput) – The reference simulation of the reference linac.

  • broken_elts (ListOfElements) – List containing all the elements of the broken linac.

  • failed_elements (Collection[Element]) – Cavities that failed.

  • compensating_elements (Collection[Element]) – Cavities that will be used for the compensation.

  • design_space_kw – Holds information on variables/constraints limits/initial values. Used to compute the limits that phi_s must respect when the synchronous phase is defined as an objective.

  • limits_from_design_space_kw (dict[str, Any])

Return type:

None

_reference_simulation_output

The reference simulation of the reference linac.

_reference_elts

All the reference elements.

_failed_elements

Broken elements.

_objective_elements: list[Element]

List of elements were an objective is evaluated

abstractmethod get_objectives()[source]

Create the Objective instances.

Return type:

list[Objective]

_set_zone_to_recompute(**wtf)[source]

Determine which (sub)list of elements should be recomputed.

Also determine the elements where objectives are evaluated. You can override this method for your specific preset.

Parameters:

wtf (Any)

Return type:

tuple[list[Element], list[Element]]

compute_residuals(simulation_output)[source]

Compute residuals on objectives for a simulation.

Parameters:

simulation_output (SimulationOutput)

Return type:

ndarray[tuple[Any, ...], dtype[double]]

_abc_impl = <_abc._abc_data object at 0x7318f8f81340>
class CorrectorAtExit(reference_simulation_output, broken_elts, failed_elements, compensating_elements, limits_from_design_space_kw)[source]

Bases: ObjectiveFactory

Propagate beam up to final cavities, where an energy boost is given.

The idea behind this strategy is the following:

  • Use n_compensating cavities around the failure to shape the beam and propagate it without losses.

  • Rephase downstream cavities to keep the beam as intact as possible.

  • Give an ultimate energy boost to the beam with the last n_correctors cavities.

This method is very similar to the one used at SNS [SP22]. In this paper however, there are no compensating cavities around the failure.

See also

strategy.corrector_at_exit()

Parameters:
objective_position_preset: list[Literal['end of last altered lattice', 'one lattice after last altered lattice', 'end of last failed lattice', 'one lattice after last failed lattice', 'end of linac', 'end of every altered lattice']] = ['end of last altered lattice']

List of positions telling where objectives should be evaluated.

get_objectives()[source]

Give adapted objectives.

We start by looking at the _failed_elements list:

  • If it has elements, we are around a failure and we will try to keep a kinetic energy not too far from the nominal energy. More importantly, we try to minimize the mismatch factor at the exit of the compensation zone.

  • If it is empty, it means that there is no nearby failed cavity. We are at the exit of the linac and will try to retrieve nominal energy at the end of the linac.

Return type:

list[Objective]

_preaccelerate(elt)[source]

Get reasonable energy at exit of compensation zone.

Parameters:

elt (Element)

Return type:

Objective

_preshape(elt)[source]

Minimize mismatch factor at exit of compensation zone.

Parameters:

elt (Element)

Return type:

Objective

_retrieve_energy(elt)[source]

Retrieve energy at the end of the linac.

Parameters:

elt (Element)

Return type:

Objective

_abc_impl = <_abc._abc_data object at 0x7318f903ff80>
class EnergyMismatch(reference_simulation_output, broken_elts, failed_elements, compensating_elements, limits_from_design_space_kw)[source]

Bases: ObjectiveFactory

A set of two objectives: energy and mismatch.

We try to match the kinetic energy and the mismatch factor at the end of the last altered lattice (the last lattice with a compensating or broken cavity).

This set of objectives is adapted when you do not need to retrieve the absolute beam phase at the exit of the compensation zone, ie when rephasing all downstream cavities is not an issue.

Parameters:
objective_position_preset: list[Literal['end of last altered lattice', 'one lattice after last altered lattice', 'end of last failed lattice', 'one lattice after last failed lattice', 'end of linac', 'end of every altered lattice']] = ['end of last altered lattice']

List of positions telling where objectives should be evaluated.

get_objectives()[source]

Give objects to match kinetic energy, phase and mismatch factor.

Return type:

list[Objective]

_get_w_kin(elt)[source]

Return object to match energy.

Parameters:

elt (Element)

Return type:

Objective

_get_mismatch(elt)[source]

Return object to keep mismatch as low as possible.

Parameters:

elt (Element)

Return type:

Objective

_abc_impl = <_abc._abc_data object at 0x7318f903fec0>
class EnergyPhaseMismatch(reference_simulation_output, broken_elts, failed_elements, compensating_elements, limits_from_design_space_kw)[source]

Bases: ObjectiveFactory

A set of three objectives: energy, absolute phase, mismatch.

We try to match the kinetic energy, the absolute phase and the mismatch factor at the end of the last altered lattice (the last lattice with a compensating or broken cavity). With this preset, it is recommended to set constraints on the synchrous phase to help the optimisation algorithm to converge.

This set of objectives is robust and rapid for ADS.

Parameters:
objective_position_preset: list[Literal['end of last altered lattice', 'one lattice after last altered lattice', 'end of last failed lattice', 'one lattice after last failed lattice', 'end of linac', 'end of every altered lattice']] = ['end of last altered lattice']

List of positions telling where objectives should be evaluated.

get_objectives()[source]

Give objects to match kinetic energy, phase and mismatch factor.

Return type:

list[Objective]

_get_w_kin(elt)[source]

Return object to match energy.

Parameters:

elt (Element)

Return type:

Objective

_get_phi_abs(elt)[source]

Return object to match phase.

Parameters:

elt (Element)

Return type:

Objective

_get_mismatch(elt)[source]

Return object to keep mismatch as low as possible.

Parameters:

elt (Element)

Return type:

Objective

_abc_impl = <_abc._abc_data object at 0x7318f903fc40>
class EnergySyncPhaseMismatch(reference_simulation_output, broken_elts, failed_elements, compensating_elements, limits_from_design_space_kw)[source]

Bases: ObjectiveFactory

Match the synchronous phase, the energy and the mismatch factor.

It is very similar to EnergyPhaseMismatch, except that synchronous phases are declared as objectives. Objective will be 0 when synchronous phase is within the imposed limits.

Note

Do not set synchronous phases as constraints when using this preset.

This set of objectives is slower than EnergyPhaseMismatch. However, it can help keeping the acceptance as high as possible.

Parameters:
objective_position_preset: list[Literal['end of last altered lattice', 'one lattice after last altered lattice', 'end of last failed lattice', 'one lattice after last failed lattice', 'end of linac', 'end of every altered lattice']] = ['end of last altered lattice']

List of positions telling where objectives should be evaluated.

get_objectives()[source]

Give objects to match kinetic energy, phase and mismatch factor.

Return type:

list[Objective]

_get_w_kin(elt)[source]

Return object to match energy.

Parameters:

elt (Element)

Return type:

Objective

_get_phi_abs(elt)[source]

Return object to match phase.

Parameters:

elt (Element)

Return type:

Objective

_get_mismatch(elt)[source]

Return object to keep mismatch as low as possible.

Parameters:

elt (Element)

Return type:

Objective

_get_phi_s(cavity)[source]

Objective to have sync phase within bounds.

Todo

Allow from_file.

Parameters:

cavity (FieldMap)

Return type:

Objective

_abc_impl = <_abc._abc_data object at 0x7318f903ea00>
class EnergySeveralMismatches(reference_simulation_output, broken_elts, failed_elements, compensating_elements, limits_from_design_space_kw)[source]

Bases: ObjectiveFactory

Match energy and mismatch (the latter on several periods).

Experimental.

Parameters:
objective_position_preset: list[Literal['end of last altered lattice', 'one lattice after last altered lattice', 'end of last failed lattice', 'one lattice after last failed lattice', 'end of linac', 'end of every altered lattice']] = ['end of last altered lattice', 'one lattice after last altered lattice']

List of positions telling where objectives should be evaluated.

get_objectives()[source]

Give objects to match kinetic energy and mismatch factor.

Return type:

list[Objective]

_get_w_kin(elt)[source]

Return object to match energy.

Parameters:

elt (Element)

Return type:

Objective

_get_mismatch(elt)[source]

Return object to keep mismatch as low as possible.

Parameters:

elt (Element)

Return type:

Objective

_abc_impl = <_abc._abc_data object at 0x7318f903db00>
class RegularEnvelope(reference_simulation_output, broken_elts, failed_elements, compensating_elements, design_space_kw, n_lattices=5)[source]

Bases: ObjectiveFactory

Showcase how MinimizeVariation can be used.

Here, we take \(\beta_{\phi,\,W}\) at the exit of the n_lattices lattices after the last failure. We try to minimize standard deviation of these envelopes.

Parameters:
compensation_zone_override_settings = {   'full_lattices': True,     'full_linac': False,     'start_at_beginning_of_linac': False}
__init__(reference_simulation_output, broken_elts, failed_elements, compensating_elements, design_space_kw, n_lattices=5)[source]

Create the object.

Parameters:

  • reference_simulation_output (SimulationOutput) – The reference simulation of the reference linac.

  • broken_elts (ListOfElements) – List containing all the elements of the broken linac.

  • failed_elements (list[Element]) – Cavities that failed.

  • compensating_elements (list[Element]) – Cavities that will be used for the compensation.

  • design_space_kw (dict[str, Any]) – Holds information on variables/constraints limits/initial values. Used to compute the limits that phi_s must respect when the synchronous phase is defined as an objective.

  • n_lattices (int, default: 5) – Number of lattices on which envelope should be checked.

Return type:

None

get_objectives()[source]

Return twiss and energy at end of lattices after failure.

Return type:

list[Objective]

_get_std_twiss_beta()[source]

Return object to match envelope.

Return type:

Objective

_abc_impl = <_abc._abc_data object at 0x7318f903d500>
class Spiral2(reference_simulation_output, broken_elts, failed_elements, compensating_elements, limits_from_design_space_kw)[source]

Bases: CorrectorAtExit

Testing best SPIRAL2 compensation method.

Tests on CMA06 compensation. Currently, CorrectorAtExit leads to the best results. First attempts to set CMA07 as buncher were not convincing.

Parameters:
_abc_impl = <_abc._abc_data object at 0x7318f903e9c0>
OBJECTIVE_PRESETS = {   'CorrectorAtExit': <class 'lightwin.optimisation.objective.factory.CorrectorAtExit'>,     'EnergyMismatch': <class 'lightwin.optimisation.objective.factory.EnergyMismatch'>,     'EnergyPhaseMismatch': <class 'lightwin.optimisation.objective.factory.EnergyPhaseMismatch'>,     'EnergySeveralMismatches': <class 'lightwin.optimisation.objective.factory.EnergySeveralMismatches'>,     'EnergySyncPhaseMismatch': <class 'lightwin.optimisation.objective.factory.EnergySyncPhaseMismatch'>,     'RegularEnvelope': <class 'lightwin.optimisation.objective.factory.RegularEnvelope'>,     'experimental': <class 'lightwin.optimisation.objective.factory.CorrectorAtExit'>,     'rephased_ADS': <class 'lightwin.optimisation.objective.factory.EnergyMismatch'>,     'simple_ADS': <class 'lightwin.optimisation.objective.factory.EnergyPhaseMismatch'>,     'sync_phase_as_objective_ADS': <class 'lightwin.optimisation.objective.factory.EnergySyncPhaseMismatch'>}

Maps the objective_preset key in TOML wtf subsection with actual objects in LightWin

class PackedElements(broken_elts, failed_elements, compensating_elements)[source]

Bases: object

Pack Element info to instantiate ObjectiveFactory.

See also

Fault.packed_elements

Parameters:
broken_elts: ListOfElements

Contains the full linac being fixed.

failed_elements: tuple[Element, ...]

The elements of broken_elts that failed.

compensating_elements: tuple[Element, ...]

Elements of broken_elts used for compensation.

__init__(broken_elts, failed_elements, compensating_elements)
Parameters:
Return type:

None

class ObjectiveMetaFactory(reference_simulation_output)[source]

Bases: object

An object creating ObjectiveFactory for every Fault.

Parameters:

reference_simulation_output (SimulationOutput)

__init__(reference_simulation_output)[source]
Parameters:

reference_simulation_output (SimulationOutput)

Return type:

None

create(objective_preset, limits_from_design_space_kw, packed_elements, objective_factory_class=None)[source]

Create object that will create all the Objective.

Parameters:

  • objective_preset (Literal['CorrectorAtExit', 'EnergyMismatch', 'EnergyPhaseMismatch', 'EnergySeveralMismatches', 'EnergySyncPhaseMismatch', 'RegularEnvelope', 'experimental', 'rephased_ADS', 'simple_ADS'])

  • limits_from_design_space_kw (dict[str, Any])

  • packed_elements (PackedElements)

  • objective_factory_class (type[ObjectiveFactory] | None, default: None)

Return type:

ObjectiveFactory

_factory_class(objective_preset, objective_factory_class=None)[source]

Determine type of ObjectiveFactory to use.

This method does not instantiate the ObjectiveFactory.

Parameters:

  • objective_preset (Literal['CorrectorAtExit', 'EnergyMismatch', 'EnergyPhaseMismatch', 'EnergySeveralMismatches', 'EnergySyncPhaseMismatch', 'RegularEnvelope', 'experimental', 'rephased_ADS', 'simple_ADS'])

  • objective_factory_class (type[ObjectiveFactory] | None, default: None)

Return type:

type[ObjectiveFactory]