KatScript quick reference

• This is a quick KatScript reference. For the full specification: KatScript.

• Click a row to see more information about an item.

• You can copy the syntax overview by using the button appearing on the right of the syntax.

• The full syntax can be viewed and copied in the expanded view.

• Use the input box on the right to quickly filter visible items.

Elements

Name

Syntax overview

Laser

l name P=1 f=0 phase=0

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

Full syntax

l name P=1 f=0 phase=0 signals_only=false

Required arguments

Argument	Type	Description
name	str	Name of the newly created laser.

Optional arguments

Argument	Type	Description
P	float	Power of the laser (in Watts), defaults to 1 W.
f	float or Frequency	Frequency-offset of the laser from the default (in Hz) or Frequency object. Defaults to 0 Hz offset.
phase	float	Phase-offset of the laser from the default, defaults to zero.
signals_only	bool	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.

Aliases:

l, laser, Laser

More info

• Full reference: laser

Mirror

m name R T L phi=0 Rc=inf xbeta=0 ybeta=0

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.

Full syntax

m name R=none T=none L=none phi=0 Rc=inf xbeta=0 ybeta=0 misaligned=false imaginary_transmission=true

Required arguments

Argument	Type	Description
name	str	Name of newly created mirror.

Optional arguments

Argument	Type	Description
R	float	Reflectivity of the mirror; defaults to 0.5.
T	float	Transmittance of the mirror; defaults to 0.5.
L	float	Loss of the mirror; defaults to 0.0.
phi	float	Tuning of the mirror (in degrees); defaults to 0.0.
Rc	float or container of two floats	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, ybeta	float	Misalignment of the mirror in yaw and pitch in units of radians
misaligned	bool	When True the mirror will be significantly misaligned and assumes any reflected beam is dumped. Transmissions will still occur.
imaginary_transmission	bool	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

Aliases:

m, mirror, Mirror

More info

• Full reference: mirror

Beamsplitter

bs name R T L phi=0 alpha=0 Rc=inf xbeta=0 ybeta=0

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.

Full syntax

bs name R=none T=none L=none phi=0 alpha=0 Rc=inf xbeta=0 ybeta=0 plane=0 misaligned=false imaginary_transmission=true

Required arguments

Argument	Type	Description
name	str	Name of newly created beamsplitter.

Optional arguments

Argument	Type	Description
R	float	Reflectivity of the beamsplitter.
T	float	Transmissivity of the beamsplitter.
L	float	Loss of the beamsplitter.
phi	float	Microscopic tuning of the beamsplitter (in degrees).
alpha	float	Angle of incidence (in degrees)
Rc	float	Radius of curvature (in metres); defaults to numpy.inf to indicate a planar surface.
xbeta, ybeta	float	Angle of misalignment in the yaw plane (xbeta) and pitch (ybeta), respectively (in radians); defaults to 0.
plane	str	Plane of incidence, either ‘xz’ or ‘yz’. Defaults to ‘xz’.
misaligned	bool	When True the beamsplitter will be significantly misaligned and assumes any reflected beam is dumped. Transmissions will still occur.

Aliases:

bs, beamsplitter, Beamsplitter

More info

• Full reference: beamsplitter

Modulator

mod name f midx order=1 mod_type=pm phase=0.0

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

Full syntax

mod name f midx order=1 mod_type=pm phase=0.0 positive_only=false

Required arguments

Argument	Type	Description
name	str	Name of newly created modulator.
midx	float	Modulation index, >= 0.

Optional arguments

Argument	Type	Description
f	float or Frequency	Frequency of the modulation (in Hz) or Frequency object.
order	int	Maximum order of modulations to produce. Must be 1 for amplitude modulation. Defaults to 1.
mod_type	str	Modulation type: - ‘am’ (amplitude modulation) - ‘pm’ (phase modulation) - ‘yaw’ (alignment modulation) (EXPERIMENTAL) - ‘pitch’ (alignment modulation) (EXPERIMENTAL) Defaults to ‘pm’.
phase	float	Relative phase of modulation (in degrees). Defaults to 0.0.
positive_only	bool	If True, only produce positive-frequency sidebands. Defaults to False.

Aliases:

mod, modulator, Modulator

More info

• Full reference: modulator

Space

s name portA portB L=0.0 nr=1.0

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

Full syntax

s name portA portB L=0.0 nr=1.0 user_gouy_x=none user_gouy_y=none

Required arguments

Argument	Type	Description
portA, portB	Port	Ports to connect.

Optional arguments

Argument	Type	Description
name	str	Name of newly created space. If not specified, a name is automatically generated.
L	float	Geometric length of newly created Space instance; defaults to 0.
nr	float	Index of refraction of newly created Space instance; defaults to 1.0.
user_gouy_x, user_gouy_y	float	User-defined gouy phase to override the calculated value.

Aliases:

s, space, Space

More info

• Full reference: space

Cavity

cav name source

Represents a cavity in an interferometer configuration.

Full syntax

cav name source via=none priority=0

Required arguments

Argument	Type	Description
name	str	Name of newly created cavity.
source	OpticalNode 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.

Optional arguments

Argument	Type	Description
via	OpticalNode	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.
priority	number or 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.

Aliases:

cav, cavity, Cavity

More info

• Full reference: cavity

Gaussian beam

gauss name node

Beam parameter at a specific node of a model.

Full syntax

gauss name node priority=0 **kwargs

Aliases:

gauss

More info

• Full reference: gauss

Lens

lens name f=inf

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

Full syntax

lens name f=inf

Required arguments

Argument	Type	Description
name	str	Name of newly created lens.

Optional arguments

Argument	Type	Description
f	float	Focal length of the lens in metres; defaults to infinity.

Aliases:

lens, Lens

More info

• Full reference: lens

Nothing

nothing name

Represents an empty point in the interferometer configuration.

Full syntax

nothing name

Required arguments

Argument	Type	Description
name	str	Name of newly created nothing.

Aliases:

nothing, Nothing

More info

• Full reference: nothing

Signal generator

sgen name node amplitude=1 phase=0

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

Full syntax

sgen name node amplitude=1 phase=0

Required arguments

Argument	Type	Description
name	str	Name of newly created signal generator.
node	.class:finesse.components.node.Node	A node to inject a signal into.

Optional arguments

Argument	Type	Description
amplitude	float	Amplitude of the signal in volts.
phase	float	Phase-offset of the signal from the default in degrees, defaults to zero.

Aliases:

sgen, signal_generator, SignalGenerator

More info

• Full reference: signal_generator

Squeezer

sq name db f=0 angle=0

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.

Full syntax

sq name db f=0 angle=0

Required arguments

Argument	Type	Description
name	str	Name of the newly created squeezer.
db	float	Squeezing factor (in amplitude decibels). 6dB gives a factor of 2 reduction in noise.

Optional arguments

Argument	Type	Description
f	float or Frequency	Frequency-offset of the squeezer from the default (in Hz) or Frequency object. Defaults to 0 Hz offset.
angle	float	Squeezing angle (in degrees). Defaults to zero.

Aliases:

sq, squeezer, Squeezer

More info

• Full reference: squeezer

Isolator

isol name S=0.0

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.

Full syntax

isol name S=0.0

Required arguments

Argument	Type	Description
name	str	Name of newly created isolator.
S	float	Power suppression in dB. Defaults to 0

Aliases:

isol, isolator, Isolator

More info

• Full reference: isolator

Suspension ZPK

sus_zpk name connected_to zpk_plant

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.

Full syntax

sus_zpk name connected_to zpk_plant

Required arguments

Argument	Type	Description
name	str	Element name
connected_to	Element or mechanical port	Mechanical port or element to attach this suspension to
zpk_plant	dict	Dictionary of {(output, input):(z,p,k)}

Aliases:

sus_zpk, suspension_zpk, SuspensionZPK

More info

• Full reference: suspension_zpk

Astigmatic lens

alens name fx=inf fy=inf

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

Full syntax

alens name fx=inf fy=inf

Required arguments

Argument	Type	Description
name	str	Name of newly created lens.

Optional arguments

Argument	Type	Description
fx	float	Focal length in x-z plane of the lens in metres; defaults to infinity.
fy	float	Focal length of y-z plane the lens in metres; defaults to infinity.

Aliases:

alens, AstigmaticLens

More info

• Full reference: alens

Amplifier

amplifier name gain=1

Missing summary

Full syntax

amplifier name gain=1

Aliases:

amplifier, Amplifier

More info

• Full reference: amplifier

Degree of freedom

dof name *node_amplitude_pairs DC=0

Missing summary

Full syntax

dof name *node_amplitude_pairs DC=0

Aliases:

dof, degree_of_freedom, DegreeOfFreedom

More info

• Full reference: degree_of_freedom

Directional beamsplitter

dbs name

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

Full syntax

dbs name

Required arguments

Argument	Type	Description
name	str	Name of newly created directional beamsplitter.

Aliases:

dbs, directional_beamsplitter, DirectionalBeamsplitter

More info

• Full reference: directional_beamsplitter

Frequency loss

floss name f loss=0 phase=0

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

Full syntax

floss name f loss=0 phase=0

Required arguments

Argument	Type	Description
name	str	Name of newly created lens.

Optional arguments

Argument	Type	Description
f	float	Frequency to apply loss and phase to.
loss	float	Fractional loss at the frequency
phase	float	Phase change at the frequency

Aliases:

floss, FrequencyLoss

More info

• Full reference: floss

Free mass

free_mass name connected_to mass=inf I_yaw=inf I_pitch=inf

Simple free mass suspension of an object.

Full syntax

free_mass name connected_to mass=inf I_yaw=inf I_pitch=inf

Aliases:

free_mass, FreeMass

More info

• Full reference: free_mass

Lock

lock name error_signal feedback gain accuracy enabled=true offset=0

A simple lock which computes and applies the feedback to a given parameter using an error signal.

Full syntax

lock name error_signal feedback gain accuracy enabled=true offset=0

Required arguments

Argument	Type	Description
name	str	Name of newly created lock.
error_signal	Any	An error signal parameter or an object capable of producing a real-type error signal. This is typically a demodulated PowerDetector instance (or the name of the instance).
feedback	Parameter	A parameter of the model to apply the locks’ feedback signal to.
gain	float	Control loop gain.
accuracy	float	Threshold to decide whether the loop is locked.
enabled	boolean	If true this lock will run when the RunLocks() action is used. Explicitly specifying the name of the lock will override this setting, e.g. RunLocks(name).
offset	float	An offset that is applied to the error signal before it is used.

Aliases:

lock, Lock

More info

• Full reference: lock

Noise

noise name node ASD

Missing summary

Full syntax

noise name node ASD

Aliases:

noise, ClassicalNoise

More info

• Full reference: noise

Pendulum

pendulum name connected_to mass=inf Qz=1000 fz=1 I_yaw=inf Qyaw=1000 fyaw=1 I_pitch=inf Qpitch=1000 fpitch=1

Simple pendulum suspension of an object.

Full syntax

pendulum name connected_to mass=inf Qz=1000 fz=1 I_yaw=inf Qyaw=1000 fyaw=1 I_pitch=inf Qpitch=1000 fpitch=1

Aliases:

pendulum, Pendulum

More info

• Full reference: pendulum

Wire

w name nodeA nodeB delay=0 gain=1

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.

Full syntax

w name nodeA nodeB delay=0 gain=1

Required arguments

Argument	Type	Description
nodeA, nodeB	SignalNode	Signal nodes to connect together.

Optional arguments

Argument	Type	Description
name	str	Name of newly created wire.
delay	float	A delay time for the signal to flow from A to B in seconds
gain	float	A scaling factor that can be used to scale the output relative to the input.

Aliases:

w, wire, Wire

More info

• Full reference: wire

Telescope

tel name

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.

Full syntax

tel name

Required arguments

Argument	Type	Description
name	str	Name of newly created telescope

Aliases:

tel, telescope, Telescope

More info

• Full reference: telescope

Test point

test name *ports

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

Full syntax

test name *ports

Aliases:

test, test_point, TestPoint

More info

• Full reference: test_point

Variable

var name value description=none units='' is_geometric=false changeable_during_simulation=true

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.

Full syntax

var name value description=none units='' is_geometric=false changeable_during_simulation=true

Aliases:

var, variable

More info

• Full reference: variable

Detectors

Name

Syntax overview

Amplitude detector

ad name node f

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

Full syntax

ad name node f n=none m=none

Required arguments

Argument	Type	Description
name	str	Name of newly created detector.
node	Node	Node to read output from.
f	float	Frequency of light to detect (in Hz).

Optional arguments

Argument	Type	Description
n	int or optional; default: None	Tangential mode index to probe. Defaults to None such that all fields of the given frequency are summed.
m	int or optional; default: None	Sagittal mode index to probe. Defaults to None such that all fields of the given frequency are summed.

Aliases:

ad, amplitude_detector, AmplitudeDetector

More info

• Full reference: amplitude_detector

Readout DC

readout_dc name optical_node

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.

Full syntax

readout_dc name optical_node=none pdtype=none output_detectors=false

Required arguments

Argument	Type	Description
name	str	Name of the readout component

Optional arguments

Argument	Type	Description
optical_node	Node or Port or None	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 Space or with finesse.model.Model.link() command (and then only a single readout can be connected per port).
pdtype	str or dict or None	A name of a pdtype definition or a dict representing a pdtype definition, by default None. See Segmented photodiodes
output_detectors	bool	Whether to add a PowerDetector and a QuantumShotNoiseDetector to the solution object, by default False

Aliases:

readout_dc, ReadoutDC

More info

• Full reference: readout_dc

Readout RF

readout_rf name optical_node f=0 phase=0

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

Full syntax

readout_rf name optical_node=none f=0 phase=0 output_detectors=false pdtype=none

Required arguments

Argument	Type	Description
name	str	Name of the readout component

Optional arguments

Argument	Type	Description
optical_node	Node or Port or None	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 Space or with link command (and then only a single readout can be connected per port).
f	float	Demodulation frequency in Hz, by default 0
phase	float	Demodulation phase in degrees, by default 0
output_detectors	bool	Whether to add a PowerDetector (DC), two PowerDetectorDemod1 ‘s (I and Q) and a QuantumShotNoiseDetectorDemod1 to the solution object, by default False
pdtype	str or dict or None	A name of a pdtype definition or a dict representing a pdtype definition, by default None. See Segmented photodiodes

Aliases:

readout_rf, ReadoutRF

More info

• Full reference: readout_rf

Power detector DC

pd name node pdtype=none

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

Full syntax

pd name node pdtype=none

Required arguments

Argument	Type	Description
name	str	Name of newly created power detector.
node	Node	Node to read output from.

Aliases:

pd, power_detector_dc, PowerDetector

More info

• Full reference: power_detector_dc

CCD, camera

ccd name node xlim ylim npts

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

Full syntax

ccd name node xlim ylim npts w0_scaled=true

Required arguments

Argument	Type	Description
name	str	Unique name of the camera.
node	OpticalNode	Node at which to detect.
xlim	sequence or scalar	Limits of the x-dimension of the image. If a single number is given then this will be computed as \(x_{\mathrm{lim}} = [-|x|, +|x|]\).
ylim	sequence or scalar	Limits of the y-dimension of the image. If a single number is given then this will be computed as \(y_{\mathrm{lim}} = [-|y|, +|y|]\).
npts	int	Number of points in both axes.

Optional arguments

Argument	Type	Description
w0_scaled	bool or optional; default: True	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

ccd, CCD

More info

• Full reference: ccd

CCD, line

ccdline name node npts x y xlim ylim

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

Full syntax

ccdline name node npts x=none y=none xlim=none ylim=none w0_scaled=true

Required arguments

Argument	Type	Description
name	str	Unique name of the camera.
node	OpticalNode	Node at which to detect.
npts	int	Number of points in slice axis.
x	scalar or None; default: None	The x coordinate of the slice. If ylim is given and this is not specified then defaults to zero. If xlim is given and this is also specified then it is ignored.
y	scalar or None; default: None	The y coordinate of the slice. If xlim is given and this is not specified then defaults to zero. If ylim is given and this is also specified then it is ignored.
xlim	scalar or size two sequence; default: None	The limits of the x-axis scan lines. A single number gives \(x_{\mathrm{axis}} \in [-|x|, +|x|]\), or a tuple of size two gives \(x_{\mathrm{axis}} \in [x[0], x[1]]\).
ylim	scalar or array-like; default: None	The limits of the y-axis scan lines. A single number gives \(y_{\mathrm{axis}} \in [-|y|, +|y|]\), or a tuple of size two gives \(y_{\mathrm{axis}} \in [y[0], y[1]]\).

Optional arguments

Argument	Type	Description
w0_scaled	bool or optional; default: True	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

ccdline, CCDScanLine

More info

• Full reference: ccdline

Field camera

fcam name node xlim ylim npts

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

Full syntax

fcam name node xlim ylim npts f=0 w0_scaled=true

Required arguments

Argument	Type	Description
name	str	Unique name of the camera.
node	OpticalNode	Node at which to detect.
xlim	sequence or scalar	Limits of the x-dimension of the image. If a single number is given then this will be computed as \(x_{\mathrm{lim}} = [-|x|, +|x|]\).
ylim	sequence or scalar	Limits of the y-dimension of the image. If a single number is given then this will be computed as \(y_{\mathrm{lim}} = [-|y|, +|y|]\).
npts	int	Number of points in both axes.

Optional arguments

Argument	Type	Description
f	scalar or optional; default: 0	Field frequency offset from the carrier to detect.
w0_scaled	bool or optional; default: True	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

fcam, FieldCamera

More info

• Full reference: fcam

Field detector

fd name node f

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

Full syntax

fd name node f

Required arguments

Argument	Type	Description
name	str	Name of newly created detector.
node	Node	Node to read output from.
f	float	Frequency of light to detect (in Hz).

Aliases:

fd, field_detector, FieldDetector

More info

• Full reference: field_detector

Math detector

mathd name expression

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

Full syntax

mathd name expression dtype='O' dtype_shape=[] unit='arb.' label=none

Required arguments

Argument	Type	Description
name	str	Name of detector
expression	Symbol	Symbolic expression to evaluate as the detectors output
dtype_shape	tuple	The expected array shape when evaluating expression. Defaults to an empty tuple. This must be an empty tuple if dtype is a scalar type or “O”.
unit	str	The unit of the output for plotting. Defaults to “arb.”
label	str or None	How to label the axis when plotting this detector. Defaults to None.

Optional arguments

Argument	Type	Description
dtype	numpy.dtype	The expected data type when evaluating expression. Defaults to “O”.

Aliases:

mathd, math_detector, MathDetector

More info

• Full reference: math_detector

Gouy detector

gouy name *args from_node to_node via_node direction=x

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

Full syntax

gouy name *args from_node=none to_node=none via_node=none direction=x

Required arguments

Argument	Type	Description
name	str	Name of newly created gouy detector.
*args	sequence	A sequence of spaces or space names.
from_node	node-like	An OpticalNode instance, or a data type which can be converted to an optical node.
to_node	node-like	An OpticalNode instance, or a data type which can be converted to an optical node.
via_node	node-like	An OpticalNode instance, or a data type which can be converted to an optical node.
direction	str	Plane to detect in - ‘x’ for tangential, ‘y’ for sagittal. Defaults to ‘x’.

Aliases:

gouy, Gouy

More info

• Full reference: gouy

Power detector demod 1

pd1 name node f

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

Full syntax

pd1 name node f phase=none pdtype=none

Required arguments

Argument	Type	Description
name	str	Name of newly created power detector.
node	Node	Node to read output from.
f	float	Demodulation frequency in Hz

Optional arguments

Argument	Type	Description
phase	float	Demodulation phase in degrees

Aliases:

pd1, power_detector_demod_1, PowerDetectorDemod1

More info

• Full reference: power_detector_demod_1

Power detector demod 2

pd2 name node f1 phase1 f2 phase2

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

Full syntax

pd2 name node f1 phase1 f2 phase2=none pdtype=none

Required arguments

Argument	Type	Description
name	str	Name of newly created power detector.
node	Node	Node to read output from.
f1	float	First demodulation frequency in Hz
phase1	float	First demodulation phase in degrees
f2	float	Second demodulation frequency in Hz

Optional arguments

Argument	Type	Description
phase2	float	Second demodulation phase in degrees

Aliases:

pd2, power_detector_demod_2, PowerDetectorDemod2

More info

• Full reference: power_detector_demod_2

Astigmatism detector

astigd name node

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

Full syntax

astigd name node

Required arguments

Argument	Type	Description
name	str	Name of the detector.
node	OpticalNode	Node to compute astigmatism at.

Aliases:

astigd, AstigmatismDetector

More info

• Full reference: astigd

Beam property detector

bp name node prop

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

Full syntax

bp name node prop direction=x q_as_bp=false

Required arguments

Argument	Type	Description
name	str	Name of newly created detector.
node	OpticalNode	Node to read output from.
prop	str or BeamProperty	The property of the beam to detect. See above for options.

Optional arguments

Argument	Type	Description
direction	str or optional; default: ‘x’	Plane to detect in - ‘x’ for tangential, ‘y’ for sagittal.
q_as_bp	bool or optional; default: False	If detecting q, should the detector output return BeamParam object instead of just a complex number.

Aliases:

bp, beam_property_detector, BeamPropertyDetector

More info

• Full reference: beam_property_detector

Cavity property detector

cp name cavity prop

Probe for detecting the properties of a cavity.

Full syntax

cp name cavity prop direction=x q_as_bp=false

Required arguments

Argument	Type	Description
name	str	Name of newly created cavity property detector.
cavity	str or Cavity	The cavity to probe. If the name is provided then the CavityPropertyDetector.cavity attribute will point to the corresponding Cavity object when adding this detector to a Model instance.
prop	str or CavityProperty	Property of the cavity to probe. See above for options.

Optional arguments

Argument	Type	Description
direction	str or optional; default: ‘x’	Plane to detect in.
q_as_bp	bool or optional; default: False	If detecting q, should the detector output return BeamParam object instead of just a complex number.

Aliases:

cp, cavity_property_detector, CavityPropertyDetector

More info

• Full reference: cavity_property_detector

CCD, pixel

ccdpx name node x=0 y=0

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

Full syntax

ccdpx name node x=0 y=0 w0_scaled=true

Required arguments

Argument	Type	Description
name	str	Unique name of the camera.
node	OpticalNode	Node at which to detect.

Optional arguments

Argument	Type	Description
x	scalar or optional; default: 0	The x co-ordinate of the pixel.
y	scalar or optional; default: 0	The y co-ordinate of the pixel.
w0_scaled	bool or optional; default: True	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

ccdpx, CCDPixel

More info

• Full reference: ccdpx

Field scan pixel

fpx name node x=0 y=0 f=0

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

Full syntax

fpx name node x=0 y=0 f=0 w0_scaled=true

Required arguments

Argument	Type	Description
name	str	Unique name of the camera.
node	OpticalNode	Node at which to detect.

Optional arguments

Argument	Type	Description
x	scalar or optional; default: 0	The x co-ordinate of the pixel.
y	scalar or optional; default: 0	The y co-ordinate of the pixel.
f	scalar or optional; default: 0	Field frequency offset from the carrier to detect.
w0_scaled	bool or optional; default: True	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

fpx, FieldPixel

More info

• Full reference: fpx

Field scan line

fline name node npts x y xlim ylim

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

Full syntax

fline name node npts x=none y=none xlim=none ylim=none f=0 w0_scaled=true

Required arguments

Argument	Type	Description
name	str	Unique name of the camera.
node	OpticalNode	Node at which to detect.
npts	int	Number of points in slice axis.
x	scalar or None; default: None	The x coordinate of the slice. If ylim is given and this is not specified then defaults to zero. If xlim is given and this is also specified then it is ignored.
y	scalar or None; default: None	The y coordinate of the slice. If xlim is given and this is not specified then defaults to zero. If ylim is given and this is also specified then it is ignored.
xlim	scalar or size two sequence; default: None	The limits of the x-axis scan lines. A single number gives \(x_{\mathrm{axis}} \in [-|x|, +|x|]\), or a tuple of size two gives \(x_{\mathrm{axis}} \in [x[0], x[1]]\).
ylim	scalar or array-like; default: None	The limits of the y-axis scan lines. A single number gives \(y_{\mathrm{axis}} \in [-|y|, +|y|]\), or a tuple of size two gives \(y_{\mathrm{axis}} \in [y[0], y[1]]\).

Optional arguments

Argument	Type	Description
f	scalar or optional; default: 0	Field frequency offset from the carrier to detect.
w0_scaled	bool or optional; default: True	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

fline, FieldScanLine

More info

• Full reference: fline

Knm detector

knmd name comp coupling n1 m1 n2 m2

Direct probe of coupling coefficients at a component.

Full syntax

knmd name comp coupling n1=none m1=none n2=none m2=none

Required arguments

Argument	Type	Description
name	str	Name of newly created KnmDetector.
comp	Connector	A component which can scatter modes.
coupling	str	Coupling direction string, e.g. “11” for coupling coefficients on reflection from the front surface of a mirror.
n1, m1, n2, m2: int or None		From (n1, m1) and To (n2, m2) mode indices of the coupling coefficient(s) to retrieve. See above for the options.

Aliases:

knmd, KnmDetector

More info

• Full reference: knmd

Mode mismatch detector

mmd name node1 node2 direction=x

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

Full syntax

mmd name node1 node2 direction=x percent=false

Required arguments

Argument	Type	Description
name	str	Name of the detector.
node1	OpticalNode or Port	Input node or port. If a Port instance is given then this node will be the input node of that port. Note that this node cannot be an output node.
node2	OpticalNode or Port	Output node or port. If a Port instance is given then this node will be the output node of that port. Note that this node cannot be an input node.

Optional arguments

Argument	Type	Description
direction	str or optional; default: “x”	Plane of computation, defaults to “x” for the tangential plane. Changing to “y” will compute the mode mismatch in the sagittal plane.
percent	bool or optional; default: True	Whether to calculate the mode mismatch as a fraction (default behaviour) or a percentage.

Aliases:

mmd, ModeMismatchDetector

More info

• Full reference: mmd

Motion detector

xd name node

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

Full syntax

xd name node

Required arguments

Argument	Type	Description
name	str	Name of newly created motion detector.
node	Node	Node to read output from.

Aliases:

xd, motion_detector, MotionDetector

More info

• Full reference: motion_detector

Optimal q detector

optbp name node f

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

Full syntax

optbp name node f fix_spot_size=false astigmatic=false accuracy=1e-09 direction=both

Required arguments

Argument	Type	Description
name	str	Name of the detector
node	[str or finesse.components.node]	Node name or object to put this detector at
f	float	Frequency component tro compute the optimal beam parameter for.

Optional arguments

Argument	Type	Description
fix_spot_size	bool	When True the optimised will keep the current spot size at the node fixed and just optimise the curvature.
astigmatic	bool	When True qx and qy will be optimised separately
accuracy	float	Approximate mismatch accuracy to try and compute the optimised beam parameter to. mismatch(q_actual, q_optimal) < accuracy
direction	str	Return either both or just the x or y modes

Aliases:

optbp, optimal_q_detector, OptimalQ

More info

• Full reference: optimal_q_detector

Quantum

Name

Syntax overview

Quantum noise detector

qnoised name node

Represents a quantum noise detector with no RF demodulations.

Full syntax

qnoised name node nsr=false sources=none exclude_sources=none

Required arguments

Argument	Type	Description
name	str	Name of newly created quantum noise detector.
node	Node	Node to read output from.

Optional arguments

Argument	Type	Description
nsr	bool	If true, calculate the noise-to-signal ratio rather than the absolute noise value.
sources	list of Connector	If given, only detect quantum noise contributions from these components.
exclude_sources	list of Connector	If given, this will not detect quantum noise contributions from any of these components, even if explicitly specified in sources.

Aliases:

qnoised, quantum_noise_detector, QuantumNoiseDetector

More info

• Full reference: quantum_noise_detector

Quantum noise detector demod 1

qnoised1 name node f phase

Represents a quantum noise detector with 1 RF demodulation.

Full syntax

qnoised1 name node f phase nsr=false sources=none exclude_sources=none

Required arguments

Argument	Type	Description
name	str	Name of newly created quantum noise detector.
node	Node	Node to read output from.
f	float	Demodulation frequency in Hz
phase	float	Demodulation phase in degrees

Optional arguments

Argument	Type	Description
nsr	bool	If true, calculate the noise-to-signal ratio rather than the absolute noise value.
sources	list of Connector	If given, only detect quantum noise contributions from these components.

Aliases:

qnoised1, quantum_noise_detector_demod_1, QuantumNoiseDetectorDemod1

More info

• Full reference: quantum_noise_detector_demod_1

Quantum noise detector demod 2

qnoised2 name node f1 phase1 f2 phase2

Represents a quantum noise detector with 2 RF demodulations.

Full syntax

qnoised2 name node f1 phase1 f2 phase2 nsr=false sources=none exclude_sources=none

Required arguments

Argument	Type	Description
name	str	Name of newly created quantum noise detector.
node	Node	Node to read output from.
f1	float	First demodulation frequency in Hz
phase1	float	First demodulation phase in degrees
f2	float	Second demodulation frequency in Hz
phase2	float	Second demodulation phase in degrees

Optional arguments

Argument	Type	Description
nsr	bool	If true, calculate the noise-to-signal ratio rather than the absolute noise value.
sources	list of Connector	If given, only detect quantum noise contributions from these components.

Aliases:

qnoised2, quantum_noise_detector_demod_2, QuantumNoiseDetectorDemod2

More info

• Full reference: quantum_noise_detector_demod_2

Quantum shot noise detector

qshot name node

Represents a quantum shot noise detector with no RF demodulations.

Full syntax

qshot name node nsr=false

Required arguments

Argument	Type	Description
name	str	Name of newly created quantum shot noise detector.
node	Node	Node to read output from.

Optional arguments

Argument	Type	Description
nsr	bool	If true, calculate the noise-to-signal ratio rather than the absolute noise value.

Aliases:

qshot, quantum_shot_noise_detector, QuantumShotNoiseDetector

More info

• Full reference: quantum_shot_noise_detector

Quantum shot noise detector demod 1

qshot1 name node f phase

Represents a quantum shot noise detector with 1 RF demodulation.

Full syntax

qshot1 name node f phase nsr=false

Required arguments

Argument	Type	Description
name	str	Name of newly created quantum shot noise detector.
node	Node	Node to read output from.
f	float	Demodulation frequency in Hz
phase	float	Demodulation phase in degrees

Optional arguments

Argument	Type	Description
nsr	bool	If true, calculate the noise-to-signal ratio rather than the absolute noise value.

Aliases:

qshot1, quantum_shot_noise_detector_demod_1, QuantumShotNoiseDetectorDemod1

More info

• Full reference: quantum_shot_noise_detector_demod_1

Quantum shot noise detector demod 2

qshot2 name node f1 phase1 f2 phase2

Represents a quantum shot noise detector with 2 RF demodulations.

Full syntax

qshot2 name node f1 phase1 f2 phase2 nsr=false

Required arguments

Argument	Type	Description
name	str	Name of newly created quantum shot noise detector.
node	Node	Node to read output from.
f1	float	First demodulation frequency in Hz
phase1	float	First demodulation phase in degrees
f2	float	Second demodulation frequency in Hz
phase2	float	Second demodulation phase in degrees

Optional arguments

Argument	Type	Description
nsr	bool	If true, calculate the noise-to-signal ratio rather than the absolute noise value.

Aliases:

qshot2, quantum_shot_noise_detector_demod_2, QuantumShotNoiseDetectorDemod2

More info

• Full reference: quantum_shot_noise_detector_demod_2

Filters

Name

Syntax overview

Butter filter

butter name order btype frequency gain=1 analog=true

Missing summary

Full syntax

butter name order btype frequency gain=1 analog=true

Aliases:

butter, filter_butter, ButterFilter

More info

• Full reference: filter_butter

Cheby1 filter

cheby1 name order rp btype frequency gain=1 analog=true

Missing summary

Full syntax

cheby1 name order rp btype frequency gain=1 analog=true

Aliases:

cheby1, filter_cheby1, Cheby1Filter

More info

• Full reference: filter_cheby1

ZPK filter

zpk name z p gain=1

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.

Full syntax

zpk name z p k=none fQ=false gain=1

Required arguments

Argument	Type	Description
name	str	Name of element in the model
z	array_like[float or Symbols]	A 1D-array of zeros. Use [] if none are required. By default these are provided in units of radians/s, not Hz.
p	array_like[float or Symbols]	A 1D-array of poles. Use [] if none are required. By default these are provided in units of radians/s, not Hz.
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.

Optional arguments

Argument	Type	Description
k	[float or Symbol]	Gain factor for the zeros and poles. If None then its value is automatically set to generate a unity gain at DC.
fQ	bool	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.

Aliases:

zpk, filter_zpk, ZPKFilter

More info

• Full reference: filter_zpk

Optical bandpass filter

obp name fc=0 bandwidth=1000

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

Full syntax

obp name fc=0 bandwidth=1000 filter_hom=none

Required arguments

Argument	Type	Description
name	str	Name of element
fc	float or symbol	Central frequency
bandwidth	float or symbol	Filter 3dB bandwidth

Optional arguments

Argument	Type	Description
filter_hom	[tuple or None]	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.

Aliases:

obp, optical_bandpass, OpticalBandpassFilter

More info

• Full reference: optical_bandpass

Actions

Note

Actions use a different syntax than the other Katscript constructs. We recommend that they are used via the Python interface. They are described here for completeness and for those who may wish to use them directly in Katscript, e.g. for serialisation.

More information on the Python API for actions

Name

Syntax overview

No x-axis

noxaxis(pre_step=none, post_step=none, name='noxaxis')

The default Action for a model when no action is specified. Solves the model without changing any parameters. Will return a solution with a single value for every detector in the model.

Full syntax

noxaxis(pre_step=none, post_step=none, name='noxaxis')

Optional arguments

Argument	Type	Description
pre_step	Action or None	An action to perform before the Noxaxis is run, by default None
post_step	Action or None	An action to perform after the Noxaxis is run, by default None
name	str	Name of the action, used to find the solution in the final output, by default “noxaxis”

Aliases:

noxaxis, Noxaxis

More info

• Full reference: noxaxis

Plot

plot(name=abcd)

Missing summary

Full syntax

plot(name=abcd)

Aliases:

plot, Plot

More info

• Full reference: plot

Sweep axis

xaxis(parameter, mode, start, stop, steps)

Sweeps a parameter and solves the model for every value in the sweep. Will a solution with an array of values for every detector in the model.

Full syntax

xaxis(
   parameter,
   mode,
   start,
   stop,
   steps,
   relative=false,
   pre_step=none,
   post_step=none,
   name='xaxis'
)

Required arguments

Argument	Type	Description
parameter	Parameter or ParameterRef or str	Parameter to sweep over.
mode	‘lin’ or ‘log’	Whether to sweep linearly or logarithmically
start	float	Starting value of the parameter sweep
stop	float	Final value of the parameter sweep.
steps	int	Number of steps in the sweep. Solution arrays will contain ‘steps+1’ values

Optional arguments

Argument	Type	Description
relative	bool	Whether to apply the changes to the parameter value on top of the current value or ignore the current value of the parameter, by default False
pre_step	Action or None	An action to perform before each step is computed, by default None
post_step	Action or None	An action to perform after each step is computed, by default None
name	str	Name of the action, used to find the solution in the final output, by default “xaxis”

Aliases:

xaxis, Xaxis

More info

• Full reference: xaxis

Frequency response

freqresp(f, inputs, outputs)

Computes the frequency response of a signal injected at various nodes to compute transfer functions to multiple output nodes. Inputs and outputs should be electrical or mechanical nodes. It does this in an efficient way by using the same model and solving for multiple RHS input vectors.

Full syntax

freqresp(f, inputs, outputs, open_loop=false, name='frequency_response')

Required arguments

Argument	Type	Description
f	array or double	Frequencies to compute the transfer functions over
inputs	iterable[str or Element]	Mechanical or electrical node to inject signal at
outputs	iterable[str or Element]	Mechanical or electrical nodes to measure output at

Optional arguments

Argument	Type	Description
open_loop	bool	Computes open loop transfer functions if the system has closed
name	str	Solution name

Aliases:

freqresp, frequency_response, FrequencyResponse

More info

• Full reference: frequency_response

ABCD matrix

abcd(name=abcd, **kwargs)

Computation of an ABCD matrix over a path.

Full syntax

abcd(name=abcd, **kwargs)

Aliases:

abcd, ABCD

More info

• Full reference: abcd

Beam trace

beam_trace(name='beam_trace', **kwargs)

Full beam tracing on a complete model.

Full syntax

beam_trace(name='beam_trace', **kwargs)

Aliases:

beam_trace, BeamTrace

More info

• Full reference: beam_trace

Eigenmodes

eigenmodes(cavity, frequency, name='eigenmodes')

For a given Cavity defined in a model, this action will compute the roundtrip operator and calculate the eigen-values and -vectors of the cavity. This will not give correct solutions for coupled cavities as these need to include additional effects.

Full syntax

eigenmodes(cavity, frequency, name='eigenmodes')

Required arguments

Argument	Type	Description
cavity	str or Cavity	cavity name or Cavity instance
frequency	float	Optical carrier or signal frequency to use for calculating the operators

Optional arguments

Argument	Type	Description
name	str	Name of the solution generated by this action

Aliases:

eigenmodes, Eigenmodes

More info

• Full reference: eigenmodes

Maximize

maximize(detector, parameter, *args, name='maximize', **kwargs)

An action that maximizes some detector output by applying some feedback to multiple targets in a model. Extra keyword arguments are passed on to the Scipy method:

Full syntax

maximize(detector, parameter, *args, name='maximize', **kwargs)

Required arguments

Argument	Type	Description
detector	str	The name of the detector output to maximize / minimize.
parameter	[Parameter or str or tuple]	The parameter or name of the parameter to optimize, or a tuple of parameters when using multiple targets to optimize over.
kwargs		Optional parameters passed to the Scipy optimisation routine as the options input. See Scipy method documentation to determine what is available.

Optional arguments

Argument	Type	Description
bounds	list	A pair of (lower, upper) bounds on the parameter value. Requires a method that uses bounds.
offset	float	An offset applied to the detector output when optimizing, defaults to 0.
kind	str	Either ‘max’ for maximization or ‘min’ for minimization, defaults to ‘max’.
max_iterations	int	Maximum number of solver iterations, defaults to 10000.
method	str	Optimisation method to use, see Scipy documentation for options.
name	str	The name of this action, defaults to ‘maximize’.
update_maps	bool	If you are changing some parameter or variable that a Map depends on then setting this flag to True will recompute the Map data for each iteration of the optimiser.
pre_step	Action	Action to run on each step of the optimisation.

Aliases:

maximize, Maximize

More info

• Full reference: maximize

Minimize

minimize(detector, parameter, *args, name='minimize', **kwargs)

An action that minimizes some detector output by applying some feedback to multiple targets in a model. Extra keyword arguments are passed on to the Scipy method:

Full syntax

minimize(detector, parameter, *args, name='minimize', **kwargs)

Required arguments

Argument	Type	Description
detector	str	The name of the detector output to maximize / minimize.
parameter	[Parameter or str or tuple]	The parameter or name of the parameter to optimize, or a tuple of parameters when using multiple targets to optimize over.
kwargs		Optional parameters passed to the Scipy optimisation routine as the options input. See Scipy method documentation to determine what is available.

Optional arguments

Argument	Type	Description
bounds	list	A pair of (lower, upper) bounds on the parameter value. Requires a method that uses bounds.
offset	float	An offset applied to the detector output when optimizing, defaults to 0.
kind	str	Either ‘max’ for maximization or ‘min’ for minimization, defaults to ‘max’.
max_iterations	int	Maximum number of solver iterations, defaults to 10000.
method	str	Optimisation method to use, see Scipy documentation for options.
name	str	The name of this action, defaults to ‘maximize’.
update_maps	bool	If you are changing some parameter or variable that a Map depends on then setting this flag to True will recompute the Map data for each iteration of the optimiser.
pre_step	Action	Action to run on each step of the optimisation.

Aliases:

minimize, Minimize

More info

• Full reference: minimize

Propagate beam

propagate_beam(name='propagation', **kwargs)

Propagation of a beam, in a single plane, through a given path.

Full syntax

propagate_beam(name='propagation', **kwargs)

Aliases:

propagate_beam, PropagateBeam

More info

• Full reference: propagate_beam

Propagate astigmatic beam

propagate_beam_astig(name='astig_propagation', **kwargs)

Propagation of a beam, in both planes, through a given path.

Full syntax

propagate_beam_astig(name='astig_propagation', **kwargs)

Aliases:

propagate_beam_astig, PropagateAstigmaticBeam

More info

• Full reference: propagate_beam_astig

Run locks

run_locks(*locks, method='proportional', scale_factor=1, sensing_matrix=none, max_iterations=10000, display_progress=false, optimize_phase=none, d_dof_phase=1e-09, set_gains=true, d_dof_gain=1e-09, exception_on_fail=true, no_warning=false, pre_step=none, show_progress_bar=none, name='run locks')

An action that iteratively moves the system to lock. Currently, lock error signals must be readouts, not detectors, for use in this action.

Full syntax

run_locks(
   *locks,
   method='proportional',
   scale_factor=1,
   sensing_matrix=none,
   max_iterations=10000,
   display_progress=false,
   optimize_phase=none,
   d_dof_phase=1e-09,
   set_gains=true,
   d_dof_gain=1e-09,
   exception_on_fail=true,
   no_warning=false,
   pre_step=none,
   show_progress_bar=none,
   name='run locks'
)

Required arguments

Argument	Type	Description
method	str or either “newton” or “proportional”	Which method to use in the locking iterations.
scale_factor	float	Factor by which to multiply all DOF changes. Should be set below 1 if it is desired to minimize overshooting.
sensing_matrix	SensingMatrixSolution or None	Sensing matrix of gains used in locking, of the type that would be returned by state.apply(SensingMatrixDC(lock_dof_names, readout_names) If None, the sensing matrix is recalculated. Recommended to be None except when locking multiple times in a row, e.g. with DragLocks.
max_iterations	int	The maximum number of locking steps in each execution of RunLocks.
display_progress	boolean	When true, displays the status of the error signals during locking iterations.
optimize_phase	boolean	Deprecated: Use an action like OptimiseRFReadoutPhaseDC instead.
d_dof_phase	float	Step size to use when optimizing the demodulation phase for each error signal/DOF pair.
set_gains	boolean	Only applies if method is “proportional”. If true, sets the gains for each error signal/DOF pair. If false, uses pre-set gains.
d_dof_gain	float	Step size to use when calculating the gain for every pair of error signals and DOFs.
exception_on_fail	boolean	When true, raise exception if maximum iterations are surpassed.
no_warning	boolean	When true, don’t even raise a warning if maximum iterations are reached. Recommended to be false unless repeatedly testing locking.
pre_step	Action	Action to apply on each step of the lock
show_progress_bar	boolean	Will enable the progress bar when true.
name	str	Name of the action.

Optional arguments

Argument	Type	Description
*locks	list	A list of locks to use in each RunLocks step. If not provided, all locks in model are used.

Aliases:

run_locks, RunLocks

More info

• Full reference: run_locks

Series

series(*actions, flatten=true, name=none)

A sequential series of actions to apply during a simulation.

Full syntax

series(*actions, flatten=true, name=none)

Required arguments

Argument	Type	Description
actions	Action	A collection of Actions to run in series
flatten	bool	When True, each action will be stored in the top level of the solution tree. When False, each action will be a child of the previous solution generated.
name	str	Optional name for the solution generated by these actions

Aliases:

series, Series

More info

• Full reference: series

Sweep 2 axes

x2axis(parameter1, mode1, start1, stop1, steps1, parameter2, mode2, steps2)

Two-dimensional version of the Xaxis action. Will solve the model for every point on a grid of values defined by the two sets of sweep arguments. Returns a solution with a two-dimensional array for every detector in the model.

Full syntax

x2axis(
   parameter1,
   mode1,
   start1,
   stop1,
   steps1,
   parameter2,
   mode2,
   start2,
   stop2,
   steps2,
   relative=false,
   pre_step=none,
   post_step=none,
   name='x2axis'
)

Required arguments

Argument	Type	Description
parameter1	Parameter or ParameterRef or str	Parameter to sweep over.
mode1	‘lin’ or ‘log’	Whether to sweep linearly or logarithmically
start1	float	Starting value of the parameter sweep
stop1	float	Final value of the parameter sweep.
steps1	int	Number of steps in the sweep. Solution arrays will contain ‘steps+1’ values
parameter2	Parameter or ParameterRef or str	Parameter to sweep over.
mode2	‘lin’ or ‘log’	Whether to sweep linearly or logarithmically
start2	float	Starting value of the parameter sweep
stop2	float	Final value of the parameter sweep.
steps2	int	Number of steps in the sweep. Solution arrays will contain ‘steps+1’ values

Optional arguments

Argument	Type	Description
relative	bool	Whether to apply the changes to the parameter value on top of the current value or ignore the current value of the parameter, by default False, by default False
pre_step	Action or None	An action to perform before each step is computed, by default None
post_step	Action or None	An action to perform after each step is computed, by default None
name	str	Name of the action, used to find the solution in the final output, by default “x2axis”

Aliases:

x2axis, X2axis

More info

• Full reference: x2axis

Sweep 3 axes

x3axis(parameter1, mode1, start1, stop1, steps1, parameter2, mode2, start2, stop2, steps2, parameter3, mode3, start3, stop3, steps3)

Three-dimensional version of the Xaxis action. Will solve the model for every point on a cube of values defined by the three sets of sweep arguments. Returns a solution with a three-dimensional array for every detector in the model.

Full syntax

x3axis(
   parameter1,
   mode1,
   start1,
   stop1,
   steps1,
   parameter2,
   mode2,
   start2,
   stop2,
   steps2,
   parameter3,
   mode3,
   start3,
   stop3,
   steps3,
   relative=false,
   pre_step=none,
   post_step=none,
   name='x3axis'
)

Required arguments

Argument	Type	Description
parameter1	Parameter or ParameterRef or str	Parameter to sweep over.
mode1	‘lin’ or ‘log’	Whether to sweep linearly or logarithmically
start1	float	Starting value of the parameter sweep
stop1	float	Final value of the parameter sweep.
steps1	int	Number of steps in the sweep. Solution arrays will contain ‘steps+1’ values
parameter2	Parameter or ParameterRef or str	Parameter to sweep over.
mode2	‘lin’ or ‘log’	Whether to sweep linearly or logarithmically
start2	float	Starting value of the parameter sweep
stop2	float	Final value of the parameter sweep.
steps2	int	Number of steps in the sweep. Solution arrays will contain ‘steps+1’ values
parameter3	Parameter or ParameterRef or str	Parameter to sweep over.
mode3	‘lin’ or ‘log’	Whether to sweep linearly or logarithmically
start3	float	Starting value of the parameter sweep
stop3	float	Final value of the parameter sweep.
steps3	int	Number of steps in the sweep. Solution arrays will contain ‘steps+1’ values

Optional arguments

Argument	Type	Description
relative	bool	Whether to apply the changes to the parameter value on top of the current value or ignore the current value of the parameter, by default False, by default False
pre_step	Action or None	An action to perform before each step is computed, by default None
post_step	Action or None	An action to perform after each step is computed, by default None
name	str	Name of the action, used to find the solution in the final output, by default “x3axis”

Aliases:

x3axis, X3axis

More info

• Full reference: x3axis

for

for(param, values, *actions)

An action changes a parameter value and runs a set of actions for each value in the array. Essentially the same as Series combined with Change. The parameter value is not reset to its original value once this action has finished.

Full syntax

for(param, values, *actions)

Required arguments

Argument	Type	Description
param	str or Parameter	Parameter to change in the model
values	array_like	Array of values to use for the parameter
*actions	tuple(Action)	Actions to run for each parameter value.

Aliases:

for, For

More info

• Full reference: for

Antisqueezing

antisqueezing(f, squeezer, readout)

Computes the amount of anti-squeezing at an output from a squeezing element.

Full syntax

antisqueezing(f, squeezer, readout, signal=none, name='antisqueezing')

Required arguments

Argument	Type	Description
f	array_like	Signal frequencies to compute the anti-squeezing over
squeezer	str	Name of squeezing component
readout	str	Name of readout port to compute squeezing at
signal	str	Name of signal drive to calculate a the signal transfer function of. This is returned in sol.signal and can be used to scale the noise into equivalent units of some signal.

Aliases:

antisqueezing, AntiSqueezing

More info

• Full reference: antisqueezing

DC fields

dc_fields(name='dcfields')

An action that saves the DC (carrier) fields at all nodes, frequencies, and higher order modes for the current state of the simulation.

Full syntax

dc_fields(name='dcfields')

Optional arguments

Argument	Type	Description
name	str	Name of the solution generated by this action

Aliases:

dc_fields, DCFields

More info

• Full reference: dc_fields

Frequency response 2

freqresp2(f, inputs, outputs, name='frequency_response2')

Computes the frequency response of a signal injected at an optical port at a particular optical frequency. This differs from FrequencyResponse in the way the inputs and outputs are prescribed. For FrequencyResponse2 you specify optical input nodes and a signal output node.

Full syntax

freqresp2(f, inputs, outputs, name='frequency_response2')

Required arguments

Argument	Type	Description
f	array or double	Frequencies to compute the transfer functions over
inputs	iterable[tuple[str or Node or Frequency]]	Optical node and frequency tuple to inject at. A symbolic refence to the model’s fsig.f parameter should always be used when defining a frequency to look at.
outputs	iterable[str or Element]	Mechanical or electrical (signal)nodes to measure output to

Optional arguments

Argument	Type	Description
name	str	Solution name

Aliases:

freqresp2, frequency_response2, FrequencyResponse2

More info

• Full reference: frequency_response2

Frequency response 3

freqresp3(f, inputs, outputs, name='frequency_response3')

Computes the frequency response of a signal injected at an optical port at a particular optical frequency. This differs from FrequencyResponse in the way the inputs and outputs are prescribed. For FrequencyResponse3 you specify optical input nodes and optical output nodes.

Full syntax

freqresp3(f, inputs, outputs, name='frequency_response3')

Required arguments

Argument	Type	Description
f	array or double	Frequencies to compute the transfer functions over
inputs	iterable[tuple[str or Node or Frequency]]	Optical node and frequency tuple to inject at. A symbolic reference to the model’s fsig.f parameter should always be used when defining a frequency to look at.
outputs	iterable[tuple[str or Node or Frequency]]	Optical node and frequency tuple to measure output at. A symbolic reference to the model’s fsig.f parameter should always be used when defining a frequency to look at.

Optional arguments

Argument	Type	Description
name	str	Solution name

Aliases:

freqresp3, frequency_response3, FrequencyResponse3

More info

• Full reference: frequency_response3

Frequency response 4

freqresp4(f, inputs, outputs, name='frequency_response4')

Computes the frequency response of a signal injected at an electrical or mechanical port. This differs from FrequencyResponse in the way the inputs and outputs are prescribed. For FrequencyResponse4 you specify signal input nodes and optical output nodes.

Full syntax

freqresp4(f, inputs, outputs, name='frequency_response4')

Required arguments

Argument	Type	Description
f	array or double	Frequencies to compute the transfer functions over
inputs	iterable[str or Element]	Mechanical or electrical node to inject signal at
outputs	iterable[tuple[str or Node or Frequency]]	Optical node and frequency tuple to measure output at. A symbolic reference to the model’s fsig.f parameter should always be used when defining a frequency to look at.

Optional arguments

Argument	Type	Description
name	str	Solution name

Aliases:

freqresp4, frequency_response4, FrequencyResponse4

More info

• Full reference: frequency_response4

Get error signals

get_error_signals(*locks, name='get error signals')

An action that quickly calculates the current error signals for all or a subset of locks in a model.

Full syntax

get_error_signals(*locks, name='get error signals')

Required arguments

Argument	Type	Description
name	str	Name of the action.

Optional arguments

Argument	Type	Description
*locks	list	A list of lock names to compute the error signals for. If not provided, all locks in model are used.

Aliases:

get_error_signals, GetErrorSignals

More info

• Full reference: get_error_signals

Noise projection

noise_projection(f, *output_nodes, scaling=none, name='loop')

Missing summary

Full syntax

noise_projection(f, *output_nodes, scaling=none, name='loop')

Aliases:

noise_projection, NoiseProjection

More info

• Full reference: noise_projection

Operator

operator(start_node, end_node)

This action can be used to extract operators out from a simulation for external use. The operators are defined by a path in the network between two nodes (via some other if more direction is required).

Full syntax

operator(start_node, end_node, via=none, frequency=0, name='operator')

Required arguments

Argument	Type	Description
start_node	str	Start node name
end_node	str	End node name

Optional arguments

Argument	Type	Description
via	str	Via node to use to specify a path with multiple options
frequency	float	Optical carrier or signal frequency to use for calculating the operators
name	str	Name of the solution generated by this action

Aliases:

operator, Operator

More info

• Full reference: operator

Optimise RF readout

opt_rf_readout_phase(*args, d_dof=1e-10, name='optimise_demod_phases_dc')

This optimises the demodulation phase of ReadoutRF elements relative to some DegreeOfFreedom or driven Parameter in the model. The phases are optimised by calculating the DC response of the readouts. This Action changes the state of the model by varying the readout demodulation phases. If no arguments are given it will try to automatically optimise any lock element in the model that is using an RF readout with respect to the lock feedback parameter.

Full syntax

opt_rf_readout_phase(*args, d_dof=1e-10, name='optimise_demod_phases_dc')

Required arguments

Argument	Type	Description
args		Pairs of DegreeOfFreedom or Parameter and ReadoutRF elements, or pairs of their names. If none are provided OptimiseRFReadoutPhaseDC will automatically search for Lock elements which have ReadoutRF error signal and optimise them.

Optional arguments

Argument	Type	Description
d_dof	float	A small offset applied to the DOFs to compute the gradients of the error signals

Aliases:

opt_rf_readout_phase, OptimiseRFReadoutPhaseDC

More info

• Full reference: opt_rf_readout_phase

Pseudo lock cavity

pseudo_lock_cavity(cavity, mode=none, lowest_loss=false, feedback=none, name='pseudo_lock_cavity' )

An action that locks a cavity defined by a Cavity element to a specific mode without using any radio-frequency sensing scheme. This will only work on simple cavities that are not coupled in any way. You can specify whether to try and lock to a particular HG mode with the mode=[n,m] keyword argument, or just pick the lowest loss mode, lowest_loss=True.

Full syntax

pseudo_lock_cavity(
   cavity,
   mode=none,
   lowest_loss=false,
   feedback=none,
   name='pseudo_lock_cavity'
)

Required arguments

Argument	Type	Description
cavity	Cavity	Cavity element describing some Fabry-Perot like optical cavity

Optional arguments

Argument	Type	Description
mode	(n or m)	HG mode to try and lock to, default is [0,0]
lowest_loss	bool	Select the eigenmode which has the lowest loss, most likely the fundamental mode of the cavity. Using lowest loss will override the mode selection.
feedback	Parameter optional	If None the required cavity tuning to lock to the calculated mode will be determined from the cavity objects source node element, and the relevant phi parameter will be used. Alternatively you can specify which tuning parameter is used instead. Which should be a phi of some mirror in the cavity or a DegreeOfFreedom which controls the cavity length.
name	str	Name of the solution generated by this action

Aliases:

pseudo_lock_cavity, PseudoLockCavity

More info

• Full reference: pseudo_lock_cavity

Pseudo lock DRFPMI

pseudo_lock_drfpmi(frequency=0, apply_tunings=true, name='operator_lock')

Pseudo-locking is attempting to find an operating point for a LIGO like model without needing to use RF sidebands and readouts. Although it is not physically accurate it does provide a useful tool for analysing detectors from a more theoretical basis. This generates a PseudoLockDRFPMISolution solution containing various operators and results.

Full syntax

pseudo_lock_drfpmi(frequency=0, apply_tunings=true, name='operator_lock')

Optional arguments

Argument	Type	Description
frequency	float	Frequency to use for calculating the operators
apply_tunings	bool	When True the action will modify the model tunings
name	str	Name of the solution generated by this action

Aliases:

pseudo_lock_drfpmi, PseudoLockDRFPMI

More info

• Full reference: pseudo_lock_drfpmi

Sensing matrix DC

sensing_matrix_dc(dofs, readouts, d_dof=1e-09, name='sensing_matrix_dc')

Computes the sensing matrix elements for various degrees of freedom and readouts that should be present in the model. The solution object for this action then contains all the information on the sensing matrix. This can be plotted in polar coordinates, displayed in a table, or directly accessed.

Full syntax

sensing_matrix_dc(dofs, readouts, d_dof=1e-09, name='sensing_matrix_dc')

Required arguments

Argument	Type	Description
dofs	iterable[str]	String names of degrees of freedom
readouts	iterable[str]	String names of readouts

Optional arguments

Argument	Type	Description
d_dof	float	Small step used to compute derivative

Aliases:

sensing_matrix_dc, SensingMatrixDC

More info

• Full reference: sensing_matrix_dc

Set lock gains

set_lock_gains(*locks, d_dof_gain=1e-10, gain_scale=1, name='set gains')

An action that computes the optimal lock gains using the sensing matrix found with SensingMatrixDC. This action computes the error signal gradient for each lock with respect to its drive and sets the gain as -gain_scale/sensing.

Full syntax

set_lock_gains(
   *locks,
   d_dof_gain=1e-10,
   gain_scale=1,
   name='set gains',
   optimize_phase=none,
   verbose=false
)

Required arguments

Argument	Type	Description
name	str	Name of the action.
verbose	bool	If True this will print the name of the enabled locks and their gains.

Optional arguments

Argument	Type	Description
*locks	list	A list of locks for which to set the gain. If none provided, all enabled locks in model are used. Disabled locks that are explicitly listed will have their gains set.
d_dof_gain	float	Step size to use when calculating the gain for each error signal/DOF pair.
gain_scale	float	Extra gain scaling factor applied to the gain calculation: -gain_scale/sensing In multiple lock models where the locks are cross coupled using a gain_scale < 1 can improve the stability of the locking algorithm to stop excessively large steps.
optimize_phase	bool or optional or	Deprecated feature: Use OptimiseRFReadoutPhaseDC instead

Aliases:

set_lock_gains, SetLockGains

More info

• Full reference: set_lock_gains

Sweep

sweep( *args )

An action that sweeps N number of parameters through the values in N arrays.

Full syntax

sweep(
   *args,
   pre_step=none,
   post_step=none,
   reset_parameter=true,
   name='sweep'
)

Required arguments

Argument	Type	Description
args	[Parameter or str] or array or boolean	Expects 3 arguments per axis. The first is a full name of a Parameter or a Parameter object. The second is an array of values to step this parameter over, and lastly a boolean value to say whether this is a relative step from the parameters initial value.
name	str	Name of the action, used to find the solution in the final output.

Optional arguments

Argument	Type	Description
pre_step	Action	An action to perform before the step is computed
post_step	Action	An action to perform after the step is computed
reset_parameter	boolean	When true this action will reset the all the parameters it changed to the values before it ran.

Aliases:

sweep, Sweep

More info

• Full reference: sweep

Link

link(*args, verbose=false)

Connect multiple components together in one quick command. In many models a collection of components just need to be connected together without having to specify each port exactly. This command accepts multiple components as arguments, each is connected to the next. Interally the link command is creating spaces and wires between components but giving them automatically generated names. Therefore, the link command is useful when you are not interested in what the spaces or wires are called, which is often the case in readout paths or signal feedback loops.

Full syntax

link(*args, verbose=false)

Required arguments

Argument	Type	Description
*args	[Components or float or Port]	Separate arguments of either components or ports. A float value will create a space or wire with the provided length or time delay.

Optional arguments

Argument	Type	Description
verbose	bool	Print out what the link command is doing

Aliases:

link

More info

• Full reference: link

Signal frequency

fsig(f)

This element represents the signal frequency (fsig) used in a model. It is a unique element, which means only one can be added to any given model. This is done automatically with the name fsig. It has a single parameter f for the frequency of the signal.

Full syntax

fsig(f)

Required arguments

Argument	Type	Description
f	[float or None]	Signal frequency to use in a model [Hz]. If set to None then no signal frequencies will be modelled in the simulation.

Aliases:

fsig

More info

• Full reference: fsig

Default wavelength

lambda(value)

Set the reference wavelength used in a model.

Full syntax

lambda(value)

Required arguments

Argument	Type	Description
value	float; default: None	Reference wavelength to use in a model [Hz]. If not specified, a reference wavelength of 1064 nm is used.

Aliases:

lambda

More info

• Full reference: lambda

Modes

modes(modes=none, maxtem=none, include=none, remove=none)

Select the HOM indices to include in the model.

Full syntax

modes(modes=none, maxtem=none, include=none, remove=none)

Optional arguments

Argument	Type	Description
modes	sequence or str or optional; default: None	Identifier for the mode indices to generate. This can be: - An iterable of mode indices, where each element in the iterable must unpack to two integer convertible values. - A string identifying the type of modes to include, must be one of “off”, “even”, “odd”, “x” or “y”.
maxtem	int or optional; default: None	Optional maximum mode order.
include	sequence or str	A single mode index pair, or an iterable of mode indices, to include. Each element must unpack to two integer convertible values.
remove	sequence or str	A single mode index pair, or an iterable of mode indices, to remove. Each element must unpack to two integer convertible values.

Aliases:

modes

More info

• Full reference: modes

Phase config

phase_config(zero_k00=false, zero_tem00_gouy=true)

Coupling coefficient and Gouy phase scaling:

Full syntax

phase_config(zero_k00=false, zero_tem00_gouy=true)

Optional arguments

Argument	Type	Description
zero_k00	bool	Scale phase for k0000 (TEM00 to TEM00) coupling coefficients to 0. Defaults to True.
zero_tem00_gouy	bool	Ensure that all Gouy phases for TEM00 are 0. Defaults to True.

Aliases:

phase_config

More info

• Full reference: phase_config

Transverse electromagnetic modes

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

Distributes power into the mode HGnm.

Full syntax

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

Required arguments

Argument	Type	Description
laser	laser	The Laser to set mode power for.
n, m	int	Mode indices.
factor	float	Relative power factor, modes with equal factor will have equivalent power distributed to them.

Optional arguments

Argument	Type	Description
phase	float or optional; default = 0.0	Phase offset for the field, in degrees.

Aliases:

tem

More info

• Full reference: tem

Debug

debug(name='Debug')

An action that will start an IPython debug shell.

Full syntax

debug(name='Debug')

Aliases:

debug, Debug

More info

• Full reference: debug

Parallel

parallel(*actions)

Missing summary

Full syntax

parallel(*actions)

Aliases:

parallel, Parallel

More info

• Full reference: parallel

Print

print(*args, name='printer', eval=true)

Missing summary

Full syntax

print(*args, name='printer', eval=true)

Aliases:

print, Printer

More info

• Full reference: print

Print model

print_model(name='print_model')

An action that prints the model object being currently used to run actions.

Full syntax

print_model(name='print_model')

Aliases:

print_model, PrintModel

More info

• Full reference: print_model

Print model attribute

print_model_attr(*args, eval=true, prefix='')

Prints an attribute of the model being currently used.

Full syntax

print_model_attr(*args, eval=true, prefix='')

Required arguments

Argument	Type	Description
*args	(str or )	Strings input for the attribute to print

Optional arguments

Argument	Type	Description
eval	bool	When True symbolic expressions will be evaluated before printing. Defaults to True.
prefix	str	Optional string to print before the attributes

Aliases:

print_model_attr, PrintModelAttr

More info

• Full reference: print_model_attr

Save matrix

save_matrix(name='savematrix')

An action that will save the current state of the matrix being used by the simulation.

Full syntax

save_matrix(name='savematrix')

Aliases:

save_matrix, SaveMatrix

More info

• Full reference: save_matrix

Update maps

update_maps(*args, name='update_maps', **kwargs)

Update any maps that might be changing in the simulation.

Full syntax

update_maps(*args, name='update_maps', **kwargs)

Aliases:

update_maps, UpdateMaps

More info

• Full reference: update_maps

Change

change(change_dict=none, relative=false, name='change', **kwargs)

Changes a model Parameter to some value during an analysis.

Full syntax

change(change_dict=none, relative=false, name='change', **kwargs)

Required arguments

Argument	Type	Description
**kwargs		Alternative method to specify parameter:value pairs to change

Optional arguments

Argument	Type	Description
change_dict	dict	Dictionary of parameter:value pairs to change.
relative	bool	Whether to increment from the parameters current value or not
name	str	Name of action

Aliases:

change, Change

More info

• Full reference: change