fault_scenario module

Define a list-based class holding all the Fault to fix.

We also define fault_scenario_factory(), a factory function creating all the required FaultScenario objects.

class FaultScenario(ref_acc, fix_acc, beam_calculator, wtf, design_space_factory, fault_idx, comp_idx=None, info_other_sol=None, objective_factory_class=None, **kwargs)

Bases: list[Fault]

A class to hold all fault related data.

Parameters:

• ref_acc (Accelerator)

• fix_acc (Accelerator)

• beam_calculator (BeamCalculator)

• wtf (dict[str, Any])

• design_space_factory (DesignSpaceFactory)

• fault_idx (list[int] | list[list[int]])

• comp_idx (list[list[int]] | None, default: None)

• info_other_sol (list[dict] | None, default: None)

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

__init__(ref_acc, fix_acc, beam_calculator, wtf, design_space_factory, fault_idx, comp_idx=None, info_other_sol=None, objective_factory_class=None, **kwargs)

Create the FaultScenario and the Fault objects.

Todo

Could be cleaner.

Parameters:

• ref_acc (Accelerator) – The reference linac (nominal or baseline).

• fix_acc (Accelerator) – The broken linac to be fixed.

• beam_calculator (BeamCalculator) – The solver that will be called during the optimisation process.

• initial_beam_parameters_factory – An object to create beam parameters at the entrance of the linac portion.

• wtf (dict[str, Any]) – What To Fit dictionary. Holds information on the fixing method.

• design_space_factory (DesignSpaceFactory) – An object to easily create the proper DesignSpace.

• fault_idx (list[int] | list[list[int]]) – List containing the position of the errors. If strategy is manual, it is a list of lists (faults already gathered).

• comp_idx (list[list[int]] | None, default: None) – List containing the position of the compensating cavities. If strategy is manual, it must be provided.

• info_other_sol (list[dict] | None, default: None) – Contains information on another fit, for comparison purposes. The default is None.

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

_create_faults(reference_simulation_output, list_of_elements_factory, design_space_factory, *cavities, objective_factory_class=None)

Create the Fault objects.

Parameters:

• reference_simulation_output (SimulationOutput) – The simulation of the nominal linac we’ll try to match.

• list_of_elements_factory (ListOfElementsFactory) – An object that can create ListOfElements.

• design_space_factory (DesignSpaceFactory) – An object that can create DesignSpace.

• *cavities (Sequence[Sequence[FieldMap]]) – First if the list of gathered failed cavities. Second is the list of corresponding compensating cavities.

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

Return type:

list[Fault]

property _reference_simulation_output: SimulationOutput

Determine wich SimulationOutput is the reference.

property _optimisation_algorithms: list[OptimisationAlgorithm]

Set each fault’s optimisation algorithm.

Return type:

The optimisation algorithm for each fault in self.

fix_all()

Fix all the Fault objects in self. :rtype: None

Todo

make this more readable

_wrap_single_fix(fault, optimisation_algorithm, ref_simulation_output)

Fix a fault and recompute propagation with new settings.

Parameters:

• fault (Fault)

• optimisation_algorithm (OptimisationAlgorithm)

• ref_simulation_output (SimulationOutput)

Return type:

OptiSol

_evaluate_fit_quality(save=True, id_solver_ref=None, id_solver_fix=None)

Compute some quantities on the whole linac to see if fit is good.

Parameters:

• save (bool, default: True) – To tell if you want to save the evaluation.

• id_solver_ref (str | None, default: None) – Id of the solver from which you want reference results. The default is None. In this case, the first solver is taken (beam_calc_param).

• id_solver_fix (str | None, default: None) – Id of the solver from which you want fixed results. The default is None. In this case, the solver is the same as for reference.

Return type:

None

_set_evaluation_elements(additional_elt=None)

Set a the proper list of where to check the fit quality.

Parameters:

additional_elt (list[Element] | None, default: None)

Return type:

dict[str, Element]

_simulations_that_should_be_compared(id_solver_ref, id_solver_fix)

Get proper SimulationOutput for comparison.

Parameters:

• id_solver_ref (str | None)

• id_solver_fix (str | None)

Return type:

tuple[SimulationOutput, SimulationOutput]

pickle(pickler, path=None)

Pickle (save) the object.

This is useful for debug and temporary saves; do not use it for long time saving.

Parameters:

• pickler (MyPickler)

• path (Path | str | None, default: None)

Return type:

Path

classmethod from_pickle(pickler, path)

Instantiate object from previously pickled file.

Parameters:

• pickler (MyPickler)

• path (Path | str)

Return type:

Self

_update_status_of_cavities_to_rephase()

Change the status of cavities after first failure.

Only cavities with a reference phase different from "phi_0_abs" are altered. :rtype: None

Todo

Could probably be simpler.

_update_status_of_rephased_cavities(fault)

Modify the status of rephased cavities after compensation.

Change the cavities with status "rephased (in progress)" to "rephased (ok)" between fault and the next Fault.

Parameters:

fault (Fault)

Return type:

None

_update_status_of_broken_cavities()

Break the cavities.

Return type:

None

_transfer_phi0_from_ref_to_broken()

Transfer the reference phases from reference linac to broken.

If the absolute initial phases are not kept between reference and broken linac, it comes down to rephasing the linac. This is what we want to avoid when BeamCalculator.reference_phase_policy is set to "phi_0_abs".

Return type:

None

property _reference_phase_policy: Literal['phi_0_abs', 'phi_0_rel', 'phi_s', 'as_in_original_dat']

Give reference phase policy of BeamCalculator.

_resolve_reference_phase(reference_cavity)

Get the reference phase matching the reference phase policy.

According to the value of BeamCalculator.reference_phase_policy:

• "phi_0_abs", "phi_0_rel", "phi_s": take this reference.

• `"as_in_original_dat": take reference from reference_cavity.

Parameters:

reference_cavity (FieldMap)

Return type:

Literal['phi_0_abs', 'phi_0_rel', 'phi_s']

fault_scenario_factory(accelerators, beam_calc, wtf, design_space, objective_factory_class=None, **kwargs)

Create the FaultScenario objects (factory template).

Parameters:

• accelerators (list[Accelerator]) – Holds all the linacs. The first one must be the reference linac, while all the others will be to be fixed.

• beam_calc (BeamCalculator) – The solver that will be called during the optimisation process.

• wtf (dict[str, Any]) – The WhatToFit table of the TOML configuration file.

• design_space_kw – The design space table from the TOML configuration file.

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

• design_space (dict[str, Any])

Return type:

list[FaultScenario]

Returns:

Holds all the initialized FaultScenario objects, holding their already initialied Fault objects.

_force_element_to_index_method_creation(accelerator, beam_calculator)

Run a first simulation to link Element with their index.

Note

To initalize a Fault, you need a sub:class:.ListOfElements. To create the latter, you need a _element_to_index method. It can only be created if you know the number of steps in every Element. So, for TraceWin, we run a first simulation.

Parameters:

• accelerator (Accelerator)

• beam_calculator (BeamCalculator)

Return type:

None