tools.GradientCoefficients

class bartorch.tools.GradientCoefficients

Bases:

Spherical-harmonic coefficients of a gradient coil’s departure from linearity.

alpha[axis, n, m] and beta[axis, n, m] are the cosine and sine coefficients of order n and degree m for the scanner X, Y and Z gradients, shape (3, order + 1, order + 1). The arrays are read-only and excluded from repr, so that a table is not written to a log.

Parameters:

• basis ({"unnormalized", "normalized"}) – "unnormalized": GE .dat solid harmonics of the position in centimetres. "normalized": Siemens .grad harmonics, normalized as HCP gradunwarp normalizes them, of the position relative to reference_radius_mm.

• alpha (array_like) – Cosine and sine coefficients.

• beta (array_like) – Cosine and sine coefficients.

• reference_radius_mm (float, default=None) – Radius R0 of a normalized expansion, in millimetres.

• source_name (str, default=None) – Label of the table’s source, such as a file name.

Examples

>>> table = "0.25 m = R0\n  1 A( 1, 0)  1.0  x\n  2 A( 3, 0)  -0.025  x\n"
>>> coefficients = GradientCoefficients.from_file(table)
>>> coefficients.reference_radius_mm, coefficients.max_order
(250.0, 3)

property max_order

Largest represented spherical-harmonic order.

property mapping_sign

Sign of the evaluated field in the map from corrected to acquired positions.

classmethod from_file()

Parse a coefficient table.

Parameters:

• source (str, bytes, pathlib.Path, file object or CoefficientAccessor) – A path, the table’s own text or bytes (a string containing a line break, or naming no file, is taken as text), an open file, or an accessor.

• coefficient_format ({"auto", "dat", "grad", "coef"}, default='auto') – GE .dat (SCALE{X,Y,Z}{n} entries), Siemens .grad (A(n, m) and B(n, m) entries and R0), or a neutral Alpha_x n m value table. "auto" reads .dat when a SCALE entry is present and .grad or .coef otherwise.

• reference_radius_mm (float, default=None) – R0 for a normalized table that does not state it.

Return type:

GradientCoefficients

Raises:

ValueError – If the table has no entries, a .dat table has a nonzero DELTA, an unsupported GRADWARPTYPE or a nonzero tenth order, or a normalized table has no reference radius.