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 config.wtf.

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, str | bool | Path | float])

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:

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.

reference_elts: ListOfElements

reference_simulation_output: SimulationOutput

broken_elts: ListOfElements

failed_elements: list[Element]

compensating_elements: list[Element]

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

__post_init__(): Determine the compensation zone.

abstract _elements_where_objective_are_evaluated() → list[Element]: Determine where objectives will be evaluated.

abstract get_objectives() → list[Objective]: Create the Objective instances.

abstract property objective_position_preset: list[str]

Give a preset for zone_to_recompute().

The returned values must be in the POSITION_TO_INDEX dictionary, defined in position.

abstract property compensation_zone_override_settings: dict[str, bool]

Give flags for zone_to_recompute().

The returned dictionary may have three flags:

full_lattices
full_linac
start_at_beginning_of_linac

_set_zone_to_recompute(**wtf: Any) → Sequence[Element]

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

You can override this method for your specific preset.

static _output_objectives(objectives: list[Objective]) → None: Print information on the objectives that were created.

__init__(reference_elts: ListOfElements, reference_simulation_output: SimulationOutput, broken_elts: ListOfElements, failed_elements: list[Element], compensating_elements: list[Element], design_space_kw: dict[str, str | bool | Path | float]) → None

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

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, str | bool | Path | float])

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.

property objective_position_preset: list[str]: Set objective evaluation at end of last altered lattice.

property compensation_zone_override_settings: dict[str, bool]: Set no particular overridings.

_elements_where_objective_are_evaluated() → list[Element]: Give element at end of compensation zone.

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 0x7fd3c8affdc0>

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, str | bool | Path | float])

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.

property objective_position_preset: list[str]: Set objective evaluation at end of last altered lattice.

property compensation_zone_override_settings: dict[str, bool]: Set no particular overridings.

_elements_where_objective_are_evaluated() → list[Element]: Give element at end of compensation zone.

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 0x7fd3c8de6640>

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, str | bool | Path | float])

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.

property objective_position_preset: list[str]: Set objective evaluation at end of last altered lattice.

property compensation_zone_override_settings: dict[str, bool]: Set no particular overridings.

_elements_where_objective_are_evaluated() → list[Element]: Give element at end of compensation zone.

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 0x7fd3c90c76c0>

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, str | bool | Path | float])

Bases: ObjectiveFactory

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

Experimental.

property objective_position_preset: list[str]: Set where objective are evaluated.

property compensation_zone_override_settings: dict[str, bool]: Set no particular overridings.

_elements_where_objective_are_evaluated() → list[Element]: Give element at end of compensation zone.

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 0x7fd3c8f51440>

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.EnergySeveralMismatches'>, '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]) → 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.

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.