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).

See Also

Cavity.FSR : Free-spectral-range of a cavity. Cavity.finesse : Finesse of a cavity.

property S

The resolution of the cavity in both planes.

Cavity resolution, \(S\), is defined by,

\[S = \begin{cases} \frac{\psi_{\mathrm{rt}}}{2\pi} \mathcal{F}, & \text{if } \psi_{\mathrm{rt}} \leq \pi\\ (1 - \frac{\psi_{\mathrm{rt}}}{2\pi}) \mathcal{F}, & \text{if } \psi_{\mathrm{rt}} > \pi, \end{cases} \]

where \(\psi_{\mathrm{rt}}\) is the round-trip Gouy phase and \(\mathcal{F}\) is the cavity finesse.

Getter:

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

property Sx

The resolution of cavity in the tangential plane.

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

Getter:

Returns the tangential plane resolution (read-only).

See Also

Cavity.S

property Sy

The resolution of cavity in the sagittal plane.

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

Getter:

Returns the sagittal plane resolution (read-only).

See Also

Cavity.S

any_changing_params(geometric=False)

Determines whether any parameter of any component inside the cavity is changing.

If the optional argument geometric is True, then this will only check that the following parameters are changing:

• radii of curvature of surfaces,

• lengths of spaces,

• refractive indices of spaces,

• focal lengths of lenses,

• angles of incidence of beam splitters.

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).

See Also

Cavity.gouy

property gouy_y

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

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

Getter:

Returns the sagittal plane round-trip Gouy phase (read-only).

See Also

Cavity.gouy

property gx

The stability, g, of the cavity in the tangential plane.

Getter:

Returns the tangential plane g-factor (read-only).

See Also

Cavity.g Cavity.mx

property gy

The stability, g, of the cavity in the sagittal plane.

Getter:

Returns the sagittal plane g-factor (read-only).

See Also

Cavity.g Cavity.my

initialise()

Initialises the symbolic equations of the cavity and calculates the cavity path from the associated model.

property is_changing

Flag indicating whether any geometric parameter inside the cavity is changing.

A geometric parameter is defined as one of:

• radii of curvature of surfaces,

• focal lengths of lenses,

• angles of incidence of beam splitters,

• lengths of spaces,

• refractive indices of spaces,

i.e. any parameter which can affect the ABCD matrix values.

property is_critical

Flag indicating whether the cavity is critically stable.

This only returns True if both planes of the cavity eigenmode are critically stable.

Getter:

Returns True if \(g = 0\) or \(g = 1\), False otherwise (for both tangential, sagittal planes).

See Also

Cavity.g

property is_critical_x

Flag indicating whether the cavity is critically stable in the tangential plane.

Getter:

Returns True if \(g_x = 0\) or \(g_x = 1\), False otherwise.

See Also

Cavity.is_critical Cavity.gx

property is_critical_y

Flag indicating whether the cavity is critically stable in the sagittal plane.

Getter:

Returns True if \(g_x = 0\) or \(g_x = 1\), False otherwise.

See Also

Cavity.is_critical Cavity.gy

property is_fabry_perot

Flag indicating whether the cavity is a Fabry-Perot cavity.

Getter:

Returns true if the cavity is a Fabry-Perot, false otherwise (read-only).

property is_stable

Flag indicating whether the cavity is stable.

This only returns True if both planes of the cavity eigenmode are stable.

Getter:

Returns True if \(0 \leq g \leq 1\), False otherwise (for both tangential, sagittal planes).

See Also

Cavity.g

property is_stable_x

Flag indicating whether cavity is stable in the tangential plane.

Getter:

Returns True if \(0 \leq g_x \leq 1\), False otherwise.

See Also

Cavity.is_stable Cavity.gx

property is_stable_y

Flag indicating whether cavity is stable in the sagittal plane.

Getter:

Returns True if \(0 \leq g_y \leq 1\), False otherwise.

See Also

Cavity.is_stable Cavity.gy

property loss

The round-trip loss of the cavity as a fraction of the incoming power.

This quantity is computed via,

\[L = 1 - \prod_{\mathrm{i}}^{N_{\mathrm{refl}}} R_{\mathrm{i}} \times \prod_{\mathrm{i}}^{N_{\mathrm{trns}}} T_{\mathrm{i}}, \]

i.e. one minus the product of all reflections multiplied with the product of all transmissions for a round-trip of the cavity.

Getter:

Returns the fractional round-trip cavity loss (read-only).

property m

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

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

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:

\[-1 \leq m \leq 1. \]

Getter:

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

property mode_separation

The mode separation frequency of the cavity in both planes.

This is defined by,

\[\delta f = \begin{cases} \frac{\psi_{\mathrm{rt}}}{2\pi} \Delta f, & \text{if } \psi_{\mathrm{rt}} \leq \pi\\ (1 - \frac{\psi_{\mathrm{rt}}}{2\pi}) \Delta f, & \text{if } \psi_{\mathrm{rt}} > \pi, \end{cases} \]

where \(\psi_{\mathrm{rt}}\) is the accumulated round-trip Gouy phase and \(\Delta f\) is the FSR of the cavity.

Getter:

Returns a numpy.ndarray of the mode separation frequency in the tangential and sagittal planes, respectively (read-only).

property mode_separation_x

The mode separation frequency in the tangential plane.

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

Getter:

Returns the tangential plane mode separation frequency (read-only).

See Also

Cavity.mode_separation

property mode_separation_y

The mode separation frequency in the sagittal plane.

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

Getter:

Returns the sagittal plane mode separation frequency (read-only).

See Also

Cavity.mode_separation

property mx

The stability, m, of the cavity in the tangential plane.

Getter:

Returns the tangential plane m-factor (read-only).

See Also

Cavity.m Cavity.gx

property my

The stability, m, of the cavity in the sagittal plane.

Getter:

Returns the sagittal plane m-factor (read-only).

See Also

Cavity.m Cavity.gy

property path

The OpticalPath instance of the cavity.

Getter:

Returns the path of the cavity (read-only), i.e. the shortest round trip path from the start node of cavity (via a given node) back to the same node.

See Also

finesse.model.Model.pathRetrieves an ordered container of the path trace between two

specified nodes.

plot(direction=None, *args, **kwargs)

Plots the beam representing the cavity eigenmode over the path of the cavity.

See PropagationSolution.plot() if specifying direction or AstigmaticPropagationSolution.plot() otherwise.

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).

See Also

Cavity.FWHM : Full-width at half-maximum (FWHM) of a cavity.

property q

The eigenmode of the cavity in both planes.

For a single plane, the cavity eigenmode \(q_{\mathrm{cav}}\) is computed by solving,

\[C q_{\mathrm{cav}}^2+(D-A)q_{\mathrm{cav}} - B = 0, \]

where \(A\), \(B\), \(C\) and \(D\) are the elements of the round-trip ABCD matrix of the cavity for this plane.

Getter:

Returns a numpy.ndarray of the cavity eigenmodes in the tangential and sagittal planes, respectively, where both values are BeamParam instances (read-only).

property qx

The eigenmode of the cavity in the tangential plane.

Getter:

Returns the cavity’s tangential plane eigenmode (read-only).

See Also

Cavity.q

property qy

The eigenmode of the cavity in the sagittal plane.

Getter:

Returns the cavity’s sagittal plane eigenmode (read-only).

See Also

Cavity.q

property round_trip_optical_length

The round-trip optical path length of the cavity (in metres).

Getter:

Returns the length of a single round-trip of the cavity (read-only).

property source

Starting node of the cavity.

Getter:

Returns the cavity starting node (read-only).

property storage_time

The cavity storage time (\(\tau\)).

This quantity is defined as,

\[\tau = \frac{1}{\pi\mathrm{FWHM}}, \]

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

Getter:

Returns the storage time of the cavity (read-only).

See Also

Cavity.FWHM : Full-width at half-maximum (FWHM) of a cavity.

trace_beam()

Traces the cavity eigenmode through the cavity path.

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).