finesse.knm.matrix module

Scattering matrix data structure and associated functions for constructing different formats of this object.

class finesse.knm.matrix.KnmMatrix(const int[, : :1] modes, comp_name='', kdir='')

Bases: object

Higher-Order-Mode scattering matrix container. Essentially a wrapper around a 2D NumPy array with methods for conveniently accessing specific couplings and plotting the matrix as a color-mesh.

The underlying numpy.ndarray object can be accessed via the data attribute.

Construction of KnmMatrix objects should, generally, not be performed manually. Objects of this type are the return type of the general scattering matrix computing routines, see make_scatter_matrix(). To make a KnmMatrix object from a pre-existing matrix of complex coupling coefficients, use KnmMatrix.from_buffer().

Parameters

modesarray-like

A 2D array, or memory-view to the array, of the mode indices associated with the scattering matrix.

comp_namestr, optional; default: “”

Name of the component associated with the matrix (if any).

kdirstr, optional; default: “”

A string representing the coupling direction of the matrix, e.g. “11” for a reflection at the first surface of a mirror-like optic.

data

static from_buffer(ndarray[double complex,ndim=2], const int[:, ::1] modes, **kwargs)

Construct a KnmMatrix object from a pre-existing 2D array buffer.

This method is useful for creating KnmMatrix objects from scattering matrix data which have been computed elsewhere. One of the most common use-cases is when using KnmDetector objects in “matrix-mode”; see the documentation of this class for an example.

Parameters

buffernumpy.ndarray

A 2D array of complex values corresponding to the underlying buffer of scattering matrix data.

modesarray-like

A 2D array, or memory-view to the array, of the mode indices associated with the scattering matrix.

kwargskeyword arguments, optional

Additional args to pass to constructor of KnmMatrix.

Returns

kmatKnmMatrix

The KnmMatrix wrapper around the array buffer.

get(self, key, default=None)

Retrieves the coupling coefficient corresponding to the key, returning default if this key is invalid.

Parameters

keystr or integer sequence

A string of the format:

• “nm->n’m’” or,

• “nmn’m’”,

where n, m, n’ and m’ are all convertible to integers

Or an integer sequence of:

• length 2 – i.e. an i, j pair corresponding to the field indices.

• or length 4 – i.e. a n1, m1, n2, m2 coupling.

defaultAny, optional

The default value returned if the key is invalid.

Returns

outcomplex

The value of the coupling coefficient associated with key.

homs

modes

name

static of_zeros(const int[, : :1] modes, **kwargs)

Constuct a KnmMatrix where each element is (complex) zero.

Parameters

modesarray-like

A 2D array, or memory-view to the array, of the mode indices associated with the scattering matrix.

kwargskeyword arguments, optional

Additional args to pass to constructor of KnmMatrix.

Returns

kmatKnmMatrix

The KnmMatrix object consisting of a matrix of zeroes.

plot(self, mode='amplitude', log=False, deg=False, cmap=None, show=True, filename=None)

Plots the coupling coefficient matrix as a color-mesh.

Parameters

modestr, optional

Specifier for which attribute of the coupling coefficient to plot. This can be one of ‘amplitude’, ‘phase’, ‘real’, ‘imag’, ‘amplitude/phase’, or ‘real/imag’. Defaults to ‘amplitude’.

logbool, optional

Whether the log of the data should be plotted. This is only used for ‘amplitude’ and is ignored for all other options. Defaults to False.

degbool, optional

Whether the data should be plotted in degrees or radians. This is only used for ‘phase’ and is ignored for all other options. Defaults to False.

cmapstr, matplotlib colormap, optional

Colormap to use. Defaults to the default colormap loaded in matplotlib.rcParams.

showbool, optional

Whether to show plot or not. Defaults to true.

filenamestr, path, optional

The name of a file to save the figure to. Defaults to None so that no file is saved.

Returns

figmatplotlib figure

A handle to the figure.

finesse.knm.matrix.make_unscaled_X_scatter_knm_matrix(int[, : :1] modes)

This method returns an unscaled KnmMatrix object that represents a distortion from the integral:

\[\iint_{\infty} U_{nm}(x,y) \; x \; U_{n'm'}(x,y) \, dx \, dy \]

This essentially scatters modes by mode index \(n \pm 1\). There are some scalings proportional to \(w(x)*exp(\pm 1j*\textrm{Gouy}(z))\) missing as these can be applied as single scalars in addition to this matrix if needed.

Returns

KnmMatrix

finesse.knm.matrix.make_unscaled_Y_scatter_knm_matrix(int[, : :1] modes)

This method returns an unscaled KnmMatrix object that represents a distortion from the integral:

\[\iint_{\infty} U_{nm}(x,y) \; y \; U_{n'm'}(x,y) \, dx \, dy \]

This essentially scatters modes by mode index \(m \pm 1\). There are some scalings proportional to \(w(x)*exp(\pm 1j*\textrm{Gouy}(z))\) missing as these can be applied as single scalars in addition to this matrix if needed.

Returns

KnmMatrix

finesse.knm.matrix.reverse_gouy_phases(x_gouy1, y_gouy1, x_gouy2, y_gouy2, knm_matrix)

Adjust the phase of all coupling coefficients in the matrix knm_mat with respect to the Gouy phases.

This is required for \(k_{nmn'm'}\) calculations because in Finesse the Gouy phase is added explicitly to the amplitude coefficients in a Space / Space whereas the coupling coefficients are derived using a formula in which the Gouy phase resides in the equation for the spatial profile.