Formula reference: utils
This page is generated from the docstrings of
vaft/formula/utils.py:
9 public functions. The category overview and notation come from the module
docstring; every entry below is what vaft.formula.describe("utils.<name>") prints.
Back to the formula reference index.
Overview
This module provides common utility functions and fitting utilities used throughout the formula module.
Functions
calculate_peaking_factor— Peaking factor, central value over volume average.calculate_poloidal_flux— Poloidal flux per radian from a line integral of $RB_\theta$.calculate_toroidal_flux— Toroidal flux as a sum of $B_\varphi$ over area elements.calculate_volume_weighted_average— Volume-weighted average of a sampled profile.fit_profile— Fit a 1-D profile with a selectable model and evaluate it on a grid.gradient— Derivative $dy/dx$ on a sampled 1-D profile.make_fit_function— Build a 1-D parametric model $f(x; c_0, c_1, \dots)$ for profile fitting.normalize_profile— Linear normalisation of a profile between its axis and boundary values.trapz_integral— Definite integral $\int y\,dx$ by the trapezoidal rule.
calculate_peaking_factor
calculate_peaking_factor(central, volume_avg)
Peaking factor, central value over volume average.
\[\mathrm{PF} = \frac{X(0)}{\langle X\rangle}\]| Parameter | Type | Unit | Description |
|---|---|---|---|
central | float | any | Value on the magnetic axis. |
volume_avg | float | any | Volume average of the same quantity, same unit. |
| Returns | Type | Unit | Description |
|---|---|---|---|
| float | - | Peaking factor. |
Limitations.
No guard against a zero volume average. Tracked in #357.
calculate_poloidal_flux
calculate_poloidal_flux(R, B_theta, l, psi_axis=0.0)
Convention-sensitive.
Poloidal flux per radian from a line integral of $RB_\theta$.
\[\psi(l) = \int_0^{l} R\,B_\theta\,dl' + \psi_a\]| Parameter | Type | Unit | Description |
|---|---|---|---|
R | np.ndarray | m | Major radius along the path. |
B_theta | np.ndarray | T | Poloidal field normal to the path. |
l | np.ndarray | m | Path coordinate, monotonic. |
psi_axis | float, optional | Wb/rad | Offset added to the integral; default 0. |
| Returns | Type | Unit | Description |
|---|---|---|---|
| float | Wb/rad | Flux at the end of the path. |
Convention.
Flux per radian (COCOS 1-8 storage); multiply by $2\pi$ for the IMAS
full-weber flux. Sign follows B_theta and the direction of l.
The physics wrapper is vaft.formula.equilibrium.psi_from_RBtheta.
Numerical notes.
Trapezoidal rule over the whole path; returns the end value only.
calculate_toroidal_flux
calculate_toroidal_flux(B_phi, dA)
Convention-sensitive.
Toroidal flux as a sum of $B_\varphi$ over area elements.
\[\Phi = \sum_i B_{\varphi,i}\,\Delta A_i\]| Parameter | Type | Unit | Description |
|---|---|---|---|
B_phi | np.ndarray | T | Toroidal field on the area elements. |
dA | np.ndarray | m^2 | Area of each element, same shape. |
| Returns | Type | Unit | Description |
|---|---|---|---|
| float | Wb | Toroidal flux. |
Convention.
Full weber (toroidal flux has no per-radian form); sign of $B_\varphi$.
The physics wrapper is vaft.formula.equilibrium.phi_from_Bphi.
Numerical notes.
A Riemann sum with caller-supplied areas, not a quadrature rule; first order in the cell size. Tracked in #358.
calculate_volume_weighted_average
calculate_volume_weighted_average(x, V)
Volume-weighted average of a sampled profile.
\[\langle X\rangle = \frac{\sum_i X_i\,V_i}{\sum_i V_i}\]| Parameter | Type | Unit | Description |
|---|---|---|---|
x | np.ndarray | any | Profile values at each cell. |
V | np.ndarray | m^3 | Volume of each cell, same shape. |
| Returns | Type | Unit | Description |
|---|---|---|---|
| float | any | Volume-weighted average in the unit of |
Limitations.
No guard against a zero total volume. Tracked in #357.
fit_profile
fit_profile(x, y, y_std, x_eval, order=3, uncertainty_option=1, fitting_function='polynomial', gp_kernel=None, gp_anchor=None, n_restarts_optimizer=5)
Fit a 1-D profile with a selectable model and evaluate it on a grid.
Least-squares (scipy.optimize.curve_fit) for the parametric modes,
Gaussian-process regression (sklearn) for 'gp', linear
interpolation for 'linear', a core-polynomial/edge-exponential blend
with a $\tanh$ transition for 'core_poly_edge_exp', and square-root
modes that fit $y^2$ and return $\sqrt{f}$.
| Parameter | Type | Unit | Description |
|---|---|---|---|
x | array-like | any | Data abscissae, 1-D. |
y | array-like | any | Data values. |
y_std | array-like or None | any | Per-point uncertainty, same unit as |
x_eval | array-like | any | Evaluation grid. |
order | int, optional | - | Number of polynomial coefficients (degree |
uncertainty_option | int, optional | - | 1 (default) weights by |
fitting_function | str, optional | str | Model name, default |
gp_kernel | sklearn kernel or None, optional | n/a | Kernel for the GP mode; default constant times RBF. |
gp_anchor | tuple or None, optional | n/a |
|
n_restarts_optimizer | int, optional | - | GP hyperparameter restarts; default 5. |
| Returns | Type | Unit | Description |
|---|---|---|---|
y_eval | np.ndarray | any | Fitted values on |
y_std_eval | np.ndarray | any | Fitted uncertainty; non-zero for the GP mode only. |
fit_function | callable | n/a |
|
coeffs | np.ndarray or None | any | Fitted coefficients; |
Raises.
ValueError
Fewer than two valid points after masking, or an unknown mode.
RuntimeError
When curve_fit does not converge.
Assumptions.
x is a normalised radius on $[0, 1]$ for the constrained modes (they
force zero at $x = 1$); uncertainties are one-sigma and independent.
Limitations.
Non-finite points and non-positive y_std are dropped with a warning.
The 'linear' mode uses numpy.interp, which holds the end values
constant outside the data range (silent constant extrapolation; tracked in
#359). The square-root modes clip negative data to zero before squaring,
biasing the fit where the data cross zero, and report zero uncertainty.
A fit that returns its initial guess unchanged is reported by a warning,
not an exception.
Numerical notes.
The initial guess is scaled to max|y| so raw densities in m^-3 do not
stall the optimiser; maxfev=20000.
Examples.
fit_profile(x, y, y_std, x_eval, fitting_function=’gp’) fit_profile(x, y, y_std, x_eval, order=3, fitting_function=’polynomial’) fit_profile(x, y, y_std, x_eval, fitting_function=’linear’) fit_profile(x, y, y_std, x_eval, order=3, fitting_function=’core_poly_edge_exp’)
gradient
gradient(x, y)
Derivative $dy/dx$ on a sampled 1-D profile.
\[\frac{dy}{dx}\Big|_i \approx \frac{y_{i+1} - y_{i-1}}{x_{i+1} - x_{i-1}}\](second-order central difference on a possibly non-uniform grid).
| Parameter | Type | Unit | Description |
|---|---|---|---|
x | np.ndarray | any | Independent variable, monotonic. |
y | np.ndarray | any | Dependent variable, same length as |
| Returns | Type | Unit | Description |
|---|---|---|---|
| np.ndarray | any | $dy/dx$ at every sample, in units of |
Numerical notes.
Wraps numpy.gradient(y, x): second-order accurate in the interior,
first-order one-sided at the two end points, and noise-amplifying (a
relative noise $\delta$ on y becomes $\delta/\Delta x$ on the
derivative). Needs at least two samples; only the first axis of a 2-D
y is differentiated.
make_fit_function
make_fit_function(mode)
Build a 1-D parametric model $f(x; c_0, c_1, \dots)$ for profile fitting.
\[\begin{aligned} \text{polynomial:}\ & (1-x)\,\textstyle\sum_k c_kx^k & \text{free\_polynomial:}\ & \textstyle\sum_k c_kx^k \\ \text{exponential:}\ & (1-x)\exp\big(\textstyle\sum_k c_kx^k\big) & \text{free\_exponential:}\ & \exp\big(\textstyle\sum_k c_kx^k\big) \end{aligned}\]| Parameter | Type | Unit | Description |
|---|---|---|---|
mode | str | str | Model name, case-insensitive. One of |
| Returns | Type | Unit | Description |
|---|---|---|---|
| callable | any |
|
Raises.
ValueError For an unknown mode.
Assumptions.
x is a normalised radius on $[0, 1]$: the $(1 - x)$ factor forces the
constrained modes to zero at $x = 1$; the exponential modes are strictly
positive and decay monotonically when the polynomial is decreasing.
normalize_profile
normalize_profile(x, x_axis, x_boundary)
Linear normalisation of a profile between its axis and boundary values.
\[x_N = \frac{x - x_{\mathrm{axis}}}{x_{\mathrm{boundary}} - x_{\mathrm{axis}}}\]| Parameter | Type | Unit | Description |
|---|---|---|---|
x | float or np.ndarray | any | Values to normalise. |
x_axis | float | any | Value mapped to 0. |
x_boundary | float | any | Value mapped to 1. |
| Returns | Type | Unit | Description |
|---|---|---|---|
| float or np.ndarray | - | Normalised values, 0 at the axis value and 1 at the boundary value. |
Limitations.
No guard against x_boundary == x_axis: a degenerate equilibrium with
equal axis and boundary flux, which packaged VEST samples do contain,
returns inf/nan. Tracked in #357.
trapz_integral
trapz_integral(x, y)
vaft.formula.trapz_integral resolves to the green copy; reach this one as vaft.formula.utils.trapz_integral.
Definite integral $\int y\,dx$ by the trapezoidal rule.
\[\int y\,dx \approx \sum_i \frac{y_i + y_{i+1}}{2}\,(x_{i+1} - x_i)\]| Parameter | Type | Unit | Description |
|---|---|---|---|
x | np.ndarray | any | Sample abscissae, monotonic. |
y | np.ndarray | any | Integrand at the samples. |
| Returns | Type | Unit | Description |
|---|---|---|---|
| float | any | Integral over the sampled range, in units of |
Numerical notes.
numpy.trapezoid through vaft.compat.trapz_compat; second-order
accurate in the spacing, exact for piecewise-linear integrands, and
sign-reversed for a decreasing x. A same-named helper in
vaft.formula.green shadows this one on the package namespace
(vaft.formula.trapz_integral is the Green’s-function copy).
Refreshing this snapshot
From a checkout of the develop branch, run:
python -m vaft.formula.catalog --output /path/to/vaft-gh/_data/formula_catalog.yml
The snapshot records the SHA-256 of every vaft/formula/*.py source file; documentation
validation compares them when VAFT_REGISTRY_SOURCE points to the corresponding source checkout.
The same text is available offline as vaft.formula.describe("<name>"),
vaft.formula.search("<text>") and vaft.formula.list_formulas(category="<category>").