Internal

Public APIs

TestParticle.BiMaxwellian Type

Type for BiMaxwellian velocity distributions with respect to the magnetic field.

source

TestParticle.BiMaxwellian Method

 BiMaxwellian(B::Vector{U}, u0::Vector{T}, ppar, pperp, n; m=mᵢ)

Construct a BiMaxwellian distribution with magnetic field B, bulk velocity u0, parallel thermal pressure ppar, perpendicular thermal pressure pperp, and number density n in SI units. The default particle is proton.

source

TestParticle.Cartesian Type

Cartesian grid.

source

TestParticle.Maxwellian Type

Type for Maxwellian velocity distributions.

source

TestParticle.Maxwellian Method

 Maxwellian(u0::AbstractVector{T}, p, n; m=mᵢ)

Construct a Maxwellian distribution with bulk velocity u0, thermal pressure p, and number density n in SI units. The default particle is proton.

source

TestParticle.Spherical Type

Spherical grid with uniform r, θ and ϕ.

source

TestParticle.SphericalNonUniformR Type

Spherical grid with non-uniform r and uniform θ, ϕ.

source

TestParticle.energy2velocity Method

Return velocity magnitude from energy in [eV].

source

TestParticle.get_energy Method

Calculate the energy [eV] of a relativistic particle from γv.

source

TestParticle.get_energy Method

Return the energy [eV] from relativistic sol.

source

TestParticle.get_gc Method

 get_gc(xu, param)
 get_gc(x, y, z, vx, vy, vz, bx, by, bz, q2m)

Calculate the coordinates of the guiding center according to the phase space coordinates of a particle. Reference: wiki

Nonrelativistic definition:

$$\mathbf{X}=\mathbf{x}-m\frac{\mathbf{b}\times \mathbf{v}}{qB}$$source

TestParticle.get_gc_func Method

 get_gc_func(param)

Return the function for plotting the orbit of guiding center.

Example

param = prepare(E, B; species = Proton)
# The definitions of stateinit, tspan, E and B are ignored.
prob = ODEProblem(trace!, stateinit, tspan, param)
sol = solve(prob, Vern7(); dt = 2e-11)

f = Figure(fontsize = 18)
ax = Axis3(f[1, 1], aspect = :data)
gc = param |> get_gc_func
gc_plot(x, y, z, vx, vy, vz) = (gc(SA[x, y, z, vx, vy, vz])...,)
lines!(ax, sol, idxs = (gc_plot, 1, 2, 3, 4, 5, 6))

source

TestParticle.get_gyrofrequency Function

get_gyrofrequency(B=5e-9; q=qᵢ, m=mᵢ)

Return the gyrofrequency [rad/s].

Arguments

• B::AbstractFloat: Magnetic field magnitude [T]. Default is 5 nT.

• q::AbstractFloat: Charge [C]. Default is proton charge.

• m::AbstractFloat: Mass [kg]. Default is proton mass.

source

TestParticle.get_gyroperiod Function

get_gyroperiod(B=5e-9; q=qᵢ, m=mᵢ)

Return the gyroperiod [s].

Arguments

• B::AbstractFloat: Magnetic field magnitude [T]. Default is 5 nT.

• q::AbstractFloat: Charge [C]. Default is proton charge.

• m::AbstractFloat: Mass [kg]. Default is proton mass.

source

TestParticle.get_gyroradius Method

get_gyroradius(V, B; q=qᵢ, m=mᵢ)

Return the gyroradius [m].

Arguments

• V::AbstractFloat: Velocity magnitude [m/s] (usually perpendicular to the magnetic field).

• B::AbstractFloat: Magnetic field magnitude [T].

• q::AbstractFloat: Charge [C]. Default is proton charge.

• m::AbstractFloat: Mass [kg]. Default is proton mass.

source

TestParticle.get_velocity Method

Return velocity from relativistic γv in sol.

source

TestParticle.prepare Function

prepare(args...; kwargs...) -> (q2m, m, E, B, F)
prepare(E, B, F = ZeroField(); kwargs...)
prepare(grid::CartesianGrid, E, B, F = ZeroField(); kwargs...)
prepare(x, E, B, F = ZeroField(); dir = 1, kwargs...)
prepare(x, y, E, B, F = ZeroField(); kwargs...)
prepare(x, y, z, E, B, F = ZeroField(); kwargs...)

Return a tuple consists of particle charge-mass ratio for a prescribed species of charge q and mass m, mass m for a prescribed species, analytic/interpolated EM field functions, and external force F.

Prescribed species are Electron and Proton; other species can be manually specified with species=Ion/User, q and m.

Direct range input for uniform grid in 1/2/3D is supported. For 1D grid, an additional keyword dir is used for specifying the spatial direction, 1 -> x, 2 -> y, 3 -> z. For 3D grid, the default grid type is Cartesian. To use Spherical grid, an additional keyword gridtype is needed. For Spherical grid, dimensions of field arrays should be (Br, Bθ, Bϕ).

Keywords

• order::Int=1: order of interpolation in [1,2,3].

• bc::Int=1: type of boundary conditions, 1 -> NaN, 2 -> periodic.

• species::Species=Proton: particle species.

• q=1.0: particle charge. Only works when Species=User.

• m=1.0: particle mass. Only works when Species=User.

• gridtype::Grid=Cartesian(): type of grid in Cartesian(), Spherical(), SphericalNonUniformR.

source

TestParticle.sample Method

 sample(vdf::Maxwellian)

Sample a 3D velocity from a Maxwellian distribution vdf using the Box-Muller method.

 sample(vdf::BiMaxwellian)

Sample a 3D velocity from a BiMaxwellian distribution vdf using the Box-Muller method.

source

TestParticle.trace! Method

trace!(dy, y, p, t)

ODE equations for charged particle moving in static EM field and external force field with in-place form.

source

TestParticle.trace Method

trace(y, p, t) -> SVector{6, Float64}

ODE equations for charged particle moving in static EM field and external force field with out-of-place form.

source

TestParticle.trace_gc! Method

 trace_gc!(dy, y, p, t)

Guiding center equations for nonrelativistic charged particle moving in static EM field with in-place form. Variable y = (x, y, z, u), where u is the velocity along the magnetic field at (x,y,z).

source

TestParticle.trace_gc_1st! Method

1st order approximation of guiding center equations.

source

TestParticle.trace_gc_drifts! Method

 trace_gc_drifts!(dx, x, p, t)

Equations for tracing the guiding center using analytical drifts, including the grad-B drift, curvature drift, and ExB drift. Parallel velocity is also added. This expression requires the full particle trajectory p.sol.

source

TestParticle.trace_normalized! Method

 trace_normalized!(dy, y, p, t)

Normalized ODE equations for charged particle moving in static EM field with in-place form. If the field is in 2D X-Y plane, periodic boundary should be applied for the field in z via the extrapolation function provided by Interpolations.jl.

source

TestParticle.trace_relativistic! Method

 trace_relativistic!(dy, y, p, t)

ODE equations for relativistic charged particle (x, γv) moving in static EM field with in-place form.

source

TestParticle.trace_relativistic Method

 trace_relativistic(y, p, t) -> SVector{6}

ODE equations for relativistic charged particle (x, γv) moving in static EM field with out-of-place form.

source

TestParticle.trace_relativistic_normalized! Method

 trace_relativistic_normalized!(dy, y, p, t)

Normalized ODE equations for relativistic charged particle (x, γv) moving in static EM field with in-place form.

source

TestParticle.trace_relativistic_normalized Method

 trace_relativistic_normalized(y, p, t)

Normalized ODE equations for relativistic charged particle (x, γv) moving in static EM field with out-of-place form.

source

Private types and methods

TestParticle.AbstractTraceSolution Type

Abstract type for tracing solutions.

source

TestParticle.Field Type

 Field{itd, F} <: AbstractField{itd}

A representation of a field function f, defined by:

time-independent field

$$\mathbf{F}=F(\mathbf{x}),$$

time-dependent field

$$\mathbf{F}=F(\mathbf{x},t).$$

Arguments

• field_function::Function: the function of field.

• itd::Bool: whether the field function is time dependent.

• F: the type of field_function.

source

TestParticle.GCTuple Type

The type of parameter tuple for guiding center problem.

source

TestParticle.Grid Type

Type for grid.

source

TestParticle.Species Type

Type for the particles, Proton, Electron, Ion, or User.

source

TestParticle.TraceSolution Method

Interpolate solution at time x. Forward tracing only.

source

TestParticle.VDF Type

Abstract type for velocity distribution functions.

source

TestParticle._boris! Method

Apply Boris method for particles with index in irange.

source

TestParticle._prepare Method

Prepare for advancing.

source

TestParticle.cart2sph Method

Convert from Cartesian to spherical coordinates vector.

source

TestParticle.cross! Method

In-place cross product.

source

TestParticle.dipole Method

Calculates the magnetic field from a dipole with magnetic moment M at r.

source

TestParticle.dipole_fieldline Function

 dipole_fieldline(ϕ, L=2.5, nP=100)

Creates nP points on one field line of the magnetic field from a dipole. In a centered dipole magnetic field model, the path along a given L shell can be described as r = L*cos²λ, where r is the radial distance (in planetary radii) to a point on the line, λ is its co-latitude, and L is the L-shell of interest.

source

TestParticle.getB_CS_harris Function

 getB_CS_harris(B₀, L)

Return the magnetic field at location r near a current sheet with magnetic strength B₀ and sheet length L. The current sheet is assumed to lie in the z = 0 plane.

source

TestParticle.getB_bottle Method

 getB_bottle(x, y, z, distance, a, b, I1, I2) -> StaticVector{Float64, 3}

Get magnetic field from a magnetic bottle. Reference: wiki

Arguments

• x,y,z::Float: particle coordinates in [m].

• distance::Float: distance between solenoids in [m].

• a::Float: radius of each side coil in [m].

• b::Float: radius of central coil in [m].

• I1::Float: current in the solenoid times number of windings in side coils in [A].

• I2::Float: current in the central solenoid times number of windings in the central loop in [A].

source

TestParticle.getB_current_loop Method

 getB_current_loop(x, y, z, cl::Currentloop) -> StaticVector{Float64, 3}

Get magnetic field at [x, y, z] from a magnetic mirror generated from two coils.

Arguments

• x,y,z::Float: particle coordinates in [m].

• distance::Float: distance between solenoids in [m].

• a::Float: radius of each side coil in [m].

• I1::Float: current in the solenoid times number of windings in side coils.

source

TestParticle.getB_dipole Method

Analytic magnetic field function for testing. Return in SI unit.

source

TestParticle.getB_mirror Method

 getB_mirror(x, y, z, distance, a, I1) -> StaticVector{Float64, 3}

Get magnetic field at [x, y, z] from a magnetic mirror generated from two coils.

Arguments

• x,y,z::Float: particle coordinates in [m].

• distance::Float: distance between solenoids in [m].

• a::Float: radius of each side coil in [m].

• I1::Float: current in the solenoid times number of windings in side coils.

source

TestParticle.getB_tokamak_coil Method

 getB_tokamak_coil(x, y, z, a, b, ICoils, IPlasma) -> StaticVector{Float64, 3}

Get the magnetic field from a Tokamak topology consists of 16 coils. Original: Tokamak-Fusion-Reactor

Arguments

• x,y,z::Float: location in [m].

• a::Float: radius of each coil in [m].

• b::Float: radius of central region in [m].

• ICoil::Float: current in the coil times number of windings in [A].

• IPlasma::Float: current of the plasma in [A].

source

TestParticle.getB_tokamak_profile Method

 getB_tokamak_profile(x, y, z, q_profile, a, R₀, Bζ0) -> StaticVector{Float64, 3}

Reconstruct the magnetic field distribution from a safe factor(q) profile. Reference: Tokamak, 4th Edition, John Wesson.

Arguments

• x,y,z::Float: location in [m].

• q_profile::Function: profile of q. The variable of this function must be the normalized radius.

• a::Float: minor radius [m].

• R₀::Float: major radius [m].

• Bζ0::Float: toroidal magnetic field on axis [T].

source

TestParticle.getE_dipole Method

Analytic electric field function for testing.

source

TestParticle.get_interpolator Method

 get_interpolator(A, gridx, gridy, gridz, order::Int=1, bc::Int=1)
 get_interpolator(gridtype, A, grid1, grid2, grid3, order::Int=1, bc::Int=1)

Return a function for interpolating field array A on the grid given by gridx, gridy, and gridz.

Arguments

• gridtype: Cartesian, Spherical or SphericalNonUniformR.

• A: field array. For vector field, the first dimension should be 3.

• order::Int=1: order of interpolation in [1,2,3].

• bc::Int=1: type of boundary conditions, 1 -> NaN, 2 -> periodic, 3 -> Flat.

Notes

The input array A may be modified in-place for memory optimization.

source

TestParticle.get_rotation_matrix Method

 get_rotation_matrix(axis::AbstractVector, angle::Real) --> SMatrix{3,3}

Create a rotation matrix for rotating a 3D vector around a unit axis by an angle in radians. Reference: Rotation matrix from axis and angle

Example

using LinearAlgebra
v = [-0.5, 1.0, 1.0]
v̂ = normalize(v)
θ = deg2rad(-74)
R = get_rotation_matrix(v̂, θ)

source

TestParticle.getchargemass Method

 getchargemass(species::Species, q, m)

Return charge and mass for species. For species = Ion, q and m are charge and mass numbers. For species = User, the input q and m are returned as is.

source

TestParticle.getinterp Function

 getinterp(::Grid, A, gridx, gridy, gridz, order::Int=1, bc::Int=1)

Return a function for interpolating field array A on the grid given by gridx, gridy, and gridz.

Arguments

• order::Int=1: order of interpolation in [1,2,3].

• bc::Int=1: type of boundary conditions, 1 -> NaN, 2 -> periodic, 3 -> Flat.

• dir::Int: 1/2/3, representing x/y/z direction.

Notes

The input array A may be modified in-place for memory optimization.

source

TestParticle.getinterp_scalar Function

 getinterp_scalar(::Grid, A, gridx, gridy, gridz, order::Int=1, bc::Int=1)

Return a function for interpolating scalar array A on the grid given by gridx, gridy, and gridz. Currently only 3D arrays are supported.

Arguments

• order::Int=1: order of interpolation in [1,2,3].

• bc::Int=1: type of boundary conditions, 1 -> NaN, 2 -> periodic, 3 -> Flat.

• dir::Int: 1/2/3, representing x/y/z direction.

source

TestParticle.is_time_dependent Method

Judge whether the field function is time dependent.

source

TestParticle.makegrid Method

Return uniform range from 2D/3D CartesianGrid.

source

TestParticle.set_axes_equal Method

 set_axes_equal(ax)

Set 3D plot axes to equal scale for Matplotlib. Make axes of 3D plot have equal scale so that spheres appear as spheres and cubes as cubes. Required since ax.axis('equal') and ax.set_aspect('equal') don't work on 3D.

source

TestParticle.solve Function

 solve(prob::TraceProblem; trajectories::Int=1, dt::AbstractFloat,
 savestepinterval::Int=1, isoutofdomain::Function=ODE_DEFAULT_ISOUTOFDOMAIN,
     n::Int=1)

Trace particles using the Boris method with specified prob.

keywords

• trajectories::Int: number of trajectories to trace.

• dt::AbstractFloat: time step.

• savestepinterval::Int: saving output interval.

• isoutofdomain::Function: a function with input of position and velocity vector xv that determines whether to stop tracing.

• n::Int: number of substeps for the Multistep Boris method. Default is 1 (standard Boris).

source

TestParticle.sph2cart Method

Convert from spherical to Cartesian coordinates vector.

source

TestParticle.sph_to_cart_vector Method

Convert a vector from spherical to Cartesian.

source

TestParticle.update_location! Method

Update location in one timestep dt.

source

TestParticle.update_velocity! Method

 update_velocity!(xv, paramBoris, param, dt, t)

Update velocity using the Boris method, Birdsall, Plasma Physics via Computer Simulation. Reference: DTIC

source

TestParticle.update_velocity_multistep! Method

update_velocity_multistep!(xv, paramBoris, param, dt, t, n)

Update velocity using the Multistep Boris method. Reference: Zenitani & Kato 2025

source