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(accelerator_id, beam_calculator_id, elts, 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, pow_lost=None)

Bases: object

Store the information produced by a BeamCalculator.

Used for fitting, post-processing, plotting.

Parameters:

• accelerator_id (str) – Associated Accelerator.id. Looks like: 0000001_Solution.

• beam_calculator_id (str) – ID of solver that created this object. Also used as the name of the subdirectory where results should be saved. Typically, "0_Envelope1D" or "1_TraceWin".

• elts (ListOfElements) – Elements on which this object was calculated.

• 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 (CavParams) – 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) – 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[tuple[Any, ...], dtype[double]] | 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[tuple[Any, ...], dtype[double]]] | None, default: None) – Cumulated transfer matrices in the [z-delta] plane. The default is None.

• pow_lost (ndarray[tuple[Any, ...], dtype[double]] | None, default: None) – Lost power along linac in \(\mathrm{W}\). Can only be given by TraceWin.

accelerator_id: str

beam_calculator_id: str

elts: ListOfElements

is_multiparticle: bool

is_3d: bool

synch_trajectory: ParticleFullTrajectory

cav_params: CavParams

beam_parameters: BeamParameters

element_to_index: ELEMENT_TO_INDEX_T

set_of_cavity_settings: SetOfCavitySettings

transfer_matrix: TransferMatrix | None = None

z_abs: ndarray[tuple[Any, ...], dtype[float64]] | None = None

in_tw_fashion: DataFrame | None = None

r_zz_elt: list[ndarray[tuple[Any, ...], dtype[float64]]] | None = None

pow_lost: ndarray[tuple[Any, ...], dtype[float64]] | None = None

__post_init__()

Save complementary data, such as Element indexes.

Return type:

None

__str__()

Give a resume of the data that is stored.

Return type:

str

property is_reference: bool

Tell whether this objects concerns a nominal linac.

Todo

Not very robust.

has(key)

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)

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)

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)

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 | None

classmethod from_pickle(pickler, path=None)

Instantiate object from previously pickled file.

Parameters:

• pickler (MyPickler) – Pickler object.

• path (Path | str | None, default: None) – Path to the pickled object file. If not provided, use Tk to open GUI and let user choose.

Return type:

Self

plot(key, to_deg=True, grid=True, x=None, legend_entry=None, ax=None, **kwargs)

Plot the key.

This method does not use the default plotting module, but pandas dataframe plotting method.

Parameters:

• key (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'])

• to_deg (bool, default: True)

• grid (bool, default: True)

• x (Literal['z_abs', 'elt_idx'] | None, default: None)

• legend_entry (str | None, default: None)

• ax (Axes | None, default: None)

Return type:

Axes | None

__init__(accelerator_id, beam_calculator_id, elts, 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, pow_lost=None)

Parameters:

• accelerator_id (str)

• beam_calculator_id (str)

• elts (ListOfElements)

• is_multiparticle (bool)

• is_3d (bool)

• synch_trajectory (ParticleFullTrajectory)

• cav_params (CavParams)

• beam_parameters (BeamParameters)

• element_to_index (ELEMENT_TO_INDEX_T)

• set_of_cavity_settings (SetOfCavitySettings)

• transfer_matrix (TransferMatrix | None, default: None)

• z_abs (ndarray[tuple[Any, ...], dtype[double]] | None, default: None)

• in_tw_fashion (DataFrame | None, default: None)

• r_zz_elt (list[ndarray[tuple[Any, ...], dtype[double]]] | None, default: None)

• pow_lost (ndarray[tuple[Any, ...], dtype[double]] | None, default: None)

Return type:

None

_to_deg(val)

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

Parameters:

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

Return type:

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