Beam initialization

The functions below allow to initialize a relativistic particle beam with various distributions in space (e.g. Gaussian, flat-top, from a file, etc.). In each case, the self-consistent space-charge fields are automatically calculated by the code, and added to the simulation.

fbpic.lpa_utils.bunch.add_particle_bunch(sim, q, m, gamma0, n, p_zmin, p_zmax, p_rmin, p_rmax, p_nr=2, p_nz=2, p_nt=4, dens_func=None, boost=None, direction='forward', z_injection_plane=None, initialize_self_field=True, boost_positions_in_dens_func=False)

Introduce a simple relativistic particle bunch in the simulation, along with its space charge field.

Uniform particle distribution with weights according to density function.

Parameters:

• sim (a Simulation object) – The structure that contains the simulation.

• q (float (in Coulomb)) – Charge of the particle species

• m (float (in kg)) – Mass of the particle species

• gamma0 (float) – The Lorentz factor of the particles

• n (float (in particles per m^3)) – Density of the bunch

• p_zmin (float (in meters)) – The minimal z position above which the particles are initialized

• p_zmax (float (in meters)) – The maximal z position below which the particles are initialized

• p_rmin (float (in meters)) – The minimal r position above which the particles are initialized

• p_rmax (float (in meters)) – The maximal r position below which the particles are initialized

• p_nz (int) – Number of macroparticles per cell along the z directions

• p_nr (int) – Number of macroparticles per cell along the r directions

• p_nt (int) – Number of macroparticles along the theta direction

• 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 to True, then dens_func can be expressed as a function of z taken in the lab frame. Otherwise, it has to be expressed as a function of z taken in the boosted frame.

• boost (a BoostConverter object, optional) – A BoostConverter object defining the Lorentz boost of the simulation.

• direction (string, optional) – Can be either “forward” or “backward”. Propagation direction of the beam.

• z_injection_plane (float (in meters) or None) – When z_injection_plane is not None, then particles have a ballistic motion for z<z_injection_plane. This is sometimes useful in boosted-frame simulations. z_injection_plane is always given in the lab frame.

• initialize_self_field (bool, optional) – Whether to calculate the initial space charge fields of the bunch and add these fields to the fields on the grid (Default: True)

• 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

fbpic.lpa_utils.bunch.add_particle_bunch_gaussian(sim, q, m, sig_r, sig_z, n_emit, gamma0, sig_gamma, n_physical_particles, n_macroparticles, tf=0.0, zf=0.0, boost=None, save_beam=None, z_injection_plane=None, initialize_self_field=True, symmetrize=False)

Introduce a relativistic Gaussian particle bunch in the simulation, along with its space charge field.

The bunch is initialized with a normalized emittance n_emit, in such a way that it will be focused at time tf, at the position zf. Thus if tf is not 0, the bunch will be initially out of focus. (This does not take space charge effects into account.)

Parameters:

• sim (a Simulation object) – The structure that contains the simulation.

• q (float (in Coulomb)) – Charge of the particle species

• m (float (in kg)) – Mass of the particle species

• sig_r (float (in meters)) – The transverse RMS bunch size.

• sig_z (float (in meters)) – The longitudinal RMS bunch size.

• n_emit (float (in meters)) – The normalized emittance of the bunch.

• gamma0 (float) – The Lorentz factor of the electrons.

• sig_gamma (float) – The absolute energy spread of the bunch.

• n_physical_particles (float) – The number of physical particles (e.g. electrons) the bunch should consist of.

• n_macroparticles (int) – The number of macroparticles the bunch should consist of.

• zf (float (in meters), optional) – Position of the focus.

• tf (float (in seconds), optional) – Time at which the bunch reaches focus.

• boost (a BoostConverter object, optional) – A BoostConverter object defining the Lorentz boost of the simulation.

• save_beam (string, optional) – Saves the generated beam distribution as an .npz file “string”.npz

• z_injection_plane (float (in meters) or None) – When z_injection_plane is not None, then particles have a ballistic motion for z<z_injection_plane. This is sometimes useful in boosted-frame simulations. z_injection_plane is always given in the lab frame.

• initialize_self_field (bool, optional) – Whether to calculate the initial space charge fields of the bunch and add these fields to the fields on the grid (Default: True)

• symmetrize (bool, optional) – Whether to symmetrize the beam with 4-fold rotational symmetry. (Meaning that, for every macroparticle, 3 other macroparticles that are rotated by +pi/2, +pi, -pi/2 in the transverse plane) This ensures that the beam has exactly 0 initial offset in x and y

fbpic.lpa_utils.bunch.add_particle_bunch_from_arrays(sim, q, m, x, y, z, ux, uy, uz, w, boost=None, direction='forward', z_injection_plane=None, initialize_self_field=True)

Introduce a relativistic particle bunch in the simulation, along with its space charge field, loading particles from numpy arrays.

Parameters:

• sim (a Simulation object) – The structure that contains the simulation.

• q (float) – Charge of the particle species

• m (float) – Mass of the particle species

• x (1d arrays of length (N_macroparticles,)) – The positions of the particles in x, y, z in meters

• y (1d arrays of length (N_macroparticles,)) – The positions of the particles in x, y, z in meters

• z (1d arrays of length (N_macroparticles,)) – The positions of the particles in x, y, z in meters

• ux (1d arrays of length (N_macroparticles,)) – The dimensionless momenta of the particles in each direction

• uy (1d arrays of length (N_macroparticles,)) – The dimensionless momenta of the particles in each direction

• uz (1d arrays of length (N_macroparticles,)) – The dimensionless momenta of the particles in each direction

• w (1d array of length (N_macroparticles,)) – The weight of the particles, i.e. the number of physical particles that each macroparticle corresponds to.

• boost (a BoostConverter object, optional) – A BoostConverter object defining the Lorentz boost of the simulation.

• direction (string, optional) – Can be either “forward” or “backward”. Propagation direction of the beam.

• z_injection_plane (float (in meters) or None) – When z_injection_plane is not None, then particles have a ballistic motion for z<z_injection_plane. This is sometimes useful in boosted-frame simulations. z_injection_plane is always given in the lab frame.

• initialize_self_field (bool, optional) – Whether to calculate the initial space charge fields of the bunch and add these fields to the fields on the grid (Default: True)

fbpic.lpa_utils.bunch.add_particle_bunch_openPMD(sim, q, m, ts_path, z_off=0.0, species=None, select=None, iteration=None, boost=None, z_injection_plane=None, initialize_self_field=True)

Introduce a relativistic particle bunch in the simulation, along with its space charge field, loading particles from an openPMD timeseries.

Parameters:

• sim (a Simulation object) – The structure that contains the simulation.

• q (float (in Coulomb)) – Charge of the particle species

• m (float (in kg)) – Mass of the particle species

• ts_path (string) – The path to the directory where the openPMD files are. For the moment, only HDF5 files are supported. There should be one file per iteration, and the name of the files should end with the iteration number, followed by ‘.h5’ (e.g. data0005000.h5)

• z_off (float (in meters)) – Shift the particle positions in z by z_off. By default the initialized phasespace is centered at z=0.

• species (string) – A string indicating the name of the species This is optional if there is only one species

• select (dict, optional) – Either None or a dictionary of rules to select the particles, of the form ‘x’ : [-4., 10.] (Particles having x between -4 and 10 microns) ‘ux’ : [-0.1, 0.1] (Particles having ux between -0.1 and 0.1 mc) ‘uz’ : [5., None] (Particles with uz above 5 mc)

• iteration (integer (optional)) – The iteration number of the openPMD file from which to extract the particles.

• boost (a BoostConverter object, optional) – A BoostConverter object defining the Lorentz boost of the simulation.

• z_injection_plane (float (in meters) or None) – When z_injection_plane is not None, then particles have a ballistic motion for z<z_injection_plane. This is sometimes useful in boosted-frame simulations. z_injection_plane is always given in the lab frame.

• initialize_self_field (bool, optional) – Whether to calculate the initial space charge fields of the bunch and add these fields to the fields on the grid (Default: True)

fbpic.lpa_utils.bunch.add_particle_bunch_file(sim, q, m, filename, n_physical_particles, z_off=0.0, boost=None, direction='forward', z_injection_plane=None, initialize_self_field=True)

Introduce a relativistic particle bunch in the simulation, along with its space charge field, loading particles from text file.

Parameters:

• sim (a Simulation object) – The structure that contains the simulation.

• q (float (in Coulomb)) – Charge of the particle species

• m (float (in kg)) – Mass of the particle species

• filename (string) – the file containing the particle phase space in seven columns all float, no header x [m] y [m] z [m] ux [unitless] uy [unitless] uz [unitless]

• n_physical_particles (float) – The number of physical particles (e.g. electrons) the bunch should consist of.

• z_off (float (in meters)) – Shift the particle positions in z by z_off

• boost (a BoostConverter object, optional) – A BoostConverter object defining the Lorentz boost of the simulation.

• direction (string, optional) – Can be either “forward” or “backward”. Propagation direction of the beam.

• z_injection_plane (float (in meters) or None) – When z_injection_plane is not None, then particles have a ballistic motion for z<z_injection_plane. This is sometimes useful in boosted-frame simulations. z_injection_plane is always given in the lab frame.

• initialize_self_field (bool, optional) – Whether to calculate the initial space charge fields of the bunch and add these fields to the fields on the grid (Default: True)

Warning

The former methods to initialize electron beams have been updated to allow the use of arbitrary particle beams.

Although the old methods (e.g. add_elec_bunch) can still be used (for backward compatibility), we recommend using the new more flexible methods instead.