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_elts, reference_simulation_output, broken_elts, failed_elements, compensating_elements, design_space_kw)[source]

Bases: ABC

A base class to create Objective.

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

Parameters:

  • objective_position_preset (list[str]) – List of keys to dynamically select where the objectives should be matched.

  • compensation_zone_override_settings (dict[str, bool]) – 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_elts (ListOfElements)

  • reference_simulation_output (SimulationOutput)

  • broken_elts (ListOfElements)

  • failed_elements (list[Element])

  • compensating_elements (list[Element])

  • 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']]
compensation_zone_override_settings = {   'full_lattices': False,     'full_linac': False,     'start_at_beginning_of_linac': False}
__init__(reference_elts, reference_simulation_output, broken_elts, failed_elements, compensating_elements, design_space_kw)[source]

Create the object.

Parameters:

  • reference_elts (ListOfElements) – All the reference elements.

  • 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, str | bool | pathlib.Path | float]) – 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.

abstract 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 gives 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]]

static _output_objectives(objectives)[source]

Print information on the objectives that were created.

Parameters:

objectives (list[Objective])

Return type:

None

_abc_impl = <_abc._abc_data object at 0x73dca705eac0>
class EnergyMismatch(reference_elts, reference_simulation_output, broken_elts, failed_elements, compensating_elements, 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']
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 0x73dca6f911c0>
class EnergyPhaseMismatch(reference_elts, reference_simulation_output, broken_elts, failed_elements, compensating_elements, 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']
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 0x73dca6f90c00>
class EnergySyncPhaseMismatch(reference_elts, reference_simulation_output, broken_elts, failed_elements, compensating_elements, 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']
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 0x73dca6f91280>
class EnergySeveralMismatches(reference_elts, reference_simulation_output, broken_elts, failed_elements, compensating_elements, 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']
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 0x73dca6f919c0>
class Spiral2(reference_elts, reference_simulation_output, broken_elts, failed_elements, compensating_elements, design_space_kw)[source]

Bases: ObjectiveFactory

Try something.

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 every altered lattice']
compensation_zone_override_settings = {   'full_lattices': True,     'full_linac': False,     'start_at_beginning_of_linac': False}
get_objectives()[source]

Return twiss and energy at end of lattices after failure.

Return type:

list[Objective]

_get_twiss_alpha(elt)[source]

Return object to match spread.

Parameters:

elt (Element)

Return type:

Objective

_get_twiss_beta(elt)[source]

Return object to match envelope.

Parameters:

elt (Element)

Return type:

Objective

_get_w_kin(elt)[source]

Return object to keep energy reasonable.

Parameters:

elt (Element)

Return type:

Objective

_abc_impl = <_abc._abc_data object at 0x73dca6f91540>
OBJECTIVE_PRESETS = {   'EnergyMismatch': <class 'lightwin.optimisation.objective.factory.EnergyMismatch'>,     'EnergyPhaseMismatch': <class 'lightwin.optimisation.objective.factory.EnergyPhaseMismatch'>,     'EnergySyncPhaseMismatch': <class 'lightwin.optimisation.objective.factory.EnergySyncPhaseMismatch'>,     'experimental': <class 'lightwin.optimisation.objective.factory.Spiral2'>,     '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'>}
get_objectives_and_residuals_function(objective_preset, reference_elts, reference_simulation_output, broken_elts, failed_elements, compensating_elements, design_space_kw, objective_factory_class=None)[source]

Instantiate objective factory and create objectives.

Parameters:

  • reference_elts (ListOfElements) – All the reference elements.

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

  • broken_elts (ListOfElements) – The elements of the broken linac.

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

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

  • design_space_kw (dict | None, optional) – Used when we need to determine the limits for phi_s. Those limits are defined in the .ini configuration file.

  • objective_factory_class (type[ObjectiveFactory] | None, optional) – If provided, will override the objective_preset. Used to let user define it’s own ObjectiveFactory without altering the source code.

  • objective_preset (str)

Return type:

tuple[list[Element], list[Objective], Callable[[SimulationOutput], ndarray]]

Returns:

  • elts_of_compensation_zone (list[Element]) – Portion of the linac that will be recomputed during the optimisation process.

  • objectives (list[Objective]) – Objectives that the optimisation algorithm will try to match.

  • compute_residuals (Callable[[SimulationOutput], np.ndarray]) – Function that converts a SimulationOutput to a plain numpy array of residues.

_compute_residuals(simulation_output, objectives)[source]

Compute residuals on given Objectives for given SimulationOutput.

Parameters:
Return type:

ndarray