simulation_results module

Define an object to store CST simulation results.

Note

As for now, it can only load data stored in a single file. For Position Monitor exports (one file = one time step), see dedicated package PositionMonitor.

Todo

Evaluate expressions such as param2 = 2 * param1

Todo

Allow to have P_rms instead of E_acc; E_acc does not make a lot of sense in a lot of cases.

exception MissingFileError[source]

Bases: Exception

Error raised when a mandatory CST file was not found.

class CSTResults(id, e_acc, time, population, p_rms=None, plotter=None, trim_trailing=False, period=None, parameters=None, stl_alpha=None, particle_monitor=None, **kwargs)[source]

Bases: SimulationResults

Store a single CST simulation results.

Parameters:
__init__(id, e_acc, time, population, p_rms=None, plotter=None, trim_trailing=False, period=None, parameters=None, stl_alpha=None, particle_monitor=None, **kwargs)[source]

Instantiate, post-process.

Parameters:

  • id (int) – Unique simulation identifier.

  • e_acc (float) – Accelerating field in \(\mathrm{V/m}\).

  • time (ndarray) – Time in \(\mathrm{ns}\).

  • population (ndarray) – Evolution of population with time. Same shape as time.

  • p_rms (float | None, default: None) – RMS power in \(\mathrm{W}\).

  • plotter (Plotter | None, default: None) – An object allowing to plot data.

  • trim_trailing (bool, default: False) – To remove the last simulation points, when the population is 0. Used with SPARK3D (CSV import) for consistency with CST.

  • period (float | None, default: None) – RF period in \(\mathrm{ns}\). Mandatory for exponential growth fits.

  • parameters (dict[str, float | bool | str] | None, default: None) – Additional information on the simulation. Typically, value of magnetic field, number of PIC cells, simulation flags…

  • stl_path – Path to the STL file holding the 3D structure of the system. If given, we automatically load it.

  • stl_alpha (float | None, default: None) – Transparency for the 3D mesh.

  • particle_monitor (ParticleMonitor | None, default: None) – Stores all particle monitor data.

hist(x, bins=200, hist_range=None, plotter=None, filter=None, **kwargs)[source]

Create a histogram.

Parameters:

  • x (Literal['emission_energy', 'collision_energy', 'collision_angle']) – Name of the data to plot.

  • bins (int, default: 200) – Number of histogram bins.

  • hist_range (tuple[float, float] | None, default: None) – Lower and upper value for the histogram.

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

  • filter (Union[Literal['seed', 'emitted', 'collision', 'no collision'], Callable[[Particle], bool], None], default: None) – To plot only some of the particles.

Return type:

Any

plot_3d(key, **kwargs)[source]
Parameters:

key (Literal['trajectory', 'collision_distribution', 'emission_distribution'])

Return type:

Any

plot_mesh(*args, **kwargs)[source]

Plot the stored mesh.

Return type:

Any

plot_trajectories(emission_color=None, collision_color=None, lw=7, r=8, plotter=None, filter=None, **kwargs)[source]

Plot trajectories in 3D.

Parameters:

  • emission_color (str | None, default: None) – If provided, the first known position is colored with this color.

  • collision_color (str | None, default: None) – If provided, the last known position is colored with this color.

  • collision_point – If provided and collision_color is not None, we plot this point instead of the last of points. This is useful when the extrapolated time is large, and actuel collision point may differ significantly from last position points.

  • lw (int, default: 7) – Trajectory line width.

  • r (int, default: 8) – Size of the emission/collision points.

  • plotter (Plotter | None, default: None) – An object allowing to plot data.

  • filter (Union[Literal['seed', 'emitted', 'collision', 'no collision'], Callable[[Particle], bool], None], default: None) – To select the particles to be plotted.

Return type:

Any

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

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: False) – To tell if you want to average the number of particles over one period. It is recommended with CST, but does not bring anything for SPARK3D. The default is False.

  • 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.

  • minimum_number_of_points (int, default: 20) – Minimum number of fitting points; under this limit, a warning is issued. For CST, should be at least 10 or 20. With SPARK3D, there are two points per RF period so a value of 2 or 4 should be enough.

  • min_points_per_period (int, default: 5) – Minimum number of points per period. In SPARK3D, we only have two points per RF period so this number should be lower to avoid unnecessary warnings.

Return type:

None

_abc_impl = <_abc._abc_data object at 0x756080281a00>
class CSTResultsFactory(*args, plotter=None, freq_ghz=None, e_acc_parameter=('E_acc', 'e_acc', 'accelerating_field'), e_acc_file_mv_m='E_acc in MV per m.txt', p_rms_file=None, stl_path=None, stl_alpha=None, **kwargs)[source]

Bases: SimulationResultsFactory

Define an object to easily instantiate CSTResults.

Parameters:

  • plotter (Plotter | None, default: None)

  • freq_ghz (float | None, default: None)

  • e_acc_parameter (Sequence[str], default: ('E_acc', 'e_acc', 'accelerating_field'))

  • e_acc_file_mv_m (str, default: 'E_acc in MV per m.txt')

  • p_rms_file (str | None, default: None)

  • stl_path (Path | str | None, default: None)

  • stl_alpha (float | None, default: None)

_parameters_file = 'Parameters.txt'
_time_population_file = 'Particle vs. Time.txt'
__init__(*args, plotter=None, freq_ghz=None, e_acc_parameter=('E_acc', 'e_acc', 'accelerating_field'), e_acc_file_mv_m='E_acc in MV per m.txt', p_rms_file=None, stl_path=None, stl_alpha=None, **kwargs)[source]

Instantiate object.

If necessary, override default e_acc filename.

Parameters:

  • plotter (Plotter | None, default: None) – Object to plot data.

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

  • e_acc_parameter (Sequence[str], default: ('E_acc', 'e_acc', 'accelerating_field')) – The possible names of the accelerating field in Parameters.txt; we try all of them sequentially, and resort to taking it from a file if it was not successful. You can pass in an empty tuple to force the use of the file.

  • e_acc_file_mv_m (str, default: 'E_acc in MV per m.txt') – Name of the file where the value of the accelerating field in \(\mathrm{MV/m}\) is written. This is a fallback, we prefer getting accelerating field from the Parameters.txt file.

  • e_acc_file – Name of the file where the value of the RMS power in W is written. If not provided, we do not load RMS power.

  • stl_path (Path | str | None, default: None) – Path to the STL file describing the geometry. Used by ParticleMonitor to compute emission and collision angles, and realize 3D plots.

  • stl_alpha (float | None, default: None) – Transparency for the 3D mesh.

  • p_rms_file (str | None, default: None)

property mandatory_files: set[str]

Give the name of the mandatory files.

from_simulation_folder(folderpath, delimiter='\\t', folder_particle_monitor=None, load_first_n_particles=None)[source]

Instantiate results from a mmdd-xxxxxxx folder.

The expected structure is the following:

mmdd-xxxxxxx
├── 'Adimensional e.txt'
├── 'Adimensional h.txt'
├── 'E_acc in MV per m.txt'           # Mandatory if E_acc not in :file:`Parameters.txt`
├──  Parameters.txt                   # Mandatory
├── 'ParticleInfo [PIC]'
│   ├── 'Emitted Secondaries.txt'
│   └── 'Particle vs. Time.txt'       # Mandatory
├── 'TD Number of mesh cells.txt'
└── 'TD Total solver time.txt'

Non-mandatory files data will be loaded in the parameters attribute.

If you want to load particle monitor data, you must provide folder_particle_monitor where all particle monitors are stored. Typical structure is:

folder_particle_monitor
├──'position  monitor 1_0.117175810039043.txt'
├──'position  monitor 1_0.156234413385391.txt'
├──'position  monitor 1_0.19529302418232.txt'
├──'position  monitor 1_0.232905015349388.txt'
├──'position  monitor 1_0.271963626146317.txt'
├──...
└──'position  monitor 1_7.81172066926956E-02.txt'
Parameters:

  • folderpath (Path) – Path to a mmdd-xxxxxxx folder, holding the results of a single simulation among a parametric simulation export.

  • delimiter (str, default: '\\t') – Delimiter between two columns.

  • folder_particle_monitor (str | Path | None, default: None) – Holds all the particle monitor files.

  • load_first_n_particles (int | None, default: None) – If provided, we only load the load_first_n_particles first particles. Useful for debugging/speeding up.

Returns:

results – Instantiated object.

Return type:

CSTResults

_abc_impl = <_abc._abc_data object at 0x756080281d80>
_pop_e_acc(raw_results, folder)[source]

Pop the value of the accelerating field from raw_results.

First, we try to get it from the Parameters.txt under the names listed in self._e_acc_parameter. If was not found, we look into the self._e_acc_file_mv_m file.

Parameters:
Return type:

float

from_simulation_folders(master_folder, delimiter='\\t')[source]

Load all mmdd-xxxxxxx folders in master_folder.

Note

Loading of ParticleMonitor for multiple simulations is currently not supported.

Parameters:

  • master_folder (Path)

  • delimiter (str, default: '\\t')

Return type:

list[CSTResults]