optimisation.objective.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 config.optimisation.objective.

Todo

decorator to auto output the variables and constraints?

Todo

Clarify that objective_position_preset should be understandable by failures.position.

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.

_abc_impl = <_abc._abc_data object>

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

_get_mismatch(elt: Element) → Objective: Return object to keep mismatch as low as possible.

_get_w_kin(elt: Element) → Objective: Return object to match energy.

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

get_objectives() → list[Objective]: Give objects to match kinetic energy, phase and mismatch factor.

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

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.

_abc_impl = <_abc._abc_data object>

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

_get_mismatch(elt: Element) → Objective: Return object to keep mismatch as low as possible.

_get_phi_abs(elt: Element) → Objective: Return object to match phase.

_get_w_kin(elt: Element) → Objective: Return object to match energy.

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

get_objectives() → list[Objective]: Give objects to match kinetic energy, phase and mismatch factor.

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

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.

_abc_impl = <_abc._abc_data object>

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

_get_mismatch(elt: Element) → Objective: Return object to keep mismatch as low as possible.

_get_w_kin(elt: Element) → Objective: Return object to match energy.

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

get_objectives() → list[Objective]: Give objects to match kinetic energy and mismatch factor.

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

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.

_abc_impl = <_abc._abc_data object>

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

_get_mismatch(elt: Element) → Objective: Return object to keep mismatch as low as possible.

_get_phi_abs(elt: Element) → Objective: Return object to match phase.

_get_phi_s(cavity: FieldMap) → Objective: Objective to have sync phase within bounds.

Todo

Allow from_file.

_get_w_kin(elt: Element) → Objective: Return object to match energy.

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

get_objectives() → list[Objective]: Give objects to match kinetic energy, phase and mismatch factor.

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

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.

reference_elts

All the reference elements.

Type:: ListOfElements

reference_simulation_output

The reference simulation of the reference linac.

Type:: SimulationOutput

broken_elts

List containing all the elements of the broken linac.

Type:: ListOfElements

failed_elements

Cavities that failed.

Type:: list[Element]

compensating_elements

Cavities that will be used for the compensation.

Type:: list[Element]

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.

Type:: dict[str, str | bool | Path | float]

__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

__post_init__(): Determine the compensation zone.

_abc_impl = <_abc._abc_data object>

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

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

_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.

broken_elts: ListOfElements

compensating_elements: list[Element]

abstract property compensation_zone_override_settings: dict[str, bool]

Give flags for failures.position.zone_to_recompute().

The returned dictionary may have three flags:

full_lattices
full_linac
start_at_beginning_of_linac

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

failed_elements: list[Element]

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

abstract property objective_position_preset: list[str]

Give a preset for failures.position.zone_to_recompute().

The returned values must be in the POSITION_TO_INDEX dictionary of failures.position.

reference_elts: ListOfElements

reference_simulation_output: SimulationOutput

_compute_residuals(simulation_output: SimulationOutput, objectives: Collection[Objective]) → ndarray: Compute residuals on given Objectives for given SimulationOutput.

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.