Process reference: particle

Generated from the docstrings of vaft.process.particle: 6 public functions. Each entry is what vaft.process.describe("particle.<name>") prints. All process categories

Overview

Numerics are machine-independent and use SI units. No ODS, solver installation, plotting backend, collisions or transport model is required. Native integration times are preserved; interpolation is only an explicitly recorded comparison or presentation operation. Fields and records live in vaft.data.particle.

Functions

`analyze_particle_orbit`	Evaluate field, energy, invariants, ordering and defined bounce cycles. Convention
`compare_particle_orbits`	Pair full and GC trajectories on common physical times without extrapolation.
`particle_motion_case`	Compute a reproducible matched full-orbit/GC reference experiment.
`particle_to_guiding_center`	Convert simultaneous particle initial data to a leading-order GC state. Convention
`trace_guiding_center`	Integrate the static Hamiltonian GC equations with adaptive DOP853. Convention
`trace_particle_orbit`	Integrate a full Lorentz trajectory using the shared centered Boris step.

`analyze_particle_orbit`

Machine-independentConvention-sensitive source

analyze_particle_orbit(trajectory, *, bounce_coordinate=None)

Evaluate field, energy, invariants, ordering and defined bounce cycles.

Name	Type	Unit	Description
`trajectory`	ParticleTrajectory	-	Native computed particle or GC states.
`bounce_coordinate`	callable, optional	m	Signed field-line arc coordinate s(position) for a known periodic bounce. None leaves action undefined; it is never inferred from an arbitrary 3-D history.
Returns
—	dict	-	Native-time arrays, dimensional scales, residuals and bounce evidence.

Convention

Full-orbit total energy uses laboratory kinetic energy plus q Phi. GC energy uses p_parallel^2/(2m) + mu B + q Phi. Canonical toroidal momentum uses x p_y - y p_x + q (x A_y - y A_x), in the field’s declared gauge.

Processing steps · Applicability · Limitations · Provenance

Processing steps

Sample fields; resolve parallel and perpendicular energy in the local drift frame; evaluate model-appropriate invariants and dimensionless ordering. Detect turns, then evaluate action only on a supplied periodic arc coordinate whose sampled cycle closes within resolution.

Applicability

Machine-independent. Static fields with adequate numerical resolution.

Limitations

Full-orbit mu is an instantaneous estimate; its gyrovariation is physical. Derivative diagnostics are NaN with an unavailable audit when their stencil crosses the domain boundary; local state diagnostics remain available. Fixed GC mu is not an adiabaticity test. Finite orbit momentum changes under nonaxisymmetry alone do not demonstrate transport or NTV torque.

Provenance

J. R. Cary and A. J. Brizard, Rev. Mod. Phys. 81 (2009) 693.

`compare_particle_orbits`

Machine-independent source

compare_particle_orbits(full, guiding_center, *, time=None)

Pair full and GC trajectories on common physical times without extrapolation.

Name	Type	Unit	Description
`full`	ParticleTrajectory	-	Full Lorentz orbit.
`guiding_center`	ParticleTrajectory	-	Independently integrated GC orbit of the same particle and field.
`time`	array_like, optional	s	Strictly increasing comparison times; defaults to full samples in the common valid interval.
Returns
—	ParticleComparison	-	Local-center separation, time pairing and approximation evidence.

Processing steps · Applicability · Limitations · Provenance

Processing steps

Check particle, field and time compatibility; estimate the local full-orbit center in the drift frame; linearly interpolate both positions on a shared physical coordinate. Record initialization and ordering separately.

Applicability

Machine-independent. Matched initial conditions in a controlled GC regime.

Limitations

Local center subtraction is not higher-order gyroaveraging. Separation includes initialization, phase and GC approximation error; numerical and ordering scans are needed to attribute it. A one-gyroperiod time-window average is supplied separately, with incomplete edge windows omitted.

Provenance

F. F. Chen, Introduction to Plasma Physics and Controlled Fusion, 3rd ed. (2016), Sec. 2.2.

`particle_motion_case`

Machine-independent source

particle_motion_case(kind='gyration', *, charge=1.0, mass=1.0, speed=None, pitch_angle=None, aspect_ratio=3.0, perturbation=0.02, duration=None, dt=0.05)

Compute a reproducible matched full-orbit/GC reference experiment.

Name	Type	Unit	Description
`kind`	str, optional	-	gyration, exb_drift, grad_b_drift, curvature_drift, toroidal_drift, magnetic_mirror, mirror_passing, tokamak_trapped, tokamak_passing or symmetry_breaking; gyration is the simplest reference default.
`charge`	float, optional	C	Signed nonzero charge; 1 C is an illustrative SI reference particle.
`mass`	float, optional	kg	Positive mass; 1 kg is an illustrative SI reference particle.
`speed`	float, optional	m/s	Drift-frame launch speed; None chooses a documented case default.
`pitch_angle`	float, optional	rad	Launch angle from B in [0,pi]; None chooses trapped/passing defaults.
`aspect_ratio`	float, optional	-	Major/minor radius ratio of the toroidal reference; default three.
`perturbation`	float, optional	-	Signed 3-D harmonic amplitude for symmetry_breaking; default 0.02.
`duration`	float, optional	s	Physical integration duration; None uses the case reference interval.
`dt`	float, optional	s	Full-orbit step, GC maximum step is four times this numerical default.
Returns
—	ParticleComparison	-	Matched integrated trajectories with reference case and validity metadata.

Processing steps · Defaults · Applicability · Limitations · Provenance

Processing steps

Build a solenoidal static reference field, initialize a physical particle, apply the documented leading-order GC conversion, and integrate both models to the same physical end time. Pair only their common valid interval.

Defaults

Charge and mass define an illustrative SI particle, not an electron/ion mass ratio. Geometry, speed, pitch and duration are educational benchmark choices; all resolved values are recorded. dt is numerical convenience and must be reduced when charge/mass increases.

Applicability

Machine-independent. Controlled reference experiments, not discharge predictions.

Limitations

Tokamak references use an analytic circular field, not force-balanced VEST equilibrium. Symmetry-breaking output alone establishes no transport rate. Time-varying fields and the second invariant under slow variation are deferred.

Provenance

Particle-motion work packages #2004 through #2009.

`particle_to_guiding_center`

Machine-independentConvention-sensitive source

particle_to_guiding_center(q, m, x, v, field)

Show source vaft/process/particle.py, lines 327–387

def particle_to_guiding_center(q, m, x, v, field):
    """Convert simultaneous particle initial data to a leading-order GC state.

    Parameters
    ----------
    q : float
        Signed nonzero charge [C].
    m : float
        Positive mass [kg].
    x : array_like
        Particle Cartesian position [m].
    v : array_like
        Particle simultaneous Cartesian velocity [m/s].
    field : ParticleField
        Static Cartesian field [-].

    Returns
    -------
    dict
        GC position, p_parallel, mu and declared transformation order [-].

    Convention
    ----------
    Subtract local E-cross-B velocity before estimating gyromotion. The
    magnetic moment and parallel momentum are leading-order drift-frame
    estimates, not a first-order Lie-transform particle/GC transformation.

    Applicability
    -------------
    Machine-independent. Magnetized weak-flow initial states.

    Limitations
    -----------
    Initial transformation error remains part of a full-orbit/GC comparison.

    Provenance
    ----------
    .. [1] F. F. Chen, Introduction to Plasma Physics and Controlled Fusion,
       3rd ed. (2016), Sec. 2.2.
    """
    x = _initial(q, m, x, 1.0, 1.0, 0.0)
    v = np.asarray(v, float)
    if v.shape != (3,) or not np.all(np.isfinite(v)):
        raise ValueError("v must be a finite 3-vector")
    B = field.magnetic(x)
    magnitude = np.linalg.norm(B)
    b = B / magnitude
    drift = np.cross(field.electric(x), B) / magnitude**2
    relative = v - drift
    parallel = relative @ b
    X = x - gyration_offset(q, m, B, relative)
    field.check_position(X)
    return {
        "position": X,
        "p_parallel": float(m * parallel),
        "mu": float(
            magnetic_moment(m, np.linalg.norm(relative - parallel * b), magnitude)
        ),
        "transformation": "leading-order local drift-frame gyration offset",
        "approximation_order": "zeroth-order GC initialization; no Lie-transform correction",
    }

Convert simultaneous particle initial data to a leading-order GC state.

Name	Type	Unit	Description
`q`	float	C	Signed nonzero charge.
`m`	float	kg	Positive mass.
`x`	array_like	m	Particle Cartesian position.
`v`	array_like	m/s	Particle simultaneous Cartesian velocity.
`field`	ParticleField	-	Static Cartesian field.
Returns
—	dict	-	GC position, p_parallel, mu and declared transformation order.

Convention

Subtract local E-cross-B velocity before estimating gyromotion. The magnetic moment and parallel momentum are leading-order drift-frame estimates, not a first-order Lie-transform particle/GC transformation.

Applicability · Limitations · Provenance

Applicability

Machine-independent. Magnetized weak-flow initial states.

Limitations

Initial transformation error remains part of a full-orbit/GC comparison.

Provenance

F. F. Chen, Introduction to Plasma Physics and Controlled Fusion, 3rd ed. (2016), Sec. 2.2.

`trace_guiding_center`

Machine-independentConvention-sensitive source

trace_guiding_center(q, m, X0, p_parallel0, mu, field, *, duration, dt, t0=0.0, rtol=1e-09, atol=1e-11)

Integrate the static Hamiltonian GC equations with adaptive DOP853.

Name	Type	Unit	Description
`q`	float	C	Signed nonzero charge.
`m`	float	kg	Positive mass.
`X0`	array_like	m	Initial guiding-center Cartesian position.
`p_parallel0`	float	kg m/s	Initial signed parallel kinetic momentum.
`mu`	float	J/T	Nonnegative magnetic moment, held constant by the model.
`field`	ParticleField	-	Static field with Jacobian or explicit numerical derivative step.
`duration`	float	s	Positive physical duration.
`dt`	float	s	Maximum accepted integration step.
`t0`	float, optional	s	Initial timestamp, a coordinate origin.
`rtol`	float, optional	-	Relative numerical tolerance, a numerical convenience.
`atol`	float, optional	-	Absolute tolerance on dimensionless scaled state, a numerical convenience.
Returns
—	ParticleTrajectory	-	Native accepted steps with momentum, model-constant mu and termination.

Convention

Static SI Cartesian fields; this is a weak-flow, nonrelativistic GC model. Numerical energy conservation is tested, not enforced by projection.

Processing steps · Applicability · Limitations · Provenance

Processing steps

Scale position by a local gyroradius and momentum by characteristic kinetic momentum, integrate the Hamiltonian B-star equations, and preserve accepted states. A field boundary or B-star singularity terminates the trace.

Applicability

Machine-independent. Smooth magnetized static fields, small gyroradius ordering and weak electrostatic drift.

Limitations

DOP853 is not symplectic. No long-time invariant guarantee is claimed. mu conservation is imposed; assess adiabaticity against full Lorentz runs.

Provenance

J. R. Cary and A. J. Brizard, Rev. Mod. Phys. 81 (2009) 693.

`trace_particle_orbit`

Machine-independent source

trace_particle_orbit(q, m, x0, v0, field, *, duration, dt, t0=0.0)

Integrate a full Lorentz trajectory using the shared centered Boris step.

Name	Type	Unit	Description
`q`	float	C	Signed nonzero particle charge.
`m`	float	kg	Positive mass.
`x0`	array_like	m	Initial Cartesian position.
`v0`	array_like	m/s	Initial simultaneous Cartesian velocity.
`field`	ParticleField	-	Static magnetic and electrostatic field in Cartesian SI units.
`duration`	float	s	Positive physical duration.
`dt`	float	s	Positive integration step; the last step is shortened to duration.
`t0`	float, optional	s	Initial physical timestamp; zero is a coordinate origin.
Returns
—	ParticleTrajectory	-	Native simultaneous states and explicit termination reason.

Processing steps · Applicability · Limitations · Provenance

Processing steps

Validate initial data, then use drift-kick-drift Boris updates. Check field domains at every sampled position. Preserve only valid completed steps.

Applicability

Machine-independent. Nonrelativistic collisionless motion in static fields.

Limitations

Fixed-step integration must resolve the largest gyrofrequency encountered. A boundary event retains the last valid step, not an inferred wall impact. Steps smaller than the timestamp spacing are rejected; shift t0 toward zero when resolving very short motion at a large absolute time origin.

Provenance

J. P. Boris, Proc. 4th Conf. Numer. Sim. Plasmas, NRL (1970), 3.

Process reference: particle

Process reference: particle

Overview

Functions

`analyze_particle_orbit`

Processing steps

Applicability

Limitations

Provenance

`compare_particle_orbits`

Processing steps

Applicability

Limitations

Provenance

`particle_motion_case`

Processing steps

Defaults

Applicability

Limitations

Provenance

`particle_to_guiding_center`

Applicability

Limitations

Provenance

`trace_guiding_center`

Processing steps

Applicability

Limitations

Provenance

`trace_particle_orbit`

Processing steps

Applicability

Limitations

Provenance

results matching ""

No results matching ""

Process reference: particle

Overview

Functions

Processing steps

Applicability

Limitations

Provenance

Processing steps

Applicability

Limitations

Provenance

Processing steps

Defaults

Applicability

Limitations

Provenance

Applicability

Limitations

Provenance

Processing steps

Applicability

Limitations

Provenance

Processing steps

Applicability

Limitations

Provenance

Related resources

API

results matching ""

No results matching ""