finesse.components package

Subpackages

finesse.components.modal package

Submodules

finesse.components.beamsplitter module

Optical components representing physical beamsplitters.

class finesse.components.beamsplitter.Beamsplitter(*args, **kwargs)

Bases: Surface

The beamsplitter component represents a thin dielectric surface with associated properties such as reflectivity, tuning, and radius of curvature. It has four optical ports p1, p2, p3, and p4 which describe the four beams incident on either side of this surface. p1 and p2 are on side 1 and p3 and p4 are on side 2. A 100% transmissive beamsplitter will transmit all of the light incident at p1 to p3.

It also has a mechanical port mech which has nodes for longitudinal, yaw, and pitch motions. These mechanical nodes are purely for exciting small signal oscillations of the mirror. Static offsets in longitudinal displacements are set by the phi parameter (in units of degrees), misalignments in yaw by the xbeta parameter, and pitch the ybeta parameter. Macroscopic angle of incidence of the beamsplitter is set by the alpha parameter.

Beamsplitters physically operate the same as mirror components, except for the non-normal angle of incidence option.

See RTL relationship for more information on how the RTL relationship is handled.

Parameters

namestr: Name of newly created beamsplitter.
Rfloat, optional: Reflectivity of the beamsplitter.
Tfloat, optional: Transmissivity of the beamsplitter.
Lfloat, optional: Loss of the beamsplitter.
phifloat, optional: Microscopic tuning of the beamsplitter (in degrees).
alphafloat, optional: Angle of incidence (in degrees)
Rcfloat, optional: Radius of curvature (in metres); defaults to numpy.inf to indicate a planar surface.
xbeta, ybetafloat, optional: Angle of misalignment in the yaw plane (xbeta) and pitch (ybeta), respectively (in radians); defaults to 0.
planestr, optional: Plane of incidence, either ‘xz’ or ‘yz’. Defaults to ‘xz’.
misalignedbool, optional: When True the beamsplitter will be significantly misaligned and assumes any reflected beam is dumped. Transmissions will still occur.

Attributes

Attributes are set via the Python API and not available via KatScript.

surface_mapfinesse.knm.maps.Map: Decsribes the surface distortion of this beamsplitter component. Coordinate system to the map is right-handed with the postive-z direction as the surface normal on the port 1 side of the beamsplitter.

ABCD(from_node, to_node, direction='x', symbolic=False, copy=True, retboth=False, allow_reverse=False)

Returns the ABCD matrix of the beam splitter for the specified coupling.

The matrices for transmission and reflection are different for the sagittal and tangential planes (\(M_s\) and \(M_t\)), as shown below.

Transmission

For the tangential plane (direction = ‘x’),

\[M_t = \begin{pmatrix} \frac{\cos{\alpha_2}}{\cos{\alpha_1}} & 0 \\ \frac{\Delta n}{R_c} & \frac{\cos{\alpha_1}}{\cos{\alpha_2}} \end{pmatrix}, \]

and for the sagittal plane (direction = ‘y’),

\[M_s = \begin{pmatrix} 1 & 0 \\ \frac{\Delta n}{R_c} & 1 \end{pmatrix}, \]

where \(\alpha_1\) is the angle of incidence of the beam splitter and \(\alpha_2\) is given by Snell’s law (\(n_1\sin{\alpha_1} = n_2\sin{\alpha_2}\)). The quantity \(\Delta n\) is given by,

\[\Delta_n = \frac{n_2 \cos{\alpha_2} - n_1 \cos{\alpha_1}}{ \cos{\alpha_1} \cos{\alpha_2} }. \]

If the direction of propagation is reversed such that the radius of curvature of the beam splitter is in this direction, then the elements \(A\) and \(D\) of the tangential matrix (\(M_t\)) are swapped.

Reflection

The reflection at the front surface of the beam splitter is given by,

\[M_t = \begin{pmatrix} 1 & 0 \\ -\frac{2n_1}{R_c \cos{\alpha_1}} & 1 \end{pmatrix}, \]

for the tangential plane, and,

\[M_s = \begin{pmatrix} 1 & 0 \\ -\frac{2n_1 \cos{\alpha_2}}{R_c} & 1 \end{pmatrix}, \]

for the sagittal plane.

At the back surface \(R_c \rightarrow - R_c\) and \(\alpha_1 \rightarrow - \alpha_2\).

See Connector.ABCD() for descriptions of parameters, return values and possible exceptions.

Raises

treTotalReflectionError: If total reflection occurs for the specified coupling - i.e. if \(\sin{\alpha_2} > 1.0\).

property L: L : float, optional Loss of the beamsplitter.

property R: R : float, optional Reflectivity of the beamsplitter.

property Rcx: Radius of curvature (x)

property Rcy: Radius of curvature (y)

property T: T : float, optional Transmissivity of the beamsplitter.

property abcd12x

Numeric ABCD matrix from port 1 to port 2 in the tangential plane.

Equivalent to beamsplitter.ABCD(1, 2, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd12y

Numeric ABCD matrix from port 1 to port 2 in the sagittal plane.

Equivalent to beamsplitter.ABCD(1, 2, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd13x

Numeric ABCD matrix from port 1 to port 3 in the tangential plane.

Equivalent to beamsplitter.ABCD(1, 3, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd13y

Numeric ABCD matrix from port 1 to port 3 in the sagittal plane.

Equivalent to beamsplitter.ABCD(1, 3, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd21x

Numeric ABCD matrix from port 2 to port 1 in the tangential plane.

Equivalent to beamsplitter.ABCD(2, 1, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd21y

Numeric ABCD matrix from port 2 to port 1 in the sagittal plane.

Equivalent to beamsplitter.ABCD(2, 1, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd24x

Numeric ABCD matrix from port 2 to port 4 in the tangential plane.

Equivalent to beamsplitter.ABCD(2, 4, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd24y

Numeric ABCD matrix from port 2 to port 4 in the sagittal plane.

Equivalent to beamsplitter.ABCD(2, 4, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd31x

Numeric ABCD matrix from port 3 to port 1 in the tangential plane.

Equivalent to beamsplitter.ABCD(3, 1, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd31y

Numeric ABCD matrix from port 3 to port 1 in the sagittal plane.

Equivalent to beamsplitter.ABCD(3, 1, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd34x

Numeric ABCD matrix from port 3 to port 4 in the tangential plane.

Equivalent to beamsplitter.ABCD(3, 4, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd34y

Numeric ABCD matrix from port 3 to port 4 in the sagittal plane.

Equivalent to beamsplitter.ABCD(3, 4, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd42x

Numeric ABCD matrix from port 4 to port 2 in the tangential plane.

Equivalent to beamsplitter.ABCD(4, 2, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd42y

Numeric ABCD matrix from port 4 to port 2 in the sagittal plane.

Equivalent to beamsplitter.ABCD(4, 2, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd43x

Numeric ABCD matrix from port 4 to port 3 in the tangential plane.

Equivalent to beamsplitter.ABCD(4, 3, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd43y

Numeric ABCD matrix from port 4 to port 3 in the sagittal plane.

Equivalent to beamsplitter.ABCD(4, 3, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property alpha: alpha : float, optional Angle of incidence (in degrees)

property alpha2

Angle of incidence on side 2 in degrees, i.e. port 3 and 4 side.

Returns

alpha2Symbol: Symbolic form of alpha on side 2. Use float() to convert to a numerical value if needed.

Raises

Will raise a TotalReflectionError if total internal reflection is occuring at this beamsplitter.

get_adjacent_port(p): Get the port adjacent (on the same side of the surface) as p.

property misaligned: misaligned : bool, optional When True the beamsplitter will be significantly misaligned and assumes any reflected beam is dumped. Transmissions will still occur.

optical_equations()

property phi: phi : float, optional Microscopic tuning of the beamsplitter (in degrees).

property plane: plane : str, optional Plane of incidence, either ‘xz’ or ‘yz’. Defaults to ‘xz’.

property refractive_index_1: Refractive index on size 1 (port 1 and 2)

property refractive_index_2: Refractive index on size 2 (port 3 and 4)

property xbeta: Yaw misalignment

property ybeta: Pitch misalignment

finesse.components.cavity module

Optical cavities with associated properties.

class finesse.components.cavity.Cavity(*args, **kwargs)

Bases: TraceDependency

Represents a cavity in an interferometer configuration.

This class stores the shortest round-trip path from the start node of the cavity (via a given node) back to the same node, and holds symbolic expressions for each physical attribute of the cavity. Numeric values corresponding to these attributes are obtained through the relevant properties.

Adding a Cavity to a Model results in the beam parameters of all nodes in the cavity path being set according to the cavity eigenmode (finesse.components.cavity.Cavity.q) when a beam trace is performed (e.g. at the start of a modal based simulation). The mode of the cavity is then also used as a trace starting point when setting beam parameters at nodes outside of the cavity - see Tracing the beam for details on the beam tracing algorithm.

Parameters

namestr

Name of newly created cavity.

sourceOpticalNode or Port

Node / Port that the cavity path starts from. If no via node is specified, then the cavity path will be given by the shortest path from source back to the component that owns source.

If a port is given then the output optical node of that port will be used as the source.

viaOpticalNode, optional

Node that the cavity path must traverse via; defaults to None.

Note that, unlike source, this cannot be a Port object as this would be ambiguous for beamsplitter type components - i.e. determination of which node to use cannot be assumed automatically.

prioritynumber, optional; default: 0

Priority value for beam tracing. Beam tracing dependencies are sorted in descending order of priority - i.e. higher priority value dependencies will be traced first. Any dependency with a priority value of zero will be traced, after non-zero priority dependencies, in alphabetic order of the dependency names.

property ABCD

The round-trip ABCD matrix of the cavity in both planes.

Getter:: Returns a numpy.ndarray with shape (2, 2, 2) of the cavity round-trip matrices in the tangential and sagittal planes, respectively (read-only).

property ABCDx

The tangential round-trip ABCD matrix of the cavity.

Getter:: Returns the cavity round-trip matrix in the tangential plane (read-only).

property ABCDy

The sagittal round-trip ABCD matrix of the cavity.

Getter:: Returns the cavity round-trip matrix in the sagittal plane (read-only).

property FSR

The free-spectral-range (FSR) of the cavity.

This quantity is defined as,

\[\mathrm{FSR} = \frac{c}{L}, \]

where \(c\) is the speed of light and \(L\) is the round trip optical path length of the cavity.

Getter:: Returns the cavity free-spectral-range (read-only).

property FWHM

The cavity full-width-half-maximum (FWHM).

This quantity is defined as,

\[\mathrm{FWHM} = \frac{\mathrm{FSR}}{\mathcal{F}}, \]

where \(\mathcal{F}\) is the cavity finesse.

Getter:: Returns the FWHM of the cavity (read-only).

Parameters

geometricbool: If true then only checks parameters which affect ABCD matrices.

Returns

flagbool: True if any parameter is changing (subject to the condition outlined above), False otherwise.

draw()

A string representation of the cavity route.

Returns

sstr: The node path of the cavity as a string.

property finesse

The finesse of the cavity.

This quantity is defined as,

\[\mathcal{F} = \frac{\pi \sqrt{\widetilde{l}}}{1 - \widetilde{l}}, \]

where \(\widetilde{l} = \sqrt{1 - L}\) and \(L\) is the cavity loss.

Getter:: Returns the cavity finesse (read-only).

property g

The stability of the cavity, in both planes, given by the \(g\)-factor:

\[g = \frac{A + D + 2}{4}, \]

where \(A\) and \(D\) are the relevant entries of the cavity round-trip ABCD matrix. The cavity is stable if the following condition is satisfied:

\[0 \leq g \leq 1. \]

Getter:: Returns a numpy.ndarray of the cavity stability in the tangential and sagittal planes, respectively (read-only).

generate_abcd_str()

Generates a string representation of the cavity round-trip ABCD matrix operations.

This can be useful for debugging purposes as the returned string will correspond exactly to the operation performed internally for calculating the round-trip matrices.

The format of each matrix symbol will be <comp>__<from_port>_<to_port>, e.g. the reflection at the rear (port two) surface of a mirror named ITM would be represented as ITM__p2_p2. The matrix multiplication is denoted via the @ symbol.

Returns

abcd_strstr: A string representing the operation to obtain the cavity round-trip ABCD matrix (in either plane).

get_exit_nodes()

Obtains a dictionary of source: target mappings where source -> target and target is an exit node of the cavity.

An exit node is defined to be a node that is not internal to the cavity, rather it is obtained on propagation from an internal node to outside the cavity.

Returns

exit_nodesdict: A dictionary of source: target mappings.

property gouy

The accumulated round-trip Gouy phase of the cavity in both planes (in degrees).

This is given by,

\[\psi_{\mathrm{rt}} = 2\,\arccos{\left( \mathrm{sgn}(B) \sqrt{g} \right)}, \]

where \(B\) is the corresponding element of the round-trip ABCD matrix and \(g\) is the cavity stability parameter returned by Cavity.g.

Getter:: Returns a numpy.ndarray of the accumulated round-trip Gouy phase in the tangential and sagittal planes, respectively (read-only).

property gouy_x

The round-trip Gouy phase in the tangential plane (in degrees).

If the cavity is not stable, then np.nan is returned.

Getter:: Returns the tangential plane round-trip Gouy phase (read-only).

Returns

figFigure: Handle to the figure.
axsaxes: The axis handles.

property pole

The pole-frequency of the cavity.

This quantity is defined as,

\[f_{\mathrm{pole}} = \frac{\mathrm{FWHM}}{2}, \]

where \(\mathrm{FWHM}\) is the full-width at half-maximum of the cavity resonance.

Getter:: Returns the cavity pole-frequency (read-only).

Returns

outBeamTraceSolution: An object representing the results of the tracing routine.

property via

Via node of the cavity.

Getter:: Returns the cavity via node (read-only).

property w0

The waist size of the cavity in both planes.

Getter:: Returns a numpy.ndarray of the cavity waist size in the tangential and sagittal planes, respectively (read-only).

property w0x

The waist size of the cavity in the tangential plane.

Equivalent to cavity.qx.w0.

Getter:: Returns the cavity waist size in the tangential plane (read-only).

property w0y

The waist size of the cavity in the sagittal plane.

Equivalent to cavity.qy.w0.

Getter:: Returns the cavity waist size in the sagittal plane (read-only).

property waistpos

The position of the cavity waist in both planes.

This distance to the waist is measured using the position of Cavity.source node as the origin.

Getter:: Returns a numpy.ndarray of the cavity waist position in the tangential and sagittal planes, respectively (read-only).

property waistpos_x

The waist position of the cavity in the tangential plane.

Equivalent to cavity.qx.z.

Getter:: Returns the cavity waist position in the tangential plane (read-only).

property waistpos_y

The waist position of the cavity in the sagittal plane.

Equivalent to cavity.qy.z.

Getter:: Returns the cavity waist position in the sagittal plane (read-only).

finesse.components.directional_beamsplitter module

Optical components performing directional redirection of beams.

class finesse.components.directional_beamsplitter.DirectionalBeamsplitter(*args, **kwargs)

Bases: Connector

Represents a directional beamsplitter optical component. Connections made between ports:

port 1 to port 3
port 3 to port 4
port 4 to port 2
port 2 to port 1

Parameters

namestr: Name of newly created directional beamsplitter.

optical_equations()

finesse.components.dof module

class finesse.components.dof.DOFWorkspace(owner, sim): Bases: ConnectorWorkspace

class finesse.components.dof.DegreeOfFreedom(*args, **kwargs)

Bases: Connector

property DC: DC state of degree of freedom

property amplitudes

Amplitudes a node is driving.

Getter:: Returns copy of the amplitudes a node is driving.

property dc_enabled

Whether all driving nodes have an associated DC parameter.

Getter:: Returns True if all driving nodes have an associated DC parameter that can be varied.

property drives

Nodes this degree of freedom is driving.

Getter:: Returns the nodes this degree of freedom drives.

property node_amplitude_pairs

finesse.components.electronics module

class finesse.components.electronics.Amplifier(*args, **kwargs)

Bases: Connector

eval(f)

fill(ws)

property gain: Gain

class finesse.components.electronics.ButterFilter(*args, **kwargs)

Bases: ZPKFilter

property analog

property btype

property frequency

property gain: Gain

property order

set_zpk()

class finesse.components.electronics.Cheby1Filter(*args, **kwargs)

Bases: ZPKFilter

property gain: Gain

class finesse.components.electronics.Filter(*args, **kwargs)

Bases: Connector

This is a generic Filter element that encapsulates some of the Scipy signal filter tools. The sys attribute is the filter object which can be ZPK, BA, or SOS.

Parameters

namestr: Name of element in the model
gainParameter: Overall floating point value gain to apply to the filter.

bode_plot(f=None, n=None, return_axes=False)

Plots Bode for this filter.

Parameters

foptional: Frequencies to plot for in Hz (Not radians)
nint, optional: number of points to plot

Returns

axis : Matplotlib axis for plot if return_axes=True

fill(ws)

property gain: gain : Parameter Overall floating point value gain to apply to the filter.

class finesse.components.electronics.FilterWorkspace: Bases: ConnectorWorkspace

class finesse.components.electronics.TestPoint(*args, **kwargs)

Bases: Connector

A simple component which has an arbitrary number of test nodes that can be connected to and from.

Examples

You could make an electronic element that has three ports:

>>> from finesse.components.electronics import TestPoint
>>> model.add(TestPoint('test', 'A', 'B', 'C'))

The element is called test. This has three ports called A, B, and C, each with a single node called io, as it can be outputed to inputted to.

class finesse.components.electronics.ZPKFilter(*args, **kwargs)

Bases: Filter

A zero-pole-gain filter element that is used for shaping signals in simulations. It is a two port element. p1 is the input port and p2 is the output port. Each one has a single node: p1.i and p2.o.

Parameters

namestr: Name of element in the model
zarray_like[float | Symbols]: A 1D-array of zeros. Use [] if none are required. By default these are provided in units of radians/s, not Hz.
parray_like[float | Symbols]: A 1D-array of poles. Use [] if none are required. By default these are provided in units of radians/s, not Hz.
k[float | Symbol], optional: Gain factor for the zeros and poles. If None then its value is automatically set to generate a unity gain at DC.
fQbool, optional: When True the zeros and poles can be specified in a tuple of (frequency, quality factor) for each pole and zero. This automatically adds the complex conjugate pair.
gainParameter: Overall gain for the filter. Differs from k as this is a Parameter so can be easily switched on/off or varied during a simulation.

Examples

Below are a few examples of using a ZPK filter in a simple simulation and plotting the output.

>>> import finesse
>>> finesse.init_plotting()
>>> model = finesse.Model()
>>> model.parse("""
... # Finesse always expects some optics to be present
... # so we make a laser incident on some photodiode
... l l1 P=1
... readout_dc PD l1.p1.o
... # Amplitude modulate a laser
... sgen sig l1.amp
...
... zpk ZPK_unity [] []
... link(PD.DC, ZPK_unity)
... ad unity ZPK_unity.p2.o f=fsig
...
... zpk ZPK_1 [] [-10*2*pi]
... link(PD.DC, ZPK_1)
... ad zpk1 ZPK_1.p2.o f=fsig
...
... zpk ZPK_2 [-10*2*pi] []
... link(PD.DC, ZPK_2)
... ad zpk2 ZPK_2.p2.o f=fsig
...
... # Using symbolics
... variable a 20*2*pi
... zpk ZPK_symbol [] [-1j*a, 1j*a] -1
... link(PD.DC, ZPK_symbol)
... ad symbol ZPK_symbol.p2.o f=fsig
...
... # Using gain parameter instead of k keeps the unity response at DC but
... # just flips the sign
... zpk ZPK_symbol2 [] [-1j*a, 1j*a] gain=-1
... link(PD.DC, ZPK_symbol2)
... ad symbol_gain ZPK_symbol2.p2.o f=fsig
...
... # Symbolics for an RC low pass filter
... variable R 100
... variable C 10u
... zpk ZPK_RC [] [-1/(R*C)]
... link(PD.DC, ZPK_RC)
... ad RC ZPK_RC.p2.o f=fsig
...
... fsig(1)
... """)

>>> sol = model.run("xaxis(fsig, log, 0.1, 10k, 1000)")
>>> sol.plot(log=True)

eval(f)

Calculate the value of this filter over some frequencies.

Parameters

farray_like: Frequencies in units of Hz

Returns

Harray_like: Complex valued filter output

property gain: gain : Parameter Overall gain for the filter. Differs from k as this is a Parameter so can be easily switched on/off or varied during a simulation.

property sys

The scipy sys object.

In this case it is a tuple of (zeros, poles, k). This does not convert any symbolics used into numerics.

finesse.components.frequency_loss module

A component that introduces some loss for particular frequencies or light, relative to the carrier frequency.

This can be used to introduce sideband imbalance, for example.

class finesse.components.frequency_loss.FrequencyLoss(*args, **kwargs)

Bases: Connector

Represents an unphysical element which introduces a loss and/or phase for a particular frequency.

Parameters

namestr: Name of newly created lens.
ffloat, optional: Frequency to apply loss and phase to.
lossfloat, optional: Fractional loss at the frequency
phasefloat, optional: Phase change at the frequency

property f: f : float, optional Frequency to apply loss and phase to.

property loss: loss : float, optional Fractional loss at the frequency

property phase: phase : float, optional Phase change at the frequency

class finesse.components.frequency_loss.FrequencyLossWorkspace(owner, sim): Bases: ConnectorWorkspace

finesse.components.gauss module

User-defined Gaussian beam tracing dependencies at a node.

class finesse.components.gauss.Gauss(*args, **kwargs)

Bases: TraceDependency

Beam parameter at a specific node of a model.

The following are legal initialisations of a Gauss object:

# Non-astigmatic
q = Gauss('name', node, q=q)
q = Gauss('name', node, w0=w0, z=z) # waist size and position
q = Gauss('name', node, zr=zr, z=z) # Rayleigh range and waist position
q = Gauss('name', node, w=w, Rc=Rc) # beam size and RoC
q = Gauss('name', node, w=w, S=S) # beam size and curvature

# Astigmatic
q = Gauss('name', node, qx=qx, qy=qy)
q = Gauss('name', node, w0x=wx, zx=zx, w0y=wy, zy=zy)
q = Gauss('name', node, zrx=zrx, zx=zx, zry=zry, zy=zy)
q = Gauss('name', node, wx=wx, Rcx=Rcx, wy=wy, Rcy=Rcy)
q = Gauss('name', node, wx=wx, Sx=Sx, wy=wy, Sy=Sy)

See gaussian.BeamParam for more detailed descriptions of these variables.

property is_changing

Whether the Gauss object is changing or not.

This is used internally when initialising simulation states.

property node

The optical node associated with the Gauss object.

Getter:: Returns the associated OpticalNode instance (read-only).

property qx

Tangential plane beam parameter.

Getter:: Returns the beam parameter in the tangential plane.
Setter:: Sets the beam parameter for the tangential plane.

property qy

Sagittal plane beam parameter.

Getter:: Returns the beam parameter in the sagittal plane.
Setter:: Sets the beam parameter for the sagittal plane.

property w0x: Waist size (x)

property w0y: Waist size (y)

property zx: Distance to waist (x)

property zy: Distance to waist (y)

finesse.components.general module

Top-level objects which specific optical, and otherwise, components should inherit from.

class finesse.components.general.Connector(*args, **kwargs)

Bases: ModelElement, ABC

Base class for any component which connects nodes together.

Internally it stores the nodes and the connections associated with the component. During the matrix build this class will then ensure that the matrix elements for each coupling requested are allocated and and the required matrix view for editing their values is retrieved.

The inheriting class should call _register_node and _register_coupling to define the connections it wants to use.

Parameters

namestr: Name of the new Connector instance.

ABCD(from_node, to_node, direction='x', symbolic=False, copy=True, retboth=False, allow_reverse=False)

Parameters

from_nodeOpticalNode or Port or str or int: Input node. If a port, or string repr of a port, is given then the input optical node of that port will be used.
to_nodeOpticalNode or Port or str or int: Output node. If a port, or string repr of a port, is given then the output optical node of that port will be used.
directionstr, optional; default: ‘x’: Direction of ABCD matrix computation, default is ‘x’ for tangential plane.
symbolicbool, optional; default: False: Whether to return the symbolic matrix (as given by equations above). Defaults to False such that the numeric matrix is returned.
copybool, optional; default: True: Whether to return a copy of ABCD matrix (or matrices if retboth is true). Defaults to True so that the internal matrix cannot be accidentally altered. Use caution if switching this flag off.
retbothbool, optional; default: False: Whether to return both the symbolic and numeric matrices as a tuple in that order.
allow_reversebool, optional: When True, if the coupling does not exist at the component from_node->to_node but to_node->from_node does exist, it will return the ABCD from that. Otherwise a NoCouplingError will be raised.

Returns

Mnumpy.ndarray: The ABCD matrix of the specified coupling for the mirror. This is symbolic if either of symbolic or retboth flags are True.
M2numpy.ndarray: Only returned if retboth is True, otherwise just M above is returned. This will always be the numeric matrix.

Raises

finesse.exceptions.NoCouplingError: If no coupling exists between from_node and to_node.
finesse.exceptions.NoABCDCoupling: If no ABCD matrix has been defined for the requested coupling.
finesse.exceptions.TotalReflectionError: Total reflection of a beam at a component when performing beam tracing.

property all_internal_connections: A dictionary of all the connections this element is making between its nodes.

property all_internal_optical_connections: A dictionary of all the optical connections this element is making between its nodes.

property borrows_nodes

Whether this element borrows node references from another.

When this is True the element may not create all of its own nodes and just link into one that already exists and is owned by another element.

check_coupling(from_node, to_node): Checks that a coupling exists between from_node -> to_node and raises a ValueError if not.

coupling_type(from_node, to_node)

Obtains the type of coupling (see CouplingType) between the two specified nodes at this component.

Parameters

from_nodeNode: Node which has a forwards coupling to to_node.
to_nodeNode: Node which has a backwards coupling from from_node.

Returns

coupling_tCouplingType: The type of coupling between the specified nodes.

property electrical_ports: tuple[Port, ...]

Retrieves the electrical ports available at the object.

Returns

tuple: Read-only tuple of the ports available at this object.

interaction_type(from_node, to_node)

Obtains the type of interaction (see InteractionType) between the two specified nodes at this component.

Parameters

from_nodeNode: Node which has a forwards coupling to to_node.
to_nodeNode: Node which has a backwards coupling from from_node.

Returns

interaction_tInteractionType: The type of interaction between the specified nodes.

is_valid_coupling(from_node, to_node): Flags whether the provided node coupling exists at this connector.

property mechanical_ports: tuple[Port, ...]

Retrieves the mechanical ports available at the object.

Returns

tuple: Read-only tuple of the ports available at this object.

property nodes

All the nodes of all the ports at this component. Order is likely to be the order in which the ports and nodes were created, but this is not guaranteed.

Returns

nodestuple(Node): Copy of nodes dictionary

property optical_nodes

The optical nodes stored by the connector.

Getter:: Returns a list of the stored optical nodes (read-only).

property optical_ports: tuple[Port, ...]

Retrieves the optical ports available at the object.

Returns

tuple: Read-only tuple of the optical ports available at this object.

property ports: tuple[Port, ...]

Retrieves the ports available at the object.

Returns

tuple: Read-only tuple of the ports available at this object.

register_abcd_matrix(M_sym, *couplings)

Register an ABCD matrix of the given symbolic form for a sequence of coupling(s).

Specifying several couplings for one M_sym means that all these node couplings will point to the same reference ABCDs — i.e. the matrices kept in the underlying ABCD matrix store will be the same blocks of memory.

Warning

This should only be used in the _resymbolise_ABCDs method of Connectors, when implementing a new component.

Parameters

M_symnumpy.ndarray

A 2x2 matrix of symbolic elements describing the analytic form of the ABCD matrix for the given coupling(s).

couplingssequence of tuples

Arguments of tuples giving the node couplings which are described by the given symbolic ABCD matrix M_sym.

These tuples can be of size two or three, with the first two elements always as the from_node -> to_node instances. The former case implies that both the tangential and sagittal plane ABCD matrix couplings are equal and so both directions ‘x’ and ‘y’ in the underlying matrices store will be set to the same values. Whilst the latter case, where the third element is either ‘x’ or ‘y’, sets just these direction keys to this matrix.

replace(sub: str, component: str | None = None, optical_ports: None | list[str] = None, mechanical_ports: None | list[str] = None, electrical_ports: None | list[str] = None, verbose: bool = False) → str

Unparse the model of this Connector and replace the Connector with a new section of katscript. Returns the katscript for the model with component replaced.

Parameters

substr

New section of katscript that will replace the katscript line defining the component to replace.

componentstr | None, optional

Replacement string for any references of the component name, by default None

optical_portsNone | list[str], optional

Replacement ports for any references of the component optical ports, by default None

mechanical_portsNone | list[str], optional

Replacement ports for any references of the component mechanical ports, by default None

electrical_portsNone | list[str], optional

Replacement ports for any references of the component electrical ports, by default None

verbosebool, optional

Whether to print a diff between the current and new KatScript,: by default False

Returns

str: KatScript with the component replaced.

Raises

FinesseException: When the component to replace is not of type Connector.

property signal_nodes

The signal nodes stored by the connector.

Getter:: Returns a list of the stored signal nodes (read-only).

class finesse.components.general.CouplingType(*values)

Bases: Enum

An enum describing the type of coupling between two nodes.

ELECTRICAL_TO_ELECTRICAL = 3

ELECTRICAL_TO_OPTICAL = 4

ELETRICAL_TO_MECHANICAL = 5

MECHANICAL_TO_ELECTRICAL = 8

MECHANICAL_TO_MECHANICAL = 6

MECHANICAL_TO_OPTICAL = 7

OPTICAL_TO_ELECTRICAL = 1

OPTICAL_TO_MECHANICAL = 2

OPTICAL_TO_OPTICAL = 0

class finesse.components.general.FrequencyGenerator

Bases: object

The base class for components which generate optical frequencies.

A component inheriting from this class will allow the model to query the component to ask what frequencies it wants to use. Frequency generation comes in the form of either a laser or something that modulates.

class finesse.components.general.InteractionType(*values)

Bases: Enum

An enum describing the type of interaction between two nodes.

REFLECTION = 0

TRANSMISSION = 1

class finesse.components.general.LocalDegreeOfFreedom(name, DC=None, AC_IN=None, DC_2_AC_scaling=None, AC_OUT=None)

Bases: object

A local degree of freedom definition that combines a DC parameter and AC nodes at some element. For example, this can pair a mirror tuning and it the AC mechanical nodes into one “Degree of Freedom” that can be referenced to scan, drive, or readout. Some DOFs do not have a DC equivalent so the DC part may be None. A DOF can have a different input (drive) and output (readout) signal node. This is used in more advanced cases such as suspension systems, where you drive some motion through a force/torque actuation on some part of the suspension but the readout is in displacement/rotation of the final optic.

Parameters

namestr: Name should be the full-name of the definition for a particular element, e.g. m1.dofs.z if this is wrong, then unparsing will not work correctly
DCParameter, optional: The DC equivlent of the AC signal node of an element, setting to None means no DC actuation happens.
AC_INSignalNode: The node that is driven for this degree of freedom, cannot be None.
DC_2_AC_scalingfloat, optional: Scaling factor relating the DC and AC parameter and nodes. For example, the scaling between phi (degrees) and mirror.mech.z (meters).
AC_OUTSignalNode, optional: The node that is read out to describe this degree of freedom, if None there is nothing to readout here.

property AC_IN_type

property AC_OUT_type

class finesse.components.general.MechanicalConnector(*args, **kwargs)

Bases: Connector

property connected_to: Connector: Component that this mechanical element is connected to

property mech_port: Port: Mechanical port that this component is using the nodes from

class finesse.components.general.NoiseGenerator

Bases: object

The base class for components which generate some kind of noise.

A component inheriting from this class will allow the model to query the component to ask what noise it generates.

property noises

class finesse.components.general.NoiseType(*values)

Bases: Enum

An enum describing the type of noise a component generates.

QUANTUM = 0

class finesse.components.general.Variable(*args, **kwargs)

Bases: ModelElement

The variable element acts slightly different to other elements. When added to a model it creates a new finesse.parameter.Parameter in the model it has been added to. This does the same as calling finesse.model.Model.add_parameter(). This new parameter can be used like a variable for making symbolic links to or for storing some useful number about the model.

See finesse.model.Model.add_parameter() for more details.

finesse.components.general.borrows_nodes(): Flags that a ModelElement will be making references to nodes owner by other elements, or borrows a reference.

finesse.components.general.determine_coupling_type(from_node, to_node)

Retrieves the type of coupling (see CouplingType) between two nodes.

Parameters

from_nodeNode: Node which couples into to_node.
to_nodeNode: Node which has a coupling from from_node.

Returns

coupling_tCouplingType: The type of coupling between the two given nodes.

finesse.components.general.unique_element()

Flags that this element type is unique in a model.

In other words, only one of these element types can be in a single model.

finesse.components.isolator module

Optical components performing directional suppression of beams.

class finesse.components.isolator.Isolator(*args, **kwargs)

Bases: Connector

Represents an isolator optical component with a suppression factor. Suppresses the light field transmitted from p2 to p1. The field from p1 to p2 is.

Parameters

namestr: Name of newly created isolator.
Sfloat: Power suppression in dB. Defaults to 0

property S: S : float Power suppression in dB. Defaults to 0

optical_equations()

property suppression_factor: float: Factor by which the light field transmitted from p2 to p1 is supressed.

finesse.components.laser module

Laser-type optical components for producing beams.

class finesse.components.laser.Laser(*args, **kwargs)

Bases: Connector, FrequencyGenerator

Represents a laser producing a beam with associated properties such as power and frequency.

Parameters

namestr: Name of the newly created laser.
Pfloat, optional: Power of the laser (in Watts), defaults to 1 W.
ffloat or Frequency, optional: Frequency-offset of the laser from the default (in Hz) or Frequency object. Defaults to 0 Hz offset.
phasefloat, optional: Phase-offset of the laser from the default, defaults to zero.
signals_onlybool, optional: When True, this laser component will only inject signal sidebands. They will use the current carrier value as a scaling terms but the carrier will not be injected into the simulation. This allows a user to just inject signal sidebands into a model.

Attributes

add_gouy_phasebool: When set to True the gouy phase of the current beam parameters values at the laser will be added to the optical field outputs during the simulation. When False, it will not. This can be used with set_output_field() to force a particular optical field output from a laser.

DEFAULT_POWER_COEFFS = {(0, 0): (1.0, 0.0)}

property P: P : float, optional Power of the laser (in Watts), defaults to 1 W.

property f: f : float or Frequency, optional Frequency-offset of the laser from the default (in Hz) or Frequency object. Defaults to 0 Hz offset.

get_output_field(homs)

Get optical field outputted as a HOM vector.

Returns the complex amplitude of the modes specified in homs. This does not respect the add_gouy_phase` attribute of the laser element and will always return the complex amplitude without the gouy phase. If the gouy phase is required then it is recommended to use a FieldDetector at the laser output with add_gouy_phase set to True.

Parameters

homssequence: Collection of (n, m) higher order modes to retrieve the output field for. Typically this is just the model.homs value. The output E vector will match the ordering of homs.

Returns

sequence: The output fields for homs. If a given (n, m) has no defined coefficients, its field defaults to 0.

optical_equations()

property phase: phase : float, optional Phase-offset of the laser from the default, defaults to zero.

property power_coeffs

The relative power factors and phase offsets for each HGnm mode.

Getter:: Returns the mode factors and phase offsets as a dict with the mode indices as keys. Read-only.

set_output_field(E, homs)

Set optical field outputted using HOM vector.

This changes the output power and mode content of the laser to match the requested E field.

Parameters

Esequence: The complex optical field amplitude for homs.
homssequence: Sequence of (n, m) higher order modes. Typically this is just the model.homs value. It should match the size of E.

Notes

If you do not want the gouy phase due to the current beam parameter values set at the laser to be added to the output, set the add_gouy_phase attribute of the laser element to False.

property signals_only: signals_only : bool, optional When True, this laser component will only inject signal sidebands. They will use the current carrier value as a scaling terms but the carrier will not be injected into the simulation. This allows a user to just inject signal sidebands into a model.

source_equation(node, f): Returns optical carrier field to inject for a simulation.

tem(n, m, factor, phase=0.0)

Distributes power into the mode HGnm.

Parameters

n, mint: Mode indices.
factorfloat: Relative power factor, modes with equal factor will have equivalent power distributed to them.
phasefloat, optional; default = 0.0: Phase offset for the field, in degrees.

Notes

This does not change the total power of the laser, rather, it redistributes this power into / out of the specified mode.

finesse.components.lens module

Transmissive optical components which focus or disperse light beams.

class finesse.components.lens.AstigmaticLens(*args, **kwargs)

Bases: BaseLens

Represents a thin astigmatic lens optical component with an associated focal lengths.

Notes

The specified focal length f is only accurate when the lens is attached to spaces with index of refraction close to 1. This component exists so that one can use the intuitive focal length parameter instead of having to set radii of curvature as with e.g. Mirror.

Parameters

namestr: Name of newly created lens.
fxfloat, optional: Focal length in x-z plane of the lens in metres; defaults to infinity.
fyfloat, optional: Focal length of y-z plane the lens in metres; defaults to infinity.

Attributes

OPD_mapfinesse.knm.maps.Map: A map that is used to describe the transverse spatial amplitude and phase variations beyond a simple lensing. Typically the map applied is describing the dnr/dT temperature effects in some substrate.

property fx: fx : float, optional Focal length in x-z plane of the lens in metres; defaults to infinity.

property fy: fy : float, optional Focal length of y-z plane the lens in metres; defaults to infinity.

class finesse.components.lens.BaseLens(*args, **kwargs)

Bases: Connector, ABC

Represents a thin lens optical component with an associated focal length.

Notes

The specified focal length f is only accurate when the lens is attached to spaces with index of refraction close to 1. This component exists so that one can use the intuitive focal length parameter instead of having to set radii of curvature as with e.g. Mirror.

Parameters

namestr: Name of newly created lens.
ffloat, optional: Focal length of the lens in metres; defaults to infinity.

Attributes

OPD_mapfinesse.knm.maps.Map: A map that is used to describe the transverse spatial amplitude and phase variations beyond a simple lensing. Typically the map applied is describing the dnr/dT temperature effects in some substrate.

ABCD(from_node, to_node, direction='x', symbolic=False, copy=True, retboth=False, allow_reverse=False)

Returns the ABCD matrix of the lens for the specified coupling.

This is given by,

\[M = \begin{pmatrix} 1 & 0 \\ -\frac{1}{f} & 1 \end{pmatrix}, \]

where \(f\) is the focal length of the lens.

See Connector.ABCD() for descriptions of parameters, return values and possible exceptions.

optical_equations()

class finesse.components.lens.Lens(*args, **kwargs)

Bases: BaseLens

Represents a thin lens optical component with an associated focal length.

Notes

The specified focal length f is only accurate when the lens is attached to spaces with index of refraction close to 1. This component exists so that one can use the intuitive focal length parameter instead of having to set radii of curvature as with e.g. Mirror.

Parameters

namestr: Name of newly created lens.
ffloat, optional: Focal length of the lens in metres; defaults to infinity.

Attributes

OPD_mapfinesse.knm.maps.Map: A map that is used to describe the transverse spatial amplitude and phase variations beyond a simple lensing. Typically the map applied is describing the dnr/dT temperature effects in some substrate.

property f: f : float, optional Focal length of the lens in metres; defaults to infinity.

finesse.components.mechanical module

class finesse.components.mechanical.FreeMass(*args, **kwargs)

Bases: MechanicalConnector

Simple free mass suspension of an object.

The object being suspended must have a mechanical port with nodes z, pitch, and yaw and forces F_z, F_pitch, and F_yaw.

property I_pitch: Moment of inertia (pitch)

property I_yaw: Moment of inertia (yaw)

fill(self, ws)

property mass: Mass

class finesse.components.mechanical.FreeMassWorkspace: Bases: ConnectorWorkspace

class finesse.components.mechanical.MIMOTFWorkspace(owner, sim, bool refill, unsigned int N_numerators)

Bases: ConnectorWorkspace

Workspace that contains MIMO transfer functions stored in a numerator/denominator basis.

H(self, int numerator_idx) → double complex

add_numerator(self, double[::1] num)

num_numerators

set_denominator(self, double[::1] denom)

set_s(self, double complex s) → void

class finesse.components.mechanical.Pendulum(*args, **kwargs)

Bases: MechanicalConnector

Simple pendulum suspension of an object.

The object being suspended must have a mechanical port with nodes z, pitch, and yaw and forces F_z, F_pitch, and F_yaw.

property I_pitch: Moment of inertia (pitch)

property I_yaw: Moment of inertia (yaw)

property Qpitch

property Qyaw

property Qz

fill(self, ws)

property fpitch

property fyaw

property fz

property mass: Mass

class finesse.components.mechanical.PendulumMassWorkspace: Bases: ConnectorWorkspace

class finesse.components.mechanical.SuspensionTFPlant(*args, **kwargs)

Bases: Connector

A customised suspension element that accepts arbitrary input and output nodes and a 2D array of control.TransferFunction objects that define a transfer function between each of them. See the Python Control package for more details on these.

Inputs and outputs must be named in the format port.name
Inputs must be unique to outputs
All plant transfer functions must have the same denominators

The mechanical port of other optical elements can be connected to this suspension by using the connections_to dictionary input. This takes the name of a port defined in this suspension and maps it to the mechanical port of another element.

The plant, inputs, and outputs cannot be changed once initialised. There is no KatScript interface for this component.

Parameters

namestr: Name of element
inputsarray_like, list: Sequence of inputs for this plant, should be strings of the format port.node
outputsarray_like, list: Sequence of outputs for this plant, should be strings of the format port.node
plantarray_like, list[list]: A 2D array of control.TransferFunction that describe the transfer function between each input to every output. Shape should be [len(outputs), len(inputs)]. Elements can also be None which means no coupling between each transfer function.
connections_todict[str: SignalNode], optional: Dict of port names at this suspension component and a mechanical port of some other element. Names of nodes at in each port should be identical. Keys of the dict should be in the format port.node. Values should be mechanical nodes of other elements.

bode(self, f, input_node, output_node, **kwargs): Make a bode plot for a particular node coupling for this suspension. See finesse.plotting.bode for the actual plotting method.

property connections_to

property inputs

property outputs

property plant

class finesse.components.mechanical.SuspensionZPK(*args, **kwargs)

Bases: MechanicalConnector

A suspension that models multiple poles and zeros for the z, yaw, or pitch motion of an optic. The user must ensure that minus signs are correct for this transfer function as well as defining complex conjugae pairs for physically correct behaviour.

ZPK terms are in units of radians/s.

Parameters

namestr: Element name
connected_toElement or mechanical port: Mechanical port or element to attach this suspension to
zpk_plantdict: Dictionary of {(output, input):(z,p,k)}

Examples

>>> import matplotlib.pyplot as plt
>>> import finesse
>>> from finesse.components.mechanical import SuspensionZPK
>>>
>>> model = finesse.Model()
>>> model.fsig.f = 1
>>> model.parse("m m1 R=1 T=0")
>>> zpk_plant = {}
>>> # F_z to z (longitudinal force to displacement)
>>> zpk_plant['z', 'F_z'] = ([], [10], 1)
>>> model.add(SuspensionZPK('sus', model.m1.mech, zpk_plant))
>>> out = model.run("frequency_response(geomspace(1m, 100, 100), m1.mech.F_z, m1.mech.z)")
>>> plt.loglog(out.f, abs(out['m1.mech.F_z', 'm1.mech.z']))

fill(self, ws)

class finesse.components.mechanical.SuspensionZPKWorkspace: Bases: ConnectorWorkspace

finesse.components.mechanical.eval_tf_vec(const double complex[::1] s, const double[::1] num, const double[::1] den, double complex[::1] out)

finesse.components.mirror module

Dielectric interface type components representing physical mirrors.

class finesse.components.mirror.Mirror(*args, **kwargs)

Bases: Surface

The mirror component represents a thin dielectric surface with associated properties such as reflectivity, tuning, and radius of curvature. Mirror components are nominally at normal incidence to the beams. It has two optical ports p1 and p2 which describes the two beams incident on either side of this surface. The surface normal points out of the mirror on the p1 side. A mirror also has a mechanical port mech which has nodes for longitudinal, yaw, and pitch motions. These mechanical nodes are purely for exciting small signal oscillations of the mirror. Static offsets in longitudinal displacements are set by the phi parameter (in units of degrees), yaw by the xbeta parameter, and pitch the ybeta parameter.

Parameters

namestr: Name of newly created mirror.
Rfloat, optional: Reflectivity of the mirror; defaults to 0.5.
Tfloat, optional: Transmittance of the mirror; defaults to 0.5.
Lfloat, optional: Loss of the mirror; defaults to 0.0.
phifloat, optional: Tuning of the mirror (in degrees); defaults to 0.0.
Rcfloat or container of two floats, optional: The radius of curvature of the mirror (in metres); defaults to a flat mirror (Rc=np.inf). Astigmatic mirrors can also be set with Rc=(Rcx, Rcy). A positive value results in a concave mirror on the p1 side of the mirror.
xbeta, ybetafloat, optional: Misalignment of the mirror in yaw and pitch in units of radians
misalignedbool, optional: When True the mirror will be significantly misaligned and assumes any reflected beam is dumped. Transmissions will still occur.
imaginary_transmissionbool, optional: Convention for the transmission and reflection reciprocity relations. ‘True’ uses imaginary transmission and equal real reflection from both sides ‘False’ uses real transmission, negative reflection from side 1, and positive reflection from side 2. defaults to True

Attributes

Attributes are set via the Python API and not available via KatScript.

surface_mapfinesse.knm.maps.Map: Decsribes the surface distortion of this mirror component. Coordinate system to the map is right-handed with the postive-z direction as the surface normal on the port 1 side of the mirror.

ABCD(from_node, to_node, direction='x', symbolic=False, copy=True, retboth=False, allow_reverse=False)

Returns the ABCD matrix of the mirror for the specified coupling.

In both cases below, the sign of the radius is defined such that \(R_c\) is negative if the centre of the sphere is located in the direction of propagation.

Transmission

For transmission this is given by,

\[M_{t} = \begin{pmatrix} 1 & 0 \\ \frac{n_2 - n_1}{R_c} & 1 \end{pmatrix}, \]

where \(n_2\) and \(n_1\) are the indices of refraction of the spaces connected to the mirror and \(R_c\) is the radius of curvature of the mirror.

The matrix for transmission in the opposite direction of propagation is identical.

Reflection

In the case of reflection the matrix is,

\[M_{r} = \begin{pmatrix} 1 & 0 \\ -\frac{2n_1}{R_c} & 1 \end{pmatrix}. \]

Reflection at the back surface can be described by the same type of matrix by setting the \(C\) element to \(C = 2n_2/R_c\).

See Connector.ABCD() for descriptions of parameters, return values and possible exceptions.

property L: L : float, optional Loss of the mirror; defaults to 0.0.

property R: R : float, optional Reflectivity of the mirror; defaults to 0.5.

property Rcx: Radius of curvature (x)

property Rcy: Radius of curvature (y)

property T: T : float, optional Transmittance of the mirror; defaults to 0.5.

property abcd11x

Numeric ABCD matrix from port 1 to port 1 in the tangential plane.

Equivalent to mirror.ABCD(1, 1, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd11y

Numeric ABCD matrix from port 1 to port 1 in the sagittal plane.

Equivalent to mirror.ABCD(1, 1, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd12x

Numeric ABCD matrix from port 1 to port 2 in the tangential plane.

Equivalent to mirror.ABCD(1, 2, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd12y

Numeric ABCD matrix from port 1 to port 2 in the sagittal plane.

Equivalent to mirror.ABCD(1, 2, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd21x

Numeric ABCD matrix from port 2 to port 1 in the tangential plane.

Equivalent to mirror.ABCD(2, 1, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd21y

Numeric ABCD matrix from port 2 to port 1 in the sagittal plane.

Equivalent to mirror.ABCD(2, 1, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd22x

Numeric ABCD matrix from port 2 to port 2 in the tangential plane.

Equivalent to mirror.ABCD(2, 2, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd22y

Numeric ABCD matrix from port 2 to port 2 in the sagittal plane.

Equivalent to mirror.ABCD(2, 2, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property misaligned: misaligned : bool, optional When True the mirror will be significantly misaligned and assumes any reflected beam is dumped. Transmissions will still occur.

optical_equations()

property phi: phi : float, optional Tuning of the mirror (in degrees); defaults to 0.0.

property refractive_index_1: Refractive index on size 1 (port 1)

property refractive_index_2: Refractive index on size 2 (port 2)

property xbeta: Yaw misalignment

property ybeta: Pitch misalignment

finesse.components.modulator module

Optical components performing modulation of beams.

class finesse.components.modulator.Modulator(*args, **kwargs)

Bases: Connector, FrequencyGenerator

Represents a modulator optical component with associated properties such as modulation frequency, index and order.

Parameters

namestr: Name of newly created modulator.
ffloat or Frequency, optional: Frequency of the modulation (in Hz) or Frequency object.
midxfloat: Modulation index, >= 0.
orderint, optional: Maximum order of modulations to produce. Must be 1 for amplitude modulation. Defaults to 1.
mod_typestr, optional: Modulation type, either ‘am’ (amplitude modulation) or ‘pm’ (phase modulation). Defaults to ‘pm’.
phasefloat, optional: Relative phase of modulation (in degrees). Defaults to 0.0.
positive_onlybool, optional: If True, only produce positive-frequency sidebands. Defaults to False.

property f: f : float or Frequency, optional Frequency of the modulation (in Hz) or Frequency object.

property midx: midx : float Modulation index, >= 0.

property mod_type: mod_type : str, optional Modulation type, either ‘am’ (amplitude modulation) or ‘pm’ (phase modulation). Defaults to ‘pm’.

optical_equations()

property order: order : int, optional Maximum order of modulations to produce. Must be 1 for amplitude modulation. Defaults to 1.

property phase: phase : float, optional Relative phase of modulation (in degrees). Defaults to 0.0.

property positive_only: positive_only : bool, optional If True, only produce positive-frequency sidebands. Defaults to False.

finesse.components.node module

Objects for connecting and registering connections between components.

class finesse.components.node.Node(name, port, node_type, direction)

Bases: object

Represents a specific connection at a component.

Mathematically a node represents a single equation in the interferometer matrix.

A node can only be owned by a single component instance - with weak references stored by the connected components.

Parameters

namestr: Name of newly created node.
componentPort: The port that this node belongs to.
node_typeNodeType: Physical node type.

property component: ModelElement

The component which has ownership of this node.

Getter:: Returns the component that this node belongs to (read-only).

property connections

Connections of this node.

Getter:: Returns a collection of Space, Wire, or DegreeOfFreedom objects attached to this node (read-only).

property direction

NodeDirection of this node.

This is largely a description to help understand how external information flow in and out of a component. Inside a component all nodes will couple to one another in more complex ways.

Input nodes are those going into a component, whereas output describe those leaving. For example incident and reflected light fields.

Bidrectional takes information either direction. For example a mechanical degree of freedom, external forces can be applied to it, or its motion can be coupled to some external system.

Getter:: Returns the directionality of the node (read-only).

property full_name

Full name.

Getter:: Returns a full name of the node: {component name}.{port name}.{node name}

property is_input

Flag indicating whether this node is an input to the associated component.

Getter:: Returns True if the field at this node goes into self.component (read-only).

is_neighbour(node)

Checks if node is a connected by an edge to this node.

Parameters

nodeNode: Node with which to check connection.

Returns

flagbool: True if node is connected to this node, False otherwise.

property name

Name of the node object.

Getter:: Returns the name of the node (read-only).

property port: Port

Port this node is attached to.

Getter:: Returns the port of this node (read-only).

property port_name

Port name.

Getter:: Returns a shortened name of the node: {port name}.{node name}

property tag

Tagged name of the node object.

Getter:: Returns the tagged (user-defined) name of the node (read-only).

property type

NodeType of the node object.

Getter:: Returns the node-type of the node (read-only).

class finesse.components.node.NodeDirection(*values)

Bases: Enum

Enum describing the direction that information at a Node flows.

This is largely a description to help understand how external information flows in and out of a component. Inside a component all nodes will couple to one another in more complex ways.

Input nodes are those going into a component, whereas output describe those leaving. For example incident and reflected light fields.

Bidrectional takes information either direction. For example a mechanical degree of freedom, external forces can be applied to it, or its motion can be coupled to some external system.

BIDIRECTIONAL = 2

INPUT = 0

OUTPUT = 1

class finesse.components.node.NodeType(*values)

Bases: Enum

Enum describing the physical connection type of a Node

ELECTRICAL = 1

MECHANICAL = 2

OPTICAL = 0

class finesse.components.node.OpticalNode(name, port, direction)

Bases: Node

Represents a specific optical port connection at a component.

OpticalNodes also have additional physical properties such as the beam parameter (of type BeamParam) at the nodes’ position within the interferometer.

Parameters

namestr: Name of the optical node.
portPort: The port that this node belongs to.
directionNodeDirection: True if the field at this node is going into the component.

static get_opposite_direction(node)

Returns the opposite direction of a node from either a Node object or a full string name qualifier for a node, component.port.direction l1.p1.o.

Parameters

node[str | Node]: Node to invert

property opposite

The opposite direction node.

Getter:: Returns the opposite direction node to this one.

property q

Beam parameter value at this node.

Getter:: Returns the beam parameter at this node. If the beam parameters in the tangential and sagittal planes are different then it returns a tuple of the two parameters.
Setter:: Sets the beam parameter at this node. If the argument provided is a 2-tuple then the parameter is set astigmatically for the node.

property qx

Beam parameter value in the tangential plane.

Getter:: Returns the beam parameter at the node in the tangential plane.
Setter:: Sets the beam parameter at the node in the tangential plane.

property qy

Beam parameter value in the sagittal plane.

Getter:: Returns the beam parameter at the node in the sagittal plane.
Setter:: Sets the beam parameter at the node in the sagittal plane.

property space

A reference to the Space object attached to this node.

Getter:: Returns a reference to the Space object attached to the node (read-only).

class finesse.components.node.Port(name, component, node_type)

Bases: Freezable

A collection of all the nodes at a specific point/surface of a component.

Parameters

namestr: Name of newly created node.
componentSub-class of Connector: The component that this node belongs to.
node_typeNodeType: Physical node type.

property attached_to

Components that this port is attached to. Optical ports are only ever connected to Space elements. Ports containing signal nodes can have multiple connections and returns a Set.

Getter:: Returns the component this port is attached to, or returns None if no such connected component exists. Signal ports return a Set of components attached (read-only).

property component: ModelElement

The component which has ownership of this port.

Getter:: Returns the component that this port belongs to (read-only).

property enabled

property full_name

Getter:: Returns a full name of the port: {component name}.{port name}

get_unique_node(predicate: Callable[[Node], bool])

Returns the unique node at this port that satisfies the provided predicate. If multiple nodes satisfy this predicate then a RuntimeError is raised.

Parameters

predicateCallable[[Node], bool]: A callable that accepts a Node and returns a boolean value

Examples

Selecting a unique output node:: port.get_unique_node(lambda node: not node.is_input)

property is_connected

Flag indicating whether the port is attached to another component.

Getter:: Returns true if this port is attached to another component (read-only).

property name

Name of the port object.

Getter:: Returns the name of the port (read-only).

node(name): Get a node at this port by its name.

property nodes

Nodes associated with the port.

Getter:: Returns a tuple of the associated nodes at this port (read-only).

property refractive_index

If the port is an Optical port, this will return a symbolic value for the refractive index at this port. The refractive index is set by the Space elements that are attached to it.

Returns

nrSymbol: Symbolic value for refractive index

property space

Space that the port is attached to. Equivalent to Port.attached_to.

Getter:: Returns the space that this port is attached to (read-only).

property type

NodeType of the port object.

Getter:: Returns the node-type of the port (read-only).

class finesse.components.node.SignalNode(name, port, direction, node_type)

Bases: Node

Represents a specific small signal degree of freedom. A signal is some small AC oscillation in some property, such as longitudinal motion, voltage, laser amplitude, etc.

Parameters

namestr: Name of the mechanical motion.
portPort: The port that this node belongs to.
num_frequenciesint: Number of mechanical frequencies to model

property frequencies

property num_frequencies

finesse.components.nothing module

Contains the class Nothing which represents an empty/null point in a configuration.

class finesse.components.nothing.Nothing(*args, **kwargs)

Bases: Connector

Represents an empty point in the interferometer configuration.

Nothing is just some point in space that can be connected to. For example, you can use this to propagate a beam from some component out to some arbitrary point to make a measurement at. You can also use this to split spaces up, if you wanted to measure something inbetween two components. It can also be used to replace a component, for example if you want to remove a lens or a mirror in some beam path.

Parameters

namestr: Name of newly created nothing.

optical_equations()

class finesse.components.nothing.NothingWorkspace(owner, sim): Bases: ConnectorWorkspace

finesse.components.optical_bandpass module

class finesse.components.optical_bandpass.OpticalBandpassFilter(*args, **kwargs)

Bases: Connector

An idealised optical bandpass filter that will transmit an optical frequency around some central frequency with a 3dB bandwidth.

Notes

Currently this is a classical component. No quantum noise losses are applied to any filtered fields or modes, which means no additional vaccum noise is injected back into the system for this lost information.

Parameters

namestr: Name of element
fcfloat, symbol: Central frequency
bandwidthfloat, symbol: Filter 3dB bandwidth
filter_hom[tuple | None], optional: Individual higher order modes can be filtered and transmitted by setting this to a tuple of (n, m). If None then no mode filtering is done. This cannot be changed during a simulation.

property bandwidth: bandwidth : float, symbol Filter 3dB bandwidth

property fc: fc : float, symbol Central frequency

finesse.components.readout module

A components sub-module containing classes for detecting intensity fluctuations at a physical point in a model.

These Readout components essentially describe baseband and broadband detectors such as DC and RF demodulated photodiodes typically used in optical experiments.

class finesse.components.readout.ReadoutDC(*args, **kwargs)

Bases: _Readout

A Readout component which represents a photodiode measuring the intensity of some incident field. Audio band intensity signals present in the incident optical field are converted into an electrical signal and output at the self.DC port, which has a single self.DC.o node.

See Readouts for more information.

Parameters

namestr

Name of the readout component

optical_nodeNode | Port | None, optional

Optical node this readout should look at. Because the readout borrows the node, it can be connected anywhere in the model, like a detector. When passing None, the readout should be connected explicitly with a finesse.components.space.Space or with finesse.model.Model.link() command (and then only a single readout can be connected per port).

pdtypestr | dict | None, optional

A name of a pdtype definition or a dict representing a pdtype definition,: by default None. See Segmented photodiodes

output_detectorsbool, optional

Whether to add a PowerDetector and a QuantumShotNoiseDetector to the solution object, by default False

Raises

TypeError: When optical_node is not a Port or a Node object, or the NodeType is not NodeType.Optical

outputs: ReadoutDCOutputs

class finesse.components.readout.ReadoutDCOutputs(readout: ReadoutDC): Bases: ReadoutOutputs

class finesse.components.readout.ReadoutDetectorOutput(*args, **kwargs)

Bases: ModelElement

A placeholder element that represents a detector output generated by a Readout element.

Notes

These should not be created directly by a user. It is internally created and added by a Readout component.

property readout

class finesse.components.readout.ReadoutOutputs: Bases: ABC

class finesse.components.readout.ReadoutRF(*args, **kwargs)

Bases: _Readout

A readout component which represents a demodulated photodiode. The self.I and self.Q electrical ports contain the signal of the two quadratures.

See Readouts for more information.

Parameters

namestr

Name of the readout component

optical_nodeNode | Port | None, optional

Optical node this readout should look at. Because the readout borrows the node, it can be connected anywhere in the model, like a detector. When passing None, the readout should be connected explicitly with a finesse.components.space.Space or with finesse.model.Model.link() command (and then only a single readout can be connected per port).

ffloat, optional

Demodulation frequency in Hz, by default 0

phasefloat, optional

Demodulation phase in degrees, by default 0

output_detectorsbool, optional

Whether to add a PowerDetector (DC), two PowerDetectorDemod1 ‘s (I and Q) and a QuantumShotNoiseDetectorDemod1 to the solution object, by default False

pdtypestr | dict | None, optional

A name of a pdtype definition or a dict representing a pdtype definition,: by default None. See Segmented photodiodes

property f: f : float, optional Demodulation frequency in Hz, by default 0

outputs: ReadoutRFOutputs

property phase: phase : float, optional Demodulation phase in degrees, by default 0

class finesse.components.readout.ReadoutRFOutputs(readout: ReadoutRF): Bases: ReadoutOutputs

class finesse.components.readout.ReadoutWorkspace: Bases: ConnectorWorkspace

finesse.components.replace module

class finesse.components.replace.ConnectorReplacer(katscript, connector: Connector)

Bases: object

replace(sub: str, component: str | None = None, optical_ports: None | list[str] = None, mechanical_ports: None | list[str] = None, electrical_ports: None | list[str] = None, verbose: bool = False) → str

exception finesse.components.replace.MissingReplacementError(message, **kwargs): Bases: FinesseException

finesse.components.replace.green(text, html=False)

finesse.components.replace.print_diff(old: str, new: str) → None

finesse.components.replace.red(text, html=False)

finesse.components.signal module

Signal-type electrical component for producing signal inputs.

class finesse.components.signal.SignalGenerator(*args, **kwargs)

Bases: Connector

Represents a signal generator which produces a signal with a given amplitude and phase.

Parameters

namestr: Name of newly created signal generator.
node.class:finesse.components.node.Node: A node to inject a signal into.
amplitudefloat, optional: Amplitude of the signal in volts.
phasefloat, optional: Phase-offset of the signal from the default in degrees, defaults to zero.

property amplitude: amplitude : float, optional Amplitude of the signal in volts.

property f: Signal frequency being injected, is always the fsig of the model.

property node

Change the node the signal generator injects into.

Setter:: Change the node the signal generator injects into.

property phase: phase : float, optional Phase-offset of the signal from the default in degrees, defaults to zero.

finesse.components.space module

Space-type objects representing physical distances between components.

class finesse.components.space.Space(*args, **kwargs)

Bases: Connector

Represents a space between two components in the interferometer configuration, with a given length and index of refraction.

There can be many spaces in a model which are not of much interest and do not need to be referred to. For example, the link command will create spaces between components without giving an explicit name, just specifying a distance between them.

All Space elements are added to the Model’s .spaces namespace so they can all easily be iterated over. You can also find spaces which had no name specified and thus have an autogenerated name. User specified Space’s with names will be put in the main Model namespace so that they can be accessed like any other element in the model.

Parameters

namestr, optional: Name of newly created space. If not specified, a name is automatically generated.
portA, portBPort: Ports to connect.
Lfloat, optional: Geometric length of newly created Space instance; defaults to 0.
nrfloat, optional: Index of refraction of newly created Space instance; defaults to 1.0.
user_gouy_x, user_gouy_yfloat, optional: User-defined gouy phase to override the calculated value.

ABCD(from_node, to_node, direction='x', symbolic=False, copy=True, retboth=False, allow_reverse=False)

Returns the ABCD matrix of the space for the specified coupling.

This is given by,

\[M = \begin{pmatrix} 1 & \frac{L}{n_r} \\ 0 & 1 \end{pmatrix}, \]

where \(L\) is the length of the space and \(n_r\) is the index of refraction.

See Connector.ABCD() for descriptions of parameters, return values and possible exceptions.

property L: L : float, optional Geometric length of newly created Space instance; defaults to 0.

property abcd

Numeric ABCD matrix.

Equivalent to any of space.ABCD(1, 2, "x"), space.ABCD(2, 1, "x"), space.ABCD(1, 2, "y"), space.ABCD(2, 1, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix (read-only).

connect(portA, portB)

Sets the ports of this Space.

Parameters

portAPort, optional: Port to connect
portBPort, optional: Port to connect

gouy(q1, q2)

Computes the Gouy phase in degrees from beam parameters.

Parameters

q1complex, BeamParam: Starting beam parameter
q2complex, BeamParam: Ending beam parameter

Returns

outfloat: Gouy phase (in degrees)

property gouy_x

property gouy_y

property nr: nr : float, optional Index of refraction of newly created Space instance; defaults to 1.0.

optical_equations()

Calculates the optical equations for the space component.

Returns

dict: A dictionary containing the optical equations for the space component.
The keys match the optical couplings defined by the Space, and the values represent the corresponding complex coupling equations.

property portA

property portB

replace(*args, **kwargs) → str

Unparse the model of this Connector and replace the Connector with a new section of katscript. Returns the katscript for the model with component replaced.

Parameters

substr

New section of katscript that will replace the katscript line defining the component to replace.

componentstr | None, optional

Replacement string for any references of the component name, by default None

optical_portsNone | list[str], optional

Replacement ports for any references of the component optical ports, by default None

mechanical_portsNone | list[str], optional

Replacement ports for any references of the component mechanical ports, by default None

electrical_portsNone | list[str], optional

Replacement ports for any references of the component electrical ports, by default None

verbosebool, optional

Whether to print a diff between the current and new KatScript,: by default False

Returns

str: KatScript with the component replaced.

Raises

FinesseException: When the component to replace is not of type Connector.

property user_gouy_x: Gouy phase (x)

property user_gouy_y: Gouy phase (y)

finesse.components.squeezer module

Squeezer-type optical components for producing squeezed light inputs.

class finesse.components.squeezer.Squeezer(*args, **kwargs)

Bases: Connector, FrequencyGenerator, NoiseGenerator

Represents a squeezer producing a squeezed-light beam with a given squeezing in decibels and angle. The upper and conjugate of the lower sidebands can be excited in a signal analysis by injecting into the .upper and .lower_conj signal nodes.

Parameters

namestr: Name of the newly created squeezer.
dbfloat: Squeezing factor (in amplitude decibels). 6dB gives a factor of 2 reduction in noise.
ffloat or Frequency, optional: Frequency-offset of the squeezer from the default (in Hz) or Frequency object. Defaults to 0 Hz offset.
anglefloat, optional: Squeezing angle (in degrees). Defaults to zero.

property angle: angle : float, optional Squeezing angle (in degrees). Defaults to zero.

property db: db : float Squeezing factor (in amplitude decibels). 6dB gives a factor of 2 reduction in noise.

property f: f : float or Frequency, optional Frequency-offset of the squeezer from the default (in Hz) or Frequency object. Defaults to 0 Hz offset.

property lower

finesse.components.surface module

class finesse.components.surface.Surface(*args, **kwargs)

Bases: Connector

Abstract optical surface interface providing an object with common properties for Mirror and Beamsplitter to inherit from.

Parameters

namestr: Name of newly created surface.
Rfloat, optional: Reflectivity of the surface.
Tfloat, optional: Transmissivity of the surface.
Lfloat, optional: Loss of the surface.
phifloat, optional: Microscopic tuning of the surface (in degrees).
Rcfloat, optional: Radius of curvature (in metres); defaults to numpy.inf to indicate a planar surface. An astigmatic surface can be set with Rc = (Rcx, Rcy).

property L: L : float, optional Loss of the surface.

property R: R : float, optional Reflectivity of the surface.

property Rc

The radius of curvature of the mirror in metres, for both the tangential and sagittal planes.

Getter:: Returns values of both planes’ radii of curvature as a numpy.ndarray where the first element is the tangential plane RoC and the second element is the sagittal plane RoC.
Setter:: Sets the radius of curvature.

Examples

The following sets the radii of curvature of an object m, which is a sub-instance of Surface, in both directions to 2.5 m:

>>> m.Rc = 2.5

Whilst this would set the radius of curvature in the x-direction (tangential plane) to 2.5 m and the radius of curvature in the y-direction (sagittal plane) to 2.7 m:

>>> m.Rc = (2.5, 2.7)

property Rcx: Radius of curvature (x)

property Rcy: Radius of curvature (y)

property T: T : float, optional Transmissivity of the surface.

actuate_roc(dioptres, direction=('x', 'y'))

Actuate on the radius of curvature (RoC) of the surface with a specified dioptre shift.

Sets the RoC to a new value, \(R_2\), via,

\[R_2 = \frac{2}{d + \frac{2}{R_1}},\]

where \(R_1\) is the current RoC and \(d\) is the dioptre shift (i.e. the dioptre argument).

By default, both planes of curvature are shifted. To shift, e.g., only the tangential plane, specify direction="x".

Parameters

dioptresfloat: Shift in surface RoC in dioptres.
directiontuple or str, optional; default: (“x”, “y”): RoC plane to shift, defaults to both tangential and sagittal.

check_rtl()

property phi: phi : float, optional Microscopic tuning of the surface (in degrees).

set_RTL(R=None, T=None, L=None)

Set the values for the R, T and L properties of the surface.

One of the following combination must be specified:

R and T or,

R and L or,

T and L or,

R and T and L

In the first three cases, the remaining parameter is set via the condition,

\[R + T + L = 1 \]

Parameters

Rscalar: Value of the reflectivity to set.
Tscalar: Value of the transmissivity to set.
Lscalar: Value of the loss to set.

Raises

ValueError

If a combination other than one of the above is specified.

Or if R, T and L are all given but they sum to anything other than one.

property xbeta: Misalignment (x)

property ybeta: Misalignment (y)

finesse.components.telescope module

class finesse.components.telescope.Telescope(*args, **kwargs)

Bases: Connector

This component represents a perfectly matching and adapting telescope. It will not change the beam parameter on transmission of the component and any field coming in will be transmitted to the other side into the other beam parameter. This should be used in cases when you want to connect to optical systems but do not want to design a complicated optical telescope system to mode-match them both, or in cases where one system has a changing parameter but you don’t care about the details of the telescope.

No beam is traced through the telescope so you must specify a beam parameter or a cavity on both sides of the telescope. If not, a tracing error will occur.

Currently no losses, mismatch, or misalignments can be induced at this telescope. There is no accumulated Gouy phase or plane-wave propagation phase.

Parameters

namestr: Name of newly created telescope

class finesse.components.telescope.TelescopeWorkspace(owner, sim): Bases: ConnectorWorkspace

finesse.components.trace_dependency module

Base class for dependencies of beam tracing routines.

class finesse.components.trace_dependency.TraceDependency(*args, **kwargs)

Bases: ModelElement

Base for classes which are dependency objects of beam tracing.

Both Cavity and Gauss inherit from this class.

Parameters

namestr: Name of newly created trace dependency.
prioritynumber, optional; default: 0: Priority value for beam tracing. See TraceDependency.priority.

make_final()

Give this trace dependency the lowest priority in the model.

Internally this will set the priority of this dependency to the current lowest priority in the model minus one.

property priority

The priority value of the dependency.

Larger values indicate higher priority for beam tracing. The list Model.trace_order is sorted in descending order of trace dependency priority values. Dependencies with equal priority values will be ordered alphabetically by their names.

Getter:: Returns the priority value.
Setter:: Sets the priority value and re-sorts the associated Model.trace_order accordingly.

take_priority()

Give this trace dependency the highest priority in the model.

Internally this will set the priority of this dependency to the current highest priority in the model plus one.

finesse.components.wire module

Wire-type objects representing electrical connections between components.

class finesse.components.wire.Wire(*args, **kwargs)

Bases: Connector

A wire represents a flow of information between signal nodes. It connects two specific signal nodes. Signal nodes have a direction associated with them: input, output, or bidirectional. Depending on what direction each node has depends on what the wire will setup when it is connected. When connecting ports the wire will look at the name of each node in the port and connect nodes with the same name.

Parameters

namestr, optional: Name of newly created wire.
nodeA, nodeBSignalNode: Signal nodes to connect together.
delayfloat, optional: A delay time for the signal to flow from A to B in seconds
gainfloat, optional: A scaling factor that can be used to scale the output relative to the input.

connect(A, B)

Connects A to B signal nodes together with a Wire element. If A or B are ports then the first node is selected from the port to connect. If A or B have more than one node then you should specify.

explicitly which one to use - an exception will be raised in this case.

Parameters

ASignalNode or Port: First signal node or Electrical port with a single node
BSignalNode or Port: Second signal node or Electrical port with a single node

property delay: delay : float, optional A delay time for the signal to flow from A to B in seconds

fill(ws)

property gain: gain : float, optional A scaling factor that can be used to scale the output relative to the input.

property nodeA

property nodeB

class finesse.components.wire.WireWorkspace: Bases: ConnectorWorkspace

finesse.components.workspace module

class finesse.components.workspace.ConnectionSetting(*values)

Bases: IntFlag

DIAGONAL = 1

DISABLED = 0

MATRIX = 2

class finesse.components.workspace.Connections

Bases: object

This is a container object for storing the connection submatrices defined by a component. This is used in the default case where no optimised C class is provided.

class finesse.components.workspace.ConnectorCallbacks(*values)

Bases: IntFlag

FILL_INPUT_NOISE = 8

FILL_MATRIX = 1

FILL_NOISE = 4

FILL_RHS = 2

class finesse.components.workspace.ConnectorMatrixSimulationInfo(connections=None, noise_sources=None)

Bases: object

add_fill_function(self, callback, bool refill)

This adds a callback function that will be used by the model to fill the matrix elements. This can either be a Python function or cdef wrapped with FillFuncWrapper.

Parameters

callbackCallable or FillFuncWrapper: Callback for fill function
refillboolean: Flags that this fill function will need to be called multiple times during simulation to refill the simulation matrix

callback_flag

connection_settings

connections

noise_sources

set_fill_noise_function(self, noise_type, callback): This sets the callback function that will be used by the model to fill the noise matrix elements. This can either be a Python function, which accepts a

set_fill_quantum_noise_input_function(self, callback): This sets the callback function that will be used by the model to fill the quantum noise matrix elements due to input nodes.

set_fill_rhs_fn(self, callback): This sets the callback function that will be used by the model to fill the RHS vector elements. This can either be a Python function or cdef wrapped with FillFuncWrapper.

class finesse.components.workspace.ConnectorWorkspace(owner, sim, carrier_connections=None, signal_connections=None, values=None, noise_sources=None)

Bases: ABCDWorkspace

This workspace represents the basic container for storing details for modelling Connector elements - those which form edges and nodes in a model.

carrier

input_noise

output_noise

signal

class finesse.components.workspace.FillFuncWrapper

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_fill(ConnectorWorkspace ptr_ws) noexcept:
>>>    cdef MirrorWorkspace ws = <MirrorWorkspace>ptr_ws
>>>    ...
>>>
>>> fill = FillFuncWrapper.make_from_ptr(c_fill)

class finesse.components.workspace.NoiseInfo(int num_nodes, int num_frequencies): Bases: object

class finesse.components.workspace.NoiseSources

Bases: object

This is a container object for storing the noise submatrices defined by a component. This is used in the default case where no optimised C class is provided.

Module contents

The components module contains all the component type of an interferometer configuration including the general objects required to connect them and register node connections.

These include not only optical components such as mirrors and lasers but also electrical and mechanical component types found in physical interferometers.

class finesse.components.Amplifier(*args, **kwargs)

Bases: Connector

eval(f)

fill(ws)

property gain: Gain

class finesse.components.AstigmaticLens(*args, **kwargs)

Bases: BaseLens

Represents a thin astigmatic lens optical component with an associated focal lengths.

Notes

The specified focal length f is only accurate when the lens is attached to spaces with index of refraction close to 1. This component exists so that one can use the intuitive focal length parameter instead of having to set radii of curvature as with e.g. Mirror.

Parameters

namestr: Name of newly created lens.
fxfloat, optional: Focal length in x-z plane of the lens in metres; defaults to infinity.
fyfloat, optional: Focal length of y-z plane the lens in metres; defaults to infinity.

Attributes

OPD_mapfinesse.knm.maps.Map: A map that is used to describe the transverse spatial amplitude and phase variations beyond a simple lensing. Typically the map applied is describing the dnr/dT temperature effects in some substrate.

property fx: fx : float, optional Focal length in x-z plane of the lens in metres; defaults to infinity.

property fy: fy : float, optional Focal length of y-z plane the lens in metres; defaults to infinity.

class finesse.components.Beamsplitter(*args, **kwargs)

Bases: Surface

The beamsplitter component represents a thin dielectric surface with associated properties such as reflectivity, tuning, and radius of curvature. It has four optical ports p1, p2, p3, and p4 which describe the four beams incident on either side of this surface. p1 and p2 are on side 1 and p3 and p4 are on side 2. A 100% transmissive beamsplitter will transmit all of the light incident at p1 to p3.

It also has a mechanical port mech which has nodes for longitudinal, yaw, and pitch motions. These mechanical nodes are purely for exciting small signal oscillations of the mirror. Static offsets in longitudinal displacements are set by the phi parameter (in units of degrees), misalignments in yaw by the xbeta parameter, and pitch the ybeta parameter. Macroscopic angle of incidence of the beamsplitter is set by the alpha parameter.

Beamsplitters physically operate the same as mirror components, except for the non-normal angle of incidence option.

See RTL relationship for more information on how the RTL relationship is handled.

Parameters

namestr: Name of newly created beamsplitter.
Rfloat, optional: Reflectivity of the beamsplitter.
Tfloat, optional: Transmissivity of the beamsplitter.
Lfloat, optional: Loss of the beamsplitter.
phifloat, optional: Microscopic tuning of the beamsplitter (in degrees).
alphafloat, optional: Angle of incidence (in degrees)
Rcfloat, optional: Radius of curvature (in metres); defaults to numpy.inf to indicate a planar surface.
xbeta, ybetafloat, optional: Angle of misalignment in the yaw plane (xbeta) and pitch (ybeta), respectively (in radians); defaults to 0.
planestr, optional: Plane of incidence, either ‘xz’ or ‘yz’. Defaults to ‘xz’.
misalignedbool, optional: When True the beamsplitter will be significantly misaligned and assumes any reflected beam is dumped. Transmissions will still occur.

Attributes

Attributes are set via the Python API and not available via KatScript.

surface_mapfinesse.knm.maps.Map: Decsribes the surface distortion of this beamsplitter component. Coordinate system to the map is right-handed with the postive-z direction as the surface normal on the port 1 side of the beamsplitter.

ABCD(from_node, to_node, direction='x', symbolic=False, copy=True, retboth=False, allow_reverse=False)

Returns the ABCD matrix of the beam splitter for the specified coupling.

The matrices for transmission and reflection are different for the sagittal and tangential planes (\(M_s\) and \(M_t\)), as shown below.

Transmission

For the tangential plane (direction = ‘x’),

\[M_t = \begin{pmatrix} \frac{\cos{\alpha_2}}{\cos{\alpha_1}} & 0 \\ \frac{\Delta n}{R_c} & \frac{\cos{\alpha_1}}{\cos{\alpha_2}} \end{pmatrix}, \]

and for the sagittal plane (direction = ‘y’),

\[M_s = \begin{pmatrix} 1 & 0 \\ \frac{\Delta n}{R_c} & 1 \end{pmatrix}, \]

where \(\alpha_1\) is the angle of incidence of the beam splitter and \(\alpha_2\) is given by Snell’s law (\(n_1\sin{\alpha_1} = n_2\sin{\alpha_2}\)). The quantity \(\Delta n\) is given by,

\[\Delta_n = \frac{n_2 \cos{\alpha_2} - n_1 \cos{\alpha_1}}{ \cos{\alpha_1} \cos{\alpha_2} }. \]

If the direction of propagation is reversed such that the radius of curvature of the beam splitter is in this direction, then the elements \(A\) and \(D\) of the tangential matrix (\(M_t\)) are swapped.

Reflection

The reflection at the front surface of the beam splitter is given by,

\[M_t = \begin{pmatrix} 1 & 0 \\ -\frac{2n_1}{R_c \cos{\alpha_1}} & 1 \end{pmatrix}, \]

for the tangential plane, and,

\[M_s = \begin{pmatrix} 1 & 0 \\ -\frac{2n_1 \cos{\alpha_2}}{R_c} & 1 \end{pmatrix}, \]

for the sagittal plane.

At the back surface \(R_c \rightarrow - R_c\) and \(\alpha_1 \rightarrow - \alpha_2\).

See Connector.ABCD() for descriptions of parameters, return values and possible exceptions.

Raises

treTotalReflectionError: If total reflection occurs for the specified coupling - i.e. if \(\sin{\alpha_2} > 1.0\).

property L: L : float, optional Loss of the beamsplitter.

property R: R : float, optional Reflectivity of the beamsplitter.

property Rcx: Radius of curvature (x)

property Rcy: Radius of curvature (y)

property T: T : float, optional Transmissivity of the beamsplitter.

property abcd12x

Numeric ABCD matrix from port 1 to port 2 in the tangential plane.

Equivalent to beamsplitter.ABCD(1, 2, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd12y

Numeric ABCD matrix from port 1 to port 2 in the sagittal plane.

Equivalent to beamsplitter.ABCD(1, 2, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd13x

Numeric ABCD matrix from port 1 to port 3 in the tangential plane.

Equivalent to beamsplitter.ABCD(1, 3, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd13y

Numeric ABCD matrix from port 1 to port 3 in the sagittal plane.

Equivalent to beamsplitter.ABCD(1, 3, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd21x

Numeric ABCD matrix from port 2 to port 1 in the tangential plane.

Equivalent to beamsplitter.ABCD(2, 1, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd21y

Numeric ABCD matrix from port 2 to port 1 in the sagittal plane.

Equivalent to beamsplitter.ABCD(2, 1, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd24x

Numeric ABCD matrix from port 2 to port 4 in the tangential plane.

Equivalent to beamsplitter.ABCD(2, 4, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd24y

Numeric ABCD matrix from port 2 to port 4 in the sagittal plane.

Equivalent to beamsplitter.ABCD(2, 4, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd31x

Numeric ABCD matrix from port 3 to port 1 in the tangential plane.

Equivalent to beamsplitter.ABCD(3, 1, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd31y

Numeric ABCD matrix from port 3 to port 1 in the sagittal plane.

Equivalent to beamsplitter.ABCD(3, 1, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd34x

Numeric ABCD matrix from port 3 to port 4 in the tangential plane.

Equivalent to beamsplitter.ABCD(3, 4, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd34y

Numeric ABCD matrix from port 3 to port 4 in the sagittal plane.

Equivalent to beamsplitter.ABCD(3, 4, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd42x

Numeric ABCD matrix from port 4 to port 2 in the tangential plane.

Equivalent to beamsplitter.ABCD(4, 2, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd42y

Numeric ABCD matrix from port 4 to port 2 in the sagittal plane.

Equivalent to beamsplitter.ABCD(4, 2, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd43x

Numeric ABCD matrix from port 4 to port 3 in the tangential plane.

Equivalent to beamsplitter.ABCD(4, 3, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd43y

Numeric ABCD matrix from port 4 to port 3 in the sagittal plane.

Equivalent to beamsplitter.ABCD(4, 3, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property alpha: alpha : float, optional Angle of incidence (in degrees)

property alpha2

Angle of incidence on side 2 in degrees, i.e. port 3 and 4 side.

Returns

alpha2Symbol: Symbolic form of alpha on side 2. Use float() to convert to a numerical value if needed.

Raises

Will raise a TotalReflectionError if total internal reflection is occuring at this beamsplitter.

get_adjacent_port(p): Get the port adjacent (on the same side of the surface) as p.

property misaligned: misaligned : bool, optional When True the beamsplitter will be significantly misaligned and assumes any reflected beam is dumped. Transmissions will still occur.

optical_equations()

property phi: phi : float, optional Microscopic tuning of the beamsplitter (in degrees).

property plane: plane : str, optional Plane of incidence, either ‘xz’ or ‘yz’. Defaults to ‘xz’.

property refractive_index_1: Refractive index on size 1 (port 1 and 2)

property refractive_index_2: Refractive index on size 2 (port 3 and 4)

property xbeta: Yaw misalignment

property ybeta: Pitch misalignment

class finesse.components.ButterFilter(*args, **kwargs)

Bases: ZPKFilter

property analog

property btype

property frequency

property gain: Gain

property order

set_zpk()

class finesse.components.Cavity(*args, **kwargs)

Bases: TraceDependency

Represents a cavity in an interferometer configuration.

This class stores the shortest round-trip path from the start node of the cavity (via a given node) back to the same node, and holds symbolic expressions for each physical attribute of the cavity. Numeric values corresponding to these attributes are obtained through the relevant properties.

Adding a Cavity to a Model results in the beam parameters of all nodes in the cavity path being set according to the cavity eigenmode (finesse.components.cavity.Cavity.q) when a beam trace is performed (e.g. at the start of a modal based simulation). The mode of the cavity is then also used as a trace starting point when setting beam parameters at nodes outside of the cavity - see Tracing the beam for details on the beam tracing algorithm.

Parameters

namestr

Name of newly created cavity.

sourceOpticalNode or Port

Node / Port that the cavity path starts from. If no via node is specified, then the cavity path will be given by the shortest path from source back to the component that owns source.

If a port is given then the output optical node of that port will be used as the source.

viaOpticalNode, optional

Node that the cavity path must traverse via; defaults to None.

Note that, unlike source, this cannot be a Port object as this would be ambiguous for beamsplitter type components - i.e. determination of which node to use cannot be assumed automatically.

prioritynumber, optional; default: 0

Priority value for beam tracing. Beam tracing dependencies are sorted in descending order of priority - i.e. higher priority value dependencies will be traced first. Any dependency with a priority value of zero will be traced, after non-zero priority dependencies, in alphabetic order of the dependency names.

property ABCD

The round-trip ABCD matrix of the cavity in both planes.

Getter:: Returns a numpy.ndarray with shape (2, 2, 2) of the cavity round-trip matrices in the tangential and sagittal planes, respectively (read-only).

property ABCDx

The tangential round-trip ABCD matrix of the cavity.

Getter:: Returns the cavity round-trip matrix in the tangential plane (read-only).

property ABCDy

The sagittal round-trip ABCD matrix of the cavity.

Getter:: Returns the cavity round-trip matrix in the sagittal plane (read-only).

property FSR

The free-spectral-range (FSR) of the cavity.

This quantity is defined as,

\[\mathrm{FSR} = \frac{c}{L}, \]

where \(c\) is the speed of light and \(L\) is the round trip optical path length of the cavity.

Getter:: Returns the cavity free-spectral-range (read-only).

property FWHM

The cavity full-width-half-maximum (FWHM).

This quantity is defined as,

\[\mathrm{FWHM} = \frac{\mathrm{FSR}}{\mathcal{F}}, \]

where \(\mathcal{F}\) is the cavity finesse.

Getter:: Returns the FWHM of the cavity (read-only).

Parameters

geometricbool: If true then only checks parameters which affect ABCD matrices.

Returns

flagbool: True if any parameter is changing (subject to the condition outlined above), False otherwise.

draw()

A string representation of the cavity route.

Returns

sstr: The node path of the cavity as a string.

property finesse

The finesse of the cavity.

This quantity is defined as,

\[\mathcal{F} = \frac{\pi \sqrt{\widetilde{l}}}{1 - \widetilde{l}}, \]

where \(\widetilde{l} = \sqrt{1 - L}\) and \(L\) is the cavity loss.

Getter:: Returns the cavity finesse (read-only).

property g

The stability of the cavity, in both planes, given by the \(g\)-factor:

\[g = \frac{A + D + 2}{4}, \]

where \(A\) and \(D\) are the relevant entries of the cavity round-trip ABCD matrix. The cavity is stable if the following condition is satisfied:

\[0 \leq g \leq 1. \]

Getter:: Returns a numpy.ndarray of the cavity stability in the tangential and sagittal planes, respectively (read-only).

generate_abcd_str()

Generates a string representation of the cavity round-trip ABCD matrix operations.

This can be useful for debugging purposes as the returned string will correspond exactly to the operation performed internally for calculating the round-trip matrices.

The format of each matrix symbol will be <comp>__<from_port>_<to_port>, e.g. the reflection at the rear (port two) surface of a mirror named ITM would be represented as ITM__p2_p2. The matrix multiplication is denoted via the @ symbol.

Returns

abcd_strstr: A string representing the operation to obtain the cavity round-trip ABCD matrix (in either plane).

get_exit_nodes()

Obtains a dictionary of source: target mappings where source -> target and target is an exit node of the cavity.

An exit node is defined to be a node that is not internal to the cavity, rather it is obtained on propagation from an internal node to outside the cavity.

Returns

exit_nodesdict: A dictionary of source: target mappings.

property gouy

The accumulated round-trip Gouy phase of the cavity in both planes (in degrees).

This is given by,

\[\psi_{\mathrm{rt}} = 2\,\arccos{\left( \mathrm{sgn}(B) \sqrt{g} \right)}, \]

where \(B\) is the corresponding element of the round-trip ABCD matrix and \(g\) is the cavity stability parameter returned by Cavity.g.

Getter:: Returns a numpy.ndarray of the accumulated round-trip Gouy phase in the tangential and sagittal planes, respectively (read-only).

property gouy_x

The round-trip Gouy phase in the tangential plane (in degrees).

If the cavity is not stable, then np.nan is returned.

Getter:: Returns the tangential plane round-trip Gouy phase (read-only).

Returns

figFigure: Handle to the figure.
axsaxes: The axis handles.

property pole

The pole-frequency of the cavity.

This quantity is defined as,

\[f_{\mathrm{pole}} = \frac{\mathrm{FWHM}}{2}, \]

where \(\mathrm{FWHM}\) is the full-width at half-maximum of the cavity resonance.

Getter:: Returns the cavity pole-frequency (read-only).

Returns

outBeamTraceSolution: An object representing the results of the tracing routine.

property via

Via node of the cavity.

Getter:: Returns the cavity via node (read-only).

property w0

The waist size of the cavity in both planes.

Getter:: Returns a numpy.ndarray of the cavity waist size in the tangential and sagittal planes, respectively (read-only).

property w0x

The waist size of the cavity in the tangential plane.

Equivalent to cavity.qx.w0.

Getter:: Returns the cavity waist size in the tangential plane (read-only).

property w0y

The waist size of the cavity in the sagittal plane.

Equivalent to cavity.qy.w0.

Getter:: Returns the cavity waist size in the sagittal plane (read-only).

property waistpos

The position of the cavity waist in both planes.

This distance to the waist is measured using the position of Cavity.source node as the origin.

Getter:: Returns a numpy.ndarray of the cavity waist position in the tangential and sagittal planes, respectively (read-only).

property waistpos_x

The waist position of the cavity in the tangential plane.

Equivalent to cavity.qx.z.

Getter:: Returns the cavity waist position in the tangential plane (read-only).

property waistpos_y

The waist position of the cavity in the sagittal plane.

Equivalent to cavity.qy.z.

Getter:: Returns the cavity waist position in the sagittal plane (read-only).

class finesse.components.Cheby1Filter(*args, **kwargs)

Bases: ZPKFilter

property gain: Gain

class finesse.components.Connector(*args, **kwargs)

Bases: ModelElement, ABC

Base class for any component which connects nodes together.

Internally it stores the nodes and the connections associated with the component. During the matrix build this class will then ensure that the matrix elements for each coupling requested are allocated and and the required matrix view for editing their values is retrieved.

The inheriting class should call _register_node and _register_coupling to define the connections it wants to use.

Parameters

namestr: Name of the new Connector instance.

ABCD(from_node, to_node, direction='x', symbolic=False, copy=True, retboth=False, allow_reverse=False)

Parameters

from_nodeOpticalNode or Port or str or int: Input node. If a port, or string repr of a port, is given then the input optical node of that port will be used.
to_nodeOpticalNode or Port or str or int: Output node. If a port, or string repr of a port, is given then the output optical node of that port will be used.
directionstr, optional; default: ‘x’: Direction of ABCD matrix computation, default is ‘x’ for tangential plane.
symbolicbool, optional; default: False: Whether to return the symbolic matrix (as given by equations above). Defaults to False such that the numeric matrix is returned.
copybool, optional; default: True: Whether to return a copy of ABCD matrix (or matrices if retboth is true). Defaults to True so that the internal matrix cannot be accidentally altered. Use caution if switching this flag off.
retbothbool, optional; default: False: Whether to return both the symbolic and numeric matrices as a tuple in that order.
allow_reversebool, optional: When True, if the coupling does not exist at the component from_node->to_node but to_node->from_node does exist, it will return the ABCD from that. Otherwise a NoCouplingError will be raised.

Returns

Mnumpy.ndarray: The ABCD matrix of the specified coupling for the mirror. This is symbolic if either of symbolic or retboth flags are True.
M2numpy.ndarray: Only returned if retboth is True, otherwise just M above is returned. This will always be the numeric matrix.

Raises

finesse.exceptions.NoCouplingError: If no coupling exists between from_node and to_node.
finesse.exceptions.NoABCDCoupling: If no ABCD matrix has been defined for the requested coupling.
finesse.exceptions.TotalReflectionError: Total reflection of a beam at a component when performing beam tracing.

property all_internal_connections: A dictionary of all the connections this element is making between its nodes.

property all_internal_optical_connections: A dictionary of all the optical connections this element is making between its nodes.

property borrows_nodes

Whether this element borrows node references from another.

When this is True the element may not create all of its own nodes and just link into one that already exists and is owned by another element.

check_coupling(from_node, to_node): Checks that a coupling exists between from_node -> to_node and raises a ValueError if not.

coupling_type(from_node, to_node)

Obtains the type of coupling (see CouplingType) between the two specified nodes at this component.

Parameters

from_nodeNode: Node which has a forwards coupling to to_node.
to_nodeNode: Node which has a backwards coupling from from_node.

Returns

coupling_tCouplingType: The type of coupling between the specified nodes.

property electrical_ports: tuple[Port, ...]

Retrieves the electrical ports available at the object.

Returns

tuple: Read-only tuple of the ports available at this object.

interaction_type(from_node, to_node)

Obtains the type of interaction (see InteractionType) between the two specified nodes at this component.

Parameters

from_nodeNode: Node which has a forwards coupling to to_node.
to_nodeNode: Node which has a backwards coupling from from_node.

Returns

interaction_tInteractionType: The type of interaction between the specified nodes.

is_valid_coupling(from_node, to_node): Flags whether the provided node coupling exists at this connector.

property mechanical_ports: tuple[Port, ...]

Retrieves the mechanical ports available at the object.

Returns

tuple: Read-only tuple of the ports available at this object.

property nodes

All the nodes of all the ports at this component. Order is likely to be the order in which the ports and nodes were created, but this is not guaranteed.

Returns

nodestuple(Node): Copy of nodes dictionary

property optical_nodes

The optical nodes stored by the connector.

Getter:: Returns a list of the stored optical nodes (read-only).

property optical_ports: tuple[Port, ...]

Retrieves the optical ports available at the object.

Returns

tuple: Read-only tuple of the optical ports available at this object.

property ports: tuple[Port, ...]

Retrieves the ports available at the object.

Returns

tuple: Read-only tuple of the ports available at this object.

register_abcd_matrix(M_sym, *couplings)

Register an ABCD matrix of the given symbolic form for a sequence of coupling(s).

Specifying several couplings for one M_sym means that all these node couplings will point to the same reference ABCDs — i.e. the matrices kept in the underlying ABCD matrix store will be the same blocks of memory.

Warning

This should only be used in the _resymbolise_ABCDs method of Connectors, when implementing a new component.

Parameters

M_symnumpy.ndarray

A 2x2 matrix of symbolic elements describing the analytic form of the ABCD matrix for the given coupling(s).

couplingssequence of tuples

Arguments of tuples giving the node couplings which are described by the given symbolic ABCD matrix M_sym.

These tuples can be of size two or three, with the first two elements always as the from_node -> to_node instances. The former case implies that both the tangential and sagittal plane ABCD matrix couplings are equal and so both directions ‘x’ and ‘y’ in the underlying matrices store will be set to the same values. Whilst the latter case, where the third element is either ‘x’ or ‘y’, sets just these direction keys to this matrix.

replace(sub: str, component: str | None = None, optical_ports: None | list[str] = None, mechanical_ports: None | list[str] = None, electrical_ports: None | list[str] = None, verbose: bool = False) → str

Unparse the model of this Connector and replace the Connector with a new section of katscript. Returns the katscript for the model with component replaced.

Parameters

substr

New section of katscript that will replace the katscript line defining the component to replace.

componentstr | None, optional

Replacement string for any references of the component name, by default None

optical_portsNone | list[str], optional

Replacement ports for any references of the component optical ports, by default None

mechanical_portsNone | list[str], optional

Replacement ports for any references of the component mechanical ports, by default None

electrical_portsNone | list[str], optional

Replacement ports for any references of the component electrical ports, by default None

verbosebool, optional

Whether to print a diff between the current and new KatScript,: by default False

Returns

str: KatScript with the component replaced.

Raises

FinesseException: When the component to replace is not of type Connector.

property signal_nodes

The signal nodes stored by the connector.

Getter:: Returns a list of the stored signal nodes (read-only).

class finesse.components.DegreeOfFreedom(*args, **kwargs)

Bases: Connector

property DC: DC state of degree of freedom

property amplitudes

Amplitudes a node is driving.

Getter:: Returns copy of the amplitudes a node is driving.

property dc_enabled

Whether all driving nodes have an associated DC parameter.

Getter:: Returns True if all driving nodes have an associated DC parameter that can be varied.

property drives

Nodes this degree of freedom is driving.

Getter:: Returns the nodes this degree of freedom drives.

property node_amplitude_pairs

class finesse.components.DirectionalBeamsplitter(*args, **kwargs)

Bases: Connector

Represents a directional beamsplitter optical component. Connections made between ports:

port 1 to port 3
port 3 to port 4
port 4 to port 2
port 2 to port 1

Parameters

namestr: Name of newly created directional beamsplitter.

optical_equations()

class finesse.components.Filter(*args, **kwargs)

Bases: Connector

This is a generic Filter element that encapsulates some of the Scipy signal filter tools. The sys attribute is the filter object which can be ZPK, BA, or SOS.

Parameters

namestr: Name of element in the model
gainParameter: Overall floating point value gain to apply to the filter.

bode_plot(f=None, n=None, return_axes=False)

Plots Bode for this filter.

Parameters

foptional: Frequencies to plot for in Hz (Not radians)
nint, optional: number of points to plot

Returns

axis : Matplotlib axis for plot if return_axes=True

fill(ws)

property gain: gain : Parameter Overall floating point value gain to apply to the filter.

class finesse.components.FreeMass(*args, **kwargs)

Bases: MechanicalConnector

Simple free mass suspension of an object.

The object being suspended must have a mechanical port with nodes z, pitch, and yaw and forces F_z, F_pitch, and F_yaw.

property I_pitch: Moment of inertia (pitch)

property I_yaw: Moment of inertia (yaw)

fill(self, ws)

property mass: Mass

class finesse.components.FrequencyGenerator

Bases: object

The base class for components which generate optical frequencies.

A component inheriting from this class will allow the model to query the component to ask what frequencies it wants to use. Frequency generation comes in the form of either a laser or something that modulates.

class finesse.components.FrequencyLoss(*args, **kwargs)

Bases: Connector

Represents an unphysical element which introduces a loss and/or phase for a particular frequency.

Parameters

namestr: Name of newly created lens.
ffloat, optional: Frequency to apply loss and phase to.
lossfloat, optional: Fractional loss at the frequency
phasefloat, optional: Phase change at the frequency

property f: f : float, optional Frequency to apply loss and phase to.

property loss: loss : float, optional Fractional loss at the frequency

property phase: phase : float, optional Phase change at the frequency

class finesse.components.Gauss(*args, **kwargs)

Bases: TraceDependency

Beam parameter at a specific node of a model.

The following are legal initialisations of a Gauss object:

# Non-astigmatic
q = Gauss('name', node, q=q)
q = Gauss('name', node, w0=w0, z=z) # waist size and position
q = Gauss('name', node, zr=zr, z=z) # Rayleigh range and waist position
q = Gauss('name', node, w=w, Rc=Rc) # beam size and RoC
q = Gauss('name', node, w=w, S=S) # beam size and curvature

# Astigmatic
q = Gauss('name', node, qx=qx, qy=qy)
q = Gauss('name', node, w0x=wx, zx=zx, w0y=wy, zy=zy)
q = Gauss('name', node, zrx=zrx, zx=zx, zry=zry, zy=zy)
q = Gauss('name', node, wx=wx, Rcx=Rcx, wy=wy, Rcy=Rcy)
q = Gauss('name', node, wx=wx, Sx=Sx, wy=wy, Sy=Sy)

See gaussian.BeamParam for more detailed descriptions of these variables.

property is_changing

Whether the Gauss object is changing or not.

This is used internally when initialising simulation states.

property node

The optical node associated with the Gauss object.

Getter:: Returns the associated OpticalNode instance (read-only).

property qx

Tangential plane beam parameter.

Getter:: Returns the beam parameter in the tangential plane.
Setter:: Sets the beam parameter for the tangential plane.

property qy

Sagittal plane beam parameter.

Getter:: Returns the beam parameter in the sagittal plane.
Setter:: Sets the beam parameter for the sagittal plane.

property w0x: Waist size (x)

property w0y: Waist size (y)

property zx: Distance to waist (x)

property zy: Distance to waist (y)

class finesse.components.Isolator(*args, **kwargs)

Bases: Connector

Represents an isolator optical component with a suppression factor. Suppresses the light field transmitted from p2 to p1. The field from p1 to p2 is.

Parameters

namestr: Name of newly created isolator.
Sfloat: Power suppression in dB. Defaults to 0

property S: S : float Power suppression in dB. Defaults to 0

optical_equations()

property suppression_factor: float: Factor by which the light field transmitted from p2 to p1 is supressed.

class finesse.components.Laser(*args, **kwargs)

Bases: Connector, FrequencyGenerator

Represents a laser producing a beam with associated properties such as power and frequency.

Parameters

namestr: Name of the newly created laser.
Pfloat, optional: Power of the laser (in Watts), defaults to 1 W.
ffloat or Frequency, optional: Frequency-offset of the laser from the default (in Hz) or Frequency object. Defaults to 0 Hz offset.
phasefloat, optional: Phase-offset of the laser from the default, defaults to zero.
signals_onlybool, optional: When True, this laser component will only inject signal sidebands. They will use the current carrier value as a scaling terms but the carrier will not be injected into the simulation. This allows a user to just inject signal sidebands into a model.

Attributes

add_gouy_phasebool: When set to True the gouy phase of the current beam parameters values at the laser will be added to the optical field outputs during the simulation. When False, it will not. This can be used with set_output_field() to force a particular optical field output from a laser.

DEFAULT_POWER_COEFFS = {(0, 0): (1.0, 0.0)}

property P: P : float, optional Power of the laser (in Watts), defaults to 1 W.

property f: f : float or Frequency, optional Frequency-offset of the laser from the default (in Hz) or Frequency object. Defaults to 0 Hz offset.

get_output_field(homs)

Get optical field outputted as a HOM vector.

Returns the complex amplitude of the modes specified in homs. This does not respect the add_gouy_phase` attribute of the laser element and will always return the complex amplitude without the gouy phase. If the gouy phase is required then it is recommended to use a FieldDetector at the laser output with add_gouy_phase set to True.

Parameters

homssequence: Collection of (n, m) higher order modes to retrieve the output field for. Typically this is just the model.homs value. The output E vector will match the ordering of homs.

Returns

sequence: The output fields for homs. If a given (n, m) has no defined coefficients, its field defaults to 0.

optical_equations()

property phase: phase : float, optional Phase-offset of the laser from the default, defaults to zero.

property power_coeffs

The relative power factors and phase offsets for each HGnm mode.

Getter:: Returns the mode factors and phase offsets as a dict with the mode indices as keys. Read-only.

set_output_field(E, homs)

Set optical field outputted using HOM vector.

This changes the output power and mode content of the laser to match the requested E field.

Parameters

Esequence: The complex optical field amplitude for homs.
homssequence: Sequence of (n, m) higher order modes. Typically this is just the model.homs value. It should match the size of E.

Notes

If you do not want the gouy phase due to the current beam parameter values set at the laser to be added to the output, set the add_gouy_phase attribute of the laser element to False.

property signals_only: signals_only : bool, optional When True, this laser component will only inject signal sidebands. They will use the current carrier value as a scaling terms but the carrier will not be injected into the simulation. This allows a user to just inject signal sidebands into a model.

source_equation(node, f): Returns optical carrier field to inject for a simulation.

tem(n, m, factor, phase=0.0)

Distributes power into the mode HGnm.

Parameters

n, mint: Mode indices.
factorfloat: Relative power factor, modes with equal factor will have equivalent power distributed to them.
phasefloat, optional; default = 0.0: Phase offset for the field, in degrees.

Notes

This does not change the total power of the laser, rather, it redistributes this power into / out of the specified mode.

class finesse.components.Lens(*args, **kwargs)

Bases: BaseLens

Represents a thin lens optical component with an associated focal length.

Notes

The specified focal length f is only accurate when the lens is attached to spaces with index of refraction close to 1. This component exists so that one can use the intuitive focal length parameter instead of having to set radii of curvature as with e.g. Mirror.

Parameters

namestr: Name of newly created lens.
ffloat, optional: Focal length of the lens in metres; defaults to infinity.

Attributes

OPD_mapfinesse.knm.maps.Map: A map that is used to describe the transverse spatial amplitude and phase variations beyond a simple lensing. Typically the map applied is describing the dnr/dT temperature effects in some substrate.

property f: f : float, optional Focal length of the lens in metres; defaults to infinity.

class finesse.components.LocalDegreeOfFreedom(name, DC=None, AC_IN=None, DC_2_AC_scaling=None, AC_OUT=None)

Bases: object

A local degree of freedom definition that combines a DC parameter and AC nodes at some element. For example, this can pair a mirror tuning and it the AC mechanical nodes into one “Degree of Freedom” that can be referenced to scan, drive, or readout. Some DOFs do not have a DC equivalent so the DC part may be None. A DOF can have a different input (drive) and output (readout) signal node. This is used in more advanced cases such as suspension systems, where you drive some motion through a force/torque actuation on some part of the suspension but the readout is in displacement/rotation of the final optic.

Parameters

namestr: Name should be the full-name of the definition for a particular element, e.g. m1.dofs.z if this is wrong, then unparsing will not work correctly
DCParameter, optional: The DC equivlent of the AC signal node of an element, setting to None means no DC actuation happens.
AC_INSignalNode: The node that is driven for this degree of freedom, cannot be None.
DC_2_AC_scalingfloat, optional: Scaling factor relating the DC and AC parameter and nodes. For example, the scaling between phi (degrees) and mirror.mech.z (meters).
AC_OUTSignalNode, optional: The node that is read out to describe this degree of freedom, if None there is nothing to readout here.

property AC_IN_type

property AC_OUT_type

class finesse.components.Mirror(*args, **kwargs)

Bases: Surface

The mirror component represents a thin dielectric surface with associated properties such as reflectivity, tuning, and radius of curvature. Mirror components are nominally at normal incidence to the beams. It has two optical ports p1 and p2 which describes the two beams incident on either side of this surface. The surface normal points out of the mirror on the p1 side. A mirror also has a mechanical port mech which has nodes for longitudinal, yaw, and pitch motions. These mechanical nodes are purely for exciting small signal oscillations of the mirror. Static offsets in longitudinal displacements are set by the phi parameter (in units of degrees), yaw by the xbeta parameter, and pitch the ybeta parameter.

Parameters

namestr: Name of newly created mirror.
Rfloat, optional: Reflectivity of the mirror; defaults to 0.5.
Tfloat, optional: Transmittance of the mirror; defaults to 0.5.
Lfloat, optional: Loss of the mirror; defaults to 0.0.
phifloat, optional: Tuning of the mirror (in degrees); defaults to 0.0.
Rcfloat or container of two floats, optional: The radius of curvature of the mirror (in metres); defaults to a flat mirror (Rc=np.inf). Astigmatic mirrors can also be set with Rc=(Rcx, Rcy). A positive value results in a concave mirror on the p1 side of the mirror.
xbeta, ybetafloat, optional: Misalignment of the mirror in yaw and pitch in units of radians
misalignedbool, optional: When True the mirror will be significantly misaligned and assumes any reflected beam is dumped. Transmissions will still occur.
imaginary_transmissionbool, optional: Convention for the transmission and reflection reciprocity relations. ‘True’ uses imaginary transmission and equal real reflection from both sides ‘False’ uses real transmission, negative reflection from side 1, and positive reflection from side 2. defaults to True

Attributes

Attributes are set via the Python API and not available via KatScript.

surface_mapfinesse.knm.maps.Map: Decsribes the surface distortion of this mirror component. Coordinate system to the map is right-handed with the postive-z direction as the surface normal on the port 1 side of the mirror.

ABCD(from_node, to_node, direction='x', symbolic=False, copy=True, retboth=False, allow_reverse=False)

Returns the ABCD matrix of the mirror for the specified coupling.

In both cases below, the sign of the radius is defined such that \(R_c\) is negative if the centre of the sphere is located in the direction of propagation.

Transmission

For transmission this is given by,

\[M_{t} = \begin{pmatrix} 1 & 0 \\ \frac{n_2 - n_1}{R_c} & 1 \end{pmatrix}, \]

where \(n_2\) and \(n_1\) are the indices of refraction of the spaces connected to the mirror and \(R_c\) is the radius of curvature of the mirror.

The matrix for transmission in the opposite direction of propagation is identical.

Reflection

In the case of reflection the matrix is,

\[M_{r} = \begin{pmatrix} 1 & 0 \\ -\frac{2n_1}{R_c} & 1 \end{pmatrix}. \]

Reflection at the back surface can be described by the same type of matrix by setting the \(C\) element to \(C = 2n_2/R_c\).

See Connector.ABCD() for descriptions of parameters, return values and possible exceptions.

property L: L : float, optional Loss of the mirror; defaults to 0.0.

property R: R : float, optional Reflectivity of the mirror; defaults to 0.5.

property Rcx: Radius of curvature (x)

property Rcy: Radius of curvature (y)

property T: T : float, optional Transmittance of the mirror; defaults to 0.5.

property abcd11x

Numeric ABCD matrix from port 1 to port 1 in the tangential plane.

Equivalent to mirror.ABCD(1, 1, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd11y

Numeric ABCD matrix from port 1 to port 1 in the sagittal plane.

Equivalent to mirror.ABCD(1, 1, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd12x

Numeric ABCD matrix from port 1 to port 2 in the tangential plane.

Equivalent to mirror.ABCD(1, 2, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd12y

Numeric ABCD matrix from port 1 to port 2 in the sagittal plane.

Equivalent to mirror.ABCD(1, 2, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd21x

Numeric ABCD matrix from port 2 to port 1 in the tangential plane.

Equivalent to mirror.ABCD(2, 1, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd21y

Numeric ABCD matrix from port 2 to port 1 in the sagittal plane.

Equivalent to mirror.ABCD(2, 1, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd22x

Numeric ABCD matrix from port 2 to port 2 in the tangential plane.

Equivalent to mirror.ABCD(2, 2, "x").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property abcd22y

Numeric ABCD matrix from port 2 to port 2 in the sagittal plane.

Equivalent to mirror.ABCD(2, 2, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix for this coupling (read-only).

property misaligned: misaligned : bool, optional When True the mirror will be significantly misaligned and assumes any reflected beam is dumped. Transmissions will still occur.

optical_equations()

property phi: phi : float, optional Tuning of the mirror (in degrees); defaults to 0.0.

property refractive_index_1: Refractive index on size 1 (port 1)

property refractive_index_2: Refractive index on size 2 (port 2)

property xbeta: Yaw misalignment

property ybeta: Pitch misalignment

class finesse.components.Modulator(*args, **kwargs)

Bases: Connector, FrequencyGenerator

Represents a modulator optical component with associated properties such as modulation frequency, index and order.

Parameters

namestr: Name of newly created modulator.
ffloat or Frequency, optional: Frequency of the modulation (in Hz) or Frequency object.
midxfloat: Modulation index, >= 0.
orderint, optional: Maximum order of modulations to produce. Must be 1 for amplitude modulation. Defaults to 1.
mod_typestr, optional: Modulation type, either ‘am’ (amplitude modulation) or ‘pm’ (phase modulation). Defaults to ‘pm’.
phasefloat, optional: Relative phase of modulation (in degrees). Defaults to 0.0.
positive_onlybool, optional: If True, only produce positive-frequency sidebands. Defaults to False.

property f: f : float or Frequency, optional Frequency of the modulation (in Hz) or Frequency object.

property midx: midx : float Modulation index, >= 0.

property mod_type: mod_type : str, optional Modulation type, either ‘am’ (amplitude modulation) or ‘pm’ (phase modulation). Defaults to ‘pm’.

optical_equations()

property order: order : int, optional Maximum order of modulations to produce. Must be 1 for amplitude modulation. Defaults to 1.

property phase: phase : float, optional Relative phase of modulation (in degrees). Defaults to 0.0.

property positive_only: positive_only : bool, optional If True, only produce positive-frequency sidebands. Defaults to False.

class finesse.components.Node(name, port, node_type, direction)

Bases: object

Represents a specific connection at a component.

Mathematically a node represents a single equation in the interferometer matrix.

A node can only be owned by a single component instance - with weak references stored by the connected components.

Parameters

namestr: Name of newly created node.
componentPort: The port that this node belongs to.
node_typeNodeType: Physical node type.

property component: ModelElement

The component which has ownership of this node.

Getter:: Returns the component that this node belongs to (read-only).

property connections

Connections of this node.

Getter:: Returns a collection of Space, Wire, or DegreeOfFreedom objects attached to this node (read-only).

property direction

NodeDirection of this node.

This is largely a description to help understand how external information flow in and out of a component. Inside a component all nodes will couple to one another in more complex ways.

Input nodes are those going into a component, whereas output describe those leaving. For example incident and reflected light fields.

Bidrectional takes information either direction. For example a mechanical degree of freedom, external forces can be applied to it, or its motion can be coupled to some external system.

Getter:: Returns the directionality of the node (read-only).

property full_name

Full name.

Getter:: Returns a full name of the node: {component name}.{port name}.{node name}

property is_input

Flag indicating whether this node is an input to the associated component.

Getter:: Returns True if the field at this node goes into self.component (read-only).

is_neighbour(node)

Checks if node is a connected by an edge to this node.

Parameters

nodeNode: Node with which to check connection.

Returns

flagbool: True if node is connected to this node, False otherwise.

property name

Name of the node object.

Getter:: Returns the name of the node (read-only).

property port: Port

Port this node is attached to.

Getter:: Returns the port of this node (read-only).

property port_name

Port name.

Getter:: Returns a shortened name of the node: {port name}.{node name}

property tag

Tagged name of the node object.

Getter:: Returns the tagged (user-defined) name of the node (read-only).

property type

NodeType of the node object.

Getter:: Returns the node-type of the node (read-only).

class finesse.components.NodeDirection(*values)

Bases: Enum

Enum describing the direction that information at a Node flows.

This is largely a description to help understand how external information flows in and out of a component. Inside a component all nodes will couple to one another in more complex ways.

Input nodes are those going into a component, whereas output describe those leaving. For example incident and reflected light fields.

Bidrectional takes information either direction. For example a mechanical degree of freedom, external forces can be applied to it, or its motion can be coupled to some external system.

BIDIRECTIONAL = 2

INPUT = 0

OUTPUT = 1

class finesse.components.NodeType(*values)

Bases: Enum

Enum describing the physical connection type of a Node

ELECTRICAL = 1

MECHANICAL = 2

OPTICAL = 0

class finesse.components.Nothing(*args, **kwargs)

Bases: Connector

Represents an empty point in the interferometer configuration.

Nothing is just some point in space that can be connected to. For example, you can use this to propagate a beam from some component out to some arbitrary point to make a measurement at. You can also use this to split spaces up, if you wanted to measure something inbetween two components. It can also be used to replace a component, for example if you want to remove a lens or a mirror in some beam path.

Parameters

namestr: Name of newly created nothing.

optical_equations()

class finesse.components.OpticalBandpassFilter(*args, **kwargs)

Bases: Connector

An idealised optical bandpass filter that will transmit an optical frequency around some central frequency with a 3dB bandwidth.

Notes

Currently this is a classical component. No quantum noise losses are applied to any filtered fields or modes, which means no additional vaccum noise is injected back into the system for this lost information.

Parameters

namestr: Name of element
fcfloat, symbol: Central frequency
bandwidthfloat, symbol: Filter 3dB bandwidth
filter_hom[tuple | None], optional: Individual higher order modes can be filtered and transmitted by setting this to a tuple of (n, m). If None then no mode filtering is done. This cannot be changed during a simulation.

property bandwidth: bandwidth : float, symbol Filter 3dB bandwidth

property fc: fc : float, symbol Central frequency

class finesse.components.Pendulum(*args, **kwargs)

Bases: MechanicalConnector

Simple pendulum suspension of an object.

The object being suspended must have a mechanical port with nodes z, pitch, and yaw and forces F_z, F_pitch, and F_yaw.

property I_pitch: Moment of inertia (pitch)

property I_yaw: Moment of inertia (yaw)

property Qpitch

property Qyaw

property Qz

fill(self, ws)

property fpitch

property fyaw

property fz

property mass: Mass

class finesse.components.Port(name, component, node_type)

Bases: Freezable

A collection of all the nodes at a specific point/surface of a component.

Parameters

namestr: Name of newly created node.
componentSub-class of Connector: The component that this node belongs to.
node_typeNodeType: Physical node type.

property attached_to

Components that this port is attached to. Optical ports are only ever connected to Space elements. Ports containing signal nodes can have multiple connections and returns a Set.

Getter:: Returns the component this port is attached to, or returns None if no such connected component exists. Signal ports return a Set of components attached (read-only).

property component: ModelElement

The component which has ownership of this port.

Getter:: Returns the component that this port belongs to (read-only).

property enabled

property full_name

Getter:: Returns a full name of the port: {component name}.{port name}

get_unique_node(predicate: Callable[[Node], bool])

Returns the unique node at this port that satisfies the provided predicate. If multiple nodes satisfy this predicate then a RuntimeError is raised.

Parameters

predicateCallable[[Node], bool]: A callable that accepts a Node and returns a boolean value

Examples

Selecting a unique output node:: port.get_unique_node(lambda node: not node.is_input)

property is_connected

Flag indicating whether the port is attached to another component.

Getter:: Returns true if this port is attached to another component (read-only).

property name

Name of the port object.

Getter:: Returns the name of the port (read-only).

node(name): Get a node at this port by its name.

property nodes

Nodes associated with the port.

Getter:: Returns a tuple of the associated nodes at this port (read-only).

property refractive_index

If the port is an Optical port, this will return a symbolic value for the refractive index at this port. The refractive index is set by the Space elements that are attached to it.

Returns

nrSymbol: Symbolic value for refractive index

property space

Space that the port is attached to. Equivalent to Port.attached_to.

Getter:: Returns the space that this port is attached to (read-only).

property type

NodeType of the port object.

Getter:: Returns the node-type of the port (read-only).

class finesse.components.ReadoutDC(*args, **kwargs)

Bases: _Readout

A Readout component which represents a photodiode measuring the intensity of some incident field. Audio band intensity signals present in the incident optical field are converted into an electrical signal and output at the self.DC port, which has a single self.DC.o node.

See Readouts for more information.

Parameters

namestr

Name of the readout component

optical_nodeNode | Port | None, optional

Optical node this readout should look at. Because the readout borrows the node, it can be connected anywhere in the model, like a detector. When passing None, the readout should be connected explicitly with a finesse.components.space.Space or with finesse.model.Model.link() command (and then only a single readout can be connected per port).

pdtypestr | dict | None, optional

A name of a pdtype definition or a dict representing a pdtype definition,: by default None. See Segmented photodiodes

output_detectorsbool, optional

Whether to add a PowerDetector and a QuantumShotNoiseDetector to the solution object, by default False

Raises

TypeError: When optical_node is not a Port or a Node object, or the NodeType is not NodeType.Optical

outputs: ReadoutDCOutputs

class finesse.components.ReadoutRF(*args, **kwargs)

Bases: _Readout

A readout component which represents a demodulated photodiode. The self.I and self.Q electrical ports contain the signal of the two quadratures.

See Readouts for more information.

Parameters

namestr

Name of the readout component

optical_nodeNode | Port | None, optional

Optical node this readout should look at. Because the readout borrows the node, it can be connected anywhere in the model, like a detector. When passing None, the readout should be connected explicitly with a finesse.components.space.Space or with finesse.model.Model.link() command (and then only a single readout can be connected per port).

ffloat, optional

Demodulation frequency in Hz, by default 0

phasefloat, optional

Demodulation phase in degrees, by default 0

output_detectorsbool, optional

Whether to add a PowerDetector (DC), two PowerDetectorDemod1 ‘s (I and Q) and a QuantumShotNoiseDetectorDemod1 to the solution object, by default False

pdtypestr | dict | None, optional

A name of a pdtype definition or a dict representing a pdtype definition,: by default None. See Segmented photodiodes

property f: f : float, optional Demodulation frequency in Hz, by default 0

outputs: ReadoutRFOutputs

property phase: phase : float, optional Demodulation phase in degrees, by default 0

class finesse.components.SignalGenerator(*args, **kwargs)

Bases: Connector

Represents a signal generator which produces a signal with a given amplitude and phase.

Parameters

namestr: Name of newly created signal generator.
node.class:finesse.components.node.Node: A node to inject a signal into.
amplitudefloat, optional: Amplitude of the signal in volts.
phasefloat, optional: Phase-offset of the signal from the default in degrees, defaults to zero.

property amplitude: amplitude : float, optional Amplitude of the signal in volts.

property f: Signal frequency being injected, is always the fsig of the model.

property node

Change the node the signal generator injects into.

Setter:: Change the node the signal generator injects into.

property phase: phase : float, optional Phase-offset of the signal from the default in degrees, defaults to zero.

class finesse.components.Space(*args, **kwargs)

Bases: Connector

Represents a space between two components in the interferometer configuration, with a given length and index of refraction.

There can be many spaces in a model which are not of much interest and do not need to be referred to. For example, the link command will create spaces between components without giving an explicit name, just specifying a distance between them.

All Space elements are added to the Model’s .spaces namespace so they can all easily be iterated over. You can also find spaces which had no name specified and thus have an autogenerated name. User specified Space’s with names will be put in the main Model namespace so that they can be accessed like any other element in the model.

Parameters

namestr, optional: Name of newly created space. If not specified, a name is automatically generated.
portA, portBPort: Ports to connect.
Lfloat, optional: Geometric length of newly created Space instance; defaults to 0.
nrfloat, optional: Index of refraction of newly created Space instance; defaults to 1.0.
user_gouy_x, user_gouy_yfloat, optional: User-defined gouy phase to override the calculated value.

ABCD(from_node, to_node, direction='x', symbolic=False, copy=True, retboth=False, allow_reverse=False)

Returns the ABCD matrix of the space for the specified coupling.

This is given by,

\[M = \begin{pmatrix} 1 & \frac{L}{n_r} \\ 0 & 1 \end{pmatrix}, \]

where \(L\) is the length of the space and \(n_r\) is the index of refraction.

See Connector.ABCD() for descriptions of parameters, return values and possible exceptions.

property L: L : float, optional Geometric length of newly created Space instance; defaults to 0.

property abcd

Numeric ABCD matrix.

Equivalent to any of space.ABCD(1, 2, "x"), space.ABCD(2, 1, "x"), space.ABCD(1, 2, "y"), space.ABCD(2, 1, "y").

Getter:: Returns a copy of the (numeric) ABCD matrix (read-only).

connect(portA, portB)

Sets the ports of this Space.

Parameters

portAPort, optional: Port to connect
portBPort, optional: Port to connect

gouy(q1, q2)

Computes the Gouy phase in degrees from beam parameters.

Parameters

q1complex, BeamParam: Starting beam parameter
q2complex, BeamParam: Ending beam parameter

Returns

outfloat: Gouy phase (in degrees)

property gouy_x

property gouy_y

property nr: nr : float, optional Index of refraction of newly created Space instance; defaults to 1.0.

optical_equations()

Calculates the optical equations for the space component.

Returns

dict: A dictionary containing the optical equations for the space component.
The keys match the optical couplings defined by the Space, and the values represent the corresponding complex coupling equations.

property portA

property portB

replace(*args, **kwargs) → str

Unparse the model of this Connector and replace the Connector with a new section of katscript. Returns the katscript for the model with component replaced.

Parameters

substr

New section of katscript that will replace the katscript line defining the component to replace.

componentstr | None, optional

Replacement string for any references of the component name, by default None

optical_portsNone | list[str], optional

Replacement ports for any references of the component optical ports, by default None

mechanical_portsNone | list[str], optional

Replacement ports for any references of the component mechanical ports, by default None

electrical_portsNone | list[str], optional

Replacement ports for any references of the component electrical ports, by default None

verbosebool, optional

Whether to print a diff between the current and new KatScript,: by default False

Returns

str: KatScript with the component replaced.

Raises

FinesseException: When the component to replace is not of type Connector.

property user_gouy_x: Gouy phase (x)

property user_gouy_y: Gouy phase (y)

class finesse.components.Squeezer(*args, **kwargs)

Bases: Connector, FrequencyGenerator, NoiseGenerator

Represents a squeezer producing a squeezed-light beam with a given squeezing in decibels and angle. The upper and conjugate of the lower sidebands can be excited in a signal analysis by injecting into the .upper and .lower_conj signal nodes.

Parameters

namestr: Name of the newly created squeezer.
dbfloat: Squeezing factor (in amplitude decibels). 6dB gives a factor of 2 reduction in noise.
ffloat or Frequency, optional: Frequency-offset of the squeezer from the default (in Hz) or Frequency object. Defaults to 0 Hz offset.
anglefloat, optional: Squeezing angle (in degrees). Defaults to zero.

property angle: angle : float, optional Squeezing angle (in degrees). Defaults to zero.

property db: db : float Squeezing factor (in amplitude decibels). 6dB gives a factor of 2 reduction in noise.

property f: f : float or Frequency, optional Frequency-offset of the squeezer from the default (in Hz) or Frequency object. Defaults to 0 Hz offset.

property lower

class finesse.components.Surface(*args, **kwargs)

Bases: Connector

Abstract optical surface interface providing an object with common properties for Mirror and Beamsplitter to inherit from.

Parameters

namestr: Name of newly created surface.
Rfloat, optional: Reflectivity of the surface.
Tfloat, optional: Transmissivity of the surface.
Lfloat, optional: Loss of the surface.
phifloat, optional: Microscopic tuning of the surface (in degrees).
Rcfloat, optional: Radius of curvature (in metres); defaults to numpy.inf to indicate a planar surface. An astigmatic surface can be set with Rc = (Rcx, Rcy).

property L: L : float, optional Loss of the surface.

property R: R : float, optional Reflectivity of the surface.

property Rc

The radius of curvature of the mirror in metres, for both the tangential and sagittal planes.

Getter:: Returns values of both planes’ radii of curvature as a numpy.ndarray where the first element is the tangential plane RoC and the second element is the sagittal plane RoC.
Setter:: Sets the radius of curvature.

Examples

The following sets the radii of curvature of an object m, which is a sub-instance of Surface, in both directions to 2.5 m:

>>> m.Rc = 2.5

Whilst this would set the radius of curvature in the x-direction (tangential plane) to 2.5 m and the radius of curvature in the y-direction (sagittal plane) to 2.7 m:

>>> m.Rc = (2.5, 2.7)

property Rcx: Radius of curvature (x)

property Rcy: Radius of curvature (y)

property T: T : float, optional Transmissivity of the surface.

actuate_roc(dioptres, direction=('x', 'y'))

Actuate on the radius of curvature (RoC) of the surface with a specified dioptre shift.

Sets the RoC to a new value, \(R_2\), via,

\[R_2 = \frac{2}{d + \frac{2}{R_1}},\]

where \(R_1\) is the current RoC and \(d\) is the dioptre shift (i.e. the dioptre argument).

By default, both planes of curvature are shifted. To shift, e.g., only the tangential plane, specify direction="x".

Parameters

dioptresfloat: Shift in surface RoC in dioptres.
directiontuple or str, optional; default: (“x”, “y”): RoC plane to shift, defaults to both tangential and sagittal.

check_rtl()

property phi: phi : float, optional Microscopic tuning of the surface (in degrees).

set_RTL(R=None, T=None, L=None)

Set the values for the R, T and L properties of the surface.

One of the following combination must be specified:

R and T or,

R and L or,

T and L or,

R and T and L

In the first three cases, the remaining parameter is set via the condition,

\[R + T + L = 1 \]

Parameters

Rscalar: Value of the reflectivity to set.
Tscalar: Value of the transmissivity to set.
Lscalar: Value of the loss to set.

Raises

ValueError

If a combination other than one of the above is specified.

Or if R, T and L are all given but they sum to anything other than one.

property xbeta: Misalignment (x)

property ybeta: Misalignment (y)

class finesse.components.SuspensionTFPlant(*args, **kwargs)

Bases: Connector

A customised suspension element that accepts arbitrary input and output nodes and a 2D array of control.TransferFunction objects that define a transfer function between each of them. See the Python Control package for more details on these.

Inputs and outputs must be named in the format port.name
Inputs must be unique to outputs
All plant transfer functions must have the same denominators

The mechanical port of other optical elements can be connected to this suspension by using the connections_to dictionary input. This takes the name of a port defined in this suspension and maps it to the mechanical port of another element.

The plant, inputs, and outputs cannot be changed once initialised. There is no KatScript interface for this component.

Parameters

namestr: Name of element
inputsarray_like, list: Sequence of inputs for this plant, should be strings of the format port.node
outputsarray_like, list: Sequence of outputs for this plant, should be strings of the format port.node
plantarray_like, list[list]: A 2D array of control.TransferFunction that describe the transfer function between each input to every output. Shape should be [len(outputs), len(inputs)]. Elements can also be None which means no coupling between each transfer function.
connections_todict[str: SignalNode], optional: Dict of port names at this suspension component and a mechanical port of some other element. Names of nodes at in each port should be identical. Keys of the dict should be in the format port.node. Values should be mechanical nodes of other elements.

bode(self, f, input_node, output_node, **kwargs): Make a bode plot for a particular node coupling for this suspension. See finesse.plotting.bode for the actual plotting method.

property connections_to

property inputs

property outputs

property plant

class finesse.components.SuspensionZPK(*args, **kwargs)

Bases: MechanicalConnector

A suspension that models multiple poles and zeros for the z, yaw, or pitch motion of an optic. The user must ensure that minus signs are correct for this transfer function as well as defining complex conjugae pairs for physically correct behaviour.

ZPK terms are in units of radians/s.

Parameters

namestr: Element name
connected_toElement or mechanical port: Mechanical port or element to attach this suspension to
zpk_plantdict: Dictionary of {(output, input):(z,p,k)}

Examples

>>> import matplotlib.pyplot as plt
>>> import finesse
>>> from finesse.components.mechanical import SuspensionZPK
>>>
>>> model = finesse.Model()
>>> model.fsig.f = 1
>>> model.parse("m m1 R=1 T=0")
>>> zpk_plant = {}
>>> # F_z to z (longitudinal force to displacement)
>>> zpk_plant['z', 'F_z'] = ([], [10], 1)
>>> model.add(SuspensionZPK('sus', model.m1.mech, zpk_plant))
>>> out = model.run("frequency_response(geomspace(1m, 100, 100), m1.mech.F_z, m1.mech.z)")
>>> plt.loglog(out.f, abs(out['m1.mech.F_z', 'm1.mech.z']))

fill(self, ws)

class finesse.components.Telescope(*args, **kwargs)

Bases: Connector

This component represents a perfectly matching and adapting telescope. It will not change the beam parameter on transmission of the component and any field coming in will be transmitted to the other side into the other beam parameter. This should be used in cases when you want to connect to optical systems but do not want to design a complicated optical telescope system to mode-match them both, or in cases where one system has a changing parameter but you don’t care about the details of the telescope.

No beam is traced through the telescope so you must specify a beam parameter or a cavity on both sides of the telescope. If not, a tracing error will occur.

Currently no losses, mismatch, or misalignments can be induced at this telescope. There is no accumulated Gouy phase or plane-wave propagation phase.

Parameters

namestr: Name of newly created telescope

class finesse.components.TestPoint(*args, **kwargs)

Bases: Connector

A simple component which has an arbitrary number of test nodes that can be connected to and from.

Examples

You could make an electronic element that has three ports:

>>> from finesse.components.electronics import TestPoint
>>> model.add(TestPoint('test', 'A', 'B', 'C'))

The element is called test. This has three ports called A, B, and C, each with a single node called io, as it can be outputed to inputted to.

class finesse.components.Variable(*args, **kwargs)

Bases: ModelElement

The variable element acts slightly different to other elements. When added to a model it creates a new finesse.parameter.Parameter in the model it has been added to. This does the same as calling finesse.model.Model.add_parameter(). This new parameter can be used like a variable for making symbolic links to or for storing some useful number about the model.

See finesse.model.Model.add_parameter() for more details.

class finesse.components.Wire(*args, **kwargs)

Bases: Connector

A wire represents a flow of information between signal nodes. It connects two specific signal nodes. Signal nodes have a direction associated with them: input, output, or bidirectional. Depending on what direction each node has depends on what the wire will setup when it is connected. When connecting ports the wire will look at the name of each node in the port and connect nodes with the same name.

Parameters

namestr, optional: Name of newly created wire.
nodeA, nodeBSignalNode: Signal nodes to connect together.
delayfloat, optional: A delay time for the signal to flow from A to B in seconds
gainfloat, optional: A scaling factor that can be used to scale the output relative to the input.

connect(A, B)

Connects A to B signal nodes together with a Wire element. If A or B are ports then the first node is selected from the port to connect. If A or B have more than one node then you should specify.

explicitly which one to use - an exception will be raised in this case.

Parameters

ASignalNode or Port: First signal node or Electrical port with a single node
BSignalNode or Port: Second signal node or Electrical port with a single node

property delay: delay : float, optional A delay time for the signal to flow from A to B in seconds

fill(ws)

property gain: gain : float, optional A scaling factor that can be used to scale the output relative to the input.

property nodeA

property nodeB

class finesse.components.ZPKFilter(*args, **kwargs)

Bases: Filter

A zero-pole-gain filter element that is used for shaping signals in simulations. It is a two port element. p1 is the input port and p2 is the output port. Each one has a single node: p1.i and p2.o.

Parameters

namestr: Name of element in the model
zarray_like[float | Symbols]: A 1D-array of zeros. Use [] if none are required. By default these are provided in units of radians/s, not Hz.
parray_like[float | Symbols]: A 1D-array of poles. Use [] if none are required. By default these are provided in units of radians/s, not Hz.
k[float | Symbol], optional: Gain factor for the zeros and poles. If None then its value is automatically set to generate a unity gain at DC.
fQbool, optional: When True the zeros and poles can be specified in a tuple of (frequency, quality factor) for each pole and zero. This automatically adds the complex conjugate pair.
gainParameter: Overall gain for the filter. Differs from k as this is a Parameter so can be easily switched on/off or varied during a simulation.

Examples

Below are a few examples of using a ZPK filter in a simple simulation and plotting the output.

>>> import finesse
>>> finesse.init_plotting()
>>> model = finesse.Model()
>>> model.parse("""
... # Finesse always expects some optics to be present
... # so we make a laser incident on some photodiode
... l l1 P=1
... readout_dc PD l1.p1.o
... # Amplitude modulate a laser
... sgen sig l1.amp
...
... zpk ZPK_unity [] []
... link(PD.DC, ZPK_unity)
... ad unity ZPK_unity.p2.o f=fsig
...
... zpk ZPK_1 [] [-10*2*pi]
... link(PD.DC, ZPK_1)
... ad zpk1 ZPK_1.p2.o f=fsig
...
... zpk ZPK_2 [-10*2*pi] []
... link(PD.DC, ZPK_2)
... ad zpk2 ZPK_2.p2.o f=fsig
...
... # Using symbolics
... variable a 20*2*pi
... zpk ZPK_symbol [] [-1j*a, 1j*a] -1
... link(PD.DC, ZPK_symbol)
... ad symbol ZPK_symbol.p2.o f=fsig
...
... # Using gain parameter instead of k keeps the unity response at DC but
... # just flips the sign
... zpk ZPK_symbol2 [] [-1j*a, 1j*a] gain=-1
... link(PD.DC, ZPK_symbol2)
... ad symbol_gain ZPK_symbol2.p2.o f=fsig
...
... # Symbolics for an RC low pass filter
... variable R 100
... variable C 10u
... zpk ZPK_RC [] [-1/(R*C)]
... link(PD.DC, ZPK_RC)
... ad RC ZPK_RC.p2.o f=fsig
...
... fsig(1)
... """)

>>> sol = model.run("xaxis(fsig, log, 0.1, 10k, 1000)")
>>> sol.plot(log=True)

eval(f)

Calculate the value of this filter over some frequencies.

Parameters

farray_like: Frequencies in units of Hz

Returns

Harray_like: Complex valued filter output

property gain: gain : Parameter Overall gain for the filter. Differs from k as this is a Parameter so can be easily switched on/off or varied during a simulation.

property sys

The scipy sys object.

In this case it is a tuple of (zeros, poles, k). This does not convert any symbolics used into numerics.

finesse.components package

Subpackages

Submodules

finesse.components.beamsplitter module

Parameters

Attributes

Raises

Returns

Raises

finesse.components.cavity module

Parameters

See Also

See Also

See Also

Parameters

Returns

Returns

Returns

Returns

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

See Also

Returns

See Also

See Also

See Also

See Also

Returns

finesse.components.directional_beamsplitter module

Parameters

finesse.components.dof module

finesse.components.electronics module

Parameters

Parameters

Returns

Examples

Parameters

Examples

Parameters

Returns

finesse.components.frequency_loss module

Parameters

finesse.components.gauss module

finesse.components.general module

Parameters

Parameters

Returns

Raises

Parameters

Returns

Returns

Parameters

Returns

Returns

Returns

Returns

Returns

Parameters

Parameters

Returns

Raises

Parameters

Parameters

Returns

finesse.components.isolator module

Parameters

finesse.components.laser module

Parameters