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: ListOfElements, reference_simulation_output: SimulationOutput, broken_elts: ListOfElements, failed_elements: list[Element], compensating_elements: list[Element], design_space_kw: dict[str, Any])

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.

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: ListOfElements, reference_simulation_output: SimulationOutput, broken_elts: ListOfElements, failed_elements: list[Element], compensating_elements: list[Element], design_space_kw: dict[str, Any]) → None

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() → list[Objective]

Create the Objective instances.

_set_zone_to_recompute(**wtf: Any) → tuple[list[Element], list[Element]]

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.

static _output_objectives(objectives: list[Objective]) → None

Print information on the objectives that were created.

_abc_impl = <_abc._abc_data object at 0x7f36f755f180>
class EnergyMismatch(reference_elts: ListOfElements, reference_simulation_output: SimulationOutput, broken_elts: ListOfElements, failed_elements: list[Element], compensating_elements: list[Element], design_space_kw: dict[str, Any])

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.

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() → list[Objective]

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

_get_w_kin(elt: Element) → Objective

Return object to match energy.

_get_mismatch(elt: Element) → Objective

Return object to keep mismatch as low as possible.

_abc_impl = <_abc._abc_data object at 0x7f36f75b1c00>
class EnergyPhaseMismatch(reference_elts: ListOfElements, reference_simulation_output: SimulationOutput, broken_elts: ListOfElements, failed_elements: list[Element], compensating_elements: list[Element], design_space_kw: dict[str, Any])

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.

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() → list[Objective]

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

_get_w_kin(elt: Element) → Objective

Return object to match energy.

_get_phi_abs(elt: Element) → Objective

Return object to match phase.

_get_mismatch(elt: Element) → Objective

Return object to keep mismatch as low as possible.

_abc_impl = <_abc._abc_data object at 0x7f36f75b2100>
class EnergySyncPhaseMismatch(reference_elts: ListOfElements, reference_simulation_output: SimulationOutput, broken_elts: ListOfElements, failed_elements: list[Element], compensating_elements: list[Element], design_space_kw: dict[str, Any])

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.

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() → list[Objective]

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

_get_w_kin(elt: Element) → Objective

Return object to match energy.

_get_phi_abs(elt: Element) → Objective

Return object to match phase.

_get_mismatch(elt: Element) → Objective

Return object to keep mismatch as low as possible.

_get_phi_s(cavity: FieldMap) → Objective

Objective to have sync phase within bounds.

Todo

Allow from_file.

_abc_impl = <_abc._abc_data object at 0x7f36f75b2740>
class EnergySeveralMismatches(reference_elts: ListOfElements, reference_simulation_output: SimulationOutput, broken_elts: ListOfElements, failed_elements: list[Element], compensating_elements: list[Element], design_space_kw: dict[str, Any])

Bases: ObjectiveFactory

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

Experimental.

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() → list[Objective]

Give objects to match kinetic energy and mismatch factor.

_get_w_kin(elt: Element) → Objective

Return object to match energy.

_get_mismatch(elt: Element) → Objective

Return object to keep mismatch as low as possible.

_abc_impl = <_abc._abc_data object at 0x7f36f7cf5500>
class Spiral2(reference_elts: ListOfElements, reference_simulation_output: SimulationOutput, broken_elts: ListOfElements, failed_elements: list[Element], compensating_elements: list[Element], design_space_kw: dict[str, Any])

Bases: ObjectiveFactory

Try something.

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() → list[Objective]

Return twiss and energy at end of lattices after failure.

_get_twiss_alpha(elt: Element) → Objective

Return object to match spread.

_get_twiss_beta(elt: Element) → Objective

Return object to match envelope.

_get_w_kin(elt: Element) → Objective

Return object to keep energy reasonable.

_abc_impl = <_abc._abc_data object at 0x7f36f75b2180>
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: str, reference_elts: ListOfElements, reference_simulation_output: SimulationOutput, broken_elts: ListOfElements, failed_elements: list[Element], compensating_elements: list[Element], design_space_kw: dict[str, float | bool | str | Path], objective_factory_class: type[ObjectiveFactory] | None = None) → tuple[list[Element], list[Objective], Callable[[SimulationOutput], ndarray]]

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.

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: SimulationOutput, objectives: Collection[Objective]) → ndarray

Compute residuals on given Objectives for given SimulationOutput.