Creating particle species

Species are created by using the Species class (defined in scripts/species.py) . For example:

beam = Species(type=Potassium, charge_state=+1, name="Beam ions (K+)")

plasma_electrons = Species(type=Electron, name="Plasma electrons", color=red)

plasma_ions = Species(type=Hydrogen, charge_state=+1, name="Plasma ions", color=green)

The color argument specifies the color of the markers that will be used when plotting particles of the species (defaulting to black). The Species instance can be used to access information about the species. For example:

beam.sq # gives the charge of the species

beam.charge # also the charge

beam.mass # the mass of the species

beam.emitn # normalized emittance

beam.hxrms # time history of Xrms in the z-windows

These can be use to set the quantities as well. For example:

beam.emitn = 1.1e-6

More things are available as well. For example

plasma_electrons.ppzx() # plots the particles in z-x space. The particles will be red.

plasma_ions.getx() # returns a list of all of the plasma ions x positions

plasma_ions.add_uniform_cylinder(...) # creates particles

Particle data

The particle data can be accessed in one of two ways. The arrays can be accessed directly - for example beam.xp will directly access the arrays holding the x coordinates. The data can be obtained indirectly as well, via the "get" routines. For example beam.getx(). In serial, beam.getx() will return the same array as beam.xp, but in parallel, beam.getx() will gather the data from all of the processors, whereas beam.xp is only the data for particles in the local domain. The "get" routines can be used for down selection of the particles, for instance beam.getz(xl=0.1, xu=0.2) will get the z of particle within (0.1 <= x <= 0.2).

In addition to the basic particle quantities, further quantities can be added. These are quantities that are saved for each particles and are carried with them. There are a number of quantities that are automatically initialized by Warp. For example, setting

top.tbirthpid = nextpid()

will save the time of birth for each particle. The routine "nextpid()" sets up the space for the new quantity. The birth time for each particle can later be retrieved using the species instance - beam.tbirth, or beam.gettbirth(). Other built in quantities include saving additional information about the particle's birth and the data from the previous time step. See the Particles module in top.v for the list of built in quantities that can be setup.

The species instance allows one to add user defined particle quantities. For instance, a quantity called alpha can be created.

beam.addpid('alpha')

The quantity would need to be setup by the user. For example, it could be passed into the particle creation routines,

beam.add_uniform_cylinder(..., alpha=1.1)

or set directly,

beam.alpha = 1.1

The data can be obtained either directly, via beam.alpha, or indirectly, via beam.getalpha().

An important note is that when a quantity is setup for one species, it will then be available in all species. So, with the example of "alpha", one would also have the data plasma_ions.alpha.