tomotok.inversions package

2. tomotok.inversions package#

The heart of the package containing the inversion algorithms.

Two orthogonal class hierarchies compose to form each algorithm.

The first defines what problem is solved. The most general is Inversion, used as a base for the concrete inversion algorithms. The next step in the class hierarchy is RegularisedInversion, which implements the basic regularisation workflow. It is a template class, as it does not implement a method for determining the regularisation parameter or the mathematical basis for inversion. Regularisation parameter selection is injected through dedicated RegularisationSelector objects, while the most specific subclasses implement the actual inversion algorithms.

The second defines how the underlying linear system is solved, represented by the Solver class hierarchy in solvers. The base Solver class defines the common interface for solving linear systems, while concrete implementations such as CholeskySolver or SparseInvSolver provide specific numerical strategies and are injected into an Inversion as a swappable backend.

Currently, the following inversions are implemented:

Biorthogonal basis decomposition (BOB): a method without regularisation based on the Inversion class.
Linear algebraic methods (LAME): methods based on algebraic decomposition of the geometry and regularisation matrices with subsequent series expansion that replaces the solver. These methods are based on the RegularisedInversion class and include the GevAlgebraic method based on generalised eigenvalue decomposition and the SvdAlgebraic method based on singular value decomposition.
Tikhonov regularisation scheme

Regularised inversions can be used directly or in an iterative process with updated regularisation. This is the basis of the Minimum Fisher Regularisation (MFR) method, which is currently the only implemented iterative regularisation method.

class tomotok.inversions.Bob(engine: Solver | None = None, decomposed_matrix: sparray | None = None, basis: sparray | None = None)#

Bases: Inversion

BiOrthogonal Basis decomposition

Attributes:

basisscipy.sparse.spmatrix: \(\mathbf{b}_i\) basis vectors of reconstruction plane
basis_invscipy.sparse.spmatrix: inverse of basis matrix, used for transformation to node basis
decomposed_matrixscipy.sparse.csr_matrix: \(\hat{\mathbf{e}}_i\) decomposed matrix used to transform image into reconstruction plane
normsnumpy.ndarray: node norms used in thresholding

Methods

`__call__`(data[, gmat, basis])	Executes the inversion using
`compute_coordinates`(a)	Computes coordinate matrix for transformation to reconstruction plane.
`decompose`(gmat, basis[, reg_factor])	Decomposes the geometry matrix using basis vectors
`invert`(data)	Uses decomposed matrix to project data into reconstruction plane and then transform to node basis.
`load_decomposition`(floc)	Loads decomposed matrix and basis from an HDF file.
`normalise`([precision])	Computes normalisation factors for decomposition matrix.
`save_decomposition`(floc[, description])	Saves decomposition matrix and basis to hdf file.
`thresholding`(image, c[, precision, conv])	Applies thresholding method to provided image.

decompose(gmat: csr_array | csc_array, basis: csc_array, reg_factor: float = 0)#

Decomposes the geometry matrix using basis vectors

Parameters:

gmatscipy.sparse.csr_array or scipy.sparse.csc_array: geometry/contribution matrix
basissparse array: matrix with decomposition basis vectors
reg_factorfloat, optional: regularisation factor passed to cholesky decomposition determines weight of regularisation by identity matrix relatively to arbitrary matrix maximum value
solver_kwdict: keyword parameters passed to the compute_coefficients method

See also

compute_coefficients: method handling computation of coefficients to see supported solver keywords

compute_coordinates(a: csc_array) → csr_array#: Computes coordinate matrix for transformation to reconstruction plane.

__call__(data: ndarray, gmat: ndarray | csr_array | None = None, basis: ndarray | sparray | None = None) → ndarray#

Executes the inversion using

Checks whether decomposition is available and if not performs decomposition before projection.projects images

Parameters:

datanumpy.ndarray: contains signals or flattened images with shape (#channels, ) or (# channels, # time slices), each column of the input represents one time slice
gmatscipy.sparse.csr_array, optional: geometry matrix, required if decomposition was not calculated or provided in init, by default None, using previously calculated decomposition stored in the class instance
kwdict: keyword parameters passed to decompose method, used only if gmat is provided and decomposition needs to be calculated, otherwise ignored

Returns:

numpy.ndarray: inversion results with shape (# nodes, # time slices)

See also

decompose: method handling decomposition of geometry matrix to see supported keyword parameters

save_decomposition(floc: str | Path, description: str = '') → None#

Saves decomposition matrix and basis to hdf file. Norms are also included if calculated.

Parameters:

flocstr or pathlib.Path: file location with name
descriptionstr, optional: short user description for file identification

load_decomposition(floc: str | Path) → None#

Loads decomposed matrix and basis from an HDF file.

Norms are loaded only if available in the file.

Parameters:

flocstr or pathlib.Path: location of hdf file with saved decomposition

normalise(precision: float = 1e-06) → None#

Computes normalisation factors for decomposition matrix.

Parameters:

precisionfloat, optional: neglects decomposition matrix rows with lower norm, by default 1e-6

thresholding(image: ndarray, c: int, precision: float = 1e-06, conv: float = 1e-09) → ndarray#

Applies thresholding method to provided image.

Parameters:

imagenumpy.ndarray: flattened image, shape (#pixels,)
cint: thresholding sensitivity constant
precisionfloat, optional: normalisation precision, by default 1e-6
convfloat, optional: thresholding convergence limit

Returns:

numpy.ndarray: inversion result with threshold applied, shape (#pixels,)

Raises:

RuntimeError: If thresholding is called before decomposition of geometry matrix

invert(data: ndarray) → ndarray#

Uses decomposed matrix to project data into reconstruction plane and then transform to node basis.

Parameters:

datanumpy.ndarray: contains signals with shape (# channels, # time slices)

Returns:

numpy.ndarray: inversion results with shape (# nodes, # time slices)

class tomotok.inversions.CholeskySolver(check_finite: bool = False)#

Bases: Solver

Scipy based engine using Cholesky decomposition to solve linear systems.

Implementation based on dense matrices, sparse ones are converted to dense.

Methods

solve(a, b)

Sparse matrices are converted to dense arrays before decomposition.

solve(a: ndarray | sparray, b: ndarray | sparray) → ndarray | sparray#: Sparse matrices are converted to dense arrays before decomposition.

class tomotok.inversions.FastSelector(method: str = 'quantile')#

Bases: RegularisationSelector

Fast regularisation parameter selector based on decomposition of a linear algebraic method.

The regularisation parameter is estimated from the values of the diagonal matrix from the decomposition.

Attributes:

method: The method for fast regularisation parameter selection.

Methods

determine(solver[, method])

Finds regularisation parameter using linear estimate based on values of decomposition diagonal.

Notes

This selector is designed exclusively for Algebraic solver instances (SvdAlgebraic, GevAlgebraic) and will raise a TypeError if used with other solver types such as Tikhonov.

VALID_METHODS: tuple[str, ...] = ('mean', 'half', 'median', 'quantile', 'logmean')#

property method: str#: The method for fast regularisation parameter selection.

determine(solver: Algebraic, method: str | None = None) → tuple[float, dict[str, float | str]]#

Finds regularisation parameter using linear estimate based on values of decomposition diagonal.

Parameters:

solverAlgebraic: Solver instance containing decomposition spectrum in solver.s.
methodstr {‘mean’, ‘half’, ‘median’, ‘quantile’, ‘logmean’}, optional: Method for selecting regularisation parameter. If omitted, the selector default is used.

class tomotok.inversions.FixedSelector(value: float)#

Bases: RegularisationSelector

Provides fixed value of regularisation parameter.

Methods

determine([inversion])

Determines value of regularisation parameter using the fixed value.

determine(inversion: RegularisedInversion | None = None) → tuple[float, dict[str, Any]]#

Determines value of regularisation parameter using the fixed value.

Returns:

alphafloat: Regularisation parameter value.
statsdict: A dictionary containing statistics about the inversion process.

class tomotok.inversions.GevAlgebraic(regularisation_selector=None, num: int | None = None)#

Bases: Algebraic

Implements decomposition method using generalised eigenvalue decomposition (GEV) of sparse matrices.

Methods

decompose(gmat, regularisation)

Decomposes geometry and regularisation matrices to form suitable for series expansion.

References

[1]

L.C. Ingesson, “The Mathematics of Some Tomography Algorithms Used at JET,” JET Joint Undertaking, 2000

decompose(gmat: spmatrix | sparray, regularisation: spmatrix | sparray)#

Decomposes geometry and regularisation matrices to form suitable for series expansion.

Parameters:

gmatnumpy.ndarray: geometry matrix with shape (#channels, #nodes), should not be normalised for this method
regularisationnumpy.ndarray: regularisation matrix with shape (#nodes, #nodes)
eigenvaluesint, optional: number of eigenvalues to be computed, by default None, which means number of nodes eigenvalues will be computed

class tomotok.inversions.MinimumFisherRegularisation(inversion: RegularisedInversion | list[RegularisedInversion], termination_method: str = 'max_iter', mfi_num_max: int = 3)#

Bases: object

Implements the Minimum Fisher Regularisation (MFR) method for tomographic inversions.

Uses an inner loop of regularised inversions to iteratively update the regularisation matrix based on the solution from the previous iteration, effectively allowing for a spatially varying regularisation that adapts to the solution.

Attributes:

inversionRegularisedInversion or list of RegularisedInversion: the inversion(s) used in the inner loop of Minimum Fisher Regularisation if a single inversion is provided, it will be used for all MFI iterations, otherwise each inversion is used for the corresponding MFI iteration, the number of inversions must match mfi_num_max
termination_methodstr: the method used to terminate the MFI loop, currently only “max_iter” is supported
mfi_num_maxint: the maximum number of MFI loops before the iteration is stopped

Methods

__call__(data, gmat, derivatives, errors[, ...])

Inversion using the Minimum Fisher Regularisation method.

Inversion using the Minimum Fisher Regularisation method.

Parameters:

datanp.ndarray
gmatscipy.sparse.spmatrix
derivativeslist of scipy.sparse.spmatrix: list of derivative matrices with shape (#nodes, #nodes)
errorsnp.ndarray: error estimates for the data, used in the weighting of the data misfit term in the inversion
derivative_weightslist of floats or list of array-like, optional: anisotropy of derivatives used in the constrution of regularisation matrix, by default None, which corresponds to isotropic regularisation (all weights equal to 1)
mfi_num_maxint, optional: number of minimum Fisher loops before the iteration is stopped, by default 3
initial_guessnp.ndarray, optional: initial guess for the solution, used in the first MFI loop to compute node weights for regularisation matrix, by default None, which corresponds to a uniform initial guess of 1

Returns:

np.ndarray: inversion result
list: list of inversion statistics for each inner loop of the MFR algorithm

class tomotok.inversions.PearsonSelector(bounds: tuple[float, float] = (-30, 10), iter_max: int = 50, tolerance: float = 0.0001)#

Bases: RegularisationSelector

Implements regularisation based on Pearson’s chi-squared test.

Methods

determine(inversion)

Determines value of regularisation parameter using minimisation of Pearson test.

determine(inversion: RegularisedInversion) → tuple[float, dict[str, Any]]#

Determines value of regularisation parameter using minimisation of Pearson test.

The minimisation is done using the minimize_scalar function from scipy.optimize.

Parameters:

boundstuple: The bounds for the regularisation parameter.
iter_maxint: The maximum number of iterations.
tolerancefloat: The tolerance for convergence.

Returns:

sparse.spmatrix: The regularisation matrix.
dict: A dictionary containing statistics about the inversion process.

class tomotok.inversions.SparseInvSolver(sparse: bool = False)#

Bases: Solver

Solver for solving linear systems in BOB decomposition using sparse inverse from scipy.

Methods

solve(a, b)

Solves the linear system \(\mathbf{Ax}=\mathbf{b}\).

solve(a: ndarray | sparray, b: ndarray | sparray) → sparray#

Solves the linear system \(\mathbf{Ax}=\mathbf{b}\).

Parameters:

aarray_like or sparse array: System of equations matrix to be solved
barray_like: right hand side vector or matrix (in case of multiple time slices)

Returns:

numpy.ndarray: The solution of the linear system.

class tomotok.inversions.SvdAlgebraic(regularisation_selector=None, num: int | None = None)#

Bases: Algebraic

Implements decomposition method using singular value decomposition (SVD) of dense matrices.

Methods

decompose(gmat, regularisation)

Prepares matrices used in the series expansion.

References

[1]

Odstrcil et al., “Optimized tomography methods for plasma emissivity reconstruction at the ASDEX Upgrade tokamak,” Rev. Sci. Instrum., 87(12), 123505.

decompose(gmat: ndarray | spmatrix | sparray, regularisation: ndarray | spmatrix | sparray)#

Prepares matrices used in the series expansion.

This method should be implemented in derived class. The matrices are stored in the class attributes u, s, and v.

class tomotok.inversions.Tikhonov(*args, **kwargs)#

Bases: RegularisedInversion

Implements inversion based on Phillips-Tikhonov regularisation scheme.

Methods

invert(alpha)

Inverts the regularised problem using provided regularisation parameter.

invert(alpha: float) → ndarray#

Inverts the regularised problem using provided regularisation parameter.

Uses modified problem formulation and cached inputs to solve the following equation for \(\mathbf{g}\):

\[(\mathbf{T}^T \dcot \mathbf{T} + \alpha \mathbf{H}) \mathbf{g} = \mathbf{G}^T \mathbf{f} \]

Parameters:

alphafloat: regularisation parameter

2.1. Subpackages#

2.1.1. tomotok.inversions.solvers package

2.2. Submodules#

2.3. tomotok.inversions.base module#

class tomotok.inversions.base.Inversion(solver: Solver | None = None)#

Bases: object

Base class for inversion problems.

Attributes:

solver: Algebraic backend solving the system of linear equations.

Methods

__call__(data, *args, **kwargs)

Executes the entire inversion scheme, including input processing.

property solver: Solver | None#: Algebraic backend solving the system of linear equations.

__call__(data: ndarray, *args: Any, **kwargs: Any) → tuple[ndarray, dict[str, Any]]#

Executes the entire inversion scheme, including input processing.

Parameters:

datanp.ndarray: The data to be inverted.
*argstuple: Additional arguments for the solver. Typically, this includes the regularisation matrix and estimated errors.
**kwargsdict: Additional keyword arguments for the solver.

Returns:

np.ndarray: The inversion result
dict[str, Any]: A dictionary containing statistics about the inversion process

class tomotok.inversions.base.RegularisedInversion(solver: Solver | None = None, regularisation_selector: RegularisationSelector | None = None)#

Bases: Inversion

Base class for inversion methods that use regularisation.

Methods

`__call__`(data, gmat, regularisation, errors)	Executes the regularised inversion scheme.
`determine_regularisation`(args, *kwargs)	Determines the value of the regularisation parameter to be used in the inversion.
`invert`(alpha)	Inverts the regularised problem using provided regularisation parameter.

__call__(data: ndarray, gmat: sparray | ndarray, regularisation: sparray | ndarray, errors: float | ndarray) → tuple[ndarray, dict[str, Any]]#

Executes the regularised inversion scheme.

Normalises the data and geometry matrix using the provided error estimates, caches the normalised inputs, determines the regularisation parameter using the provided selector, and finally inverts the problem using the determined regularisation parameter.

Parameters:

datanp.ndarray: The data to be inverted.
gmatsparse.spmatrix or sparse.sparray or np.ndarray: The geometry matrix.
regularisationsparse.spmatrix or sparse.sparray or np.ndarray: The regularisation matrix.
errorsfloat or np.ndarray: The error estimates for the data that are used for normalisation in chi-squared test. If a single float is provided, it is assumed that the error is constant for all data points.

Returns:

np.ndarray: The inversion result.
dict[str, Any]: A dictionary containing statistics about the inversion process.

invert(alpha: float) → ndarray#

Inverts the regularised problem using provided regularisation parameter.

Uses the standard inputs to produce the regularised problem and then uses the solve method to find the solution.

Parameters:

alphafloat: Regularisation parameter value

Returns:

np.ndarray: The inversion result

determine_regularisation(*args: Any, **kwargs: Any) → tuple[float, dict[str, Any]]#

Determines the value of the regularisation parameter to be used in the inversion.

Parameters:

*argstuple: Additional arguments for the solver.
**kwargsdict: Additional keyword arguments for the solver.

Returns:

float: The regularisation parameter value.
dict[str, Any]: A dictionary containing statistics about the inversion process.

class tomotok.inversions.base.RegularisationSelector#

Bases: object

Base class for regularisation parameter selectors.

Methods

determine

determine(inversion: RegularisedInversion) → tuple[float, dict[str, Any]]#

class tomotok.inversions.base.PearsonSelector(bounds: tuple[float, float] = (-30, 10), iter_max: int = 50, tolerance: float = 0.0001)#

Bases: RegularisationSelector

Implements regularisation based on Pearson’s chi-squared test.

Methods

determine(inversion)

Determines value of regularisation parameter using minimisation of Pearson test.

determine(inversion: RegularisedInversion) → tuple[float, dict[str, Any]]#

Determines value of regularisation parameter using minimisation of Pearson test.

The minimisation is done using the minimize_scalar function from scipy.optimize.

Parameters:

boundstuple: The bounds for the regularisation parameter.
iter_maxint: The maximum number of iterations.
tolerancefloat: The tolerance for convergence.

Returns:

sparse.spmatrix: The regularisation matrix.
dict: A dictionary containing statistics about the inversion process.

class tomotok.inversions.base.FixedSelector(value: float)#

Bases: RegularisationSelector

Provides fixed value of regularisation parameter.

Methods

determine([inversion])

Determines value of regularisation parameter using the fixed value.

determine(inversion: RegularisedInversion | None = None) → tuple[float, dict[str, Any]]#

Determines value of regularisation parameter using the fixed value.

Returns:

alphafloat: Regularisation parameter value.
statsdict: A dictionary containing statistics about the inversion process.

2.4. tomotok.inversions.bob module#

Contains inversion class for Biorthogonal Basis Decomposition Algorithm proposed by J. Cavlier. It is a simplified form of wavelet-vaguelette decomposition algorithm by R. Nguyen van Yen

[BOB1]

Jordan Cavalier et al., Nucl. Fusion 59 (2019): 056025

[BOB2]

Nguyen van Yen et al., Nucl. Fusion 52 (2011): 013005

class tomotok.inversions.bob.Bob(engine: Solver | None = None, decomposed_matrix: sparray | None = None, basis: sparray | None = None)#

Bases: Inversion

BiOrthogonal Basis decomposition

Attributes:

basisscipy.sparse.spmatrix: \(\mathbf{b}_i\) basis vectors of reconstruction plane
basis_invscipy.sparse.spmatrix: inverse of basis matrix, used for transformation to node basis
decomposed_matrixscipy.sparse.csr_matrix: \(\hat{\mathbf{e}}_i\) decomposed matrix used to transform image into reconstruction plane
normsnumpy.ndarray: node norms used in thresholding

Methods

`__call__`(data[, gmat, basis])	Executes the inversion using
`compute_coordinates`(a)	Computes coordinate matrix for transformation to reconstruction plane.
`decompose`(gmat, basis[, reg_factor])	Decomposes the geometry matrix using basis vectors
`invert`(data)	Uses decomposed matrix to project data into reconstruction plane and then transform to node basis.
`load_decomposition`(floc)	Loads decomposed matrix and basis from an HDF file.
`normalise`([precision])	Computes normalisation factors for decomposition matrix.
`save_decomposition`(floc[, description])	Saves decomposition matrix and basis to hdf file.
`thresholding`(image, c[, precision, conv])	Applies thresholding method to provided image.

decompose(gmat: csr_array | csc_array, basis: csc_array, reg_factor: float = 0)#

Decomposes the geometry matrix using basis vectors

Parameters:

gmatscipy.sparse.csr_array or scipy.sparse.csc_array: geometry/contribution matrix
basissparse array: matrix with decomposition basis vectors
reg_factorfloat, optional: regularisation factor passed to cholesky decomposition determines weight of regularisation by identity matrix relatively to arbitrary matrix maximum value
solver_kwdict: keyword parameters passed to the compute_coefficients method

See also

compute_coefficients: method handling computation of coefficients to see supported solver keywords

compute_coordinates(a: csc_array) → csr_array#: Computes coordinate matrix for transformation to reconstruction plane.

__call__(data: ndarray, gmat: ndarray | csr_array | None = None, basis: ndarray | sparray | None = None) → ndarray#

Executes the inversion using

Checks whether decomposition is available and if not performs decomposition before projection.projects images

Parameters:

datanumpy.ndarray: contains signals or flattened images with shape (#channels, ) or (# channels, # time slices), each column of the input represents one time slice
gmatscipy.sparse.csr_array, optional: geometry matrix, required if decomposition was not calculated or provided in init, by default None, using previously calculated decomposition stored in the class instance
kwdict: keyword parameters passed to decompose method, used only if gmat is provided and decomposition needs to be calculated, otherwise ignored

Returns:

numpy.ndarray: inversion results with shape (# nodes, # time slices)

See also

decompose: method handling decomposition of geometry matrix to see supported keyword parameters

save_decomposition(floc: str | Path, description: str = '') → None#

Saves decomposition matrix and basis to hdf file. Norms are also included if calculated.

Parameters:

flocstr or pathlib.Path: file location with name
descriptionstr, optional: short user description for file identification

load_decomposition(floc: str | Path) → None#

Loads decomposed matrix and basis from an HDF file.

Norms are loaded only if available in the file.

Parameters:

flocstr or pathlib.Path: location of hdf file with saved decomposition

normalise(precision: float = 1e-06) → None#

Computes normalisation factors for decomposition matrix.

Parameters:

precisionfloat, optional: neglects decomposition matrix rows with lower norm, by default 1e-6

thresholding(image: ndarray, c: int, precision: float = 1e-06, conv: float = 1e-09) → ndarray#

Applies thresholding method to provided image.

Parameters:

imagenumpy.ndarray: flattened image, shape (#pixels,)
cint: thresholding sensitivity constant
precisionfloat, optional: normalisation precision, by default 1e-6
convfloat, optional: thresholding convergence limit

Returns:

numpy.ndarray: inversion result with threshold applied, shape (#pixels,)

Raises:

RuntimeError: If thresholding is called before decomposition of geometry matrix

invert(data: ndarray) → ndarray#

Uses decomposed matrix to project data into reconstruction plane and then transform to node basis.

Parameters:

datanumpy.ndarray: contains signals with shape (# channels, # time slices)

Returns:

numpy.ndarray: inversion results with shape (# nodes, # time slices)

class tomotok.inversions.bob.SparseInvSolver(sparse: bool = False)#

Bases: Solver

Solver for solving linear systems in BOB decomposition using sparse inverse from scipy.

Methods

solve(a, b)

Solves the linear system \(\mathbf{Ax}=\mathbf{b}\).

solve(a: ndarray | sparray, b: ndarray | sparray) → sparray#

Solves the linear system \(\mathbf{Ax}=\mathbf{b}\).

Parameters:

aarray_like or sparse array: System of equations matrix to be solved
barray_like: right hand side vector or matrix (in case of multiple time slices)

Returns:

numpy.ndarray: The solution of the linear system.

2.5. tomotok.inversions.lame module#

Structure of classes is based on algorithms proposed by T. Odstrcil however without sparse optimization

[optimized]

Odstrcil et al., “Optimized tomography methods for plasma emissivity reconstruction at the ASDEX Upgrade tokamak,” Rev. Sci. Instrum., 87(12), 123505.

class tomotok.inversions.lame.Algebraic(regularisation_selector=None, num: int | None = None)#

Bases: RegularisedInversion

A base class for solvers based on algebraic inversion methods.

Unlike RegularisedInversion, this class does not support inversion solvers, but implements the inversions itself. The inversion is performed using series expansion formula utilizing matrix decomposition.

The decomposition is performed in the decompose method, which should be implemented in derived classes.

Attributes:

unumpy.ndarray: decomposition matrix with shape (#channels, #channels)
snumpy.ndarray: diagonal from a decomposition matrix S with shape (#channels, )
vnumpy.ndarray: decomposition matrix with shape (#nodes, #channels)

Methods

`decompose`(gmat, regularisation, args, *kwargs)	Prepares matrices used in the series expansion.
`invert`(alpha[, data, num])	Computes emissivity \(g\) using provided regularisation parameter alpha.

u: ndarray#

s: ndarray#

v: ndarray#

decompose(gmat, regularisation, *args, **kwargs)#

Prepares matrices used in the series expansion.

This method should be implemented in derived class. The matrices are stored in the class attributes u, s, and v.

invert(alpha, data=None, num=None) → ndarray#

Computes emissivity \(g\) using provided regularisation parameter alpha.

The inversion uses decomposed vectors and series expansion to solve the regularised problem. The series expansion is based on the following formula:

\[\mathbf{g}(\alpha) = \sum_{i=1}^{m} \frac{k_{i} (\alpha)}{S_{ii}} \left( \mathbf{U}^T \cdot \mathbf{f} \cdot \tilde{\mathbf{V}} \right) {}_{*i},\]

where \(k_i(\alpha)\) are so called filtering factors computed using following formula

\[k_{i}(\alpha) = \left(1 + \frac{\alpha}{S_{ii}^2} \right)^{-1}\]

Parameters:

alphafloat: regularisation parameter
datanumpy.ndarray, optional: allows to provide data for inversion directly to this method by default None, which means that data provided to the __call__ method will be used
numint, optional: number of columns used for series expansion by default the number specified in the class initialization is used

Returns:

numpy.ndarray: results of inversion

class tomotok.inversions.lame.SvdAlgebraic(regularisation_selector=None, num: int | None = None)#

Bases: Algebraic

Implements decomposition method using singular value decomposition (SVD) of dense matrices.

Methods

decompose(gmat, regularisation)

Prepares matrices used in the series expansion.

References

[1]

Odstrcil et al., “Optimized tomography methods for plasma emissivity reconstruction at the ASDEX Upgrade tokamak,” Rev. Sci. Instrum., 87(12), 123505.

decompose(gmat: ndarray | spmatrix | sparray, regularisation: ndarray | spmatrix | sparray)#

Prepares matrices used in the series expansion.

This method should be implemented in derived class. The matrices are stored in the class attributes u, s, and v.

class tomotok.inversions.lame.GevAlgebraic(regularisation_selector=None, num: int | None = None)#

Bases: Algebraic

Implements decomposition method using generalised eigenvalue decomposition (GEV) of sparse matrices.

Methods

decompose(gmat, regularisation)

Decomposes geometry and regularisation matrices to form suitable for series expansion.

References

[1]

L.C. Ingesson, “The Mathematics of Some Tomography Algorithms Used at JET,” JET Joint Undertaking, 2000

decompose(gmat: spmatrix | sparray, regularisation: spmatrix | sparray)#

Decomposes geometry and regularisation matrices to form suitable for series expansion.

Parameters:

gmatnumpy.ndarray: geometry matrix with shape (#channels, #nodes), should not be normalised for this method
regularisationnumpy.ndarray: regularisation matrix with shape (#nodes, #nodes)
eigenvaluesint, optional: number of eigenvalues to be computed, by default None, which means number of nodes eigenvalues will be computed

class tomotok.inversions.lame.FastSelector(method: str = 'quantile')#

Bases: RegularisationSelector

Fast regularisation parameter selector based on decomposition of a linear algebraic method.

The regularisation parameter is estimated from the values of the diagonal matrix from the decomposition.

Attributes:

method: The method for fast regularisation parameter selection.

Methods

determine(solver[, method])

Finds regularisation parameter using linear estimate based on values of decomposition diagonal.

Notes

This selector is designed exclusively for Algebraic solver instances (SvdAlgebraic, GevAlgebraic) and will raise a TypeError if used with other solver types such as Tikhonov.

VALID_METHODS: tuple[str, ...] = ('mean', 'half', 'median', 'quantile', 'logmean')#

property method: str#: The method for fast regularisation parameter selection.

determine(solver: Algebraic, method: str | None = None) → tuple[float, dict[str, float | str]]#

Finds regularisation parameter using linear estimate based on values of decomposition diagonal.

Parameters:

solverAlgebraic: Solver instance containing decomposition spectrum in solver.s.
methodstr {‘mean’, ‘half’, ‘median’, ‘quantile’, ‘logmean’}, optional: Method for selecting regularisation parameter. If omitted, the selector default is used.

2.6. tomotok.inversions.mfr module#

class tomotok.inversions.mfr.MinimumFisherRegularisation(inversion: RegularisedInversion | list[RegularisedInversion], termination_method: str = 'max_iter', mfi_num_max: int = 3)#

Bases: object

Implements the Minimum Fisher Regularisation (MFR) method for tomographic inversions.

Attributes:

inversionRegularisedInversion or list of RegularisedInversion: the inversion(s) used in the inner loop of Minimum Fisher Regularisation if a single inversion is provided, it will be used for all MFI iterations, otherwise each inversion is used for the corresponding MFI iteration, the number of inversions must match mfi_num_max
termination_methodstr: the method used to terminate the MFI loop, currently only “max_iter” is supported
mfi_num_maxint: the maximum number of MFI loops before the iteration is stopped

Methods

__call__(data, gmat, derivatives, errors[, ...])

Inversion using the Minimum Fisher Regularisation method.

Parameters:

datanp.ndarray
gmatscipy.sparse.spmatrix
derivativeslist of scipy.sparse.spmatrix: list of derivative matrices with shape (#nodes, #nodes)
errorsnp.ndarray: error estimates for the data, used in the weighting of the data misfit term in the inversion
derivative_weightslist of floats or list of array-like, optional: anisotropy of derivatives used in the constrution of regularisation matrix, by default None, which corresponds to isotropic regularisation (all weights equal to 1)
mfi_num_maxint, optional: number of minimum Fisher loops before the iteration is stopped, by default 3
initial_guessnp.ndarray, optional: initial guess for the solution, used in the first MFI loop to compute node weights for regularisation matrix, by default None, which corresponds to a uniform initial guess of 1

Returns:

np.ndarray: inversion result
list: list of inversion statistics for each inner loop of the MFR algorithm

2.7. tomotok.inversions.tikhonov module#

class tomotok.inversions.tikhonov.Tikhonov(*args, **kwargs)#

Bases: RegularisedInversion

Implements inversion based on Phillips-Tikhonov regularisation scheme.

Methods

invert(alpha)

Inverts the regularised problem using provided regularisation parameter.

invert(alpha: float) → ndarray#

Inverts the regularised problem using provided regularisation parameter.

Uses modified problem formulation and cached inputs to solve the following equation for \(\mathbf{g}\):

\[(\mathbf{T}^T \dcot \mathbf{T} + \alpha \mathbf{H}) \mathbf{g} = \mathbf{G}^T \mathbf{f} \]

Parameters:

alphafloat: regularisation parameter

tomotok.inversions package

Contents

2. tomotok.inversions package#

2.1. Subpackages#

2.2. Submodules#

2.3. tomotok.inversions.base module#

2.4. tomotok.inversions.bob module#

2.5. tomotok.inversions.lame module#

2.6. tomotok.inversions.mfr module#

2.7. tomotok.inversions.tikhonov module#