API

TraceFieldlineProblem(u0, field, tspan; mode=:both)

Create SciML ODEProblems for tracing a magnetic field line through the analytical field function field(u, s). The independent variable s is arc length. mode may be :forward, :backward, or :both; the latter returns a pair of problems. Load SciMLBase (or OrdinaryDiffEqTsit5) to enable this optional interface, then use solve with a solver such as Tsit5(). For native fixed-step tracing, use trace instead.

 select_seeds(x, y, z; nsegment=(5, 5, 5))

Generate uniform seeding points in the grid range x, y and z in nsegment.

 select_seeds(x, y; nsegment=(5, 5))

Generate uniform seeding points in the grid range x and y in nsegment. If nsegment specified, use the keyword input, otherwise it will be overloaded by the 3D version seed generation function!

trace(fieldx, fieldy, fieldz, startx, starty, startz, gridx, gridy, gridz;
	alg=RK4(), kwargs...)

trace(fieldx, fieldy, fieldz, startx, starty, startz, grid::CartesianGrid;
	alg=RK4(), maxstep=20000, ds=0.01, gridtype="ndgrid", direction="both")

Stream tracing on structured mesh with field in 3D array and grid in range.

trace(field, u0::AbstractVector; alg=RK4(), ds=0.01, maxstep=20000,
      max_length=Inf, direction="both", isoutside=(u, s) -> false)

Trace the analytical vector field field(u, s) with native fixed-step RK4. u0 is a nonempty real position vector and s is signed arc length from the seed. ds must be positive. direction is "forward", "backward", or "both". Only RK4() is supported for analytical fields.

Each direction returns a named tuple (points, s, status), where points is a vector of position vectors and s contains their signed arc lengths. With direction="both", return (forward=..., backward=...); each branch starts at the seed and has its own limits. maxstep limits the number of saved points (including the seed). max_length limits arc length per branch; the last step is shortened to reach it.

isoutside(u, s) is checked before every field evaluation and before saving an endpoint. An invalid intermediate RK stage discards the entire step. No boundary intersection is computed; the result retains the last accepted point.

status is :max_length, :maxstep, :outside, :zero_field, :nonfinite_field, :nonfinite_state, or :stepsize_underflow. Exactly zero fields terminate tracing; near-zero nonzero fields are normalized. Exceptions from the field or predicate propagate to the caller.

There is no adaptive error control. Check convergence by reducing ds, or use TraceFieldlineProblem with an optional adaptive SciML solver.

 trace(mesh::SimpleMesh, vx, vy, xstart, ystart; maxIter=1000, maxLen=1000.)

2D stream tracing on unstructured quadrilateral and triangular mesh.

trace_fieldline!(du, u, field, s)

ODE for tracing a magnetic field line parameterized by arc length. field(u, s) must return the magnetic field vector at position u and arc length s.

bilin_reg(x, y, Q00, Q01, Q10, Q11)

Bilinear interpolation for x1,y1=(0,0) and x2,y2=(1,1) Q's are surrounding points such that Q00 = F[0,0], Q10 = F[1,0], etc.

euler(maxstep, ds, startx, starty, xGrid, yGrid, ux, uy)

Fast 2D tracing using Euler's method. It takes at most maxstep with step size ds tracing the vector field given by ux,uy starting from (startx,starty) in the Cartesian grid specified by ranges xGrid and yGrid. Step size is in physical unit. Return footprints' coordinates in (x, y).

euler(maxstep, ds, startx, starty, startz, xGrid, yGrid, zGrid, ux, uy, uz)

Fast 3D tracing using Euler's method. It takes at most maxstep with step size ds tracing the vector field given by ux,uy,uz starting from (startx,starty,startz) in the Cartesian grid specified by ranges xGrid, yGrid and zGrid. ds is the step size in physical unit. Return footprints' coordinates in (x,y,z).

euler_batch(maxstep, ds, startx, starty, startz, xGrid, yGrid, zGrid, ux, uy, uz)

Fast 3D tracing of multiple particles using Euler's method. Returns matrices x, y, z of size (n_particles, maxstep).

euler_batch(maxstep, ds, startx, starty, xGrid, yGrid, ux, uy)

Fast 2D tracing of multiple particles using Euler's method. Returns matrices x and y of size (n_particles, maxstep).

Return cell ID on the unstructured mesh.

Return the cellIDth element of the mesh.

grid_interp(x, y, field, ix, iy)

Interpolate a value at (x,y) in a field. ix and iy are indexes for x,y locations (0-based).

grid_interp(x, y, z, ix, iy, iz, field)

Interpolate a value at (x,y,z) in a field. ix,iy and iz are indexes for x, y and z locations (0-based).

rk4(maxstep, ds, startx, starty, xGrid, yGrid, ux, uy)

Fast and reasonably accurate 2D tracing with 4th order Runge-Kutta method and constant step size ds. See also euler.

rk4(maxstep, ds, startx, starty, startz, xGrid, yGrid, zGrid, ux, uy, uz)

Fast and reasonably accurate 3D tracing with 4th order Runge-Kutta method and constant step size ds. See also euler. ds is the step size in physical unit.

rk4_batch(maxstep, ds, startx, starty, startz, xGrid, yGrid, zGrid, ux, uy, uz)

Fast 3D tracing of multiple particles using RK4 method. Returns matrices x, y, z of size (n_particles, maxstep).

rk4_batch(maxstep, ds, startx, starty, xGrid, yGrid, ux, uy)

Fast 2D tracing of multiple particles using RK4 method. Returns matrices x and y of size (n_particles, maxstep).

trace2d_euler(fieldx, fieldy, startx, starty, gridx, gridy;
   maxstep=20000, ds=0.01, gridtype="ndgrid", direction="both")

Given a 2D vector field, trace a streamline from a given point to the edge of the vector field. The field is integrated using Euler's method, which is faster but less accurate than RK4. Only valid for regular grid with coordinates' range gridx and gridy. Step size is in same unit as the grid coordinates. The field can be in both meshgrid or ndgrid (default) format. Supporting direction of {"both","forward","backward"}.

trace2d_euler(fieldx, fieldy, startx, starty, grid::CartesianGrid; kwargs...)

trace2d_rk4(fieldx, fieldy, startx, starty, gridx, gridy;
   maxstep=20000, ds=0.01, gridtype="ndgrid", direction="both")

Given a 2D vector field, trace a streamline from a given point to the edge of the vector field. The field is integrated using Runge Kutta 4. Slower than Euler, but more accurate. The higher accuracy allows for larger step sizes ds. Step size is in same unit as the grid coordinates. See also trace2d_euler.

trace3d_euler(fieldx, fieldy, fieldz, startx, starty, startz, gridx, gridy, gridz;
   maxstep=20000, ds=0.01)

Given a 3D vector field, trace a streamline from a given point to the edge of the vector field. The field is integrated using Euler's method. Only valid for regular grid with coordinates gridx, gridy, gridz. The field can be in both meshgrid or ndgrid (default) format. Supporting direction of {"both","forward","backward"}.

trace3d_euler(fieldx, fieldy, fieldz, startx, starty, startz, grid::CartesianGrid;
   maxstep=20000, ds=0.01, gridtype="ndgrid", direction="both")

See also trace3d_rk4.

trace3d_rk4(fieldx, fieldy, fieldz, startx, starty, startz, gridx, gridy, gridz;
   maxstep=20000, ds=0.01)

Given a 3D vector field, trace a streamline from a given point to the edge of the vector field. The field is integrated using Euler's method. Only valid for regular grid with coordinates gridx, gridy, gridz. The field can be in both meshgrid or ndgrid (default) format. See also trace3d_euler.

trace3d_rk4(fieldx, fieldy, fieldz, startx, starty, startz, grid::CartesianGrid;
   maxstep=20000, ds=0.01, gridtype="ndgrid", direction="both")

See also trace3d_euler.

trilin_reg(x, y, z, Q)

Trilinear interpolation for x1,y1,z1=(0,0,0) and x2,y2,z2=(1,1,1) Q's are surrounding points such that Q000 = F[0,0,0], Q100 = F[1,0,0], etc.