ModeBasis

class hcipy.mode_basis.ModeBasis(transformation_matrix, grid=None)

Bases: object

A linear basis of modes.

Modes can be stored both in a dense or sparse format. A sparse mode basis reduces memory usage when modes are localized and contain a lot of zeros. Projection onto and linear combinations of modes are done seamlessly, regardless of the sparsity of the mode basis. If a grid is available, linear combinations automatically become Fields.

You can create your own mode bases by supplying a list of modes, or a transformation matrix that transforms from mode coefficients to the mode. You can also use a number of built-in mode bases in HCIPy.

Parameters:

transformation_matrixarray_like or list of array_like: The transformation matrix of the mode basis or a list of modes.
gridGrid or None: The grid on which the modes are defined.

Attributes Summary

`is_dense`	If the mode basis is dense.
`is_sparse`	If the mode basis is sparse.
`num_modes`	The number of modes in the ModeBasis.
`orthogonalized`	Get an orthogonalized version of this ModeBasis.
`transformation_matrix`	The transformation matrix of this mode basis.

Methods Summary

`append`(mode)	Append mode to this mode basis.
`coefficients_for`(b[, dampening_factor])	Calculate the coefficients on this mode basis in a least squares fashion.
`extend`(modes)	Extend the mode basis with modes.
`from_dict`(tree)	Make a ModeBasis from a dictionary, previously created by to_dict().
`linear_combination`(coefficients)	Calculate a linear combination using this mode basis.
`to_dense`([copy])	Convert the mode basis to a dense mode basis.
`to_dict`()	Convert the object to a dictionary for serialization.
`to_sparse`([copy])	Convert the mode basis to a sparse mode basis.

Attributes Documentation

is_dense: If the mode basis is dense.

is_sparse: If the mode basis is sparse.

num_modes: The number of modes in the ModeBasis.

orthogonalized

Get an orthogonalized version of this ModeBasis.

The resulting ModeBasis spans the same vector space, but each mode is orthogonal to all others. In general the resulting ModeBasis is dense, so no distinction is made between sparse and dense mode bases in this function. This function will always return a dense mode basis.

Returns:

ModeBasis: A mode basis with orthogonalized modes.

Raises:

NotImplementedError: If the mode basis is a mode basis containing non-scalar fields.

transformation_matrix: The transformation matrix of this mode basis.

Methods Documentation

append(mode)

Append mode to this mode basis.

Parameters:

modearray_like or Field: The mode to add to the ModeBasis

coefficients_for(b, dampening_factor=0)

Calculate the coefficients on this mode basis in a least squares fashion.

The vector b is projection onto the mode basis in a least squares fashion. This means that the const function

\[J(c) = |b - A x|^2_2 + |\lambda x|^2_2\]

is minimized, where \(x\) are the coefficients, and \(\lambda\) is the dampening factor.

If this projection needs to be done repeatedly, you may be better off calculating the inverse of the transformation matrix directly and left-multiplying that with your vector, rather than using a least squares estimation every time.

Parameters:

barray_like or Field: The vector for which to calculate the coefficients.
dampening_factorscalar: The Tikhonov dampening factor used for the least squares procedure.

Returns:

array_like: The coefficients that correspond to the vector b.

extend(modes)

Extend the mode basis with modes.

Parameters:

modeslist or array_like or ModeBasis: The modes to add to the ModeBasis.

classmethod from_dict(tree)

Make a ModeBasis from a dictionary, previously created by to_dict().

Parameters:

treedictionary: The dictionary from which to make a new ModeBasis object.

Returns:

ModeBasis: The created object.

Raises:

ValueError: If the dictionary is not formatted correctly.

linear_combination(coefficients)

Calculate a linear combination using this mode basis.

Parameters:

coefficientsarray_like or list: The coefficients of the linear combinations.

Returns:

array_like or Field: The calculated linear combination.

to_dense(copy=False)

Convert the mode basis to a dense mode basis.

Parameters:

copyboolean: Whether to force a copy or not. A copy is always made if the current ModeBasis is not dense.

Returns:

ModeBasis: The densified ModeBasis.

to_dict()

Convert the object to a dictionary for serialization.

Returns:

dictionary: The created dictionary.

to_sparse(copy=False)

Convert the mode basis to a sparse mode basis.

Parameters:

copyboolean: Whether to force a copy or not. A copy is always made if the current ModeBasis is not sparse.

Returns:

ModeBasis: The sparsified ModeBasis.

Raises:

TypeError: If this ModeBasis cannot be sparsified.