Particle Species

Each [particleX] TOML section defines one particle species. PyPIC3D supports multi-species plasmas. Particle boundary behavior is a global simulation setting stored on world.

Required Fields

Each species must define:

  • name

  • charge

  • mass

  • N_particles or N_per_cell

Example

[simulation_parameters]
shape_factor = 1

[particle1]
name = "electrons"
N_particles = 30000
charge = -1.602e-19
mass = 9.1093837e-31
temperature = 293000

Common Optional Fields

  • Thermal setup: temperature or vth (optionally Tx, Ty, Tz)

  • Weighting: weight or ds_per_debye

  • Spatial bounds: xmin/xmax, ymin/ymax, zmin/zmax

  • External initial state: initial_x/y/z, initial_vx/vy/vz (.npy)

  • Update controls: update_pos, update_v, component-level flags

Initialization Behavior

If external arrays are not provided:

  • positions are sampled uniformly inside species bounds

  • velocities are sampled from thermal distributions derived from temperature/vth

If scalar initial_x/y/z values are used, PyPIC3D places particles near that location with sub-cell variation when applicable.

Particle Boundary Conditions

Global boundary options are set with simulation_parameters.particle_x_bc, simulation_parameters.particle_y_bc, and simulation_parameters.particle_z_bc:

  • periodic

  • reflecting

  • absorbing

Absorbing particle boundaries keep the JAX particle arrays fixed-size and mark particles inactive with the particle active mask after they leave the domain. The inactive particles remain allocated for JIT shape stability, but they no longer move, push, deposit charge/current, or contribute to particle energy moments.

These are independent from field boundary conditions.

Shape Factors

simulation_parameters.shape_factor controls interpolation/deposition order:

  • 1: first-order

  • 2: second-order