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

cidx

index

CSR column indices for the stored matrix.

context

eindex

index

Column indices for stored entries of the fixed-width matrix representation.

context

ncols

Positive integer

Number of columns in the stored matrix.

context

nelement

Non-negative integer

Number of stored nonzero entries in each row of the fixed-width matrix representation.

context

nnz

Non-negative integer

Total number of nonzero entries in the CSR matrix.

context

nrows

Positive integer

Number of rows in the stored matrix.

context

ridx

index

CSR row-pointer array for the stored matrix.

context

v

matrix-dependent

CSR nonzero values for the stored matrix.

context

value

matrix-dependent

Stored matrix coefficients in fixed-width row representation.

context

width

Positive integer

Maximum number of stored nonzero entries per row in the stored matrix.

context

field-following projection matrix .bp files

Variable

Units

Description

Context

dl_par

m

Parallel distance along the magnetic field associated with the field-following projection.

context

eindex

index

Column indices for stored entries of the field-following projection matrix.

context

ncols

Positive integer

Number of columns in the field-following projection matrix.

context

nelement

Non-negative integer

Number of stored nonzero entries in each row of the field-following projection matrix.

context

nrows

Positive integer

Number of rows in the field-following projection matrix.

context

value

dimensionless

Interpolation weights for stored entries of the field-following projection matrix.

context

width

Positive integer

Maximum number of stored nonzero entries per row in the field-following projection matrix.

context

xgc.grad_rz.bp

Variable

Units

Description

Context

basis

dimensionless

Per-node poloidal derivative basis: 0 selects unit grad(psi) and its counter-clockwise perpendicular; 1 selects cylindrical R and Z.

context

eindex_r

Integer index

One-based input mesh-node column indices for the first poloidal directional-derivative matrix; only nelement_r entries per row are valid.

context

eindex_z

Integer index

One-based input mesh-node column indices for the second poloidal directional-derivative matrix; only nelement_z entries per row are valid.

context

m_r

Positive integer

Number of output mesh-node rows in the first poloidal directional-derivative matrix.

context

m_z

Positive integer

Number of output mesh-node rows in the second poloidal directional-derivative matrix.

context

n_r

Positive integer

Number of input mesh-node columns in the first poloidal directional-derivative matrix.

context

n_z

Positive integer

Number of input mesh-node columns in the second poloidal directional-derivative matrix.

context

nelement_r

Non-negative integer

Valid entry count for each row of the first poloidal directional-derivative matrix; ignore slots at or beyond this count.

context

nelement_z

Non-negative integer

Valid entry count for each row of the second poloidal directional-derivative matrix; ignore slots at or beyond this count.

context

value_r

m^-1

First poloidal directional-derivative coefficients: R derivative where basis=1, derivative along the unit grad(psi) direction where basis=0.

context

value_z

m^-1

Second poloidal directional-derivative coefficients: Z derivative where basis=1, counter-clockwise poloidal unit-direction derivative where basis=0.

context

w_r

Positive integer

Maximum stored entries per row of the first poloidal directional-derivative matrix.

context

w_z

Positive integer

Maximum stored entries per row of the second poloidal directional-derivative matrix.

context