Summary
VAFT currently distinguishes and supports the toroidal current density in equilibrium data, but it does not expose a corresponding parallel current density $J_\parallel$ derived from the reconstructed axisymmetric equilibrium.
The current equilibrium path already provides:
equilibrium.time_slice[:].profiles_2d[0].j_tor
local toroidal current density j_phi(R,Z)
equilibrium.time_slice[:].profiles_1d.j_tor
IMAS-defined flux-surface average
<j_tor / R> / <1 / R>
The distinction between those two quantities was fixed explicitly in #316.
The next step is to add a convention-aware derivation of
$$
J_\parallel(R,Z)
\frac{\mathbf J\cdot\mathbf B}{|\mathbf B|},
$$
and provide explicit, documented flux-surface reductions suitable for current-profile and MHD analysis.
This is especially useful when comparing radial current gradients: a local HFS/LFS cut of $J_\phi$ contains strong geometric $R$ and $1/R$ variation that is not the same object as a field-aligned current profile.
Current state
VAFT already computes the local toroidal current from the Grad-Shafranov source functions:
$$
j_\phi(R,Z)
-\sigma_{B_p}(2\pi)^{e_{B_p}}
\left[
R p'(\psi)
+
\frac{F F'(\psi)}{\mu_0 R}
\right],
$$
with the flux convention resolved by the equilibrium updater.
It also stores the IMAS 1-D toroidal-current quantity
$$
j_{\mathrm{tor},1D}
\frac{\left\langle j_\phi/R\right\rangle}
{\left\langle 1/R\right\rangle}.
$$
These are both $J_\phi$-related quantities. Neither is $J_\parallel$.
Repository search currently finds no dedicated j_parallel, j_par, or parallel_current equilibrium implementation.
core_profiles path support includes quantities such as j_total, j_ohmic, j_non_inductive, and j_bootstrap, but those must not be treated as aliases for equilibrium-derived $J_\parallel$ without verifying the exact IMAS physical semantics.
Physics definition
For an axisymmetric equilibrium,
$$
\mathbf B
\mathbf B_p
+
\frac{F(\psi)}{R},\hat{\boldsymbol\phi},
$$
with $F=RB_\phi$.
After resolving the equilibrium convention consistently, the poloidal current is parallel to the poloidal magnetic field,
$$
\mathbf J_p
\frac{F'(\psi)}{\mu_0}\mathbf B_p,
$$
in the standard axisymmetric convention, while $J_\phi$ is supplied by Grad-Shafranov force balance.
Therefore the local field-aligned current can be evaluated directly from components:
$$
J_\parallel
\frac{
J_R B_R + J_Z B_Z + J_\phi B_\phi
}{B}.
$$
An equivalent compact identity in a convention-normalized representation is
$$
J_\parallel
\frac{F p'}{B}
+
\frac{F' B}{\mu_0}.
$$
The implementation should prefer one convention-safe formulation and use the other as an internal verification identity. Do not hard-code signs or $2\pi$ factors independently of the existing COCOS machinery.
Goals
1. Add a pure Formula API
Add a machine-independent numerical kernel, conceptually:
parallel_current_density_from_equilibrium(
p_prime,
f,
f_prime,
b_magnitude,
*,
cocos=...,
psi_per_radian=...,
)or an equivalent API consistent with the current Formula conventions.
The function must document:
- exact mathematical definition;
- sign convention;
- poloidal-flux convention;
-
$2\pi$ handling;
- units;
- assumptions of axisymmetry and $F=F(\psi)$;
- relation to $J_\phi$;
- limitations near invalid / non-equilibrium regions.
The Formula API must not require an ODS.
2. Add an equilibrium-aware derived quantity
Provide an updater/process path that evaluates local $J_\parallel(R,Z)$ from an existing equilibrium using the same resolved flux frame already used for j_tor.
Conceptually:
psi(R,Z), p'(psi), F(psi), FF'(psi), B_R, B_Z, B_phi
|
v
J_parallel(R,Z)
Points outside the physically supported equilibrium domain should be handled explicitly rather than filled by clipped profile extrapolation.
3. Define explicit 1-D reductions
Do not introduce one ambiguous profiles_1d.j_parallel until its averaging semantics are defined.
Support or investigate explicitly named reductions such as:
$$
\langle J_\parallel\rangle,
$$
$$
\langle J_\parallel B\rangle,
$$
and
$$
\frac{\langle J_\parallel B\rangle}{\langle B^2\rangle},
$$
where scientifically useful.
These are not interchangeable quantities. Each returned quantity must carry its exact definition, units, and intended use.
For comparison with external neoclassical or stability codes, use the quantity those codes actually define rather than choosing an average by name similarity.
4. Audit IMAS / OMAS mapping before storage
Before writing a result into a standard DD path, verify the exact IMAS semantics.
In particular:
core_profiles.profiles_1d[:].j_total
core_profiles.profiles_1d[:].j_ohmic
core_profiles.profiles_1d[:].j_non_inductive
core_profiles.profiles_1d[:].j_bootstrap
must not be populated from equilibrium-derived $J_\parallel$ unless the physical definition, normalization, radial coordinate, and flux-surface averaging convention match exactly.
If no exact standard field exists for the local or reduced quantity, preserve it first as a typed/process result rather than inventing a private IDS path.
Scientific use case
A first validation/analysis view should compare, on the same equilibrium:
local HFS J_phi(psi_N)
local LFS J_phi(psi_N)
IMAS profiles_1d.j_tor
selected J_parallel flux-surface reduction
and then compare radial gradients such as
$$
\frac{dJ}{d\psi_N}
$$
without conflating geometric HFS/LFS variation of $J_\phi$ with a field-aligned current-profile gradient.
This should make the distinction visible before using current-gradient features in tearing-mode, equilibrium-quality, or profile-comparison studies.
Validation
Analytic / synthetic checks
- verify the component definition $\mathbf J\cdot\mathbf B/B$;
- verify agreement with the compact axisymmetric identity after convention normalization;
- verify simple limiting cases for $p'=0$ and/or $F'=0$;
- verify finite behavior on-axis where the equilibrium representation permits it;
- reject or mask invalid $B\rightarrow0$ points explicitly.
Consistency with existing equilibrium quantities
Flux-surface tests
- demonstrate that local HFS and LFS $J_\phi$ differ on a shaped surface as expected;
- demonstrate that the selected flux-surface reduction is independent of which geometric cut was used to visualize the surface;
- test convergence of the reduction with poloidal resolution;
- use the existing SFL / flux-surface geometry infrastructure rather than introducing a second contour convention.
Architecture
Preferred ownership:
vaft.formula.equilibrium
pure J_parallel kernel / axisymmetric identities
vaft.process.equilibrium
flux-surface evaluation / reduction where reusable
vaft.omas / vaft.imas
schema-aware extraction and population only after DD semantics are verified
vaft.view / validation
compare J_phi, j_tor, and J_parallel-derived profiles
Do not make the formula layer ODS-aware and do not create a parallel equilibrium representation.
Relationship to existing issues
Acceptance criteria
Non-goals
This issue does not require:
- a neoclassical bootstrap-current model;
- NEO / GACODE execution;
- Ohmic / bootstrap / driven-current decomposition;
- MSE reconstruction;
- 3-D perturbed parallel current;
- replacing
profiles_1d.j_tor;
- changing EFIT reconstruction defaults;
- inventing a non-standard IDS field merely to store the result.
The first target is narrower: provide a physically and conventionally unambiguous axisymmetric equilibrium-derived parallel current and make its distinction from toroidal current explicit throughout VAFT.
Summary
VAFT currently distinguishes and supports the toroidal current density in equilibrium data, but it does not expose a corresponding parallel current density$J_\parallel$ derived from the reconstructed axisymmetric equilibrium.
The current equilibrium path already provides:
The distinction between those two quantities was fixed explicitly in #316.
The next step is to add a convention-aware derivation of
$$
J_\parallel(R,Z)
\frac{\mathbf J\cdot\mathbf B}{|\mathbf B|},
$$
and provide explicit, documented flux-surface reductions suitable for current-profile and MHD analysis.
This is especially useful when comparing radial current gradients: a local HFS/LFS cut of$J_\phi$ contains strong geometric $R$ and $1/R$ variation that is not the same object as a field-aligned current profile.
Current state
VAFT already computes the local toroidal current from the Grad-Shafranov source functions:
$$
j_\phi(R,Z)
-\sigma_{B_p}(2\pi)^{e_{B_p}}
\left[
R p'(\psi)
+
\frac{F F'(\psi)}{\mu_0 R}
\right],
$$
with the flux convention resolved by the equilibrium updater.
It also stores the IMAS 1-D toroidal-current quantity
$$
j_{\mathrm{tor},1D}
\frac{\left\langle j_\phi/R\right\rangle}
{\left\langle 1/R\right\rangle}.
$$
These are both$J_\phi$ -related quantities. Neither is $J_\parallel$ .
Repository search currently finds no dedicated
j_parallel,j_par, orparallel_currentequilibrium implementation.core_profilespath support includes quantities such asj_total,j_ohmic,j_non_inductive, andj_bootstrap, but those must not be treated as aliases for equilibrium-derivedPhysics definition
For an axisymmetric equilibrium,
$$
\mathbf B
\mathbf B_p
+
\frac{F(\psi)}{R},\hat{\boldsymbol\phi},
$$
with$F=RB_\phi$ .
After resolving the equilibrium convention consistently, the poloidal current is parallel to the poloidal magnetic field,
$$
\mathbf J_p
\frac{F'(\psi)}{\mu_0}\mathbf B_p,
$$
in the standard axisymmetric convention, while$J_\phi$ is supplied by Grad-Shafranov force balance.
Therefore the local field-aligned current can be evaluated directly from components:
$$
J_\parallel
\frac{
J_R B_R + J_Z B_Z + J_\phi B_\phi
}{B}.
$$
An equivalent compact identity in a convention-normalized representation is
$$
J_\parallel
\frac{F p'}{B}
+
\frac{F' B}{\mu_0}.
$$
The implementation should prefer one convention-safe formulation and use the other as an internal verification identity. Do not hard-code signs or$2\pi$ factors independently of the existing COCOS machinery.
Goals
1. Add a pure Formula API
Add a machine-independent numerical kernel, conceptually:
or an equivalent API consistent with the current Formula conventions.
The function must document:
The Formula API must not require an ODS.
2. Add an equilibrium-aware derived quantity
Provide an updater/process path that evaluates local$J_\parallel(R,Z)$ from an existing equilibrium using the same resolved flux frame already used for
j_tor.Conceptually:
Points outside the physically supported equilibrium domain should be handled explicitly rather than filled by clipped profile extrapolation.
3. Define explicit 1-D reductions
Do not introduce one ambiguous
profiles_1d.j_paralleluntil its averaging semantics are defined.Support or investigate explicitly named reductions such as:
and
where scientifically useful.
These are not interchangeable quantities. Each returned quantity must carry its exact definition, units, and intended use.
For comparison with external neoclassical or stability codes, use the quantity those codes actually define rather than choosing an average by name similarity.
4. Audit IMAS / OMAS mapping before storage
Before writing a result into a standard DD path, verify the exact IMAS semantics.
In particular:
must not be populated from equilibrium-derived$J_\parallel$ unless the physical definition, normalization, radial coordinate, and flux-surface averaging convention match exactly.
If no exact standard field exists for the local or reduced quantity, preserve it first as a typed/process result rather than inventing a private IDS path.
Scientific use case
A first validation/analysis view should compare, on the same equilibrium:
and then compare radial gradients such as
without conflating geometric HFS/LFS variation of$J_\phi$ with a field-aligned current-profile gradient.
This should make the distinction visible before using current-gradient features in tearing-mode, equilibrium-quality, or profile-comparison studies.
Validation
Analytic / synthetic checks
Consistency with existing equilibrium quantities
j_torupdater;Flux-surface tests
Architecture
Preferred ownership:
Do not make the formula layer ODS-aware and do not create a parallel equilibrium representation.
Relationship to existing issues
profiles_2d.j_tormust be the local toroidal current and must not be confused with the 1-D flux-surface average.Acceptance criteria
j_parallelquantity is introduced without a documented averaging definition.profiles_1d.j_tor, and the selectedj_torbehavior from update_equilibrium_profiles_2d_j_tor writes a flux-surface average as if it were the local 2-D current density #316 remains unchanged.Non-goals
This issue does not require:
profiles_1d.j_tor;The first target is narrower: provide a physically and conventionally unambiguous axisymmetric equilibrium-derived parallel current and make its distinction from toroidal current explicit throughout VAFT.