3. tomotok.regularisations package

3.1. Submodules

3.2. tomotok.regularisations.derivatives module

Handles computation of derivative matrices used for regularization in MFR algorithm.

tomotok.regularisations.derivatives.all_direction_derivative_matrices(grid: RegularGrid, scheme: str = 'forward', mask: ndarray | None = None, compensate_edges: bool = True, compensation_fraction: float = 1) → list[csc_array]

Creates derivative matrices for all 8 directions using provided scheme.

Parameters:

gridRegularGrid

schemestr, optional

Selects numerical scheme to be used. Can be ‘forward’, ‘backward’, ‘central’, ‘second’. The default value is ‘forward’.

masknumpy.ndarray, optional

A bool mask determining nodes of regular grid to keep, by default None. Rows and columns representing False nodes are removed from derivative matrix. If mask is None, all rows and columns are returned.

compensate_edgesbool, optional

Subtracts from diagonal so that sum of each row is zero, by default False.

compensation_fractionfloat, optional

Fraction of diagonal elements to be subtracted, by default 1.

Returns:

list of scipy.sparse.csc_matrix

List of derivative matrices for all 8 directions with following order: right, top-right, top, top-left, left, bottom-left, bottom, bottom-right

tomotok.regularisations.derivatives.standard_anisotropic_derivative_matrices(grid: RegularGrid, flux: ndarray, mask: ndarray | None = None, compensate_edges: bool = True, compensation_fraction: float = 1) → list[csc_array]

Creates isotropic derivative matrices for parallel and perpendicular directions.

Parameters:

gridRegularGrid

fluxesnumpy.ndarray

Matrix with magnetic flux values, shape has to match grid

schemestr, optional

Selects numerical scheme to be used. Can be ‘forward’, ‘backward’, ‘central’, ‘second’. The default value is ‘forward’.

masknumpy.ndarray, optional

A bool mask determining nodes of regular grid to keep, by default None. Rows and columns representing False nodes are removed from derivative matrix. If mask is None, all rows and columns are returned.

compensate_edgesbool, optional

Subtracts from diagonal so that sum of each row is zero, by default False.

compensation_fractionfloat, optional

Fraction of row sum to subtract from diagonal, by default 1.

Returns:

list of scipy.sparse.csc_matrix

List of derivative matrices for parallel and perpendicular directions in following order: parallel counter clockwise, perpendicular counter clockwise, parallel clockwise, perpendicular clockwise

tomotok.regularisations.derivatives.reduce_matrix(mat: sparray, mask: ndarray) → sparray

Creates reduced matrix by cutting out rows and columns representing unwanted nodes.

Parameters:

matscipy.sparse.sparray

matrix to be reduced

masknumpy.ndarray of bool

mask array for selecting desired nodes, True for nodes to keep must be 1D or 2D, size must match grid size (# rows or # columns)

Returns:

scipy.sparse.sparray

reduced matrix

tomotok.regularisations.derivatives.compensate_matrix(mat: sparray, compensation_fraction: float = 1) → sparray

Subtracts from diagonal so that sum of each row is zero.

Parameters:

matscipy.sparse.sparray

matrix to be compensated

compensation_fractionfloat, optional

Fraction of row sum to subtract from diagonal, by default 1. 1 corresponds to full compensation where row sum should be zero. However, the compensation may cause small negative values due to rounding errors. Using slightly smaller value (e.g. 0.9999) can prevent this issue while still effectively acting as a zero row sum constraint.

Returns:

scipy.sparse.sparray

compensated matrix

tomotok.regularisations.derivatives.derivative_matrix(grid: RegularGrid, direction: str, scheme: str = 'forward', mask: ndarray | None = None, compensate_edges: bool = True, compensation_fraction: float = 1) → csc_array

Creates a derivative matrix using numerical differences

Parameters:

gridRegularGrid

directionstr

Determines one of the 8 possible directions that can be used. Specified using the over edge neighbor ‘right’, ‘top’, ‘left’, ‘bottom’ or combination over corner directions like ‘top-left’

schemestr, optional

Selects numerical scheme to be used. Can be ‘forward’, ‘backward’, ‘central’, ‘second’. The default value is ‘forward’.

masknumpy.ndarray, optional

A bool mask determining nodes of regular grid to keep, by default None. Rows and columns representing False nodes are removed from derivative matrix. If mask is None, all rows and columns are returned.

compensate_edgesbool, optional

Subtracts from diagonal so that sum of each row is zero, by default False.

compensation_fractionfloat, optional

Fraction of row sum to subtract from diagonal, by default 1.

Returns:

scipy.sparse.csc_array

See also

all_direction_derivative_matrices

creates derivative matrices for all 8 directions

reduce_matrix

reduces matrix by cutting out rows and columns representing unwanted nodes

compensate_matrix

subtracts from diagonal so that sum of each row is zero or nearly zero

tomotok.regularisations.derivatives.laplace_matrix(grid: RegularGrid, mask: ndarray | None = None, compensate_edges: bool = True, compensation_fraction: float = 1.0, diagonals: bool = True) → csc_array

Creates sparse laplace matrix.

Parameters:

gridRegularGrid

masknumpy.ndarray, optional

A bool mask determining nodes of regular grid to keep, by default None. Rows and columns representing False nodes are removed from derivative matrix. If mask is None, all rows and columns are returned.

compensate_edgesbool, optional

Subtracts from diagonal so that sum of each row is zero, by default False.

diagonalsbool, optional

Selects whether to use diagonal neighbors in matrix, by default True.

Returns:

scipy.sparse.csc_matrix

tomotok.regularisations.derivatives.anisotropic_derivative_matrix(grid: RegularGrid, flux: ndarray, direction: str = 'parallel', scheme: str = 'forward', mask: ndarray | None = None, compensate_edges: bool = True, compensation_fraction: float = 1.0) → csc_array

Computes derivative matrix with varying direction based on flux surfaces shapes.

Uses direction of gradient to distribute contribution to two neighboring nodes. These are designated as previous and next as the direction rotates. The weight of next node is equal to remnant of direction angle division by 1. The weight of previous node is equal to 1 minus the weight of next node.

Parameters:

gridRegularGrid

Reconstruction grid definition

fluxnumpy.ndarray

Matrix with magnetic flux values, shape has to match grid

masknumpy.ndarray of bool, optional

A bool mask determining nodes of regular grid to keep, by default None.

directionstr, optional

Direction of derivative computation, by default ‘parallel’

schemestr, optional

derivative scheme used, by default ‘forward’

• forward is in the direction of positive angle i.e. counter clockwise

• backward is in the direction of negative angle i.e. clockwise

Returns:

scipy.sparse.csc_matrix

See also

standard_anisotropic_derivative_matrices

creates derivative matrices for parallel and perpendicular directions

reduce_matrix

reduces matrix by cutting out rows and columns representing unwanted nodes

compensate_matrix

subtracts from diagonal so that sum of each row is zero or nearly zero

3.3. tomotok.regularisations.matrices module

tomotok.regularisations.matrices.weighted_squares(matrices: sparray | list[sparray], matrix_weights: float | list[float] | None = None, node_weights: float | list[float] | None = None) → csc_matrix

Computes regularisation matrix as a weighted sum of squares of the input matrices.

The weights can be based on a previous results creating an iterative non-linear regularisation scheme. For example, using inverse of the solution from the previous iteration is used in the MFR algorithm.

Parameters:

matricessparse.sparray or list of sparse.sparray

sparse matrices with numerical derivative operators with shape (#nodes, #nodes)

matrix_weightsfloat or list of floats, optional

weights assigned to individual matrices by default all weights are equal if list of floats, the matrix weights are specified for each matrix if list of arrays, the matrix weights are specified for each node of each matrix

node_weightsfloat or list of floats, optional

weights assigned to individual nodes, default is 1 for all nodes can be used to create a non-linear regularisation matrix

Returns:

sparse.csc_array

regularisation matrix with shape (#nodes, #nodes)