Process reference: profile_gradients

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

Overview

A normalized gradient such as a/L_T is a derived quantity, not a radial coordinate, and it is defined only once three separate choices are stated (issue #551):

coordinate The abscissa: where on the profile each value is placed. gradient_coordinate The physical radial variable the derivative is taken with respect to. reference_length The macroscopic length that multiplies the derivative.

A convention is a code-specific preset that resolves the last two, and nothing more: it is recorded beside the explicit values it resolved to, never instead of them.

The chain, and where each step’s state changes::

one equilibrium slice
-> every registered radial coordinate on its psi grid      [RadialCoordinateMap]
-> profile on its own grid, differentiated there
-> chain rule d/dx_g = (dx_p/dx_g) d/dx_p through the map
-> times the reference length                              [ReferenceLength]
-> placed on the requested abscissa                         [ProfileGradient]

Nothing is extrapolated. A point outside the radial support of the map, a mapping that is not monotonic, a profile value that is not positive, a coordinate the equilibrium cannot supply, and a convention whose reference length depends on configuration the caller did not pass are all refused with ValueError.

Symbol	Meaning	Unit
psi_norm	normalized poloidal flux, (psi - psi_axis)/(psi_boundary - psi_axis)	-
rho_pol_norm	sqrt(psi_norm)	-
rho_tor_norm	sqrt(Phi/Phi_boundary), Phi = int q dpsi	-
R_in, R_out	major radius of the inboard/outboard crossing at the axis height	m
r_minor	(R_out - R_in)/2	m
a_minor	r_minor on the last closed flux surface	m
r_minor_norm	r_minor/a_minor	-
L	reference length	m
x_p, x_g, x_c	profile, gradient and plot coordinate	-

r_minor is the half-width of each surface at the magnetic-axis height, from the two midplane crossings – the IMAS r_inboard/r_outboard leaves and the GACODE rmin VAFT writes. It is not the contour half-width (max R - min R)/2 that vaft.process.equilibrium.derive_global_descriptors reports as minor_radius, and it is never R_out - R_axis, rho_tor_norm, rho_pol_norm or sqrt(psi_norm).

r_minor is VAFT’s rmin: the half-distance between the two crossings at the axis height, exactly as vaft.code.gacode.inputs writes it into input.gacode. GACODE’s own RMIN_LOC is the half-width about the flux-surface centroid, so the two agree only for surfaces centred at the axis height (up-down symmetric about Z_axis); for an up-down asymmetric surface the tglf/cgyro presets reproduce VAFT’s rmin, not RMIN_LOC.

The existing coordinate tuples in vaft.plot and vaft.process.profile are unchanged; only this layer reads RADIAL_COORDINATES.

Functions

`profile_gradient`	The normalized logarithmic gradient `-L d ln f/dx_g` of a radial profile. Convention
`radial_coordinate_map`	Every registered radial coordinate on one equilibrium slice’s psi grid. Convention
`radial_coordinate_map_from_arrays`	A coordinate map from per-surface arrays a code or file already carries. Convention
`resolve_convention`	The explicit gradient coordinate and reference length a code convention stands for. Convention
`resolve_reference_length`	The reference length a normalized gradient is multiplied by, with its definition. Convention

`profile_gradient`

Machine-independentConvention-sensitive source

profile_gradient(profile, grid, profile_coordinate, *, equilibrium, coordinate=None, gradient_coordinate=UNSET, reference_length=UNSET, convention=None, metadata=None, at=None, time=None, quantity=None, source_quantity='f')

The normalized logarithmic gradient -L d ln f/dx_g of a radial profile.

The derivative is taken on the profile’s own grid, carried to the gradient coordinate by the chain rule through the equilibrium’s coordinate map, multiplied by the reference length, and placed on the requested abscissa; the result keeps every one of those choices in its metadata [-].

Name	Type	Unit	Description
`profile`	array_like	-	Strictly positive profile values, such as a temperature or density, in any unit – only `ln f` is differentiated.
`grid`	array_like	-	Where the profile is sampled, in profile_coordinate, strictly monotonic, at least three points.
`profile_coordinate`	str	-	The `RADIAL_COORDINATES` name grid is in.
`equilibrium`	RadialCoordinateMap, EquilibriumData, ODS, GEQDSK or path	-	The slice whose surfaces relate the coordinates; anything but a map goes through `radial_coordinate_map`.
`coordinate`	str, optional	-	The abscissa of the result, a `RADIAL_COORDINATES` name.
`gradient_coordinate`	str, optional	-	What the derivative is taken with respect to, a `RADIAL_COORDINATES` name.
`reference_length`	str or None, optional	-	One of `REFERENCE_LENGTHS`; `None` gives the dimensional gradient. Must be stated, here or through convention.
`convention`	str, optional	-	A `CONVENTIONS` preset resolving gradient_coordinate and reference_length; an explicit value that disagrees with it is refused.
`metadata`	mapping, optional	-	Run settings for convention and the `L_ref` record, as `resolve_convention` and `resolve_reference_length` read them.
`at`	array_like, optional	-	Abscissa values, in coordinate, to interpolate the result to after differentiating; by default the result stays on the profile’s grid.
`time`	float, optional	s	The equilibrium slice, when equilibrium is not already a map.
`quantity`	str, optional	-	Name of the result, recorded as `quantity`.
`source_quantity`	str, optional	-	Name of the differentiated profile, used in `quantity` and in the `mathematical_definition` string.
Returns
—	ProfileGradient	-	Values, abscissa, unit and the resolved record. The unit is `1` with a reference length, `m^-1` without one for a length gradient coordinate, and `1` for a normalized one.

Convention

r_minor is the midplane half-width (R_out - R_in)/2 at the magnetic-axis height, and a_minor its LCFS value; neither is the contour half-width of vaft.process.equilibrium.derive_global_descriptors. The sign is that of a decay length: with respect to an outward-increasing gradient coordinate, a profile falling outward has a positive gradient. A reference length is accepted only with r_minor or r_outboard, the lengths that increase outward. The same physical derivative under two reference lengths differs exactly by their ratio, so R_0/L_T = (R_0/a) a/L_T.

Raises

ValueError An unknown coordinate, a profile value that is not positive, a mapping that is not strictly monotonic, a point outside the map’s radial support, an unavailable coordinate or reference length, a reference length with a gradient coordinate that is not an outward length, an unstated reference length, or a convention that conflicts with the explicit arguments or cannot be resolved.

Processing steps · Defaults · Applicability · Limitations · Provenance

Processing steps

Resolve convention, if any, into the gradient coordinate and the reference length, and refuse an explicit argument that disagrees.
d ln f/dx_p on the profile’s own grid by the three-point Lagrange derivative (numpy.gradient, second-order edges – GACODE’s bound_deriv).
When x_g != x_p: x_g on the profile grid from the map by a cubic spline, and d ln f/dx_g = (dx_p/dx_g) d ln f/dx_p with both derivatives three-point on the profile grid. For a psi_norm profile both are taken in sqrt(psi_norm), in which radii and ln f are regular at the axis.
Multiply by -L, the reference length resolved on the same map; a local R_major_surface is splined to the profile grid first.
Express the profile grid in coordinate, and spline the result to at when given – differentiate first, then interpolate.

Defaults

coordinate defaults to profile_coordinate and gradient_coordinate to r_minor, the conventional gyrokinetic choice, when no convention is given. reference_length has no default: an unstated one is refused, so the result never silently becomes a/L. source_quantity = "f" is a hard-coded placeholder name.

Applicability

Machine-independent.

Limitations

The gradient coordinate is splined across the map’s surfaces, so the result is only as smooth as the map. A gradient with respect to a flux label is undefined where that label is stationary in the profile coordinate – at the axis, against a radius – and such a point is refused. The map comes from one slice; profile and equilibrium at different times are the caller’s responsibility, and time only selects the slice.

Provenance

GACODE bound_deriv.f90 and the expro order of operations – differentiate on the grid, then interpolate – as transcribed in vaft.code.gacode.tglf.bound_deriv and verified against locpargen (test/data/gacode/tglf_locpargen_48224).
Issue #551: coordinate, gradient coordinate, reference length and convention are four separate roles.

`radial_coordinate_map`

Machine-independentConvention-sensitive source

radial_coordinate_map(source, time=None)

Every registered radial coordinate on one equilibrium slice’s psi grid.

The eight names of RADIAL_COORDINATES are derived on the slice’s own psi_1d surfaces, each as a vaft.data.equilibrium.DerivedValue with its definition and derivation record, together with the two scalar reference lengths a_minor and R_major_axis [m].

Name	Type	Unit	Description
`source`	EquilibriumData, ODS, GEQDSK, IMAS equilibrium IDS or path	-	Adapted through `vaft.process.equilibrium.as_equilibrium`. Needs the R-Z flux map, the magnetic axis and `psi_1d`; `rho_tor_norm` additionally needs `q`.
`time`	float, optional	s	The slice to use, matched by time within the adaptive tolerance of `vaft.process.atomic.find_time_match_index`. Required when the source holds more than one slice.
Returns
—	RadialCoordinateMap	m	The coordinates, and `a_minor` and `R_major_axis` in metres. An unavailable entry carries its reason; a surface outside the support of the midplane inversion carries NaN; `a_minor` and `R_major_axis` are in metres.

Convention

The midplane is the horizontal line through the magnetic axis, so r_minor is the IMAS (r_outboard - r_inboard)/2. It differs from the contour half-width (max R - min R)/2 that vaft.process.equilibrium.derive_global_descriptors reports as minor_radius, and from R_out - R_axis whenever the surfaces are Shafranov-shifted. Every coordinate is COCOS-independent: each is either a ratio of fluxes with the same sign and scale or a length.

Raises

ValueError No slice at time, time missing for a multi-slice source, or a record whose time contradicts time.

Processing steps · Applicability · Limitations · Provenance

Processing steps

Select the slice by time and adapt it to one EquilibriumData.
psi_norm and rho_pol_norm by normalization (vaft.process.equilibrium.derive_radial_coordinates).
rho_tor_norm from q through vaft.data._derived.rho_tor_profile, unavailable when q cannot support a monotonic toroidal flux.
r_inboard/r_outboard from the flux along Z = Z_axis, inverted on each side of the axis without extrapolation.
r_center, r_minor, then a_minor on the psi_norm = 1 surface and r_minor_norm = r_minor/a_minor.

Applicability

Machine-independent.

Limitations

Surfaces that do not cross the axis height on both sides inside the grid (a branch that turns over before the boundary, an axis outside the grid) are NaN, and a_minor is unavailable when the boundary surface is. rho_tor_norm inherits the trapezoidal q integral and its axis-q sensitivity (#317).

Provenance

The IMAS profiles_1d.r_inboard/r_outboard definition, as vaft.omas.update.update_equilibrium_profiles_1d_radial_coordinates computes it; this keeps that construction and drops its extrapolation (#551).

`radial_coordinate_map_from_arrays`

Machine-independentConvention-sensitive source

radial_coordinate_map_from_arrays(*, r_inboard, r_outboard, psi_norm=None, rho_tor_norm=None, magnetic_axis_r=None, time=None, source='caller-supplied arrays')

A coordinate map from per-surface arrays a code or file already carries.

For a source that is not an equilibrium – an input.gacode profile, a stored profiles_1d – the midplane radii are given rather than solved. The surfaces are taken in the order given, axis first, and the last one is the reference surface of a_minor; that is the LCFS for a complete profile and GACODE’s own a = rmin[-1] for a truncated one [-].

Name	Type	Unit	Description
`r_inboard`	array_like	m	Inboard midplane major radius of each surface.
`r_outboard`	array_like	m	Outboard midplane major radius of each surface.
`psi_norm`	array_like, optional	-	Normalized poloidal flux of each surface; `rho_pol_norm` is derived from it.
`rho_tor_norm`	array_like, optional	-	Normalized toroidal-flux radius of each surface. Refused when it is the `sqrt(psi_norm)` proxy.
`magnetic_axis_r`	float, optional	m	Major radius of the magnetic axis, the `R_major_axis` reference length.
`time`	float, optional	s	The time the arrays describe, recorded only.
`source`	str, optional	-	What the arrays came from, recorded in every provenance entry.
Returns
—	RadialCoordinateMap	-	Every coordinate the arrays determine; the rest unavailable with a reason.

Convention

r_minor = (r_outboard - r_inboard)/2 and r_center their mean, as in radial_coordinate_map; a_minor is r_minor on the last surface, recorded as such in its provenance notes. A rho_tor_norm equal to sqrt(psi_norm) to within vaft.data._derived.RHO_POL_PROXY_TOLERANCE is the proxy older files store under the toroidal label, and is marked unavailable.

Raises

ValueError Arrays of different lengths, fewer than three surfaces, or non-finite midplane radii.

Defaults · Applicability · Limitations · Provenance

Defaults

source is a hard-coded label; every other default is None, meaning “not supplied”, and the coordinates that need it are unavailable rather than guessed.

Applicability

Machine-independent.

Limitations

Nothing checks that the arrays describe nested surfaces beyond the monotonicity profile_gradient demands when it maps between them. The proxy test needs psi_norm; without it a proxy cannot be recognised.

Provenance

GACODE input.gacode: rmin and rmaj are the midplane half-width and centre, and a is rmin at the last grid point (https://gacode.io/input_gacode.html).

`resolve_convention`

Machine-independentConvention-sensitive source

resolve_convention(name, metadata=None)

The explicit gradient coordinate and reference length a code convention stands for.

A convention is a shortcut, not a definition: this returns the two explicit choices of profile_gradient it resolves to, with the documentation it was resolved from, and refuses when the code’s normalization depends on run settings the caller did not pass [-].

Name	Type	Unit	Description
`name`	str	-	One of `CONVENTIONS`: `tglf`, `cgyro`, `gs2`, `gkw`, `gene`.
`metadata`	mapping, optional	-	The run’s own settings. `gs2` needs `irho` and `local_eq` (and `reference_length` when `local_eq` is true); `gkw` needs `geom_type` (and `reference_length` for `s-alpha`); `gene` needs `gradient_coordinate` and `reference_length`. A `reference_length` entry is a mapping with `value` [m], `unit` and `definition`.
Returns
—	dict	-	`convention`, `gradient_coordinate`, `reference_length` (a `REFERENCE_LENGTHS` name), `basis` (the rule applied), `source` (the documentation), and `metadata_used`.

Convention

tglf and cgyro: r_minor and a_minor, the GACODE midplane rmin and its last-surface value – VAFT’s rmin, the crossings at the axis height, which equals GACODE’s centroid-based RMIN_LOC only for surfaces centred at the axis height. gs2: irho = 2 with local_eq = False is r_minor and a_minor; with local_eq = True it is r_minor and the run’s L_ref; irho 1, 3 and 4 are refused. gkw: circ is r_minor and R_major_axis; s-alpha is r_minor and the run’s stated L_ref; miller, fourier, mxh and chease are refused. gene: whatever the run states, never a fixed major radius.

Raises

ValueError An unknown convention, a missing required setting, or a setting whose meaning the documentation does not fix.

Applicability · Limitations · Provenance

Applicability

Machine-independent.

Limitations

GS2 irho = 1 or 3 labels surfaces by a flux ratio while tprim is defined against rho/L_ref, and the documentation does not say how the two combine, so they are refused rather than guessed. GKW’s psi is the half-width between the surface’s own R_max and R_min; it equals the registry’s axis-height r_minor only for a surface symmetric about the axis height, so only the circular geometries, where that holds by construction, are resolved. The GENE manual is not publicly available, so no GENE rule is encoded.

Provenance

GACODE: https://gacode.io/tglf/tglf_list.html, https://gacode.io/cgyro/cgyro_list.html, https://gacode.io/input_gacode.html.
GS2 namelist reference, irho, rhoc, local_eq, tprim and fprim: https://gyrokinetics.gitlab.io/gs2/page/namelists/index.html; the reference length, “half the diameter of the last closed flux surface, measured on the midplane”: https://gyrokinetics.gitlab.io/gs2/page/user_manual/normalisations.html.
GKW manual, doc/manual/practise.tex: psi = (R_max - R_min)/(2 R_ref), R_ref/L_T = -(1/T) dT/dpsi, and R_ref per geometry (https://bitbucket.org/gkw/gkw/src/develop/doc/manual/).
T. Goerler et al., “The global version of the gyrokinetic turbulence code GENE”, J. Comput. Phys. 230 (2011) 7053: a generic reference length and 1/L_T = -d ln T/dx (http://genecode.org/PAPERS_2/YJCPH3630.pdf).

`resolve_reference_length`

Machine-independentConvention-sensitive source

resolve_reference_length(name, coordinate_map, metadata=None)

The reference length a normalized gradient is multiplied by, with its definition.

Turns a REFERENCE_LENGTHS name into a value with a unit, a symbol, a physical definition and the provenance of the equilibrium it came from, so that a/L_T and R/L_T are never reported by label alone [m].

Name	Type	Unit	Description
`name`	str or None	-	`None` (the dimensional gradient), `"a_minor"`, `"R_major_axis"`, `"R_major_surface"` or `"L_ref"`.
`coordinate_map`	RadialCoordinateMap	-	The slice the length is read from.
`metadata`	mapping, optional	m	For `"L_ref"` only: `metadata["reference_length"]` must be a mapping with a positive `value` in metres and a non-empty `definition`; an optional `symbol` and `source` are recorded.
Returns
—	ReferenceLength	m	The resolved length; for `name=None` one with no length at all.

Convention

a_minor is the midplane r_minor of the last closed surface – not the contour half-width (max R - min R)/2 of vaft.process.equilibrium.derive_global_descriptors. R_major_axis is the magnetic-axis major radius, symbol R_0; R_major_surface is r_center on each surface, a local length. L_ref is never assumed: an unknown L_ref does not become a_minor.

Raises

ValueError An unknown name, a length the slice cannot supply (no LCFS crossing, no axis), or "L_ref" without an explicit definition.

Applicability · Limitations · Provenance

Applicability

Machine-independent.

Limitations

L_ref is accepted only in metres; a code that normalizes by a dimensionless or flux-based length must be described by its own preset.

Provenance

Issue #551 sections 5, 6 and 15: a reference length keeps its value, unit, definition and source, and an ambiguous one is refused.

Process reference: profile_gradients

Process reference: profile_gradients

Overview

Functions

`profile_gradient`

Processing steps

Defaults

Applicability

Limitations

Provenance

`radial_coordinate_map`

Processing steps

Applicability

Limitations

Provenance

`radial_coordinate_map_from_arrays`

Defaults

Applicability

Limitations

Provenance

`resolve_convention`

Applicability

Limitations

Provenance

`resolve_reference_length`

Applicability

Limitations

Provenance

results matching ""

No results matching ""

Process reference: profile_gradients

Overview

Functions

Processing steps

Defaults

Applicability

Limitations

Provenance

Processing steps

Applicability

Limitations

Provenance

Defaults

Applicability

Limitations

Provenance

Applicability

Limitations

Provenance

Applicability

Limitations

Provenance

Related resources

API

results matching ""

No results matching ""