ParticleTracker

class plasmapy.simulation.particle_tracker.ParticleTracker(grids: AbstractGrid | Iterable[AbstractGrid], termination_condition: AbstractTerminationCondition | None = None, save_routine: AbstractSaveRoutine | None = None, dt=None, dt_range=None, field_weighting='volume averaged', req_quantities=None, verbose=True)[source]

Bases: object

A particle tracker for particles in electric and magnetic fields without inter-particle interactions.

Particles are instantiated and pushed through a grid of provided E and B fields using the Boris push algorithm. These fields are specified as part of a grid which are then interpolated to determine the local field acting on each particle.

The time step used in the push routine can be specified, or an adaptive time step will be determined based off the gyroradius of the particle. Some save routines involve time stamping the location and velocities of particles at fixed intervals. In order for this data to be coherent, it is required that all particles follow the same time step. This is referred to as a synchronized time step. If no time step is specified and the provided save routine does not require a synchronized time step, then an adaptive time step is calculated independently for each particle.

The simulation will push particles through the provided fields until a condition is met. This termination condition is provided as an instance of the AbstractTerminationCondition class as arguments to the simulation constructor. The results of a simulation can be exported by specifying an instance of the AbstractSaveRoutine class to the run method.

Parameters:

grids (An instance of AbstractGrid) – A Grid object or list of grid objects containing the required quantities. The list of required quantities varies depending on other keywords.
termination_condition (AbstractTerminationCondition) – An instance of AbstractTerminationCondition which determines when the simulation has finished. See AbstractTerminationCondition for more details.
save_routine (AbstractSaveRoutine, optional) – An instance of AbstractSaveRoutine which determines which time steps of the simulation to save. The default is DoNotSaveSaveRoutine. See AbstractSaveRoutine for more details.
dt (Quantity, optional) – An explicitly set time step in units convertible to seconds. Setting this optional keyword overrules the adaptive time step capability and forces the use of this time step throughout.
dt_range (tuple of shape (2,) of Quantity, optional) – If specified, the calculated adaptive time step will be clamped between the first and second values.
field_weighting (str) –
String that selects the field weighting algorithm used to determine what fields are felt by the particles. Options are:
- ’nearest neighbor’: Particles are assigned the fields on
  the grid vertex closest to them.
- ’volume averaged’The fields experienced by a particle are a
  volume-average of the eight grid points surrounding them.
The default is ‘volume averaged’.
req_quantities (list of str, optional) – A list of quantity keys required to be specified on the Grid object. The base particle pushing simulation requires the quantities [E_x, E_y, E_z, B_x, B_y, B_z]. If any of these quantities are missing, a warning will be given and that quantity will be assumed to be zero everywhere. This keyword is for specifying quantities in addition to these six. The default is None.
verbose (bool, optional) – If true, updates on the status of the program will be printed into the standard output while running. The default is True.

Notes

We adopt the convention of NaN values to represent various states of a particle.

If the particle’s position and velocity are not NaN, the particle is being tracked and evolved. If the particle’s position is not NaN, but the velocity is NaN, the particle has been stopped (i.e. it is still in the simulation but is no longer evolved.) If both the particle’s position and velocity are set to NaN, then the particle has been removed from the simulation.

Attributes Summary

`is_adaptive_time_step`	Return whether the simulation is calculating an adaptive time step or using the user-provided time step.
`is_synchronized_time_step`	Return if the simulation is applying the same time step across all particles.
`nparticles_tracked`	Return the number of particles that don't have NaN position or velocity.
`num_grids`	The number of grids specified at instantiation.
`on_any_grid`	Binary array for each particle indicating whether it is currently on ANY grid.
`vmax`	The maximum velocity of any particle in the simulation.

Methods Summary

`load_particles`(x, v[, particle])	Load arrays of particle positions and velocities.
`run`()	Runs a particle-tracing simulation.
`setup_adaptive_time_step`([...])	Set parameters for the adaptive time step candidates.

Attributes Documentation

is_adaptive_time_step: Return whether the simulation is calculating an adaptive time step or using the user-provided time step.

is_synchronized_time_step: Return if the simulation is applying the same time step across all particles.

nparticles_tracked: Return the number of particles that don’t have NaN position or velocity.

num_grids: The number of grids specified at instantiation.

on_any_grid: Binary array for each particle indicating whether it is currently on ANY grid.

vmax

The maximum velocity of any particle in the simulation.

This quantity is used for determining the grid crossing maximum time step.

Methods Documentation

load_particles(x, v, particle: Particle = Particle('p+')) → None[source]

Load arrays of particle positions and velocities.

Parameters:

x (Quantity, shape (N,3)) – Positions for N particles
v (Quantity, shape (N,3)) – Velocities for N particles
particle (particle-like, optional) – Representation of the particle species as either a Particle object or a string representation. The default particle is protons.

run() → None[source]

Runs a particle-tracing simulation. Time steps are adaptively calculated based on the local grid resolution of the particles and the electric and magnetic fields they are experiencing.

Return type:: None

setup_adaptive_time_step(time_steps_per_gyroperiod: int | None = 12, Courant_parameter: float | None = 0.5) → None[source]

Set parameters for the adaptive time step candidates.

Parameters:

time_steps_per_gyroperiod (int, optional) – The minimum ratio of the particle gyroperiod to the timestep. Higher numbers correspond to higher temporal resolution. The default is twelve.
Courant_parameter (float, optional) – The Courant parameter is the minimum ratio of the timestep to the grid crossing time, grid cell length / particle velocity. Lower Courant numbers correspond to higher temporal resolution.

Notes

Two candidates are calculated for the adaptive time step: a time step based on the gyroradius of the particle and a time step based on the resolution of the grid. The candidate associated with the gyroradius of the particle takes a time_steps_per_gyroperiod parameter that specifies how many times the orbit of a gyrating particles will be subdivided. The other candidate, associated with the spatial resolution of the grid object, calculates a time step using the time it would take the fastest particle to cross some fraction of a grid cell length. This fraction is the Courant number.