The Simulation class¶
The Simulation
class is top-level class in FBPIC. It contains all
the simulation data, and has the high-level method step
that performs the PIC cycle.
In addition, its method add_new_species
allows to create new particle
species, and its method set_moving_window
activates the moving window.
- class fbpic.main.Simulation(Nz, zmax, Nr, rmax, Nm, dt, p_zmin=-inf, p_zmax=inf, p_rmin=0, p_rmax=inf, p_nz=None, p_nr=None, p_nt=None, n_e=None, zmin=0.0, n_order=-1, dens_func=None, filter_currents=True, v_comoving=None, use_galilean=True, initialize_ions=False, use_cuda=False, n_guard=None, n_damp={'r': 32, 'z': 64}, exchange_period=None, current_correction='curl-free', boundaries={'r': 'reflective', 'z': 'periodic'}, gamma_boost=None, use_all_mpi_ranks=True, particle_shape='linear', verbose_level=1, smoother=None, use_ruyten_shapes=True, use_modified_volume=True)[source]¶
Initializes a simulation.
By default, this will not create any particle species. You can then add particles species to the simulation by using e.g. the method
add_new_species
of the simulation object.Note
As a short-cut, you can also directly create particle species when initializing the
Simulation
object, by passing the aguments n_e, p_rmin, p_rmax, p_nz, p_nr, p_nt, and dens_func. This will create:an electron species
(if
initialize_ions
is True) an ion species (Hydrogen 1+)
See the docstring of the method
add_new_species
for the above-mentioned arguments (where n_e has been re-labeled as n).- Parameters:
Nz (int) – The number of gridpoints along z
Nr (int) – The number of gridpoints along r
zmax (float) – The position of the edge of the simulation in z (More precisely, the position of the edge of the last cell)
rmax (float) – The position of the edge of the simulation in r (More precisely, the position of the edge of the last cell)
Nm (int) – The number of azimuthal modes taken into account. (The simulation uses the modes from m=0 to m=(Nm-1).)
dt (float) – The timestep of the simulation
n_order (int, optional) – The order of the stencil for z derivatives in the Maxwell solver. Use -1 for infinite order, i.e. for exact dispersion relation in all direction (adviced for single-GPU/single-CPU simulation). Use a positive number (and multiple of 2) for a finite-order stencil (required for multi-GPU/multi-CPU with MPI). A large n_order leads to more overhead in MPI communications, but also to a more accurate dispersion relation for electromagnetic waves. (Typically, n_order = 32 is a good trade-off.) See this article for more information.
zmin (float, optional) – The position of the edge of the simulation box. (More precisely, the position of the edge of the first cell)
initialize_ions (bool, optional) – Whether to initialize the neutralizing ions
filter_currents (bool, optional) – Whether to filter the currents and charge in k space
v_comoving (float or None, optional) – If this variable is None, the standard PSATD is used (default). Otherwise, the current is assumed to be “comoving”, i.e. constant with respect to (z - v_comoving * t). This can be done in two ways: either by - Using a PSATD scheme that takes this hypothesis into account - Solving the PSATD scheme in a Galilean frame
use_galilean (bool, optional) – Determines which one of the two above schemes is used When use_galilean is true, the whole grid moves with a speed v_comoving
use_cuda (bool, optional) – Whether to use CUDA (GPU) acceleration
n_guard (int, optional) – Number of guard cells to use at the left and right of a domain, when performing parallel (MPI) computation or when using open boundaries. Defaults to None, which calculates the required guard cells for n_order automatically (approx 2*n_order). If no MPI is used and in the case of open boundaries with an infinite order stencil, n_guard defaults to 64, if not set otherwise.
n_damp (dict, optional) – A dictionary with ‘z’ and ‘r’ as keys, and integers as values. The integers represent the number of damping cells in the longitudinal (z) and transverse (r) directions, respectively. The damping cells in z are only used if boundaries[‘z’] is ‘open’, and are added at the left and right edge of the simulation domain. The damping cells in r are used only if boundaries[‘r’] is ‘open’, and are added at upper radial boundary (at rmax).
exchange_period (int, optional) – Number of iterations before which the particles are exchanged. If set to None, the maximum exchange period is calculated automatically: Within exchange_period timesteps, the particles should never be able to travel more than (n_guard/2 - particle_shape order) cells. (Setting exchange_period to small values can substantially affect the performance)
boundaries (dict, optional) –
A dictionary with ‘z’ and ‘r’ as keys, and strings as values. This specifies the field boundary in the longitudinal (z) and transverse (r) direction respectively:
boundaries[‘z’] can be either ‘periodic’ or ‘open’ (for field-absorbing boundary).
boundaries[‘r’] can be either ‘reflective’ or ‘open’ (for field-absorbing boundary). For ‘open’, this adds Perfectly-Matched-Layers in the radial direction ; note that the computation is significantly more costly in this case.
current_correction (string, optional) – The method used in order to ensure that the continuity equation is satisfied. Either curl-free or cross-deposition. curl-free is faster but less local.
gamma_boost (float, optional) – When running the simulation in a boosted frame, set the value of gamma_boost to the corresponding Lorentz factor. All the other quantities (zmin, zmax, n_e, etc.) are to be given in the lab frame.
use_all_mpi_ranks (bool, optional) –
When launching the simulation with mpirun:
if use_all_mpi_ranks is True (default): All the MPI ranks will contribute to the same simulation, using domain-decomposition to share the work.
if use_all_mpi_ranks is False: Each MPI rank will run an independent simulation. This can be useful when running parameter scans. In this case, make sure that your input script is written so that the input parameters and output folder depend on the MPI rank.
particle_shape (str, optional) – Set the particle shape for the charge/current deposition. Possible values are ‘cubic’, ‘linear’. (‘cubic’ corresponds to third order shapes and ‘linear’ to first order shapes).
verbose_level (int, optional) – Print information about the simulation setup after initialization of the Simulation class. 0 - Print no information 1 (Default) - Print basic information 2 - Print detailed information
smoother (an instance of
BinomialSmoother
, optional) – Determines how the charge and currents are smoothed. (Default: one-pass binomial filter and no compensator.)use_ruyten_shapes (bool, optional) – Whether to use Ruyten shape factors for the particle deposition. (Ruyten JCP 105 (1993) https://doi.org/10.1006/jcph.1993.1070) This ensures that a uniform distribution of macroparticles leads to a uniform charge density deposited on the grid, even close to the axis (in the limit of many particles in r).
use_modified_volume (bool, optional) – Whether to use a slightly-modified, effective cell volume, that ensures that the charge deposited near the axis is correctly taken into account by the spectral cylindrical Maxwell solver.
- add_new_species(q, m, n=None, dens_func=None, p_nz=None, p_nr=None, p_nt=None, p_zmin=-inf, p_zmax=inf, p_rmin=0, p_rmax=inf, uz_m=0.0, ux_m=0.0, uy_m=0.0, uz_th=0.0, ux_th=0.0, uy_th=0.0, continuous_injection=True, boost_positions_in_dens_func=False, is_tracer=False)[source]¶
Create a new species (i.e. an instance of Particles) with charge q and mass m. Add it to the simulation (i.e. to the list Simulation.ptcl), and return it, so that the methods of the Particles class can be used, for this particular species.
In addition, if n is set, then new macroparticles will be created within this species (in an evenly-spaced manner).
For boosted-frame simulations (i.e. where gamma_boost as been passed to the Simulation object), all quantities that are explicitly mentioned to be in the lab frame below are automatically converted to the boosted frame.
Note
For the arguments below, it is recommended to have at least
p_nt = 4*Nm
(except in the caseNm=1
, for whichp_nt=1
is sufficient). In other words, the required number of macroparticles along theta (in order for the simulation to be properly resolved) increases with the number of azimuthal modes used.- Parameters:
q (float (in Coulombs)) – Charge of the particle species
m (float (in kg)) – Mass of the particle species
n (float (in particles per m^3) or None, optional) – Density of physical particles (in the lab frame). If this is None, no macroparticles will be created. If n is not None, evenly-spaced macroparticles will be generated.
dens_func (callable, optional) –
A function of the form dens_func( z, r ) where z and r are 1d arrays, or dens( x, y, z) where x, y and z are 1d arrays, and which returns a 1d array containing the density relative to `n` (i.e. a number between 0 and 1) at the given positions
For boosted-frame simulation: if you set
boost_positions_in_dens_func
toTrue
, thendens_func
can be expressed as a function ofz
taken in the lab frame. Otherwise, it has to be expressed as a function ofz
taken in the boosted frame.p_nz (int, optional) – The number of macroparticles per cell along the z direction
p_nr (int, optional) – The number of macroparticles per cell along the r direction
p_nt (int, optional) – The number of macroparticles along the theta direction
p_zmin (float (in meters), optional) – The minimal z position above which the particles are initialized (in the lab frame). Default: left edge of the simulation box.
p_zmax (float (in meters), optional) – The maximal z position below which the particles are initialized (in the lab frame). Default: right edge of the simulation box.
p_rmin (float (in meters), optional) – The minimal r position above which the particles are initialized (in the lab frame). Default: 0
p_rmax (floats (in meters), optional) – The maximal r position below which the particles are initialized (in the lab frame). Default: upper edge of the simulation box.
uz_m (floats (dimensionless), optional) – Normalized mean momenta (in the lab frame) of the injected particles in each direction
ux_m (floats (dimensionless), optional) – Normalized mean momenta (in the lab frame) of the injected particles in each direction
uy_m (floats (dimensionless), optional) – Normalized mean momenta (in the lab frame) of the injected particles in each direction
uz_th (floats (dimensionless), optional) – Normalized thermal momenta (in the lab frame) in each direction
ux_th (floats (dimensionless), optional) – Normalized thermal momenta (in the lab frame) in each direction
uy_th (floats (dimensionless), optional) – Normalized thermal momenta (in the lab frame) in each direction
continuous_injection (bool, optional) – Whether to continuously inject the particles, in the case of a moving window
boost_positions_in_dens_func (bool, optional) – For boosted-frame simulations: whether to automatically take into account the Lorentz transformation of the positions, in dens_func
is_tracer (bool, optional) – Setting this flag to True will allow this particle to move as a normal particle with given mass and charge, but will generate no current. This allows them to be passive tracers inside the plasma.
- Returns:
new_species
- Return type:
an instance of the Particles class
- set_moving_window(v=299792458.0, ux_m=None, uy_m=None, uz_m=None, ux_th=None, uy_th=None, uz_th=None, gamma_boost=None)[source]¶
Initializes a moving window for the simulation.
- Parameters:
v (float (in meters per seconds), optional) – The speed of the moving window
ux_m (float (dimensionless), optional) – Unused, kept for backward-compatibility
uy_m (float (dimensionless), optional) – Unused, kept for backward-compatibility
uz_m (float (dimensionless), optional) – Unused, kept for backward-compatibility
ux_th (float (dimensionless), optional) – Unused, kept for backward-compatibility
uy_th (float (dimensionless), optional) – Unused, kept for backward-compatibility
uz_th (float (dimensionless), optional) – Unused, kept for backward-compatibility
gamma_boost (float, optional) – Unused; kept for backward compatibility
- step(N=1, correct_currents=True, correct_divE=False, use_true_rho=False, move_positions=True, move_momenta=True, show_progress=True)[source]¶
Perform N PIC cycles.
- Parameters:
N (int, optional) – The number of timesteps to take Default: N=1
correct_currents (bool, optional) – Whether to correct the currents in spectral space
correct_divE (bool, optional) – Whether to correct the divergence of E in spectral space
use_true_rho (bool, optional) – Whether to use the true rho deposited on the grid for the field push or not. (requires initialize_ions = True)
move_positions (bool, optional) – Whether to move or freeze the particles’ positions
move_momenta (bool, optional) – Whether to move or freeze the particles’ momenta
show_progress (bool, optional) – Whether to show a progression bar
- fbpic.utils.random_seed.set_random_seed(random_seed)[source]¶
Fix the seed of the random number generators.
Fixing a seed helps ensure that repeatedly running the same simulation gives the same result (despite the Monte Carlo parts of the code, e.g. ionization, gaussian beam generation, etc.)
- random_seed: int
The seed of the random number generator.