plot module

Define a library to produce all these nice plots.

Todo

better detection of what is a multiparticle simulation and what is not. Currently looking for “‘partran’: 0” in the name of the solver, making the assumption that multipart is the default. But it depends on the .ini… update: just use .is_a_multiparticle_simulation

Todo

Fix when there is only one accelerator to plot.

Todo

Different plot according to dimension of FieldMap, or according to if it accelerates or not (ex when quadrupole defined by a field map)

ALLOWED_PLOT_PRESETS = [   'acceptance',     'cav',     'emittance',     'energy',     'envelopes',     'mismatch_factor',     'phase',     'transfer_matrices',     'twiss']

List of implemented presets for the plots

factory(accelerators, plots, save_fig=True, clean_fig=True, fault_scenarios=None, only_solver_id=None, **kwargs)[source]

Create all the desired plots.

Parameters:

  • accelerators (dict[int, list[Accelerator]]) –

    Mapping of scenario index to a list of accelerators for that scenario. Key 0 is always the reference (single element). All other keys are “fixed” scenarios, each potentially holding several alternative accelerators that will be overlaid on the same figure:

    {
    0: [reference_accelerator],
    1: [fixed_01],
    2: [fixed_02, alternative_02],
}

  • plots (dict[str, Any]) – The plot TOML table.

  • save_fig (bool, default: True) – If Figures should be saved.

  • clean_fig (bool, default: True) – If Figures should be cleaned between two calls of this function.

  • fault_scenarios (Sequence[FaultScenario] | None, default: None) – If provided, the position of the Objective will also appear on plots.

  • kwargs – Other tables from the TOML configuration file.

  • only_solver_id (Collection[str] | str | None, default: None)

Return type:

list[Figure]

Returns:

The created figures.

_separate_plot_presets_from_plot_modificators(plots)[source]

Separate the config entries corresponding to the name of a plot.

Parameters:

plots (dict[str, Any]) – Dictionary holding the plot configuration.

Return type:

tuple[dict[str, bool], dict[str, Any]]

Returns:

  • plot_presets – Subset of plots, with only the keys that can be found in ALLOWED_PLOT_PRESETS. Indicates which plots presets will be plotted: "cav", "emittance"…

  • plot_kwargs – Subset of plots, with only the keys corresponding to a plot modificator, eg "add_objectives".

_build_plot_groups(accelerators)[source]

Build the groups of accelerators to plot together.

Each group will produce one figure per preset. The reference accelerator is always first. Scenario 0 produces a group of just [ref_acc]. Other scenarios produce [ref_acc, *computed_accs], and are skipped entirely if none of their accelerators are computed yet.

Parameters:

accelerators (dict[int, list[Accelerator]]) – The full scenario mapping as passed to factory(). Must have the 0 key, the corresponding value must be a list containing only the reference Accelerator.

Return type:

list[list[Accelerator]]

Returns:

List of accelerator groups, one per scenario to plot.

_plot_preset(preset, *accelerators_to_plot, all_y_axis, x_axis='z_abs', save_fig=True, clean_fig=True, add_objectives=False, fault_scenarios=None, usr_kwargs=None, get_kwargs=None, symmetric_plot=False, only_solver_id=None, **kwargs)[source]

Plot a preset showing reference and all fixed alternatives for one scenario.

Parameters:

  • preset (str) – Key of ALLOWED_PLOT_PRESETS.

  • *accelerators_to_plot – Accelerators to plot. First is always the reference. May contain only the reference (scenario 0), or reference + one or more fixed alternatives.

  • all_y_axis (list[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'] | Literal['struct']]) – Name of all the y axis.

  • x_axis (Literal['z_abs', 'elt_idx'], default: 'z_abs') – Name of the x axis.

  • save_fig (bool, default: True) – To save Figures or not. Figure is saved to the path of fix_accs[0].

  • add_objectives (bool, default: False) – To add the position of objectives to the plots; if True, the fault_scenarios must be provided.

  • fault_scenarios (Sequence[list[Fault]] | None, default: None) – To plot the objectives, if add_objectives == True.

  • usr_kwargs (dict[str, Any] | None, default: None) – User-defined kwargs, passed to the matplotlib.axes.Axes.plot() method.

  • get_kwargs (dict[str, bool] | None, default: None) – Keyword arguments for the SimulationOutput.get() methods.

  • symmetric_plot (bool, default: False) – If plot should be symmetric around the x axis.

  • only_solver_id (Collection[str] | str | None, default: None) – If set, we plot only data obtained with this solver(s). Must be BeamCalculator.id (or, equivalently, a key(s) in Accelerator.simulation_outputs). Typical values: "0_Envelope1D" or "1_TraceWin".

  • **kwargs – Holds all complementary data on the plots.

  • clean_fig (bool, default: True)

Return type:

Figure

_proper_kwargs(preset, kwargs)[source]

Merge dicts, priority kwargs > PLOT_PRESETS > FALLBACK_PRESETS.

We also add a "usr_kwargs" key holding additional keywords, that will be passed to matplotlib.axes.Axes.plot().

Parameters:
Return type:

dict[str, Any]

_used_colors(axe)[source]

Associate every line label to a color.

Parameters:

axe (Axes)

Return type:

dict[str, tuple[float, float, float] | str | tuple[float, float, float, float] | tuple[tuple[float, float, float] | str, float] | tuple[tuple[float, float, float, float], float]]

_y_label(y_axis)[source]

Set the proper y axis label.

Parameters:

y_axis (str)

Return type:

str

_make_a_subplot(axe, x_axis, y_axis, colors, *accelerators, plot_section=True, symmetric_plot=False, get_kwargs=None, only_solver_id=None, **usr_kwargs)[source]

Get proper data and plot it on an Axe.

Parameters:

  • axe (Axes) – Object on which to add plot data.

  • x_axis (Literal['z_abs', 'elt_idx']) – Nature of x axis.

  • y_axis (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'] | Literal['struct']) – What to plot.

  • colors (dict[str, tuple[float, float, float] | str | tuple[float, float, float, float] | tuple[tuple[float, float, float] | str, float] | tuple[tuple[float, float, float, float], float]] | None) – Holds the line labels from previous plots and associate it to their colors.

  • accelerators (Accelerator) – Objects from which we take y_axis.

  • plot_section (bool, default: True) – To outline the different sections in the background of the plots.

  • symmetric_plot (bool, default: False) – If a symmetric plot (wrt x axis) should be added.

  • get_kwargs (dict[str, bool] | None, default: None) – Keyword arguments for the SimulationOutput.get() method.

  • only_solver_id (Collection[str] | str | None, default: None) – If set, we plot only data obtained with this solver(s). Must be BeamCalculator.id (or, equivalently, a key(s) in Accelerator.simulation_outputs). Typical values: "0_Envelope1D" or "1_TraceWin".

  • usr_kwargs – User-defined kwargs, passed to the matplotlib.axes.Axes.plot() method.

Return type:

None

plot_pty_with_data_tags(ax, x, y, idx_list, tags=True)[source]

Plot y vs x.

Data at idx_list are magnified with bigger points and data tags.