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 theAbstractSaveRoutine
class to therun
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 ofAbstractTerminationCondition
which determines when the simulation has finished. SeeAbstractTerminationCondition
for more details.save_routine (
AbstractSaveRoutine
, optional) – An instance ofAbstractSaveRoutine
which determines which time steps of the simulation to save. The default isDoNotSaveSaveRoutine
. SeeAbstractSaveRoutine
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
ofstr
, default :None
) – 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]. This keyword is for specifying quantities in addition to these six. If any required quantities are missing, those quantities will be assumed to be zero everywhere. A warning will be raised if any of the additional required quantities are missing and are set to zero.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 notNaN
, but the velocity isNaN
, 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 toNaN
, then the particle has been removed from the simulation.Attributes Summary
Return whether the simulation is calculating an adaptive time step or using the user-provided time step.
Return if the simulation is applying the same time step across all particles.
Return the number of particles that don't have NaN position or velocity.
The number of grids specified at instantiation.
Binary array for each particle indicating whether it is currently on ANY grid.
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 particlesv (
Quantity
, shape (N,3)) – Velocities for N particlesparticle (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.