Matrix Outputs
This page is generated from in-code XGC I/O metadata by utils/python/documentation/document_outputs.py.
Sparse matrix, gradient-operator and field-following projection matrix outputs. Known matrix files written through these paths include xgc.grad_rz.bp, xgc.cnv_to_surf.bp, xgc.cnv_from_surf.bp, xgc.smooth_pol.bp, xgc.hyp_vis_rad.bp, xgc.ff_1dp_fwd.bp, xgc.ff_1dp_rev.bp, xgc.ff_hdp_fwd.bp, xgc.ff_hdp_rev.bp, xgc.ff_mdp_fwd.bp, and xgc.ff_mdp_rev.bp.
Gradient operators: xgc.grad_rz.bp
This static product is written by C++ on rank zero during initialization, unless
MINIMAL_OUTPUT is defined. It preserves the historical Fortran variable
names, types, one-based column indices and BP array order. Axisymmetric meshes
use the same operators on every plane. For non-axisymmetric/stellarator meshes,
the file contains only rank zero’s right-plane operators: use
xgc.mesh.bp:rplane_rz[0,:,:] and rplane_nd_connect_list[0,:,:].
It does not contain operators for all toroidal planes.
For each suffix s=r,z, m_s is the row count, n_s the column count,
w_s the storage capacity per row, and nelement_s[i] the number of valid
slots in row i. Python/C readers see value_s and eindex_s as
[mesh_node,matrix_slot]. Construct an m_s by n_s sparse matrix using
only valid slots; subtract one from their column indices. Padding has no
meaning and may contain negative index sentinels. For example:
import numpy as np
def apply_operator(value, eindex, nelement, f):
derivative = np.zeros(len(nelement))
for i, count in enumerate(nelement):
derivative[i] = value[i, :count] @ f[eindex[i, :count] - 1]
return derivative
Apply the _r and _z matrices separately to the same scalar nodal field.
Their coefficients have units m^-1 and give positive directional derivatives;
electric field requires the additional minus sign in E=-grad(phi).
basis[i]=1 means R and Z derivatives at that output node.
basis[i]=0 means derivatives along the unit grad(psi) direction and its
counter-clockwise perpendicular in the R/Z plane, not derivatives with
respect to poloidal flux or angle. With equilibrium derivatives psi_R,psi_Z,
the unit vectors are e_psi=(psi_R,psi_Z)/|grad psi| and
e_theta=(-psi_Z,psi_R)/|grad psi|; rotate those two directional components
to obtain cylindrical R/Z components. The unit vectors themselves are not
stored in this product. Plot derivative values on the matching triangular mesh
with nodal linear interpolation; the sparse storage slots are not mesh fields.
The matrices include XGC’s boundary and local-basis fallback choices. Applying them reproduces the stored discrete operator, which need not equal a generic triangle-gradient implementation. These numerical operators have no IMAS hint or diagnostic time context.
matrix .bp files
Variable |
Units |
Description |
Context |
|---|---|---|---|
|
index |
CSR column indices for the stored matrix. |
|
|
index |
Column indices for stored entries of the fixed-width matrix representation. |
|
|
Positive integer |
Number of columns in the stored matrix. |
|
|
Non-negative integer |
Number of stored nonzero entries in each row of the fixed-width matrix representation. |
|
|
Non-negative integer |
Total number of nonzero entries in the CSR matrix. |
|
|
Positive integer |
Number of rows in the stored matrix. |
|
|
index |
CSR row-pointer array for the stored matrix. |
|
|
matrix-dependent |
CSR nonzero values for the stored matrix. |
|
|
matrix-dependent |
Stored matrix coefficients in fixed-width row representation. |
|
|
Positive integer |
Maximum number of stored nonzero entries per row in the stored matrix. |
field-following projection matrix .bp files
Variable |
Units |
Description |
Context |
|---|---|---|---|
|
m |
Parallel distance along the magnetic field associated with the field-following projection. |
|
|
index |
Column indices for stored entries of the field-following projection matrix. |
|
|
Positive integer |
Number of columns in the field-following projection matrix. |
|
|
Non-negative integer |
Number of stored nonzero entries in each row of the field-following projection matrix. |
|
|
Positive integer |
Number of rows in the field-following projection matrix. |
|
|
dimensionless |
Interpolation weights for stored entries of the field-following projection matrix. |
|
|
Positive integer |
Maximum number of stored nonzero entries per row in the field-following projection matrix. |
xgc.grad_rz.bp
Variable |
Units |
Description |
Context |
|---|---|---|---|
|
dimensionless |
Per-node poloidal derivative basis: 0 selects unit grad(psi) and its counter-clockwise perpendicular; 1 selects cylindrical R and Z. |
|
|
Integer index |
One-based input mesh-node column indices for the first poloidal directional-derivative matrix; only nelement_r entries per row are valid. |
|
|
Integer index |
One-based input mesh-node column indices for the second poloidal directional-derivative matrix; only nelement_z entries per row are valid. |
|
|
Positive integer |
Number of output mesh-node rows in the first poloidal directional-derivative matrix. |
|
|
Positive integer |
Number of output mesh-node rows in the second poloidal directional-derivative matrix. |
|
|
Positive integer |
Number of input mesh-node columns in the first poloidal directional-derivative matrix. |
|
|
Positive integer |
Number of input mesh-node columns in the second poloidal directional-derivative matrix. |
|
|
Non-negative integer |
Valid entry count for each row of the first poloidal directional-derivative matrix; ignore slots at or beyond this count. |
|
|
Non-negative integer |
Valid entry count for each row of the second poloidal directional-derivative matrix; ignore slots at or beyond this count. |
|
|
m^-1 |
First poloidal directional-derivative coefficients: R derivative where basis=1, derivative along the unit grad(psi) direction where basis=0. |
|
|
m^-1 |
Second poloidal directional-derivative coefficients: Z derivative where basis=1, counter-clockwise poloidal unit-direction derivative where basis=0. |
|
|
Positive integer |
Maximum stored entries per row of the first poloidal directional-derivative matrix. |
|
|
Positive integer |
Maximum stored entries per row of the second poloidal directional-derivative matrix. |