Bunch

Bunch is the container object for the particle data in Synergia. To create a Bunch object you need a Reference_particle for the bunch, the number of macro_particles, and the number of real_particles,

bunch = synergia.bunch.Bunch(reference_particle, total_num, real_num, comm = Commxx())

where total_num is the number of macroparticles to be simulated in the bunch, real_num is the number of real particles of the bunch. comm is an optional argument of an MPI communicator indicating the processes the bunch will span across. It is defaulted to the MPI_COMM_WORLD.

Various methods are provided to access the particle data and properties of a bunch. Commonly used ones are,

# get the number of all particles on the current rank
# the particle array stores all allocated particles. Some of the particles
# might hit the wall or get lost during the propagation. These particles
# become invalid particles but they are still kept in the particle array.
# The size() method returns the number of valid + lost particles in the
# current rank of the bunch.
Bunch.size()

# get the number of valid particles reside on the current rank
Bunch.get_local_num()

# get the total number of valid particles of this bunch
# since a bunch might span across multiple ranks so the total_num
# is always >= to the local_num of a bunch
Bunch.get_total_num()

# retrieve the bunch reference particle
Bunch.get_reference_particle()

# retrieve the lattice design reference particle
Bunch.get_design_reference_particle()

# retrieve the particle data in a 2d numpy array [0:size, 0:6]
# in the second dimension, 0 - x, 1 - xp, 2 - y, 3 - yp, 4 - cdt, 5 - dpop, 6 - id
#
# the returned array is a reference to the original particle array. it remains
# valid throughout the checkin_particles() or checkout_particles() calls.  If
# the bunch particle array is reallocated, which happens when the particle number 
# expands over the capacity of the bunch, the returned numpy array will become
# invalid.
Bunch.get_particles_numpy()

When running a simulation on compute accelerators such as GPUs, it is crucial to know that the particle data resides on both the device memory (such as GPU VRAM) and host memory. All the propagation and computation are performed on the array of device memory. But user can only access the particle data on host memory. Therefore, a sync operation is required if user seeks to read or modify the particle data during propagation.

# sync the particle data from host to device
Bunch.checkin_particles()

# sync the particle data from device to host
Bunch.checkout_particles()