Overview
tree-d-3d computes the electrostatic field of N charges in a plane, in free space, and moves
the charges in it, with an optional uniform magnetic field . Nothing is put on a mesh: the
field is a sum over the charges, made fast by a Barnes-Hut tree walk or, for line charges, a
fast multipole method, and conductors enter as charged panels on their surfaces. Two
interaction kernels, chosen per tree with kernel=:
"coulomb": point charges with the 3D Coulomb interaction, confined to the plane;"log": infinite line charges along , the Green’s function of 2D Poisson (2D Cartesian PIC).
Each equation on these pages is declared on the code that implements it, as a method card, and checked by the tests: eighteen closed forms against SymPy rules, five discretisations against their order of convergence. The pages of the section list the cards module by module; this one shows how they fit together.
The pipeline
Section titled “The pipeline”- Kernels. The exact softened sums of both kernels,
and
, define the model;
direct_fieldevaluates them in . - Tree walk. A quadtree, built level by level, carries the moments of every cell about its centre. The walk replaces a cell that looks small enough from the target by its expansion, through the quadrupole for point charges and to order in complex form for line charges, in per target:
evaluate
functionsourcePotential (M,) and field (2, M) at targets (2, M), without k_e.
- acceptance
- coulomb multipole
- coulomb field
- log multipole
- leaves
- Order
- coulomb: 3, log: 3
- Assumes
- one target at a time, an explicit stack; the cell holding the target is always opened, whatever and ; is the exact sum
- the Coulomb expansion through the quadrupole, from the Taylor series of with ; holds exactly for this softened form
- accepted log-kernel cells are unsoftened: softening acts on the direct leaf pairs only, an difference in the far field
- the order is in the size of an accepted cell's charges over its distance, so in : 3 through the quadrupole, for the log kernel (3 at the of the test problem)
- References
- Built from
- Fast multipole method: a dual-tree traversal pairs
well-separated cells, whose multipoles become local expansions (M2L), shifted down the tree
(L2L) and evaluated at the particles (L2P), in ; complex expansions for line charges,
Cartesian ones of the softened kernel for point charges (on the CPU).
fmm_atruns it at other points, with a tree of its own over them:
fmm
functionsourcePotential and field at every source, by the FMM.
- traversal
- m2l
- truncation
- l2l
- l2p
- p2p
- coulomb moments
- coulomb taylor
- coulomb m2l
- Order
- potential: 3, field: 2
- Assumes
- ; every particle is a target; each pair is listed once and used in both directions
kernel=\"coulomb\"(CPU only): Cartesian expansions of the softened kernel to total degree (order, default 4), by the Taylor recurrence; the total-degree truncation makes pair forces exactly antisymmetric; softened throughout, far field includedfmm_at: the same traversal between a tree of the targets and the sources' tree, one way, with exact sums between their leaves- the local expansion of degree about each cell centre; on the principal branch, which shifts by and drops out of
- the triangle truncation makes the mutual pair forces exactly antisymmetric (same error order, larger constant)
- log kernel: softening acts on the P2P pairs only; no automatic error control: and set the accuracy
- the error of an M2L is in the potential and in the field, the cluster size over the cell distance; the declared orders are those at the of the test problem
- References
- Built from
- Macroparticles carry a weight on mass and charge, so is kept.
- Particle pusher: an electric half-kick, the exact
gyration in over the step, another half-kick; second order, velocity Verlet at
. Absorbing walls and
simgeometryobjects remove the particles that cross them. - Boundaries. Two grounded plates by a conformal map of the strip onto the half-plane, where one image per charge makes the plates equipotentials, and conductors at prescribed potentials by the boundary-integral (panel) method: an induced line-charge density on each surface, piecewise constant on straight panels, collocated at their midpoints. The free charges of a meshless space-charge model (a gun, a beam) enter both as sources.
The reference tree is the walk of step 2 as a readable object tree. Two codes stand beside the pipeline: the smooth-membership FMM, a NumPy prototype whose forces are the exact gradient of a smooth energy, and the classic gravitational Barnes-Hut code.
Units and conventions
Section titled “Units and conventions”The kernels return raw potentials and fields; the callers multiply by
(K_E) or by the k_e they are given, so SI inputs give SI
outputs. Line charges are per unit length (C/m), and their potential is defined up to a
constant: reference_radius makes it . Complex notation
, with the conjugate field. Per-particle arrays with a component axis
are component-major, .
Not in the model
Section titled “Not in the model”- No 3D geometry or octree yet: positions, fields and trees are planar.
- No GPU version of the Coulomb FMM or of
fmm_at; the walk keeps the Coulomb quadrupole; no error estimate or automatic choice of and . - For line charges, softening only in the direct pairs: the far cells of the log tree and the FMM are unsoftened (the smooth-membership FMM has a compact softening with an exact far field).
- No periodic boundaries, dielectrics or Neumann conditions; no conductor at infinity; the
electrode system is solved directly (no FMM-accelerated GMRES); no electrodes inside
ElectrostaticSimulation(pair it withBoundaryIntegralElectrodesby hand). - No magnetic self-fields, induction, time-dependent or non-uniform ; no relativity, radiation, collisions or emission in the library (the examples add some of them).
Verification
Section titled “Verification”Besides the checks of the cards, the tests compare the flat tree with the reference tree node for node, every compiled kernel with its Python source and its NumPy, CUDA (emulated) and Metal versions, the walk and the FMM with the direct sum against and , the exact cyclotron orbit, energy and momentum over many steps, a self-similarly expanding disk of line charges, the grounded circle, the cylindrical capacitor and an L-shaped conductor against their closed forms, and the strip against charged sheets.