simulation_output module

Define a class to store outputs from different BeamCalculator.

Todo

Do I really need the r_zz_elt key??

Todo

Do I really need z_abs? Envelope1D does not uses it while TraceWin does.

Todo

Transfer matrices are stored in TransferMatrix, but also in BeamParameters.zdelta.

Todo

Maybe the synchronous phase model should appear somewhere in here?

class SimulationOutput(out_folder, is_multiparticle, is_3d, synch_trajectory, cav_params, beam_parameters, element_to_index, set_of_cavity_settings, transfer_matrix=None, z_abs=None, in_tw_fashion=None, r_zz_elt=None)[source]

Bases: object

Store the information produced by a BeamCalculator.

Used for fitting, post-processing, plotting.

Parameters:

  • out_folder (Path) – Results folder used by the BeamCalculator that created this.

  • is_multiparticle (bool) – Tells if the simulation is a multiparticle simulation.

  • is_3d (bool) – Tells if the simulation is in 3D.

  • synch_trajectory (ParticleFullTrajectory) – Holds energy, phase of the synchronous particle.

  • cav_params (dict[str, list[float | None]] | None) – Holds amplitude, synchronous phase, absolute phase, relative phase of cavities, phase acceptance, energy acceptance.

  • beam_parameters (BeamParameters) – Holds emittance, Twiss parameters, envelopes in the various phase spaces.

  • element_to_index (ELEMENT_TO_INDEX_T | None) – Takes an Element, its name, ‘first’ or ‘last’ as argument, and returns corresponding index. Index should be the same in all the arrays attributes of this class: z_abs, beam_parameters attributes, etc. Used to easily get the desired properties at the proper position.

  • set_of_cavity_settings (SetOfCavitySettings) – The cavity parameters used for the simulation.

  • transfer_matrix (TransferMatrix | None, default: None) – Holds absolute and relative transfer matrices in all planes.

  • z_abs (ndarray | None, default: None) – Absolute position in the linac in m. The default is None.

  • in_tw_fashion (DataFrame | None, default: None) – A way to output the SimulationOutput in the same way as the Data tab of TraceWin. The default is None.

  • r_zz_elt (list[ndarray] | None, default: None) – Cumulated transfer matrices in the [z-delta] plane. The default is None.

out_folder: Path
is_multiparticle: bool
is_3d: bool
synch_trajectory: ParticleFullTrajectory
cav_params: dict[str, list[float | None]] | None
beam_parameters: BeamParameters
element_to_index: ELEMENT_TO_INDEX_T | None
set_of_cavity_settings: SetOfCavitySettings
transfer_matrix: TransferMatrix | None = None
z_abs: ndarray | None = None
in_tw_fashion: DataFrame | None = None
r_zz_elt: list[ndarray] | None = None
__post_init__()[source]

Save complementary data, such as Element indexes.

Return type:

None

__str__()[source]

Give a resume of the data that is stored.

Return type:

str

property beam_calculator: str

Use out_path to retrieve name of BeamCalculator.

property is_reference: bool

Tell whether this objects concerns a nominal linac.

Todo

MMMh

property linac_id: str

Tell which linac is studied.

Todo

Fix this monstruosity.

has(key)[source]

Tell if the required attribute is in this class.

We also call the InitialBeamParameters.has(), as it is designed to handle the alias (such as twiss_zdelta <=> zdelta.twiss).

Parameters:

key (str)

Return type:

bool

get(*keys, to_numpy=True, to_deg=False, elt=None, pos=None, none_to_nan=False, handle_missing_elt=False, warn_structure_dependent=True, _remove_first=False, **kwargs)[source]

Get attributes from this class or its subcomponents.

See class docstring for parameter descriptions.

Parameters:

  • *keys (Literal['acceptance_energy', 'acceptance_phi', 'beam_parameters', 'element_to_index', 'elt_idx', 'mismatch_factor_zdelta', 'phi_s', 'set_of_cavity_settings', 'synch_trajectory', 'v_cav_mv', 'z_abs'] | Literal['alpha_phiw', 'beta_phiw', 'envelope_energy_phiw', 'envelope_pos_phiw', 'eps_phiw', 'eps_no_normalization_phiw', 'eps_normalized_phiw', 'gamma_phiw', 'sigma_phiw', 'twiss_phiw', 'alpha_phiw99', 'beta_phiw99', 'envelope_energy_phiw99', 'envelope_pos_phiw99', 'eps_phiw99', 'eps_no_normalization_phiw99', 'eps_normalized_phiw99', 'gamma_phiw99', 'sigma_phiw99', 'twiss_phiw99', 'alpha_t', 'beta_t', 'envelope_energy_t', 'envelope_pos_t', 'eps_t', 'eps_no_normalization_t', 'eps_normalized_t', 'gamma_t', 'sigma_t', 'twiss_t', 'alpha_x', 'beta_x', 'envelope_energy_x', 'envelope_pos_x', 'eps_x', 'eps_no_normalization_x', 'eps_normalized_x', 'gamma_x', 'sigma_x', 'twiss_x', 'alpha_x99', 'beta_x99', 'envelope_energy_x99', 'envelope_pos_x99', 'eps_x99', 'eps_no_normalization_x99', 'eps_normalized_x99', 'gamma_x99', 'sigma_x99', 'twiss_x99', 'alpha_y', 'beta_y', 'envelope_energy_y', 'envelope_pos_y', 'eps_y', 'eps_no_normalization_y', 'eps_normalized_y', 'gamma_y', 'sigma_y', 'twiss_y', 'alpha_y99', 'beta_y99', 'envelope_energy_y99', 'envelope_pos_y99', 'eps_y99', 'eps_no_normalization_y99', 'eps_normalized_y99', 'gamma_y99', 'sigma_y99', 'twiss_y99', 'alpha_z', 'beta_z', 'envelope_energy_z', 'envelope_pos_z', 'eps_z', 'eps_no_normalization_z', 'eps_normalized_z', 'gamma_z', 'sigma_z', 'twiss_z', 'alpha_zdelta', 'beta_zdelta', 'envelope_energy_zdelta', 'envelope_pos_zdelta', 'eps_zdelta', 'eps_no_normalization_zdelta', 'eps_normalized_zdelta', 'gamma_zdelta', 'sigma_zdelta', 'twiss_zdelta'] | Literal['alpha', 'beta', 'beta_kin', 'envelope_energy', 'envelope_pos', 'eps', 'eps_no_normalization', 'eps_normalized', 'gamma', 'gamma_kin', 'sigma', 'twiss', 'z_abs'] | Literal['phiw', 'phiw99', 't', 'x', 'x99', 'y', 'y99', 'z', 'zdelta'] | Literal['beta', 'gamma', 'phi_abs', 'synchronous', 'w_kin', 'z_in'] | Literal['e_mev', 'e_rest_mev', 'f_bunch_mhz', 'i_milli_a', 'q_adim', 'sigma', 'inv_e_rest_mev', 'gamma_init', 'omega_0_bunch', 'lambda_bunch', 'q_over_m', 'm_over_q'] | Literal['cumulated', 'individual', 'n_points', 'r_xx', 'r_yy', 'r_zdelta', 'r_zz', 'r_zdelta_11', 'r_zdelta_12', 'r_zdelta_21', 'r_zdelta_22'] | Literal['eps_t', 'eps_x', 'eps_y', 'mismatch_factor_t', 'mismatch_factor_x', 'mismatch_factor_y'] | Literal['eps_phiw99', 'eps_x99', 'eps_y99', 'pow_lost']) – Names of the desired attributes.

  • to_numpy (bool, default: True) – Convert list outputs to NumPy arrays.

  • to_deg (bool, default: False) – Multiply keys with "phi" by 180 / pi.

  • elt (str | Element | Literal['first', 'last'] | Collection[str | Element | Literal['first', 'last']] | None, default: None) – Target element name or instance, passed to recursive_getter. If several elements are provided, they must be contiguous.

  • pos (Literal['in', 'out'] | None, default: None) – Position key for slicing data arrays.

  • none_to_nan (bool, default: False) – Replace None values with np.nan.

  • handle_missing_elt (bool, default: False) – Look for an equivalent element when elt is not in SimulationOutput.element_to_index ‘s _elts.

  • warn_structure_dependent (bool, default: True) – Raise a warning when trying to access data which is structure-related rather than simulation-related.

  • _remove_first (bool, default: False) – Remove the first item of each element’s attribute except for the first element itself. Used when elt consists of several elements, in order to avoid some data to be represented twice.

  • **kwargs (Any) – Additional arguments for recursive_getter.

Returns:

A single value or tuple of values.

Return type:

Any

compute_indirect_quantities(elts, ref_simulation_output=None)[source]

Compute indirect quantities, such as mismatch factor.

Todo

Fix output_data_in_tw_fashion

Parameters:

  • elts (ListOfElements) – A full ListOfElements, containing all the elements of the linac.

  • ref_simulation_output (Self | None, default: None) – Reference simulation output; providing it allows calculation of mismatch factor.

Return type:

None

pickle(pickler, path=None)[source]

Pickle (save) the object.

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

Parameters:
Return type:

Path

classmethod from_pickle(pickler, path)[source]

Instantiate object from previously pickled file.

Parameters:
Return type:

Self

plot(key, to_deg=True, grid=True, **kwargs)[source]

Plot the key.

Parameters:

  • key (str)

  • to_deg (bool, default: True)

  • grid (bool, default: True)

Return type:

Axes | ndarray

elts()[source]

Retrieve the elements associated with this object.

Return type:

ListOfElements

__init__(out_folder, is_multiparticle, is_3d, synch_trajectory, cav_params, beam_parameters, element_to_index, set_of_cavity_settings, transfer_matrix=None, z_abs=None, in_tw_fashion=None, r_zz_elt=None)
Parameters:
Return type:

None

_to_deg(val)[source]

Convert the val[key] into deg if it is not None.

Parameters:

val (ndarray[tuple[Any, ...], dtype[float64]] | list[float | None] | float)

Return type:

ndarray[tuple[Any, ...], dtype[float64]] | list[float | None]