Buildup simulation outputs

The main output is a MATLAB .mat file, named Pyecltest.mat by default. filen_main_outp selects another name. Multiple-cloud simulations write an output file for each cloud. This page covers the buildup output; single-bunch beam monitors use HDF5 files as shown in the single-bunch tutorial.

Read a result

from PyECLOUD.myloadmat_to_obj import myloadmat_to_obj

data = myloadmat_to_obj("Pyecltest.mat")
print(sorted(name for name in vars(data) if not name.startswith("__")))
print(data.t.shape, data.Nel_timep.shape)

The loader exposes output variables as attributes and removes singleton dimensions by default (squeeze=True). Inspect shapes before indexing histograms, especially for runs with only one sample or bunch passage. Use myloadmat_to_obj("Pyecltest.mat", squeeze=False) to preserve singleton axes. The file can also be read with SciPy’s scipy.io.loadmat. The buildup tutorial plots the simulation time series. See Plotting buildup results for the full set of example figures and histogram projections.

Time series

N_steps denotes the number of saved time samples, N_pass the number of recorded bunch passages, N_bins the number of horizontal histogram bins, and N_en the number of energy bins. The time-series arrays below have shape (N_steps,) after squeezing, provided there is more than one sample.

Use the saved t array as the time coordinate. The saver uses a sampling interval based on Dt_ref * dec_fact_out; saving and tracking need not occur at the same cadence. Entries for emitted and impacting electrons accumulate over the interval since the previous saved sample.

PyECLOUD represents a transverse section. Electron population sums are normalized per unit longitudinal length, not counts integrated over a whole magnet. Weighted electron energies likewise carry that longitudinal normalization. Central and probe densities divide by the transverse sampling area to give volume density.

Variable	Meaning
t	Saved simulation times [s]; one value per recorded sample
lam_t_array	Beam line density [particles/m] at those times
Nel_timep	Electron population in the chamber [electrons/m]
Nel_emit_time	Electrons emitted during the saved interval, per metre
Nel_imp_time	Electrons impacting during the saved interval, per metre
En_emit_eV_time	Weighted emitted-electron energy during the interval [eV/m]
En_imp_eV_time	Weighted impacting-electron energy during the interval [eV/m]
En_kin_eV_time	Total weighted electron kinetic energy currently in the chamber [eV/m]
cen_density	Electron volume density in a transverse disk of radius r_center around the origin [m⁻³]

These time-series arrays share the saved sample index. With flag_detailed_MP_info, N_mp_time records the total number of macroparticles at each saved time and nel_mp_ref_time records their reference weight. Other enabled models can add fields, such as electric-field energy or cross-ionization observables.

Bunch passages and histograms

t_hist indexes bunch-passage records and xg_hist gives horizontal bin coordinates. Horizontal histograms are organized by passage and horizontal bin. Energy spectra use their own recorded times, t_En_hist, and energy-bin coordinates, En_g_hist; do not assume their number of records equals the number of bunch passages.

The passage arrays t_hist, N_mp_pass, N_mp_ref_pass, N_mp_impact_pass, and N_mp_corrected_pass have shape (N_pass,). The horizontal coordinates xg_hist have shape (N_bins,). The four horizontal histograms—nel_hist, nel_impact_hist_tot, nel_impact_hist_scrub, and energ_eV_impact_hist—have shape (N_pass, N_bins), with one row per passage and one column per bin. Singleton axes are removed by the loader’s default squeezing.

Variable	Meaning
t_hist	Times associated with bunch-passage records [s]
xg_hist	Horizontal histogram coordinates [m]
N_mp_pass	Number of macroparticles in the chamber at each passage
N_mp_ref_pass	Reference macroparticle weight at each passage
N_mp_impact_pass	Number of macroparticle impacts during each passage
N_mp_corrected_pass	Number of macroparticle tracking corrections during each passage
nel_hist	Horizontal histogram of the electron population
nel_impact_hist_tot	Horizontal histogram of electron impacts
nel_impact_hist_scrub	Horizontal impact histogram restricted to energies above scrub_en_th
energ_eV_impact_hist	Horizontal histogram of weighted energy deposited at the walls
En_hist	Impacting-electron counts per recorded interval and energy bin
all_Ekin_hist	Kinetic-energy histogram of all electrons in the chamber at each recorded energy-sampling time
t_En_hist	Times associated with the energy spectra [s]
En_g_hist	Energy-bin centres [eV]
lifetime_hist	Electron lifetime counts per recorded interval and lifetime bin, with flag_lifetime_hist
lifetime_g_hist	Lifetime-bin centres [s]
t_lifetime_hist	Saved lifetime-histogram times [s], controlled by Dt_lifetime_hist

Lifetime histograms have their own sampling interval, Dt_lifetime_hist; use t_lifetime_hist to locate their records in time.

The final bin of each energy and lifetime histogram collects entries outside the selected energy or lifetime range. Counts are binned accumulations; converting them into a density per unit energy or time requires the corresponding bin width and accumulation interval.

Other and optional fields

Some fields are absent when their feature is disabled; others may contain an empty array or a sentinel value. Inspect the saved data before plotting them.

Variable	Meaning
dec_fact_out	Time-series output sampling factor: for a fixed step Dt_ref, output is saved every dec_fact_out steps
b_spac	Bunch spacing used internally [s]
t_sc_video	Recorded space-charge update times [s]
U_sc_eV	Not used; kept for compatibility
chamber_area	Transverse chamber area [m²]
nel_hist_impact_seg	Electron impacts on chamber segments, with flag_hist_impact_seg
nel_hist_emit_seg	Emitted-electron histogram on chamber segments
energ_eV_impact_seg	Total weighted energy deposited by impacting electrons on each chamber segment [eV/m], with flag_hist_impact_seg
t_sec_beams	Times of saved secondary-beam information [s]
sec_beam_profiles	Secondary-beam line-density profiles [particles/m]
el_dens_at_probes	Volume densities at locations configured by el_density_probes [m⁻³], indexed by probe and saved sample
x_el_dens_probes, y_el_dens_probes	Probe centre coordinates [m]
r_el_dens_probes	Probe radii [m]
nel_hist_det	Detailed electron-position histogram, saved when the *_hist_det inputs are set
xg_hist_det	Coordinates of the detailed histogram bins [m], saved when the *_hist_det inputs are set
cos_angle_hist	Histogram of the cosine of electron impact angles
xg_hist_cos_angle	Coordinates of the impact-angle histogram bins

This reference adapts the output section of the original manual by Giovanni Iadarola, Eleonora Belli, Philipp Dijkstal, Lotta Mether, Annalisa Romano, Giovanni Rumolo, and Eric Wulff. Model-specific fields are not exhaustively listed here.