envelope_3d module

Define Envelope3D, an envelope solver.

class Envelope3D(*, reference_phase_policy, out_folder, default_field_map_folder, beam_kwargs, export_phase, phi_s_definition='historical', n_steps_per_cell, method='RK4', **kwargs)[source]

Bases: BeamCalculator

A 3D envelope solver.

As transverse effects are generally not predominant, I do not use this solver very often and a lot of elements are not implemented. The current list of explicitly supported elements is:

Bend

FieldMap

Diagnostic

Quad

Drift

Solenoid

The default behavior when an element in the input DAT file is not recognized, is to issue a warning and replace this element by a DRIFT.

Do not hesitate to file an issue if you need me to implement some elements.

Parameters:

  • reference_phase_policy (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | Literal['as_in_original_dat'])

  • out_folder (Path | str)

  • default_field_map_folder (Path | str)

  • beam_kwargs (BeamKwargs)

  • export_phase (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | Literal['as_in_original_dat'] | Literal['as_in_settings'])

  • phi_s_definition (Literal['historical', 'lagniel'], default: 'historical')

  • n_steps_per_cell (int)

  • method (Literal['RK4'], default: 'RK4')

flag_cython = False
__init__(*, reference_phase_policy, out_folder, default_field_map_folder, beam_kwargs, export_phase, phi_s_definition='historical', n_steps_per_cell, method='RK4', **kwargs)[source]

Set the proper motion integration function, according to inputs.

Parameters:

  • reference_phase_policy (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | Literal['as_in_original_dat'])

  • out_folder (Path | str)

  • default_field_map_folder (Path | str)

  • beam_kwargs (BeamKwargs)

  • export_phase (Literal['phi_0_abs', 'phi_0_rel', 'phi_s'] | Literal['as_in_original_dat'] | Literal['as_in_settings'])

  • phi_s_definition (Literal['historical', 'lagniel'], default: 'historical')

  • n_steps_per_cell (int)

  • method (Literal['RK4'], default: 'RK4')

Return type:

None

_set_up_specific_factories()[source]

Set up the factories specific to the BeamCalculator.

This method is called in the BeamCalculator.__init__(), hence it appears only in the base BeamCalculator.

Return type:

None

run(elts, update_reference_phase=False, **kwargs)[source]

Compute beam propagation in 3D, envelope calculation.

Parameters:

  • elts (ListOfElements) – List of elements in which the beam must be propagated.

  • update_reference_phase (bool, default: False) – To change the reference phase of cavities when it is different from the one asked in the .toml. To use after the first calculation, if BeamCalculator.flag_phi_abs does not correspond to CavitySettings.reference.

Return type:

SimulationOutput

Returns:

Holds energy, phase, transfer matrices (among others) packed into a single object.

run_with_this(set_of_cavity_settings, elts, use_a_copy_for_nominal_settings=True)[source]

Compute beam propagation with non-nominal settings.

Parameters:

  • set_of_cavity_settings (SetOfCavitySettings | None) – The new cavity settings to try. If it is None, then the cavity settings are taken from the FieldMap objects.

  • elts (ListOfElements) – List of elements in which the beam must be propagated.

  • use_a_copy_for_nominal_settings (bool, default: True) – To copy the nominal CavitySettings and avoid altering their nominal counterpart. Set it to True during optimisation, to False when you want to keep the current settings.

Return type:

SimulationOutput

Returns:

Holds energy, phase, transfer matrices (among others) packed into a single object.

post_optimisation_run_with_this(optimized_cavity_settings, full_elts, **specific_kwargs)[source]

Run Envelope3D with optimized cavity settings.

With this solver, we have nothing to do, nothing to update. Just call the regular run_with_this method.

Parameters:
Return type:

SimulationOutput

init_solver_parameters(accelerator)[source]

Create the number of steps, meshing, transfer functions for elts.

The solver parameters are stored in the Element’s beam_calc_param.

:param Object which ListOfElements must be initialized.:

Parameters:

accelerator (Accelerator)

Return type:

None

property is_a_multiparticle_simulation: bool

Return False.

property is_a_3d_simulation: bool

Return True.

_compute_cavity_parameters(results)[source]

Compute the cavity parameters by calling _phi_s_func.

Parameters:

results (dict) – The dictionary of results as returned by the transfer matrix function wrapper.

Return type:

tuple[float, float]

Returns:

Accelerating voltage in MV and synchronous phase in radians. If the cavity is failed, two np.nan are returned.

_abc_impl = <_abc._abc_data object at 0x76a8680e2f80>
_store_entry_phase_in_settings(phi_bunch_abs, cavity_settings)[source]

Set entry phase.

Parameters:
Return type:

None