simulations_results module

Define a set of simulation results.

exception UnsupportedToolError

Bases: Exception

Raise for simulation tool different from SPARK3D or CST.

exception DuplicateIndexError

Bases: Exception

Raise for simulation ID already existing.

exception NonExistingIDError

Bases: Exception

Raise when asking a non-existent ID.

class SimulationsResults(simulations_results, plotter=None)

Bases: object

Store multiple SimulationResults with retrieval methods.

SimulationResult are stored in self in the order they are given.

Parameters:

• simulations_results (Iterable[SimulationResults])

• plotter (Plotter | None, default: None)

__init__(simulations_results, plotter=None)

Sort and store the given SimulationResults instances.

Parameters:

• simulations_results (Iterable[SimulationResults]) – The individual results instances.

• plotter (Plotter | None, default: None) – An object to create the plots.

_results: list[SimulationResults]

SimulationResults sorted by increasing accelerating field

_add(result)

Add a new SimulationResults instance.

Parameters:

result (SimulationResults)

Return type:

None

get_by_id(result_id)

Retrieve a SimulationResults by its ID.

Parameters:

result_id (int)

Return type:

SimulationResults

property to_list: list[SimulationResults]

Retrieve all results sorted by acc_field.

plot(x, y, idx_to_plot=None, id_to_plot=None, to_plot=None, plotter=None, label='auto', grid=True, axes=None, sort_by_parameter=None, **kwargs)

Recursively call SimulationResults.plot().

Note

0D x vs y not implemented yet.

Parameters:

• x (Union[Literal['id', 'e_acc', 'p_rms', 'alpha'], Literal['time', 'population', 'modelled_population']]) – Name of properties to plot.

• y (Union[Literal['id', 'e_acc', 'p_rms', 'alpha'], Literal['time', 'population', 'modelled_population']]) – Name of properties to plot.

• idx_to_plot (Iterable[int] | None, default: None) – Positions in the list of SimulationResults sorted by growing accelerating field / power. Not considered if id_to_plot or to_plot is provided.

• id_to_plot (Iterable[int] | None, default: None) – ID attributes; takes preceedence over idx_to_plot. Not considered if to_plot is provided.

• to_plot (Iterable[SimulationResults] | None, default: None) – Objects to plot; takes preceedence over idx_to_plot and id_to_plot.

• plotter (Plotter | None, default: None) – Object to use for plot. If not provided, we use _plotter.

• label (Union[str, Literal['auto'], None], default: 'auto') – If provided, overrides the legend. Useful when several simulations are shown on the same plot. Use the magic keyword "auto" to legend with a short description of current object.

• grid (bool, default: True) – If grid should be plotted. Default is True.

• axes (Any | None, default: None) – Axes to re-use, if provided.

• sort_by_parameter (Collection[str] | None, default: None) – If provided, results are grouped by the given parameters before plotting.

• kwargs – Other keyword arguments passed to the Plotter.plot() method.

Returns:

Objects created by the Plotter.plot().

Return type:

Any

_to_plot(idx_to_plot=None, id_to_plot=None, to_plot=None)

Give the SimulationResults to plot.

When all arguments are None, we return all the stored SimulationResults.

Parameters:

• idx_to_plot (Iterable[int] | None, default: None) – Positions in the list of SimulationResults sorted by growing accelerating field / power. Not considered if id_to_plot or to_plot is provided.

• id_to_plot (Iterable[int] | None, default: None) – ID attributes; takes preceedence over idx_to_plot. Not considered if to_plot is provided.

• to_plot (Iterable[SimulationResults] | None, default: None) – Objects to plot; takes preceedence over idx_to_plot and id_to_plot.

Return type:

list[SimulationResults]

_plot_0d(x, y, plotter, label=None, grid=True, axes=None, to_plot=None, color='auto', **kwargs)

Concatenate and plot 0D data from results.

Parameters:

• x (Literal['id', 'e_acc', 'p_rms', 'alpha']) – Name of properties to plot.

• y (Literal['id', 'e_acc', 'p_rms', 'alpha']) – Name of properties to plot.

• plotter (Plotter) – Object to use for plot.

• label (Union[str, Literal['auto'], None], default: None) – If provided, overrides the legend. Useful when several simulations are shown on the same plot. Use the magic keyword "auto" to legend with a short description of current object.

• grid (bool, default: True) – If grid should be plotted. Default is True.

• axes (Any | None, default: None) – Axes to re-use, if provided.

• to_plot (Sequence[SimulationResults] | None, default: None) – The objects to plot. If not given, plot all the objects.

• color (Any, default: 'auto') – Color for the plot. If “auto”, we use the SimulationsResults._color attribute.

• kwargs – Other keyword arguments passed to the Plotter.plot() method.

Returns:

Objects created by the Plotter.plot().

Return type:

Any

_to_pandas(*args, results=None)

Concatenate all attributes which name is in args to a dataframe.

Todo

Review this and its error handling

Parameters:

• args (Literal['id', 'e_acc', 'p_rms', 'alpha']) – Name of SimulationResults arguments to concatenate.

• results (Sequence[SimulationResults] | None, default: None) – If given, we concatenate only the data frome these SimulationResults.

Returns:

Holds the values of every element of args.

Return type:

pandas.DataFrame

Raises:

ValueError: – If one of the args is an array or is missing.

fit_alpha(fitting_periods, running_mean=True, log_fit=True, minimum_final_number_of_electrons=0, bounds=([1e-10, -10.0], [inf, 10.0]), initial_values=[0.0, 0.0], **kwargs)

Fit exp growth factor.

Parameters:

• fitting_periods (int) – Number of periods over which the exp growth is searched. Longer is better, but you do not want to start the fit before the exp growth starts.

• running_mean (bool, default: True) – To tell if you want to average the number of particles over one period. Highly recommended.

• log_fit (bool, default: True) – To perform the fit on exp_growth_log() rather than exp_growth(). The default is True, as it generally shows better convergence.

• minimum_final_number_of_electrons (int, default: 0) – Under this final number of electrons, we do no bother finding the exp growth factor and set all fit parameters to NaN.

• bounds (tuple[list[float], list[float]], default: ([1e-10, -10.0], [inf, 10.0])) – Upper bound and lower bound for the two variables: initial number of electrons, exp growth factor.

• initial_values (list[float], optional) – Initial values for the two variables: initial number of electrons, exp growth factor.

Return type:

None

save(filepath, *to_save, sep=',', merge_on=None, **kwargs)

Concatenate all data named to_save and save it to a file.

Parameters:

• filepath (Path | str) – Where to save the file.

• to_save (Union[Literal['id', 'e_acc', 'p_rms', 'alpha'], Literal['time', 'population', 'modelled_population']]) – The list of quantities to save.

• sep (str, default: ',') – Column separator. Default is a comma.

• merge_on (Union[Literal['id', 'e_acc', 'p_rms', 'alpha'], Literal['time', 'population', 'modelled_population'], None], default: None) – If provided, the different dataframe will be merged against this column. Typical usage is merge_on="time" to have a single time column.

Return type:

None

_format_for_save(*to_save, merge_on=None, **kwargs)

Concatanate desired data into a single dataframe.

Parameters:

• to_save (Union[Literal['id', 'e_acc', 'p_rms', 'alpha'], Literal['time', 'population', 'modelled_population']]) – The list of quantities to save.

• merge_on (Union[Literal['id', 'e_acc', 'p_rms', 'alpha'], Literal['time', 'population', 'modelled_population'], None], default: None) – If provided, the different dataframe will be merged against this column. Typical usage is merge_on="time" to have a single time column.

Returns:

Contains all the data to save, with proper format.

Return type:

pd.DataFrame

parameter_values(*parameters, default=None, allow_missing=False)

Get the existing values of all parameters in the stored results.

If no parameters are given, return all parameters with their possible values.

Parameters:

• *parameters (str) – Name of the parameter(s) to get. Must be key in the parameters dictionary of the stored SimulationResult. If empty, all parameters found in any result are returned.

• default (Any, default: None) – The fallback value when the parameter is not a key of a SimulationResult.parameters.

• allow_missing (bool, default: False) – If True, an error is raised when default is present in the output set.

Returns:

all_values – Keys are all the parameters. Values corresponding values in every storred SimulationResult.

Return type:

dict[str, set]

with_parameter_value(parameters)

Yield SimulationResults matching given parameter values.

Parameters:

parameters (dict[str, Any]) – Parameter names and their required values.

Yields:

SimulationResults – SimulationResults instances whose parameters match the given values.

Return type:

Generator[SimulationResults, None, None]

show()

Show the plots that were produced.

Useful for the bash interface.

Return type:

None

class SimulationsResultsFactory(tool, plotter=None, freq_ghz=None, *args, **kwargs)

Bases: object

An object to create a SimulationsResults.

Parameters:

• tool (Literal['SPARK3D', 'CST'])

• plotter (Plotter | None, default: None)

• freq_ghz (float | None, default: None)

__init__(tool, plotter=None, freq_ghz=None, *args, **kwargs)

Create object to easily generate simulation results.

Parameters:

• tool (str) – Name of the tool.

• plotter (Plotter | None, default: None) – Object to create the plots.

• freq_ghz (float | None, default: None) – RF frequency in GHz. Used to compute RF period, which is mandatory for exp growth fitting.

create(*, filepath=None, master_folder=None, e_acc=None, **kwargs)

Create all the objects.

Parameters:

• plotter – An object to plot data.

• filepath (Path | None, default: None) – Filepath to a TXT or CSV file for SPARK3D.

• master_folder (Path | None, default: None) – Filepath to the folder holding all the mmdd-xxxxxxx folders for CST.

• e_acc (ndarray | None, default: None) – The accelerating fields, used by SPARK3D.

• kwargs – Keyword arguments passed to the appropriate subclass of SimulationResultsFactory.

Returns:

A concatenation of the individual simulations.

Return type:

SimulationsResults

_create_individual(*, plotter, filepath=None, master_folder=None, e_acc=None, **kwargs)

Create several individual SimulationResults.

Parameters:

• plotter (Plotter) – An object to plot data.

• filepath (Path | None, default: None) – Filepath to a TXT or CSV file for SPARK3D.

• master_folder (Path | None, default: None) – Filepath to the folder holding all the mmdd-xxxxxxx folders for CST.

• e_acc (ndarray | None, default: None) – The accelerating fields, used by SPARK3D.

• kwargs – Keyword arguments passed to the appropriate subclass of SimulationResultsFactory.

Returns:

The individual SimulationResults.

Return type:

Sequence[SimulationResults]

Raises:

NotImplementedError: – When self._tool is not in ("CST", "SPARK3D").