finesse.detectors package

Subpackages

finesse.detectors.compute package

Submodules

finesse.detectors.amplitude_detector module

Single-frequency amplitude and phase detector.

class finesse.detectors.amplitude_detector.AmplitudeDetector(*args, **kwargs)

Bases: MaskedDetector

Represents an amplitude detector which calculates the amplitude and phase of light fields at one frequency.

Parameters

namestr: Name of newly created detector.
nodeNode: Node to read output from.
ffloat: Frequency of light to detect (in Hz).
nint, optional; default: None: Tangential mode index to probe. Defaults to None such that all fields of the given frequency are summed.
mint, optional; default: None: Sagittal mode index to probe. Defaults to None such that all fields of the given frequency are summed.

property f: f : float Frequency of light to detect (in Hz).

property m

The sagittal mode index to probe.

Getter:: Returns the sagittal mode index being probed (read-only).

property n

The tangential mode index to probe.

Getter:: Returns the tangential mode index being probed (read-only).

finesse.detectors.astigmatism_detector module

class finesse.detectors.astigmatism_detector.AstigmatismDetector(*args, **kwargs)

Bases: Detector

Detector for astigmatism figure-of-merit at a given node.

The computed quantity is given via one minus finesse.gaussian.BeamParam.overlap().

Parameters

namestr: Name of the detector.
nodeOpticalNode: Node to compute astigmatism at.

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

finesse.detectors.bpdetector module

class finesse.detectors.bpdetector.BeamPropertyDetector(*args, **kwargs)

Bases: Detector

Probe for detecting the properties of a beam at a given node.

The valid values for prop are:

"w": beam size at node [metres],

"w0": waist size as measured at node [metres],

"z": distance to the waist from node [metres],

"zr": the Rayleigh range [metres],

"gouy": the Gouy phase of the beam at node [radians],

"div": divergence angle of the beam at node [radians],

"rc": radius of curvature of wavefront at node [metres],

"s": curvature of wavefront at node [1 / metres],

"q": beam parameter at node.

Note

The "gouy" target property here detects the Gouy phase as derived from the beam parameter \(q\) at the specified node, i.e:

\[\psi = \arctan{\left(\frac{\myRe{q}}{\myIm{q}}\right)}.\]

It does not compute any Gouy phase accumulation. Use Gouy to detect the accumulated Gouy phase over a path.

Parameters

namestr: Name of newly created detector.
nodeOpticalNode: Node to read output from.
propstr or BeamProperty: The property of the beam to detect. See above for options.
directionstr, optional; default: ‘x’: Plane to detect in - ‘x’ for tangential, ‘y’ for sagittal.
q_as_bpbool, optional; default: False: If detecting q, should the detector output return BeamParam object instead of just a complex number.

property detecting

The property of the beam which is being detected.

Getter:: Returns the detected property (read-only).

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

property prop

finesse.detectors.camera module

Detectors for capturing images, slices and single pixels of a beam.

The camera types are split into two categories (CCDs and ComplexCameras) based on the mathematical implementation shown in finesse.detectors.compute.camera.

class finesse.detectors.camera.CCD(*args, **kwargs)

Bases: CCDCamera, Image

Camera for measuring the intensity of a beam, \(I = |E(x,y)|^2\), where the unscaled x and y coordinate arrays used are finesse.detectors.camera.Image.xdata and finesse.detectors.camera.Image.ydata, respectively. Note that this is just the intensity at the points (x,y), not an integrated power over some finite pixel size.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
xlimsequence or scalar: Limits of the x-dimension of the image. If a single number is given then this will be computed as \(x_{\mathrm{lim}} = [-|x|, +|x|]\).
ylimsequence or scalar: Limits of the y-dimension of the image. If a single number is given then this will be computed as \(y_{\mathrm{lim}} = [-|y|, +|y|]\).
nptsint: Number of points in both axes.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property npts

Number of pixels in each axis.

Getter:: Returns the number of pixels in each axis.
Setter:: Sets the number of pixels in each axis.

class finesse.detectors.camera.CCDCamera(*args, **kwargs)

Bases: Camera, ABC

Abstract type for cameras which detect pixel intensity.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

class finesse.detectors.camera.CCDPixel(*args, **kwargs)

Bases: CCDCamera, Pixel

Camera for measuring the intensity of a beam, \(I = |E(x,y)|^2\), at a single point. Where the unscaled x and y coordinate used is finesse.detectors.camera.Pixel.xdata and finesse.detectors.camera.Pixel.ydata, respectively. Note that this is just the intensity at (x,y), not an integrated power over some finite pixel dimension.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
xscalar, optional; default: 0: The x co-ordinate of the pixel.
yscalar, optional; default: 0: The y co-ordinate of the pixel.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

class finesse.detectors.camera.CCDScanLine(*args, **kwargs)

Bases: CCDCamera, ScanLine

Camera for measuring the intensity of a beam, \(I = |E(x,y)|^2\), along a 1D slice. Where the unscaled x and y coordinate arrays used are finesse.detectors.camera.ScanLine.xdata and finesse.detectors.camera.ScanLine.ydata, respectively. Note that this is just the intensity at the points (x,y), not an integrated power over some finite pixel size.

The ScanLine.direction (i.e. axis of slice) is determined from which of xlim or ylim is specified.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
nptsint: Number of points in slice axis.
xscalar or None; default: None: The x coordinate of the slice. If ylim is given and this is not specified then defaults to zero. If xlim is given and this is also specified then it is ignored.
yscalar or None; default: None: The y coordinate of the slice. If xlim is given and this is not specified then defaults to zero. If ylim is given and this is also specified then it is ignored.
xlimscalar or size two sequence; default: None: The limits of the x-axis scan lines. A single number gives \(x_{\mathrm{axis}} \in [-|x|, +|x|]\), or a tuple of size two gives \(x_{\mathrm{axis}} \in [x[0], x[1]]\).
ylimscalar or array-like; default: None: The limits of the y-axis scan lines. A single number gives \(y_{\mathrm{axis}} \in [-|y|, +|y|]\), or a tuple of size two gives \(y_{\mathrm{axis}} \in [y[0], y[1]]\).
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property npts

Number of pixels in the scanning axis.

Getter:: Returns the number of pixels in the slice axis.
Setter:: Sets the number of pixels in the slice axis.

class finesse.detectors.camera.Camera(*args, **kwargs)

Bases: MaskedDetector, ABC

Base camera class.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
w0_scaledbool: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.
dtypenumpy.dtype or str: The data-type of the pixels.
shapetuple: Dimensions of the camera image.

property needs_trace: Flag indicating whether the detector requires beam traces.

property scaled_xdata

Coordinate data in the x-axis scaled to metres.

Equivalent to xdata if Camera.w0_scaled is False. Otherwise this is xdata multiplied by the tangential waist size as measured at the node.

property scaled_ydata

Coordinate data in the y-axis scaled to metres.

Equivalent to ydata if Camera.w0_scaled is False. Otherwise this is ydata multiplied by the sagittal waist size as measured at the node.

property w0_scaled

Flag for whether the x and y co-ordinates have been scaled by the waist-size of the beam parameter at the detection node.

Getter:: Returns True if x and y have been scaled by the beam waist, False otherwise.

class finesse.detectors.camera.ComplexCamera(*args, **kwargs)

Bases: Camera, ABC

Abstract type for cameras which detect pixel amplitude and phase.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
fscalar, optional; default: 0: Field frequency offset from the carrier to detect.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property f: f : scalar, optional; default: 0 Field frequency offset from the carrier to detect.

class finesse.detectors.camera.FieldCamera(*args, **kwargs)

Bases: ComplexCamera, Image

Camera for detecting the full image of the beam in terms of amplitude and phase.

Get the unscaled x and y coordinate data via finesse.detectors.camera.Image.xdata and finesse.detectors.camera.Image.ydata, respectively.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
xlimsequence or scalar: Limits of the x-dimension of the image. If a single number is given then this will be computed as \(x_{\mathrm{lim}} = [-|x|, +|x|]\).
ylimsequence or scalar: Limits of the y-dimension of the image. If a single number is given then this will be computed as \(y_{\mathrm{lim}} = [-|y|, +|y|]\).
nptsint: Number of points in both axes.
fscalar, optional; default: 0: Field frequency offset from the carrier to detect.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property f: f : scalar, optional; default: 0 Field frequency offset from the carrier to detect.

property npts

Number of pixels in each axis.

Getter:: Returns the number of pixels in each axis.
Setter:: Sets the number of pixels in each axis.

class finesse.detectors.camera.FieldPixel(*args, **kwargs)

Bases: ComplexCamera, Pixel

Camera for detecting a single pixel of the beam in terms of the amplitude and phase.

Get the unscaled x and y coordinate data via finesse.detectors.camera.Pixel.xdata and finesse.detectors.camera.Pixel.ydata, respectively.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
xscalar, optional; default: 0: The x co-ordinate of the pixel.
yscalar, optional; default: 0: The y co-ordinate of the pixel.
fscalar, optional; default: 0: Field frequency offset from the carrier to detect.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property f: f : scalar, optional; default: 0 Field frequency offset from the carrier to detect.

class finesse.detectors.camera.FieldScanLine(*args, **kwargs)

Bases: ComplexCamera, ScanLine

Camera for detecting a slice of the beam in terms of amplitude and phase.

The ScanLine.direction (i.e. axis of slice) is determined from which of xlim or ylim is specified.

Get the unscaled x and y coordinate data via finesse.detectors.camera.ScanLine.xdata and finesse.detectors.camera.ScanLine.ydata, respectively.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
nptsint: Number of points in slice axis.
xscalar or None; default: None: The x coordinate of the slice. If ylim is given and this is not specified then defaults to zero. If xlim is given and this is also specified then it is ignored.
yscalar or None; default: None: The y coordinate of the slice. If xlim is given and this is not specified then defaults to zero. If ylim is given and this is also specified then it is ignored.
xlimscalar or size two sequence; default: None: The limits of the x-axis scan lines. A single number gives \(x_{\mathrm{axis}} \in [-|x|, +|x|]\), or a tuple of size two gives \(x_{\mathrm{axis}} \in [x[0], x[1]]\).
ylimscalar or array-like; default: None: The limits of the y-axis scan lines. A single number gives \(y_{\mathrm{axis}} \in [-|y|, +|y|]\), or a tuple of size two gives \(y_{\mathrm{axis}} \in [y[0], y[1]]\).
fscalar, optional; default: 0: Field frequency offset from the carrier to detect.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property f: f : scalar, optional; default: 0 Field frequency offset from the carrier to detect.

property npts

Number of pixels in the scanning axis.

Getter:: Returns the number of pixels in the slice axis.
Setter:: Sets the number of pixels in the slice axis.

class finesse.detectors.camera.Image(xlim, ylim, npts, dtype)

Bases: object

Data structure representation of an image.

Parameters

xlimsequence or scalar: Limits of the x-dimension of the image. If a single number is given then this will be computed as \(x_{\mathrm{lim}} = [-|x|, +|x|]\).
ylimsequence or scalar: Limits of the y-dimension of the image. If a single number is given then this will be computed as \(y_{\mathrm{lim}} = [-|y|, +|y|]\).
nptsint: Number of points for both the x and y axes.
dtypestr or dtype: Data type of the image to pass to NumPy for array creation.

at(x=None, y=None)

Retrieves a slice or single pixel of the output image.

Parameters

xscalar, optional: Value indicating where to take a y-slice of the image or, if used in conjunction with y, which pixel to return. Defaults to None.
yscalar, optional: Value indicating where to take a x-slice of the image or, if used in conjunction with x, which pixel to return. Defaults to None.
magnitudebool, optional: Returns the amplitude of the detected field if True. Otherwise returns the full complex description.

Returns

outnumpy.ndarray or float: Either a slice of the image or a single pixel at the specified co-ordinates.

property npts

Number of pixels in each axis.

Getter:: Returns the number of pixels in each axis.
Setter:: Sets the number of pixels in each axis.

property resolution

The resolution of the image.

Currently this is always square (i.e. number of points in both axes always equal).

Getter:: Returns the tuple (xpts, ypts).

property xdata

The array of data points for the x-axis.

Getter:: Returns a copy of the numpy.ndarray containing the x-axis points.

property xlim

The limits of the x coordinate data.

Getter:: Returns a tuple of (xmin, xmax).
Setter:: Sets the x-axis limits.

property ydata

The array of data points for the y-axis.

Getter:: Returns a copy of the numpy.ndarray containing the y-axis points.

property ylim

The limits of the y coordinate data.

Getter:: Returns a tuple of (ymin, ymax).
Setter:: Sets the y-axis limits.

class finesse.detectors.camera.Pixel(x, y, dtype)

Bases: object

Data structure representation of a pixel of an image.

Parameters

xscalar: The x co-ordinate of the pixel.
yscalar: The y co-ordinate of the pixel.
dtypestr or dtype: Data type of the pixel.

property x

The x coordinate of the pixel.

Getter:: Returns the x coordinate of the pixel.
Setter:: Sets the x coordinate of the pixel.

property xdata

Equivalent to Pixel.x.

Getter:: Returns the x coordinate of the pixel. Read-only version.

property y

The y coordinate of the pixel.

Getter:: Returns the y coordinate of the pixel.
Setter:: Sets the y coordinate of the pixel.

property ydata

Equivalent to Pixel.y.

Getter:: Returns the y coordinate of the pixel. Read-only version.

class finesse.detectors.camera.ScanLine(npts, dtype, x=None, y=None, xlim=None, ylim=None)

Bases: object

Data structure representation of a slice of an image.

Parameters

xscalar or None: The x coordinate of the slice.
yscalar or None: The y coordinate of the slice.
xlimscalar or size two sequence: The limits of the x-axis scan lines. A single number gives \(x_{\mathrm{axis}} \in [-|x|, +|x|]\), or a tuple of size two gives \(x_{\mathrm{axis}} \in [x[0], x[1]]\).
ylimscalar or array-like: The limits of the y-axis scan lines. A single number gives \(y_{\mathrm{axis}} \in [-|y|, +|y|]\), or a tuple of size two gives \(y_{\mathrm{axis}} \in [y[0], y[1]]\).
nptsint: Number of points in slice axis.
dtypestr or dtype: Data type of the slice to pass to NumPy for array creation.

property direction

The slice axis - i.e. ‘x’ for x-axis, ‘y’ for y-axis.

Getter:: Returns a string determining the slice axis (read-only).

property npts

Number of pixels in the scanning axis.

Getter:: Returns the number of pixels in the slice axis.
Setter:: Sets the number of pixels in the slice axis.

property x

The x co-ordinate of the slice.

If ScanLine.direction is ‘x’ then this will return None.

Getter:: Returns the x coordinate of the slice.
Setter:: Sets the x coordinate of the slice.

property xdata

The numeric value(s) of the x coordinate.

If ScanLine.direction is ‘x’ then this will be a copy of the array of values, otherwise it is a single value equivalent to ScanLine.x.

Getter:: The x coordinate value(s). Read-only.

property xlim

The limits of the slice in the x-axis.

If ScanLine.direction is ‘y’ then this will return None.

Getter:: Returns a tuple of (xmin, xmax).
Setter:: Sets the x-axis limits.

property y

The y co-ordinate of the slice.

If ScanLine.direction is ‘y’ then this will return None.

Getter:: Returns the y coordinate of the slice.
Setter:: Sets the y coordinate of the slice.

property ydata

The numeric value(s) of the y coordinate.

If ScanLine.direction is ‘y’ then this will be a copy of the array of values, otherwise it is a single value equivalent to ScanLine.y.

Getter:: The y coordinate value(s). Read-only.

property ylim

The limits of the slice in the y-axis.

If ScanLine.direction is ‘x’ then this will return None.

Getter:: Returns a tuple of (ymin, ymax).
Setter:: Sets the y-axis limits.

finesse.detectors.cavity_detector module

class finesse.detectors.cavity_detector.CavityPropertyDetector(*args, **kwargs)

Bases: Detector

Probe for detecting the properties of a cavity.

The valid values for prop are:

"length" or "l": round-trip cavity length [metres],

"loss": round-trip loss as a fraction,

"finesse": the cavity finesse,

"fsr": free spectral range [Hz],

"fwhm": full-width at half-maximum (i.e. linewidth) [Hz],

"pole": cavity pole frequency [Hz],

"tau": photon storage time [s],

"abcd": round-trip ABCD matrix,

"g" or "stability": stability as g-factor,

"gouy": round-trip Gouy phase [deg],

"modesep": mode-separation frequency [Hz],

"resolution": cavity resolution [Hz],

"q": eigenmode,

"w": beam size at the cavity source node [metres],

"w0": waist size [metres],

"z": distance to the waist from the cavity source node [metres],

"zr": the Rayleigh range of the eigenmode [metres],

"div": divergence angle of cavity mode [radians],

"rc": radius of curvature of wavefront at cavity source node [metres],

"s": curvature of wavefront at cavity source node [1 / metres].

Parameters

namestr: Name of newly created cavity property detector.
cavitystr or Cavity: The cavity to probe. If the name is provided then the CavityPropertyDetector.cavity attribute will point to the corresponding Cavity object when adding this detector to a Model instance.
propstr or CavityProperty: Property of the cavity to probe. See above for options.
directionstr, optional; default: ‘x’: Plane to detect in.
q_as_bpbool, optional; default: False: If detecting q, should the detector output return BeamParam object instead of just a complex number.

property cavity: The cavity instance being probed.

property detecting

The property of the cavity which is being detected.

Getter:: Returns the detected property (read-only).

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

property prop

finesse.detectors.field_detector module

Single-frequency array of complex amplitudes detector.

class finesse.detectors.field_detector.FDWorkspace(owner, sim): Bases: DetectorWorkspace

class finesse.detectors.field_detector.FieldDetector(*args, **kwargs)

Bases: Detector

Outputs an array of the higher order modes amplitudes at a particular node and frequency. The mode ordering is given by Model.homs. Plane wave models will output a single element array.

This detector can only be used on optical nodes.

Parameters

namestr: Name of newly created detector.
nodeNode: Node to read output from.
ffloat: Frequency of light to detect (in Hz).

Examples

>>> import finesse
>>> model = finesse.Model()
>>> model.parse('''
    laser l1
    gauss g1 l1.p1.o w0=1m z=0
    m m1 R=1 T=0 xbeta=1e-9 ybeta=3e-8
    link(l1, m1)
    modes(maxtem=1)
    fd fd1 m1.p1.o 0
''')
>>> out = model.run('noxaxis()')
>>> print(out['fd1'])
array([
    0.99999998+0.00000000e+00j,
    0+1.77157478e-04j,
    0+5.90524926e-06j
])

property f: f : float Frequency of light to detect (in Hz).

finesse.detectors.general module

Top-level objects which specific detectors should inherit from.

class finesse.detectors.general.Detector(*args, **kwargs)

Bases: ABC, ModelElement

Abstract representation of a component that produces a numerical output.

User detector classes should subclass this class. The simulation will then generate a dictionary of output values.

Parameters

namestr: Name of newly created detector.
nodeNode or Port: Node to read output from. If a port is given, it must have one node, so that is is unambiguous which node to use.
dtypetype, optional: The numpy datatype for which this output result will be stored in.
unitstr, optional: A human readable unit for the output. E.g. W, m, m/rtHz.

property dtype

property dtype_shape

property dtype_size

Size of the output in terms of number of elements.

This is typically unity as most detectors return a single value via their output functions.

Equivalent to the product of Detector.dtype_shape.

property label

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

property node

The nodes this detector observes.

Getter:: Returns the detected node.

property output_information

property unit

class finesse.detectors.general.MaskedDetector(*args, **kwargs)

Bases: Detector, ABC

An abstract class from which detector types which can have mode masks derive.

Any detector object which calculates quantities involving loops over the modes of a model should inherit from this — allowing masks to be applied to mode patterns via the methods of this class. Examples of detectors which should derive from MaskedDetector are power-detectors, amplitude-detectors and cameras.

add_to_mask(modes)

Inserts the specified mode indices into the detector mask.

Parameters

modessequence, str: A single mode index pair or an iterable of mode indices. Each element must unpack to two integer convertible values.

property has_mask

Whether the detector has a mask applied to it.

Simply checks to see if the MaskedDetector.mask length is non-zero.

property mask

An array of HOMs to mask from the output. Any contributions from these modes will be zeroed when calculating the detector output.

Getter:: Returns the array of masked indices.
Setter:: Sets the masked indices. See MaskedDetector.select_mask() for the options available.

remove_from_mask(modes)

Removes the specified mode indices from the detector mask.

Parameters

modessequence, str: A single mode index pair or an iterable of mode indices. Each element must unpack to two integer convertible values.

select_mask(modes=None, maxtem=None, exclude=None)

Select the HOM indices to include in the mask.

The mode-selecting examples in Selecting the modes to model may be referred to for typical patterns when using this method, as the same concepts apply equally to making detector masks (equivalent code under-the-hood).

Parameters

modessequence, str, optional; default: None

Identifier for the mode indices to generate. This can be:

An iterable of mode indices, where each element in the iterable must unpack to two integer convertible values.
A string identifying the type of modes to include, must be one of “even”, “odd”, “x” or “y”.

By default this is None, such that, for example, this method can be used to select a mask of all modes up to a given maxtem.

maxtemint, optional; default: None

Optional maximum mode order. If not specified then the maxtem used internally will be equal to the maximum mode order of the associated model.

Note that this argument is ignored if modes is an iterable of mode indices.

excludesequence, str, optional; default: None

A mode, or iterable of modes, to exclude from the selected pattern. For example, if one calls select_mask("even", exclude="00") then the mask will be an array of all even-order HOM indices excluding the 00 mode.

Examples

See Selecting the modes to model.

class finesse.detectors.general.NoiseDetector(noise_type)

Bases: object

property noise_type

class finesse.detectors.general.SymbolDetector(*args, **kwargs)

Bases: Detector

get_output(*args)

finesse.detectors.gouy module

Accumulated Gouy phase detector.

class finesse.detectors.gouy.Gouy(*args, **kwargs)

Bases: Detector

Detector to measure the accumulated gouy phase across a sequence of spaces.

This detector can operate in one of two modes, depending upon args given:

automatically determine the spaces through an arbitrary path by specifying the from_node and to_node arguments,

OR provide a pre-determined sequence of spaces (or their names) as positional arguments.

Whichever option is chosen, this detector will compute the same fundamental quantity; that is the sum of the Gouy phases accumulated over each space (in degrees).

Parameters

namestr: Name of newly created gouy detector.
*argssequence: A sequence of spaces or space names.
from_nodenode-like: An OpticalNode instance, or a data type which can be converted to an optical node.
to_nodenode-like: An OpticalNode instance, or a data type which can be converted to an optical node.
via_nodenode-like: An OpticalNode instance, or a data type which can be converted to an optical node.
directionstr: Plane to detect in - ‘x’ for tangential, ‘y’ for sagittal. Defaults to ‘x’.

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

property spaces: The spaces that this detector will calculated the accumulated Gouy phase over.

finesse.detectors.knmdetector module

Direct probing of coupling coefficients.

class finesse.detectors.knmdetector.KnmDetector(*args, **kwargs)

Bases: Detector

Direct probe of coupling coefficients at a component.

This detector has several “modes” which depend upon the values given for the mode indices n1, m1 and n2, m2. If:

all of n1, m1, n2, m2 are specified then the detector will output a single complex coefficient corresponding to the coupling from (n1, m1) -> (n2, m2),

just n1 and m1 are specified then it will output a vector of complex coefficients corresponding to each coupling from (n1, m1) -> (n, m) for each mode (n, m) in the model,

only n2 and m2 are specified then it will output a vector of complex coefficients corresponding to each coupling from (n, m) -> (n2, m2) for each mode (n, m) in the model,

none of n1, m1, n2, m2 are specified then the detector outputs the full matrix of complex coupling coefficients.

Hint

When using this detector in “full-matrix” mode (i.e. by not giving the values for any of the mode indices), it can be useful to combine the output with the KnmMatrix object to obtain a more convenient representation of the scattering matrix.

An example of this is shown below, where the output of a detector of this type is wrapped using KnmMatrix.from_buffer().

import finesse
finesse.configure(plotting=True)
from finesse.knm.matrix import KnmMatrix

IFO = finesse.Model()
IFO.parse('''
l L0 P=1
link(L0, ITM)
m ITM R=0.99 T=0.01 Rc=-2090 xbeta=0.3u
s LARM ITM.p2 ETM.p1 L=4k
m ETM R=0.99 T=0.01 Rc=2090

cav ARM ITM.p2
modes(x, maxtem=6)

knmd K_itm_r ITM 22
''')

out = IFO.run('noxaxis()')
# Make a KnmMatrix wrapper around the output from the detector
k_mat = KnmMatrix.from_buffer(out["K_itm_r"], IFO.homs)
# Now we can perform operations such as plotting the scattering matrix
k_mat.plot(cmap="bone");

See Computing arbitrary scattering matrices for some examples on the utility that the KnmMatrix object provides.

Parameters

namestr

Name of newly created KnmDetector.

compConnector

A component which can scatter modes.

couplingstr

Coupling direction string, e.g. “11” for coupling coefficients on reflection from the front surface of a mirror.

n1, m1, n2, m2: int or None

From (n1, m1) and To (n2, m2) mode indices of the coupling coefficient(s) to retrieve.

See above for the options.

finesse.detectors.math_detector module

class finesse.detectors.math_detector.MathDetector(*args, **kwargs)

Bases: Detector

A detector that performs some math operation and outputs the result.

Parameters

namestr: Name of detector
expressionSymbol: Symbolic expression to evaluate as the detectors output
dtypenumpy.dtype, optional: The expected data type when evaluating expression. Defaults to “O”.
dtype_shapetuple: The expected array shape when evaluating expression. Defaults to an empty tuple. This must be an empty tuple if dtype is a scalar type or “O”.
unitstr: The unit of the output for plotting. Defaults to “arb.”
labelstr or None: How to label the axis when plotting this detector. Defaults to None.

Notes

If dtype does not match the result when expression is evaluated the values will be silently cast to dtype. dtype_shape is used to create a numpy array in which the results are written, if this doesn’t match this should raise some Exception when running a simulation, but this is not guaranteed. If one isn’t sure of what type expression will produce, one should leave the default “O”, the generic numpy type object, and convert the data after inspecting the result. When using the default type, some functions like Solution.plot might not be able to convert the data to an appropiate type internally, in which case they cannot be used.

Examples

KatScript example:

l l1 P=1 pd P l1.p1.o fd E l1.p1.o f=l1.f bp qx l1.p1.o q x modes(maxtem=3) gauss g1 l1.p1.o w0=1m z=0

mathd Y1 P*2 mathd Y2 P**2 mathd Y3 cos(1+P**2) mathd Y4 E*2 mathd Y5 qx+1

property expression

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

set_expression(expression, dtype='O', dtype_shape=(), unit='arb.', label=None)

class finesse.detectors.math_detector.MathDetectorWorkspace(owner, sim)

Bases: DetectorWorkspace

MathDetectorWorkspace.

finesse.detectors.mismatch_detector module

Detectors for calculating mode mismatches in an optical configuration.

class finesse.detectors.mismatch_detector.ModeMismatchDetector(*args, **kwargs)

Bases: Detector

Detector for mode mismatch figure-of-merit for a specified node coupling.

The computed quantity is given in finesse.gaussian.BeamParam.mismatch() where \(q_1\) is the input beam parameter at node1 propagated via the associated ABCD matrix to node2, and \(q_2\) is the beam parameter at node2.

As mode mismatches cannot occur over spaces in Finesse, node1 must be an input node and node2 must be an output node.

Parameters

namestr: Name of the detector.
node1OpticalNode or Port: Input node or port. If a Port instance is given then this node will be the input node of that port. Note that this node cannot be an output node.
node2OpticalNode or Port: Output node or port. If a Port instance is given then this node will be the output node of that port. Note that this node cannot be an input node.
directionstr, optional; default: “x”: Plane of computation, defaults to “x” for the tangential plane. Changing to “y” will compute the mode mismatch in the sagittal plane.
percentbool, optional; default: True: Whether to calculate the mode mismatch as a fraction (default behaviour) or a percentage.

property component

The component at which the mode mismatch is calculated.

Getter:: Returns the associated component (read-only).

property direction

The plane in which the mode mismatch is calculated.

A value of “x” represents the tangential plane, whilst “y” gives the sagittal plane.

Getter:: Returns the plane of computation as a string representation (read-only).

property in_node

Input node.

Getter:: Returns the input node (read-only).

property in_percent

Flag indicating whether the mismatch is computed as a percentage.

Getter:: Returns the percentage flag.
Setter:: Sets the percentage flag.

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

property out_node

Output node.

Getter:: Returns the output node (read-only).

finesse.detectors.motion_detector module

Motion amplitude and phase detector.

class finesse.detectors.motion_detector.MotionDetector(*args, **kwargs)

Bases: Detector

Represents a motion detector which calculates the amplitude and phase of surface motion.

Parameters

namestr: Name of newly created motion detector.
nodeNode: Node to read output from.

class finesse.detectors.motion_detector.MotionDetectorWorkspace(owner, sim): Bases: DetectorWorkspace

finesse.detectors.optimal_q module

Single-frequency array of complex amplitudes detector.

class finesse.detectors.optimal_q.OptimalQ(*args, **kwargs)

Bases: Detector

This detector tries to compute an optimal beam parameter (\(q\)) for a specified optical frequency at a node.

Output of this detector into an array solution will be a tuple of BeamParam in each transverse direction, (qx, qy). If the optimisation process fails beam parameter objects will NaN values will be returned.

Parameters

namestr: Name of the detector
node[str | finesse.components.node]: Node name or object to put this detector at
ffloat: Frequency component tro compute the optimal beam parameter for.
fix_spot_sizebool, optional: When True the optimised will keep the current spot size at the node fixed and just optimise the curvature.
astigmaticbool, optional: When True qx and qy will be optimised separately
accuracyfloat, optional: Approximate mismatch accuracy to try and compute the optimised beam parameter to. mismatch(q_actual, q_optimal) < accuracy
directionstr, optional: Return either both or just the x or y modes

Notes

This method uses the finesse.gaussian.optimise_HG00_q() or finesse.gaussian.optimise_HG00_q_scipy() for optimising the HG mode amplitudes at the node and frequency requested. This particular method finds a new set of {qx, qy} values which maximise the HG00 mode content, whilst reducing the HG20 and HG02 mode content.

Failure

If the optical field being optimised does not have a HG00 like appearance then. For example, trying to optimise the shape of an RF sideband field inside a cavity that it is not resonant in.

property astigmatic: astigmatic : bool, optional When True qx and qy will be optimised separately

property direction

Sets the output of the detector.

If both then both qx and qy are returned. if x or y are used then only the required one is returned.

property f: f : float Frequency component tro compute the optimal beam parameter for.

property fix_spot_size: fix_spot_size : bool, optional When True the optimised will keep the current spot size at the node fixed and just optimise the curvature.

class finesse.detectors.optimal_q.OptimalQWorkspace(owner, sim)

Bases: DetectorWorkspace

Workspace for calculating the output of the optimial beamparameter (q) detectors.

Parameters

ownerOptimalQ: Detector which owns this workspace
sim: Simulation this workspace should be created for

finesse.detectors.pdtypes module

Dictionaries storing the generic beat-coefficients for simulating segmented photoiodes.

Builtin pdtypes: * SINGLE - single element photodiode * XSPLIT - measuring horizontal/yaw motions * YSPLIT - measuring vertical/pitch motions

Use the function construct_segment_beat_matrix to convert these dictionary definitions into a dense or sparse CSR matrix for using in calculations.

finesse.detectors.pdtypes.construct_segment_beat_matrix(mode_index_map, beats_dict, sparse_output=False, assert_hermitian=True)

Takes a pdtype definition dict and converts it into a matrix suitable to use with a KnmMatrix.

Parameters

mode_index_mapdict[(n,m), index]: Dictionary of mode indices and index
beats_dictstr, pdtype style dict: A dictionary in the pdtype style describing a particular segmentation type for a sensor. If a string is given it will try and get a builtin pdtype dict
sparse_outputbool, optional: Return a sparse CSR matrix object rather than a dense one
assert_hermitianbool, optional: If true then the generated matrix from the pdtype definition must be Hermitian

Returns

2D Complex matrix of size (N, N) with N=len(mode_index_map) or a CSRMatrix if requested.

Examples

>>> pdtypes.construct_segment_beat_matrix(model.mode_index_map, pdtype.YSPLIT)
array([[0.        +0.j, 0.79788456+0.j, 0.        +0.j],
       [0.79788456+0.j, 0.        +0.j, 0.        +0.j],
       [0.        +0.j, 0.        +0.j, 0.        +0.j]])

Another example showing how to manually compute the segmented photodiode beat signal using this matrix output whilst misaligning some optic.

>>> import finesse
>>> import matplotlib.pyplot as plt
>>> finesse.init_plotting()
>>> # Simple laser reflecting from a steering mirror
>>> model = finesse.script.parse('''
... l l1 P=1
... bs bs1 R=1 T=0
... nothing n1
... link(l1, bs1, 10, n1)
... fd E n1.p1.i f=0
... gauss g1 l1.p1.o w=1m Rc=inf
... modes(maxtem=3)
... ''')
>>> # Run the model and extract the matrix of mode amplitudes
>>> sol = model.run("xaxis(bs1.xbeta, lin, 0, 1e-6, 4)")
>>> E = sol['E']
>>> # Get the beat matrix for a quadrant photodiode
>>> M = finesse.detectors.pdtypes.construct_segment_beat_matrix(
...     model.mode_index_map,
...     finesse.detectors.pdtypes.XSPLIT
... )
>>> # Compute E^* . M . E over the array
>>> S = (E.conj() * (M @ E.T).T).sum(1)
>>> plt.plot(sol.x1, abs(S))
>>> plt.xlabel("Misalignment [rad]")
>>> plt.ylabel("Signal [W]")
>>> plt.title("QPD alignment signal")

finesse.detectors.pdtypes.get_pdtype(pdtype: str) → dict: Returns a pdtype dictionary definition in this module for a given string name.

finesse.detectors.powerdetector module

Computes the laser power in an interferometer output or the power from an electrical signal.

class finesse.detectors.powerdetector.PowerDetector(*args, **kwargs)

Bases: MaskedDetector

Represents a power detector with no RF demodulations. It calculates the DC laser power at a node in Watts of optical power.

Parameters

namestr: Name of newly created power detector.
nodeNode: Node to read output from.

class finesse.detectors.powerdetector.PowerDetectorDemod1(*args, **kwargs)

Bases: MaskedDetector

Represents a power detector with one RF demodulation. It calculates the RF beat power at a node in Watts of optical power.

If no demodulation phase is specified then this detector outputs a complex value I+1j*Q.

Parameters

namestr: Name of newly created power detector.
nodeNode: Node to read output from.
ffloat: Demodulation frequency in Hz
phasefloat, optional: Demodulation phase in degrees

property f: f : float Demodulation frequency in Hz

property phase: phase : float, optional Demodulation phase in degrees

class finesse.detectors.powerdetector.PowerDetectorDemod2(*args, **kwargs)

Bases: MaskedDetector

Represents a power detector with two RF demodulation. It calculates the RF beat power at a node in Watts of optical power.

If no demodulation phase is specified for the final demodulation this detector outputs a complex value I+1j*Q where I and Q are the in-phase and quadrature parts of the signal.

Parameters

namestr: Name of newly created power detector.
nodeNode: Node to read output from.
f1float: First demodulation frequency in Hz
phase1float: First demodulation phase in degrees
f2float: Second demodulation frequency in Hz
phase2float, optional: Second demodulation phase in degrees

property f1: f1 : float First demodulation frequency in Hz

property f2: f2 : float Second demodulation frequency in Hz

property phase1: phase1 : float First demodulation phase in degrees

property phase2: phase2 : float, optional Second demodulation phase in degrees

finesse.detectors.quantum_noise_detector module

Photodiode quantum noise detector.

class finesse.detectors.quantum_noise_detector.GeneralQuantumNoiseDetector(*args, **kwargs)

Bases: Detector, NoiseDetector

Represents a quantum noise detector.

This detector calculates the amplitude spectral density of the photocurrent noise of a DC or demodulated photodiode output.

Parameters

namestr: Name of newly created quantum noise detector.
nodeNode: Node to read output from.
freqslist of float or Frequency, optional: List of mixer demodulation frequencies (in Hz).
phaseslist of float, optional: List of mixer demodulation phases (in Hz).
shot_onlybool, optional: If True, detect only vacuum noise contributions.

class finesse.detectors.quantum_noise_detector.QuantumNoiseDetector(*args, **kwargs)

Bases: Detector, NoiseDetector

Represents a quantum noise detector with no RF demodulations.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency.

Parameters

namestr: Name of newly created quantum noise detector.
nodeNode: Node to read output from.
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.
sourceslist of Connector, optional: If given, only detect quantum noise contributions from these components.
exclude_sourceslist of Connector, optional: If given, this will not detect quantum noise contributions from any of these components, even if explicitly specified in sources.

class finesse.detectors.quantum_noise_detector.QuantumNoiseDetectorDemod1(*args, **kwargs)

Bases: Detector, NoiseDetector

Represents a quantum noise detector with 1 RF demodulation.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency.

Parameters

namestr: Name of newly created quantum noise detector.
nodeNode: Node to read output from.
ffloat: Demodulation frequency in Hz
phasefloat: Demodulation phase in degrees
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.
sourceslist of Connector, optional: If given, only detect quantum noise contributions from these components.

property f: f : float Demodulation frequency in Hz

property phase: phase : float Demodulation phase in degrees

class finesse.detectors.quantum_noise_detector.QuantumNoiseDetectorDemod2(*args, **kwargs)

Bases: Detector, NoiseDetector

Represents a quantum noise detector with 2 RF demodulations.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency.

Parameters

namestr: Name of newly created quantum noise detector.
nodeNode: Node to read output from.
f1float: First demodulation frequency in Hz
phase1float: First demodulation phase in degrees
f2float: Second demodulation frequency in Hz
phase2float: Second demodulation phase in degrees
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.
sourceslist of Connector, optional: If given, only detect quantum noise contributions from these components.

property f1: f1 : float First demodulation frequency in Hz

property f2: f2 : float Second demodulation frequency in Hz

property phase1: phase1 : float First demodulation phase in degrees

property phase2: phase2 : float Second demodulation phase in degrees

class finesse.detectors.quantum_noise_detector.QuantumShotNoiseDetector(*args, **kwargs)

Bases: Detector

Represents a quantum shot noise detector with no RF demodulations.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency, considering only vacuum noise contributions (ignoring radiation pressure and squeezing effects).

Parameters

namestr: Name of newly created quantum shot noise detector.
nodeNode: Node to read output from.
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.

class finesse.detectors.quantum_noise_detector.QuantumShotNoiseDetectorDemod1(*args, **kwargs)

Bases: Detector

Represents a quantum shot noise detector with 1 RF demodulation.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency, considering only vacuum noise contributions (ignoring radiation pressure and squeezing effects).

Parameters

namestr: Name of newly created quantum shot noise detector.
nodeNode: Node to read output from.
ffloat: Demodulation frequency in Hz
phasefloat: Demodulation phase in degrees
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.

property f: f : float Demodulation frequency in Hz

property phase: phase : float Demodulation phase in degrees

class finesse.detectors.quantum_noise_detector.QuantumShotNoiseDetectorDemod2(*args, **kwargs)

Bases: Detector

Represents a quantum shot noise detector with 2 RF demodulations.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency, considering only vacuum noise contributions (ignoring radiation pressure and squeezing effects).

Parameters

namestr: Name of newly created quantum shot noise detector.
nodeNode: Node to read output from.
f1float: First demodulation frequency in Hz
phase1float: First demodulation phase in degrees
f2float: Second demodulation frequency in Hz
phase2float: Second demodulation phase in degrees
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.

property f1: f1 : float First demodulation frequency in Hz

property f2: f2 : float Second demodulation frequency in Hz

property phase1: phase1 : float First demodulation phase in degrees

property phase2: phase2 : float Second demodulation phase in degrees

finesse.detectors.workspace module

class finesse.detectors.workspace.DetectorWorkspace(owner, sim, values=None, OutputInformation oinfo=None, *, bool needs_carrier=False, bool needs_signal=False, bool needs_noise=False, bool needs_modal_update=False, bool needs_simulation=True)

Bases: ElementWorkspace

A base class that all detector workspaces should inherit from. Provides a generic set of data needed to compute values and output them with metadata needed for storing the outputs.

Parameters

ownerfinesse.element.ModelElement: Detector Element that owns this workspace and will be setting it up
simSimulation object: Simulation object this workspace should be associated with
values[object, finesse.element_workspace.BaseCValues], optional: The object containing the values that will be used by this workspace to calculate some output. These should match the parameters offered by the owner. A pure Python object can be used but will be slower to access. A finesse.element_workspace.BaseCValues object can also be used that offers cythonised access to parameter values
oinfoOutputInformation, optional: When provided this will set the output information of this detector, such as units, datatype, shape/dimension of outputs.
needs_carrierbool, optional: If the carrier simulation data is needed, this must be True
needs_signalbool, optional: If the signal simulation data (transfer functions) is needed, this must be True
needs_noisebool, optional: If this detector requires noise covariances to be calculated this must be True
needs_modal_update: bool, optional: If this detector outputs some modal or geometric property, this must be True.

Notes

The needs_* flags specify which simulations should be run to evaluate this workspace. At least one should be True, unless needs_simulation is flagged as False. This is to catch certain cases which mean the workspace will just not produce any output.

When adding new needs_* flag, ensure you update the MathDetector object to correctly fill these flags. The MathDetector essentially borrows workspaces from other detectors to compute its output and

get_output(self)

needs_carrier

needs_modal_update

needs_noise

needs_signal

oinfo

set_output_fn(self, callback)

class finesse.detectors.workspace.MaskedDetectorWorkspace(owner, BaseSimulation sim, values=None, oinfo=None, *, **kwargs)

Bases: DetectorWorkspace

Specialised workspace for detectors which support masking of modes.

This workspace provides attributes that are exposed to both C and Python. The sections below detail how to use these for some workspace instance ws which inherits from MaskedDetectorWorkspace.

Using via Python

The unmasked_indices_arr attribute is a numpy.ndarray, of dtype np.intp, which contains the indices of modes which are not masked. One may then simply loop over this array of indices to access the corresponding field indices, e.g

for k in ws.unmasked_indices_arr:
    # Do something with k, e.g. get field at 0 Hz freq. offset
    # at the given node for the mode index k:
    a_0k = carrier.get_out_fast(ws.dc_node_id, 0, k)
    # use a_0k for some calculation ...

Using via Cython

This workspace also provides a unmasked_mode_indices pointer (only accessible from other Cython code) which corresponds to the data of the unmasked_indices_arr NumPy array described above. The attribute num_unmasked_homs is the size of this array; i.e. the number of modes which are not masked.

One may then write an optimised loop from [0, num_unmasked_homs), e.g

cdef Py_ssize_t i, k
cdef complex_t a_0k
for i in range(ws.num_unmasked_homs):
    k = ws.unmasked_mode_indices[i]
    # Do something with k, e.g. get field at 0 Hz freq. offset
    # at the given node for the mode index k:
    a_0k = carrier.get_out_fast(ws.dc_node_id, 0, k)
    # use a_0k for some calculation ...

where each k is then the index of the mode at position i in the unmasked indices array.

Note

If the detector mask is empty (i.e. no modes are being masked) then unmasked_indices_arr (and, correspondingly, unmasked_mode_indices) will simply be an array from [0, Nhoms) where Nhoms is the total number of modes in the simulation.

has_mask

num_unmasked_HOMs

unmasked_indices_arr

class finesse.detectors.workspace.OutputFuncWrapper

Bases: object

Helper class for wrapping a C fill function that can be referenced from Python by objects. This allows a direct C call to the function from other cdef functions.

Examples

Create a C function then wrap it using this class:

>>> cdef void c_output(DetectorWorkspace ptr_ws) noexcept:
>>>    cdef PDWorkspace ws = <PDWorkspace>ptr_ws
>>>    ...
>>>
>>> fill = OutputFuncWrapper.make_from_ptr(c_fill)

class finesse.detectors.workspace.OutputInformation(name, detector_type, nodes, dtype, unit, shape, label, needs_fields, needs_trace)

Bases: object

detector_type: The type of the detector that has generated this output information.

dtype

dtype_shape

dtype_size

Size of the output in terms of number of elements.

This is typically unity as most detectors return a single value via their output functions.

Equivalent to the product of Detector.dtype_shape.

label

name

needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

needs_trace: Flag indicating whether the detector requires beam traces.

nodes

The nodes this detector observes.

Getter:: Returns copy of detected nodes.

unit

Module contents

The detectors sub-module contains various non-physical detectors that can be used to probe to simulation at any point.

Listed below are all the sub-modules within detectors with brief descriptions of what is contained in each.

class finesse.detectors.AmplitudeDetector(*args, **kwargs)

Bases: MaskedDetector

Represents an amplitude detector which calculates the amplitude and phase of light fields at one frequency.

Parameters

namestr: Name of newly created detector.
nodeNode: Node to read output from.
ffloat: Frequency of light to detect (in Hz).
nint, optional; default: None: Tangential mode index to probe. Defaults to None such that all fields of the given frequency are summed.
mint, optional; default: None: Sagittal mode index to probe. Defaults to None such that all fields of the given frequency are summed.

property f: f : float Frequency of light to detect (in Hz).

property m

The sagittal mode index to probe.

Getter:: Returns the sagittal mode index being probed (read-only).

property n

The tangential mode index to probe.

Getter:: Returns the tangential mode index being probed (read-only).

class finesse.detectors.AstigmatismDetector(*args, **kwargs)

Bases: Detector

Detector for astigmatism figure-of-merit at a given node.

The computed quantity is given via one minus finesse.gaussian.BeamParam.overlap().

Parameters

namestr: Name of the detector.
nodeOpticalNode: Node to compute astigmatism at.

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

class finesse.detectors.BeamProperty(*values)

Bases: IntFlag

DEFOCUS = 8

DISTANCE = 2

DIVERGENCE = 5

GOUY = 4

Q = 7

RAYLEIGH = 3

ROC = 6

SIZE = 0

WAISTSIZE = 1

class finesse.detectors.BeamPropertyDetector(*args, **kwargs)

Bases: Detector

Probe for detecting the properties of a beam at a given node.

The valid values for prop are:

"w": beam size at node [metres],

"w0": waist size as measured at node [metres],

"z": distance to the waist from node [metres],

"zr": the Rayleigh range [metres],

"gouy": the Gouy phase of the beam at node [radians],

"div": divergence angle of the beam at node [radians],

"rc": radius of curvature of wavefront at node [metres],

"s": curvature of wavefront at node [1 / metres],

"q": beam parameter at node.

Note

The "gouy" target property here detects the Gouy phase as derived from the beam parameter \(q\) at the specified node, i.e:

\[\psi = \arctan{\left(\frac{\myRe{q}}{\myIm{q}}\right)}.\]

It does not compute any Gouy phase accumulation. Use Gouy to detect the accumulated Gouy phase over a path.

Parameters

namestr: Name of newly created detector.
nodeOpticalNode: Node to read output from.
propstr or BeamProperty: The property of the beam to detect. See above for options.
directionstr, optional; default: ‘x’: Plane to detect in - ‘x’ for tangential, ‘y’ for sagittal.
q_as_bpbool, optional; default: False: If detecting q, should the detector output return BeamParam object instead of just a complex number.

property detecting

The property of the beam which is being detected.

Getter:: Returns the detected property (read-only).

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

property prop

class finesse.detectors.CCD(*args, **kwargs)

Bases: CCDCamera, Image

Camera for measuring the intensity of a beam, \(I = |E(x,y)|^2\), where the unscaled x and y coordinate arrays used are finesse.detectors.camera.Image.xdata and finesse.detectors.camera.Image.ydata, respectively. Note that this is just the intensity at the points (x,y), not an integrated power over some finite pixel size.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
xlimsequence or scalar: Limits of the x-dimension of the image. If a single number is given then this will be computed as \(x_{\mathrm{lim}} = [-|x|, +|x|]\).
ylimsequence or scalar: Limits of the y-dimension of the image. If a single number is given then this will be computed as \(y_{\mathrm{lim}} = [-|y|, +|y|]\).
nptsint: Number of points in both axes.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property npts

Number of pixels in each axis.

Getter:: Returns the number of pixels in each axis.
Setter:: Sets the number of pixels in each axis.

class finesse.detectors.CCDCamera(*args, **kwargs)

Bases: Camera, ABC

Abstract type for cameras which detect pixel intensity.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

class finesse.detectors.CCDPixel(*args, **kwargs)

Bases: CCDCamera, Pixel

Camera for measuring the intensity of a beam, \(I = |E(x,y)|^2\), at a single point. Where the unscaled x and y coordinate used is finesse.detectors.camera.Pixel.xdata and finesse.detectors.camera.Pixel.ydata, respectively. Note that this is just the intensity at (x,y), not an integrated power over some finite pixel dimension.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
xscalar, optional; default: 0: The x co-ordinate of the pixel.
yscalar, optional; default: 0: The y co-ordinate of the pixel.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

class finesse.detectors.CCDScanLine(*args, **kwargs)

Bases: CCDCamera, ScanLine

Camera for measuring the intensity of a beam, \(I = |E(x,y)|^2\), along a 1D slice. Where the unscaled x and y coordinate arrays used are finesse.detectors.camera.ScanLine.xdata and finesse.detectors.camera.ScanLine.ydata, respectively. Note that this is just the intensity at the points (x,y), not an integrated power over some finite pixel size.

The ScanLine.direction (i.e. axis of slice) is determined from which of xlim or ylim is specified.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
nptsint: Number of points in slice axis.
xscalar or None; default: None: The x coordinate of the slice. If ylim is given and this is not specified then defaults to zero. If xlim is given and this is also specified then it is ignored.
yscalar or None; default: None: The y coordinate of the slice. If xlim is given and this is not specified then defaults to zero. If ylim is given and this is also specified then it is ignored.
xlimscalar or size two sequence; default: None: The limits of the x-axis scan lines. A single number gives \(x_{\mathrm{axis}} \in [-|x|, +|x|]\), or a tuple of size two gives \(x_{\mathrm{axis}} \in [x[0], x[1]]\).
ylimscalar or array-like; default: None: The limits of the y-axis scan lines. A single number gives \(y_{\mathrm{axis}} \in [-|y|, +|y|]\), or a tuple of size two gives \(y_{\mathrm{axis}} \in [y[0], y[1]]\).
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property npts

Number of pixels in the scanning axis.

Getter:: Returns the number of pixels in the slice axis.
Setter:: Sets the number of pixels in the slice axis.

class finesse.detectors.Camera(*args, **kwargs)

Bases: MaskedDetector, ABC

Base camera class.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
w0_scaledbool: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.
dtypenumpy.dtype or str: The data-type of the pixels.
shapetuple: Dimensions of the camera image.

property needs_trace: Flag indicating whether the detector requires beam traces.

property scaled_xdata

Coordinate data in the x-axis scaled to metres.

Equivalent to xdata if Camera.w0_scaled is False. Otherwise this is xdata multiplied by the tangential waist size as measured at the node.

property scaled_ydata

Coordinate data in the y-axis scaled to metres.

Equivalent to ydata if Camera.w0_scaled is False. Otherwise this is ydata multiplied by the sagittal waist size as measured at the node.

property w0_scaled

Flag for whether the x and y co-ordinates have been scaled by the waist-size of the beam parameter at the detection node.

Getter:: Returns True if x and y have been scaled by the beam waist, False otherwise.

class finesse.detectors.CavityProperty(*values)

Bases: IntFlag

ABCD = 7

EIGENMODE = 12

FINESSE = 2

FSR = 3

FWHM = 4

LENGTH = 0

LOSS = 1

MODESEP = 10

POLE = 5

RESOLUTION = 11

RTGOUY = 9

SOURCE_DEFOCUS = 19

SOURCE_DISTANCE = 15

SOURCE_DIVERGENCE = 17

SOURCE_RAYLEIGH = 16

SOURCE_ROC = 18

SOURCE_SIZE = 13

SOURCE_WAISTSIZE = 14

STABILITY = 8

TAU = 6

class finesse.detectors.CavityPropertyDetector(*args, **kwargs)

Bases: Detector

Probe for detecting the properties of a cavity.

The valid values for prop are:

"length" or "l": round-trip cavity length [metres],

"loss": round-trip loss as a fraction,

"finesse": the cavity finesse,

"fsr": free spectral range [Hz],

"fwhm": full-width at half-maximum (i.e. linewidth) [Hz],

"pole": cavity pole frequency [Hz],

"tau": photon storage time [s],

"abcd": round-trip ABCD matrix,

"g" or "stability": stability as g-factor,

"gouy": round-trip Gouy phase [deg],

"modesep": mode-separation frequency [Hz],

"resolution": cavity resolution [Hz],

"q": eigenmode,

"w": beam size at the cavity source node [metres],

"w0": waist size [metres],

"z": distance to the waist from the cavity source node [metres],

"zr": the Rayleigh range of the eigenmode [metres],

"div": divergence angle of cavity mode [radians],

"rc": radius of curvature of wavefront at cavity source node [metres],

"s": curvature of wavefront at cavity source node [1 / metres].

Parameters

namestr: Name of newly created cavity property detector.
cavitystr or Cavity: The cavity to probe. If the name is provided then the CavityPropertyDetector.cavity attribute will point to the corresponding Cavity object when adding this detector to a Model instance.
propstr or CavityProperty: Property of the cavity to probe. See above for options.
directionstr, optional; default: ‘x’: Plane to detect in.
q_as_bpbool, optional; default: False: If detecting q, should the detector output return BeamParam object instead of just a complex number.

property cavity: The cavity instance being probed.

property detecting

The property of the cavity which is being detected.

Getter:: Returns the detected property (read-only).

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

property prop

class finesse.detectors.ComplexCamera(*args, **kwargs)

Bases: Camera, ABC

Abstract type for cameras which detect pixel amplitude and phase.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
fscalar, optional; default: 0: Field frequency offset from the carrier to detect.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property f: f : scalar, optional; default: 0 Field frequency offset from the carrier to detect.

class finesse.detectors.Detector(*args, **kwargs)

Bases: ABC, ModelElement

Abstract representation of a component that produces a numerical output.

User detector classes should subclass this class. The simulation will then generate a dictionary of output values.

Parameters

namestr: Name of newly created detector.
nodeNode or Port: Node to read output from. If a port is given, it must have one node, so that is is unambiguous which node to use.
dtypetype, optional: The numpy datatype for which this output result will be stored in.
unitstr, optional: A human readable unit for the output. E.g. W, m, m/rtHz.

property dtype

property dtype_shape

property dtype_size

Size of the output in terms of number of elements.

This is typically unity as most detectors return a single value via their output functions.

Equivalent to the product of Detector.dtype_shape.

property label

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

property node

The nodes this detector observes.

Getter:: Returns the detected node.

property output_information

property unit

class finesse.detectors.FieldCamera(*args, **kwargs)

Bases: ComplexCamera, Image

Camera for detecting the full image of the beam in terms of amplitude and phase.

Get the unscaled x and y coordinate data via finesse.detectors.camera.Image.xdata and finesse.detectors.camera.Image.ydata, respectively.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
xlimsequence or scalar: Limits of the x-dimension of the image. If a single number is given then this will be computed as \(x_{\mathrm{lim}} = [-|x|, +|x|]\).
ylimsequence or scalar: Limits of the y-dimension of the image. If a single number is given then this will be computed as \(y_{\mathrm{lim}} = [-|y|, +|y|]\).
nptsint: Number of points in both axes.
fscalar, optional; default: 0: Field frequency offset from the carrier to detect.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property f: f : scalar, optional; default: 0 Field frequency offset from the carrier to detect.

property npts

Number of pixels in each axis.

Getter:: Returns the number of pixels in each axis.
Setter:: Sets the number of pixels in each axis.

class finesse.detectors.FieldDetector(*args, **kwargs)

Bases: Detector

Outputs an array of the higher order modes amplitudes at a particular node and frequency. The mode ordering is given by Model.homs. Plane wave models will output a single element array.

This detector can only be used on optical nodes.

Parameters

namestr: Name of newly created detector.
nodeNode: Node to read output from.
ffloat: Frequency of light to detect (in Hz).

Examples

>>> import finesse
>>> model = finesse.Model()
>>> model.parse('''
    laser l1
    gauss g1 l1.p1.o w0=1m z=0
    m m1 R=1 T=0 xbeta=1e-9 ybeta=3e-8
    link(l1, m1)
    modes(maxtem=1)
    fd fd1 m1.p1.o 0
''')
>>> out = model.run('noxaxis()')
>>> print(out['fd1'])
array([
    0.99999998+0.00000000e+00j,
    0+1.77157478e-04j,
    0+5.90524926e-06j
])

property f: f : float Frequency of light to detect (in Hz).

class finesse.detectors.FieldPixel(*args, **kwargs)

Bases: ComplexCamera, Pixel

Camera for detecting a single pixel of the beam in terms of the amplitude and phase.

Get the unscaled x and y coordinate data via finesse.detectors.camera.Pixel.xdata and finesse.detectors.camera.Pixel.ydata, respectively.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
xscalar, optional; default: 0: The x co-ordinate of the pixel.
yscalar, optional; default: 0: The y co-ordinate of the pixel.
fscalar, optional; default: 0: Field frequency offset from the carrier to detect.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property f: f : scalar, optional; default: 0 Field frequency offset from the carrier to detect.

class finesse.detectors.FieldScanLine(*args, **kwargs)

Bases: ComplexCamera, ScanLine

Camera for detecting a slice of the beam in terms of amplitude and phase.

The ScanLine.direction (i.e. axis of slice) is determined from which of xlim or ylim is specified.

Get the unscaled x and y coordinate data via finesse.detectors.camera.ScanLine.xdata and finesse.detectors.camera.ScanLine.ydata, respectively.

Parameters

namestr: Unique name of the camera.
nodeOpticalNode: Node at which to detect.
nptsint: Number of points in slice axis.
xscalar or None; default: None: The x coordinate of the slice. If ylim is given and this is not specified then defaults to zero. If xlim is given and this is also specified then it is ignored.
yscalar or None; default: None: The y coordinate of the slice. If xlim is given and this is not specified then defaults to zero. If ylim is given and this is also specified then it is ignored.
xlimscalar or size two sequence; default: None: The limits of the x-axis scan lines. A single number gives \(x_{\mathrm{axis}} \in [-|x|, +|x|]\), or a tuple of size two gives \(x_{\mathrm{axis}} \in [x[0], x[1]]\).
ylimscalar or array-like; default: None: The limits of the y-axis scan lines. A single number gives \(y_{\mathrm{axis}} \in [-|y|, +|y|]\), or a tuple of size two gives \(y_{\mathrm{axis}} \in [y[0], y[1]]\).
fscalar, optional; default: 0: Field frequency offset from the carrier to detect.
w0_scaledbool, optional; default: True: Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

property f: f : scalar, optional; default: 0 Field frequency offset from the carrier to detect.

property npts

Number of pixels in the scanning axis.

Getter:: Returns the number of pixels in the slice axis.
Setter:: Sets the number of pixels in the slice axis.

class finesse.detectors.GeneralQuantumNoiseDetector(*args, **kwargs)

Bases: Detector, NoiseDetector

Represents a quantum noise detector.

This detector calculates the amplitude spectral density of the photocurrent noise of a DC or demodulated photodiode output.

Parameters

namestr: Name of newly created quantum noise detector.
nodeNode: Node to read output from.
freqslist of float or Frequency, optional: List of mixer demodulation frequencies (in Hz).
phaseslist of float, optional: List of mixer demodulation phases (in Hz).
shot_onlybool, optional: If True, detect only vacuum noise contributions.

class finesse.detectors.Gouy(*args, **kwargs)

Bases: Detector

Detector to measure the accumulated gouy phase across a sequence of spaces.

This detector can operate in one of two modes, depending upon args given:

automatically determine the spaces through an arbitrary path by specifying the from_node and to_node arguments,

OR provide a pre-determined sequence of spaces (or their names) as positional arguments.

Whichever option is chosen, this detector will compute the same fundamental quantity; that is the sum of the Gouy phases accumulated over each space (in degrees).

Parameters

namestr: Name of newly created gouy detector.
*argssequence: A sequence of spaces or space names.
from_nodenode-like: An OpticalNode instance, or a data type which can be converted to an optical node.
to_nodenode-like: An OpticalNode instance, or a data type which can be converted to an optical node.
via_nodenode-like: An OpticalNode instance, or a data type which can be converted to an optical node.
directionstr: Plane to detect in - ‘x’ for tangential, ‘y’ for sagittal. Defaults to ‘x’.

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

property spaces: The spaces that this detector will calculated the accumulated Gouy phase over.

class finesse.detectors.KnmDetector(*args, **kwargs)

Bases: Detector

Direct probe of coupling coefficients at a component.

This detector has several “modes” which depend upon the values given for the mode indices n1, m1 and n2, m2. If:

all of n1, m1, n2, m2 are specified then the detector will output a single complex coefficient corresponding to the coupling from (n1, m1) -> (n2, m2),

just n1 and m1 are specified then it will output a vector of complex coefficients corresponding to each coupling from (n1, m1) -> (n, m) for each mode (n, m) in the model,

only n2 and m2 are specified then it will output a vector of complex coefficients corresponding to each coupling from (n, m) -> (n2, m2) for each mode (n, m) in the model,

none of n1, m1, n2, m2 are specified then the detector outputs the full matrix of complex coupling coefficients.

Hint

When using this detector in “full-matrix” mode (i.e. by not giving the values for any of the mode indices), it can be useful to combine the output with the KnmMatrix object to obtain a more convenient representation of the scattering matrix.

An example of this is shown below, where the output of a detector of this type is wrapped using KnmMatrix.from_buffer().

import finesse
finesse.configure(plotting=True)
from finesse.knm.matrix import KnmMatrix

IFO = finesse.Model()
IFO.parse('''
l L0 P=1
link(L0, ITM)
m ITM R=0.99 T=0.01 Rc=-2090 xbeta=0.3u
s LARM ITM.p2 ETM.p1 L=4k
m ETM R=0.99 T=0.01 Rc=2090

cav ARM ITM.p2
modes(x, maxtem=6)

knmd K_itm_r ITM 22
''')

out = IFO.run('noxaxis()')
# Make a KnmMatrix wrapper around the output from the detector
k_mat = KnmMatrix.from_buffer(out["K_itm_r"], IFO.homs)
# Now we can perform operations such as plotting the scattering matrix
k_mat.plot(cmap="bone");

See Computing arbitrary scattering matrices for some examples on the utility that the KnmMatrix object provides.

Parameters

namestr

Name of newly created KnmDetector.

compConnector

A component which can scatter modes.

couplingstr

Coupling direction string, e.g. “11” for coupling coefficients on reflection from the front surface of a mirror.

n1, m1, n2, m2: int or None

From (n1, m1) and To (n2, m2) mode indices of the coupling coefficient(s) to retrieve.

See above for the options.

class finesse.detectors.MaskedDetector(*args, **kwargs)

Bases: Detector, ABC

An abstract class from which detector types which can have mode masks derive.

Any detector object which calculates quantities involving loops over the modes of a model should inherit from this — allowing masks to be applied to mode patterns via the methods of this class. Examples of detectors which should derive from MaskedDetector are power-detectors, amplitude-detectors and cameras.

add_to_mask(modes)

Inserts the specified mode indices into the detector mask.

Parameters

modessequence, str: A single mode index pair or an iterable of mode indices. Each element must unpack to two integer convertible values.

property has_mask

Whether the detector has a mask applied to it.

Simply checks to see if the MaskedDetector.mask length is non-zero.

property mask

An array of HOMs to mask from the output. Any contributions from these modes will be zeroed when calculating the detector output.

Getter:: Returns the array of masked indices.
Setter:: Sets the masked indices. See MaskedDetector.select_mask() for the options available.

remove_from_mask(modes)

Removes the specified mode indices from the detector mask.

Parameters

modessequence, str: A single mode index pair or an iterable of mode indices. Each element must unpack to two integer convertible values.

select_mask(modes=None, maxtem=None, exclude=None)

Select the HOM indices to include in the mask.

The mode-selecting examples in Selecting the modes to model may be referred to for typical patterns when using this method, as the same concepts apply equally to making detector masks (equivalent code under-the-hood).

Parameters

modessequence, str, optional; default: None

Identifier for the mode indices to generate. This can be:

An iterable of mode indices, where each element in the iterable must unpack to two integer convertible values.
A string identifying the type of modes to include, must be one of “even”, “odd”, “x” or “y”.

By default this is None, such that, for example, this method can be used to select a mask of all modes up to a given maxtem.

maxtemint, optional; default: None

Optional maximum mode order. If not specified then the maxtem used internally will be equal to the maximum mode order of the associated model.

Note that this argument is ignored if modes is an iterable of mode indices.

excludesequence, str, optional; default: None

A mode, or iterable of modes, to exclude from the selected pattern. For example, if one calls select_mask("even", exclude="00") then the mask will be an array of all even-order HOM indices excluding the 00 mode.

Examples

See Selecting the modes to model.

class finesse.detectors.MathDetector(*args, **kwargs)

Bases: Detector

A detector that performs some math operation and outputs the result.

Parameters

namestr: Name of detector
expressionSymbol: Symbolic expression to evaluate as the detectors output
dtypenumpy.dtype, optional: The expected data type when evaluating expression. Defaults to “O”.
dtype_shapetuple: The expected array shape when evaluating expression. Defaults to an empty tuple. This must be an empty tuple if dtype is a scalar type or “O”.
unitstr: The unit of the output for plotting. Defaults to “arb.”
labelstr or None: How to label the axis when plotting this detector. Defaults to None.

Notes

If dtype does not match the result when expression is evaluated the values will be silently cast to dtype. dtype_shape is used to create a numpy array in which the results are written, if this doesn’t match this should raise some Exception when running a simulation, but this is not guaranteed. If one isn’t sure of what type expression will produce, one should leave the default “O”, the generic numpy type object, and convert the data after inspecting the result. When using the default type, some functions like Solution.plot might not be able to convert the data to an appropiate type internally, in which case they cannot be used.

Examples

KatScript example:

l l1 P=1 pd P l1.p1.o fd E l1.p1.o f=l1.f bp qx l1.p1.o q x modes(maxtem=3) gauss g1 l1.p1.o w0=1m z=0

mathd Y1 P*2 mathd Y2 P**2 mathd Y3 cos(1+P**2) mathd Y4 E*2 mathd Y5 qx+1

property expression

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

set_expression(expression, dtype='O', dtype_shape=(), unit='arb.', label=None)

class finesse.detectors.ModeMismatchDetector(*args, **kwargs)

Bases: Detector

Detector for mode mismatch figure-of-merit for a specified node coupling.

The computed quantity is given in finesse.gaussian.BeamParam.mismatch() where \(q_1\) is the input beam parameter at node1 propagated via the associated ABCD matrix to node2, and \(q_2\) is the beam parameter at node2.

As mode mismatches cannot occur over spaces in Finesse, node1 must be an input node and node2 must be an output node.

Parameters

namestr: Name of the detector.
node1OpticalNode or Port: Input node or port. If a Port instance is given then this node will be the input node of that port. Note that this node cannot be an output node.
node2OpticalNode or Port: Output node or port. If a Port instance is given then this node will be the output node of that port. Note that this node cannot be an input node.
directionstr, optional; default: “x”: Plane of computation, defaults to “x” for the tangential plane. Changing to “y” will compute the mode mismatch in the sagittal plane.
percentbool, optional; default: True: Whether to calculate the mode mismatch as a fraction (default behaviour) or a percentage.

property component

The component at which the mode mismatch is calculated.

Getter:: Returns the associated component (read-only).

property direction

The plane in which the mode mismatch is calculated.

A value of “x” represents the tangential plane, whilst “y” gives the sagittal plane.

Getter:: Returns the plane of computation as a string representation (read-only).

property in_node

Input node.

Getter:: Returns the input node (read-only).

property in_percent

Flag indicating whether the mismatch is computed as a percentage.

Getter:: Returns the percentage flag.
Setter:: Sets the percentage flag.

property needs_fields: Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

property needs_trace: Flag indicating whether the detector requires beam traces.

property out_node

Output node.

Getter:: Returns the output node (read-only).

class finesse.detectors.MotionDetector(*args, **kwargs)

Bases: Detector

Represents a motion detector which calculates the amplitude and phase of surface motion.

Parameters

namestr: Name of newly created motion detector.
nodeNode: Node to read output from.

class finesse.detectors.NoiseDetector(noise_type)

Bases: object

property noise_type

class finesse.detectors.OptimalQ(*args, **kwargs)

Bases: Detector

This detector tries to compute an optimal beam parameter (\(q\)) for a specified optical frequency at a node.

Output of this detector into an array solution will be a tuple of BeamParam in each transverse direction, (qx, qy). If the optimisation process fails beam parameter objects will NaN values will be returned.

Parameters

namestr: Name of the detector
node[str | finesse.components.node]: Node name or object to put this detector at
ffloat: Frequency component tro compute the optimal beam parameter for.
fix_spot_sizebool, optional: When True the optimised will keep the current spot size at the node fixed and just optimise the curvature.
astigmaticbool, optional: When True qx and qy will be optimised separately
accuracyfloat, optional: Approximate mismatch accuracy to try and compute the optimised beam parameter to. mismatch(q_actual, q_optimal) < accuracy
directionstr, optional: Return either both or just the x or y modes

Notes

This method uses the finesse.gaussian.optimise_HG00_q() or finesse.gaussian.optimise_HG00_q_scipy() for optimising the HG mode amplitudes at the node and frequency requested. This particular method finds a new set of {qx, qy} values which maximise the HG00 mode content, whilst reducing the HG20 and HG02 mode content.

Failure

If the optical field being optimised does not have a HG00 like appearance then. For example, trying to optimise the shape of an RF sideband field inside a cavity that it is not resonant in.

property astigmatic: astigmatic : bool, optional When True qx and qy will be optimised separately

property direction

Sets the output of the detector.

If both then both qx and qy are returned. if x or y are used then only the required one is returned.

property f: f : float Frequency component tro compute the optimal beam parameter for.

property fix_spot_size: fix_spot_size : bool, optional When True the optimised will keep the current spot size at the node fixed and just optimise the curvature.

class finesse.detectors.PowerDetector(*args, **kwargs)

Bases: MaskedDetector

Represents a power detector with no RF demodulations. It calculates the DC laser power at a node in Watts of optical power.

Parameters

namestr: Name of newly created power detector.
nodeNode: Node to read output from.

class finesse.detectors.PowerDetectorDemod1(*args, **kwargs)

Bases: MaskedDetector

Represents a power detector with one RF demodulation. It calculates the RF beat power at a node in Watts of optical power.

If no demodulation phase is specified then this detector outputs a complex value I+1j*Q.

Parameters

namestr: Name of newly created power detector.
nodeNode: Node to read output from.
ffloat: Demodulation frequency in Hz
phasefloat, optional: Demodulation phase in degrees

property f: f : float Demodulation frequency in Hz

property phase: phase : float, optional Demodulation phase in degrees

class finesse.detectors.PowerDetectorDemod2(*args, **kwargs)

Bases: MaskedDetector

Represents a power detector with two RF demodulation. It calculates the RF beat power at a node in Watts of optical power.

If no demodulation phase is specified for the final demodulation this detector outputs a complex value I+1j*Q where I and Q are the in-phase and quadrature parts of the signal.

Parameters

namestr: Name of newly created power detector.
nodeNode: Node to read output from.
f1float: First demodulation frequency in Hz
phase1float: First demodulation phase in degrees
f2float: Second demodulation frequency in Hz
phase2float, optional: Second demodulation phase in degrees

property f1: f1 : float First demodulation frequency in Hz

property f2: f2 : float Second demodulation frequency in Hz

property phase1: phase1 : float First demodulation phase in degrees

property phase2: phase2 : float, optional Second demodulation phase in degrees

class finesse.detectors.QuantumNoiseDetector(*args, **kwargs)

Bases: Detector, NoiseDetector

Represents a quantum noise detector with no RF demodulations.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency.

Parameters

namestr: Name of newly created quantum noise detector.
nodeNode: Node to read output from.
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.
sourceslist of Connector, optional: If given, only detect quantum noise contributions from these components.
exclude_sourceslist of Connector, optional: If given, this will not detect quantum noise contributions from any of these components, even if explicitly specified in sources.

class finesse.detectors.QuantumNoiseDetectorDemod1(*args, **kwargs)

Bases: Detector, NoiseDetector

Represents a quantum noise detector with 1 RF demodulation.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency.

Parameters

namestr: Name of newly created quantum noise detector.
nodeNode: Node to read output from.
ffloat: Demodulation frequency in Hz
phasefloat: Demodulation phase in degrees
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.
sourceslist of Connector, optional: If given, only detect quantum noise contributions from these components.

property f: f : float Demodulation frequency in Hz

property phase: phase : float Demodulation phase in degrees

class finesse.detectors.QuantumNoiseDetectorDemod2(*args, **kwargs)

Bases: Detector, NoiseDetector

Represents a quantum noise detector with 2 RF demodulations.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency.

Parameters

namestr: Name of newly created quantum noise detector.
nodeNode: Node to read output from.
f1float: First demodulation frequency in Hz
phase1float: First demodulation phase in degrees
f2float: Second demodulation frequency in Hz
phase2float: Second demodulation phase in degrees
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.
sourceslist of Connector, optional: If given, only detect quantum noise contributions from these components.

property f1: f1 : float First demodulation frequency in Hz

property f2: f2 : float Second demodulation frequency in Hz

property phase1: phase1 : float First demodulation phase in degrees

property phase2: phase2 : float Second demodulation phase in degrees

class finesse.detectors.QuantumShotNoiseDetector(*args, **kwargs)

Bases: Detector

Represents a quantum shot noise detector with no RF demodulations.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency, considering only vacuum noise contributions (ignoring radiation pressure and squeezing effects).

Parameters

namestr: Name of newly created quantum shot noise detector.
nodeNode: Node to read output from.
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.

class finesse.detectors.QuantumShotNoiseDetectorDemod1(*args, **kwargs)

Bases: Detector

Represents a quantum shot noise detector with 1 RF demodulation.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency, considering only vacuum noise contributions (ignoring radiation pressure and squeezing effects).

Parameters

namestr: Name of newly created quantum shot noise detector.
nodeNode: Node to read output from.
ffloat: Demodulation frequency in Hz
phasefloat: Demodulation phase in degrees
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.

property f: f : float Demodulation frequency in Hz

property phase: phase : float Demodulation phase in degrees

class finesse.detectors.QuantumShotNoiseDetectorDemod2(*args, **kwargs)

Bases: Detector

Represents a quantum shot noise detector with 2 RF demodulations.

It calculates the amplitude spectral density of the photocurrent noise of a photodiode output demodulated at the signal frequency, considering only vacuum noise contributions (ignoring radiation pressure and squeezing effects).

Parameters

namestr: Name of newly created quantum shot noise detector.
nodeNode: Node to read output from.
f1float: First demodulation frequency in Hz
phase1float: First demodulation phase in degrees
f2float: Second demodulation frequency in Hz
phase2float: Second demodulation phase in degrees
nsrbool, optional: If true, calculate the noise-to-signal ratio rather than the absolute noise value.

property f1: f1 : float First demodulation frequency in Hz

property f2: f2 : float Second demodulation frequency in Hz

property phase1: phase1 : float First demodulation phase in degrees

property phase2: phase2 : float Second demodulation phase in degrees

class finesse.detectors.SymbolDetector(*args, **kwargs)

Bases: Detector

get_output(*args)