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

Laser producing a beam with a certain power, frequency and phase.

[ref.]

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

Mirror

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

Thin dielectric surface with associated properties such as reflectivity, tuning, and radius of curvature.

[ref.]

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

Beamsplitter

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

Thin dielectric surface under non-normal incidence with associated properties such as reflectivity, tuning, and radius of curvature.

[ref.]

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

Modulator

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

Modulator optical component with associated properties such as modulation frequency, index and order.

[ref.]

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

Space

s name portA portB L=0.0 nr=1.0

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

[ref.]

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

Cavity

cav name source

Cavity in an interferometer configuration.

[ref.]

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

Gaussian beam

gauss name node

Gaussian beam parameters at a specific node of the model.

[ref.]

Full syntax

gauss name node priority=0 **kwargs

Aliases:

gauss

Lens

lens name f=inf

Thin lens optical component with an associated focal length.

[ref.]

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

Nothing

nothing name

Empty point in the interferometer configuration.

[ref.]

Full syntax

nothing name

Required arguments

Argument	Type	Description
name	str	Name of newly created nothing.

Aliases:

nothing, Nothing

Signal generator

sgen name node amplitude=1 phase=0

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

[ref.]

Full syntax

sgen name node amplitude=1 phase=0

Required arguments

Argument	Type	Description
name	str	Name of newly created signal generator.
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

Squeezer

sq name db f=0 angle=0

Squeezer producing a squeezed-light beam with a given squeezing level and angle.

[ref.]

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

Isolator

isol name S=0.0

Isolator optical component with a specified suppression factor.

[ref.]

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

Suspension ZPK

sus_zpk name connected_to zpk_plant

Suspension with multiple zeros and poles for z, pitch and yaw.

[ref.]

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

Astigmatic lens

alens name fx=inf fy=inf

Thin astigmatic lens optical component with an associated focal lengths.

[ref.]

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

Amplifier

amplifier name gain=1

Amplifier with a specified gain.

[ref.]

Full syntax

amplifier name gain=1

Aliases:

amplifier, Amplifier

Degree of freedom

dof name *node_amplitude_pairs DC=0

Model parameter that drives multiple parameters of individual elements.

[ref.]

Full syntax

dof name *node_amplitude_pairs DC=0 lock_parameters=true

Required arguments

Argument	Type	Description
name	str	Name of the degree of freedom.
*node_amplitude_pairs: tuple[str, float | Symbol]		String referring to a parameter or a local degree of freedom, coupled with the amplitude with which this DOF will drive the parameter. The parameter value will be set to the product of this (symbolic) amplitude and the DOF.DC parameter. In case multiple DOFS drive the same parameter, their contributions will be summed.

Optional arguments

Argument	Type	Description
DC	float	DC value for the degree of freedom, by default 0
lock_parameters	bool	Whether to ‘lock’ the parameters driven by this degree of freedom. This prevents accidental overriding of parameter values that are meant to be controlled by a dof, by default True.

Aliases:

dof, degree_of_freedom, DegreeOfFreedom

Directional beamsplitter

dbs name

Directional beamsplitter optical component.

[ref.]

Full syntax

dbs name

Required arguments

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

Aliases:

dbs, directional_beamsplitter, DirectionalBeamsplitter

Frequency loss

floss name f loss=0 phase=0

Unphysical element which introduces a loss and/or phase for a particular frequency.

[ref.]

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

Free mass

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

Simple free-mass suspension of an object.

[ref.]

Full syntax

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

Aliases:

free_mass, FreeMass

Lock

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

Compute and apply the feedback to a given parameter using an error signal.

[ref.]

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

Noise

noise name node ASD

Classical noise amplitude spectral density.

[ref.]

Full syntax

noise name node ASD

Aliases:

noise, ClassicalNoise

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.

[ref.]

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

Wire

w name nodeA nodeB delay=0 gain=1

Flow of information between two specific signal nodes.

[ref.]

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

Telescope

tel name

This component represents a perfectly matching and adapting telescope.

[ref.]

Full syntax

tel name

Required arguments

Argument	Type	Description
name	str	Name of newly created telescope

Aliases:

tel, telescope, Telescope

Test point

test name *ports

Test point with an arbitrary number of test nodes that can be connected to and from.

[ref.]

Full syntax

test name *ports

Aliases:

test, test_point, TestPoint

Variable

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

Variable element in the model.

[ref.]

Full syntax

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

Aliases:

var, variable

Detectors

Name

Syntax overview

Amplitude detector

ad name node f

Detector for the amplitude and phase of light fields at one frequency.

[ref.]

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	Tangential mode index to probe. Defaults to None such that all fields of the given frequency are summed.
m	int	Sagittal mode index to probe. Defaults to None such that all fields of the given frequency are summed.

Aliases:

ad, amplitude_detector, AmplitudeDetector

Readout DC

readout_dc name optical_node

A Readout component which represents a photodiode measuring the intensity of some incident field.

[ref.]

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

Readout RF

readout_rf name optical_node f=0 phase=0

A readout component which represents a demodulated photodiode.

[ref.]

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	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	A name of a pdtype definition or a dict representing a pdtype definition, by default None. See Segmented photodiodes

Aliases:

readout_rf, ReadoutRF

Power detector DC

pd name node pdtype=none

Power detector that calculates the DC laser power in Watts without RF demodulations.

[ref.]

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

CCD, camera

ccd name node xlim ylim npts

Camera for measuring the intensity of a beam.

[ref.]

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	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

ccd, CCD

CCD, line

ccdline name node npts x y xlim ylim

Camera for measuring the intensity of a beam along a 1D slice.

[ref.]

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	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	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	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	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	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

ccdline, CCDScanLine

Field camera

fcam name node xlim ylim npts

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

[ref.]

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	Field frequency offset from the carrier to detect.
w0_scaled	bool	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

fcam, FieldCamera

Field detector

fd name node f

Detector for the higher-order-mode amplitudes at a particular node and frequency.

[ref.]

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

Math detector

mathd name expression

Detector that performs some math operation and outputs the result.

[ref.]

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

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.

[ref.]

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

Power detector demod 1

pd1 name node f

Power detector that calculates the RF beat power in Watts with one RF demodulation.

[ref.]

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

Power detector demod 2

pd2 name node f1 phase1 f2 phase2

Power detector that calculates the RF beat power in Watts with two RF demodulations.

[ref.]

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

Astigmatism detector

astigd name node

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

[ref.]

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

Beam property detector

bp name node prop

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

[ref.]

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	Plane to detect in - ‘x’ for tangential, ‘y’ for sagittal.
q_as_bp	bool	If detecting q, should the detector output return BeamParam object instead of just a complex number.

Aliases:

bp, beam_property_detector, BeamPropertyDetector

Cavity property detector

cp name cavity prop

Probe for detecting the properties of a cavity.

[ref.]

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	Plane to detect in.
q_as_bp	bool	If detecting q, should the detector output return BeamParam object instead of just a complex number.

Aliases:

cp, cavity_property_detector, CavityPropertyDetector

CCD, pixel

ccdpx name node x=0 y=0

Camera for measuring the intensity of a beam at a single point.

[ref.]

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	The x co-ordinate of the pixel.
y	scalar	The y co-ordinate of the pixel.
w0_scaled	bool	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

ccdpx, CCDPixel

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.

[ref.]

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	The x co-ordinate of the pixel.
y	scalar	The y co-ordinate of the pixel.
f	scalar	Field frequency offset from the carrier to detect.
w0_scaled	bool	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

fpx, FieldPixel

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.

[ref.]

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	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	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	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	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	Field frequency offset from the carrier to detect.
w0_scaled	bool	Flag indicating whether the \(x\), \(y\) axes should be scaled to the waist-size of the beam parameter at node.

Aliases:

fline, FieldScanLine

Knm detector

knmd name comp coupling n1 m1 n2 m2

Probe of coupling coefficients at a component.

[ref.]

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

Mode mismatch detector

mmd name node1 node2 direction=x

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

[ref.]

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	Plane of computation, defaults to “x” for the tangential plane. Changing to “y” will compute the mode mismatch in the sagittal plane.
percent	bool	Whether to calculate the mode mismatch as a fraction (default behaviour) or a percentage.

Aliases:

mmd, ModeMismatchDetector

Motion detector

xd name node

Motion detector which calculates the amplitude and phase of surface motion.

[ref.]

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

Optimal q detector

optbp name node f

Detector that computes an optimal beam parameter (q) for a specified optical frequency at a node.

[ref.]

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

Quantum

Name

Syntax overview

Quantum noise detector

qnoised name node

Quantum-noise detector that calculates the amplitude spectral density of photocurrent noise.

[ref.]

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

Quantum noise detector demod 1

qnoised1 name node f phase

Quantum-noise detector with one RF demodulation.

[ref.]

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

Quantum noise detector demod 2

qnoised2 name node f1 phase1 f2 phase2

Quantum-noise detector with two RF demodulations.

[ref.]

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

Quantum shot noise detector

qshot name node

Quantum shot noise detector with no RF demodulations.

[ref.]

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

Quantum shot noise detector demod 1

qshot1 name node f phase

Quantum shot noise detector with one RF demodulation.

[ref.]

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

Quantum shot noise detector demod 2

qshot2 name node f1 phase1 f2 phase2

Quantum shot noise detector with two RF demodulations.

[ref.]

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

Filters

Name

Syntax overview

Butter filter

butter name order btype frequency gain=1 analog=true

Butterworth filter used for shaping signals.

[ref.]

Full syntax

butter name order btype frequency gain=1 analog=true

Aliases:

butter, filter_butter, ButterFilter

Cheby1 filter

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

Chebyshev filter used for shaping signals.

[ref.]

Full syntax

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

Aliases:

cheby1, filter_cheby1, Cheby1Filter

ZPK filter

zpk name z p gain=1

Zero-pole-gain filter used for shaping signals.

[ref.]

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

Optical bandpass filter

obp name fc=0 bandwidth=1000

Idealised optical bandpass filter that transmits an optical frequency around some central frequency with a 3dB bandwidth.

[ref.]

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

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

Calculate the values of all detectors without sweeping any parameter; default if no other action is provided.

[ref.]

Full syntax

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

Optional arguments

Argument	Type	Description
pre_step	Action	An action to perform before the Noxaxis is run, by default None
post_step	Action	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

Plot

plot(name=abcd)

Visualize the outcome of the simulation; to be used on a solution object.

[ref.]

Full syntax

plot(name=abcd)

Aliases:

plot, Plot

Sweep axis

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

Sweep some parameter, compute all detector outputs and return a solution object with its result.

[ref.]

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	An action to perform before each step is computed, by default None
post_step	Action	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

Frequency response

freqresp(f, inputs, outputs)

Compute the frequency response of a signal injected at various nodes to obtain transfer functions to multiple output nodes.

[ref.]

Full syntax

freqresp(f, inputs, outputs, 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 nodes to inject signal at
outputs	iterable[str or Element]	Mechanical or electrical nodes to measure output at

Optional arguments

Argument	Type	Description
name	str	Solution name

Aliases:

freqresp, frequency_response, FrequencyResponse

ABCD matrix

abcd(name=abcd, **kwargs)

Compute an ABCD matrix over a path.

[ref.]

Full syntax

abcd(name=abcd, **kwargs)

Aliases:

abcd, ABCD

Beam trace

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

Trace a beam through the full model.

[ref.]

Full syntax

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

Aliases:

beam_trace, BeamTrace

Eigenmodes

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

Compute the roundtrip operator and calculate the eigen-values and -vectors of the cavity for a given Cavity defined in a model.

[ref.]

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

Maximize

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

Maximize some detector output by applying some feedback to multiple targets in a model.

[ref.]

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

Minimize

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

Minimize some detector output by applying some feedback to multiple targets in a model.

[ref.]

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

Propagate beam

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

Propagate the beam in a single plane through a given path.

[ref.]

Full syntax

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

Aliases:

propagate_beam, PropagateBeam

Propagate astigmatic beam

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

Propagate the beam in both planes through a given path.

[ref.]

Full syntax

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

Aliases:

propagate_beam_astig, PropagateAstigmaticBeam

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

Iteratively move the system to lock.

[ref.]

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

Series

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

Define a series of actions to perform during the simulation.

[ref.]

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

Sweep 2 axes

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

Sweep two parameters, compute all detector outputs and return a solution object for each parameter value.

[ref.]

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	An action to perform before each step is computed, by default None
post_step	Action	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

Sweep 3 axes

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

Sweep three parameters, compute all detector outputs and return a solution object for each parameter value.

[ref.]

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	An action to perform before each step is computed, by default None
post_step	Action	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

for

for(param, values, *actions)

Run a set of actions for each value in the array.

[ref.]

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

Antisqueezing

antisqueezing(f, squeezer, readout)

Compute the amount of antisqueezing at the output of a squeezing element.

[ref.]

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

DC fields

dc_fields(name='dcfields')

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

[ref.]

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

Frequency response 2

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

Compute the frequency response of a signal injected at an optical port at a particular optical frequency.

[ref.]

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

Frequency response 3

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

Compute the frequency response of a signal injected at an optical port at a particular optical frequency.

[ref.]

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

Frequency response 4

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

Compute the frequency response of a signal injected at an electrical or mechanical port.

[ref.]

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

Get error signals

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

Calculate the current error signals for all or a subset of locks in a model.

[ref.]

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

Noise projection

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

Missing summary.

[ref.]

Full syntax

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

Aliases:

noise_projection, NoiseProjection

Operator

operator(start_node, end_node)

Extract operators defined by a path between two nodes in the network for external use.

[ref.]

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

Optimise RF readout

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

Optimize the demodulation phase of ReadoutRF elements relative to some DegreeOfFreedom or driven Parameter in the model.

[ref.]

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

Pseudo lock cavity

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

Lock a cavity defined by a Cavity element to a specific mode without using any radio-frequency sensing scheme.

[ref.]

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

Pseudo lock DRFPMI

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

Find an operating point for a LIGO-like model without using RF sidebands and readouts.

[ref.]

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

Sensing matrix DC

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

Compute the sensing matrix elements for various degrees of freedom and readouts present in the model.

[ref.]

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

Set lock gains

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

Compute the optimal lock gains using the sensing matrix found with SensingMatrixDC.

[ref.]

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	Deprecated feature: Use OptimiseRFReadoutPhaseDC instead

Aliases:

set_lock_gains, SetLockGains

Sweep

sweep( *args )

Sweep N parameters through values in N arrays.

[ref.]

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

Link

link(*args, verbose=false)

Connect multiple components together in one quick command.

[ref.]

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

Signal frequency

fsig(f)

Represent the signal frequency used in a model.

[ref.]

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

Default wavelength

lambda(value)

Define the wavelength of the model, default is 1064 nm.

[ref.]

Full syntax

lambda(value)

Required arguments

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

Aliases:

lambda

Modes

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

Select the HOM indices to include in the model.

[ref.]

Full syntax

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

Optional arguments

Argument	Type	Description
modes	sequence or str	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	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

Phase config

phase_config(zero_k00=false, zero_tem00_gouy=true)

Specify coupling coefficients and Gouy-phase scaling to change computation of higher-order modes.

[ref.]

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

Transverse electromagnetic modes

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

Distribute power into the mode HGnm.

[ref.]

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	Phase offset for the field, in degrees.

Aliases:

tem

Debug

debug(name='Debug')

Start an IPython debug shell.

[ref.]

Full syntax

debug(name='Debug')

Aliases:

debug, Debug

Parallel

parallel(*actions)

Create copies of the model and restart the simulation for each action in the parallel arguments.

[ref.]

Full syntax

parallel(*actions)

Aliases:

parallel, Parallel

Print

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

Print properties of the model, for example as part of a series action.

[ref.]

Full syntax

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

Aliases:

print, Printer

Print model

print_model(name='print_model')

Print the model object that is used to run actions.

[ref.]

Full syntax

print_model(name='print_model')

Aliases:

print_model, PrintModel

Print model attribute

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

Print an attribute of the model.

[ref.]

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

Save matrix

save_matrix(name='savematrix')

Save the current state of the matrix being used in the simulation.

[ref.]

Full syntax

save_matrix(name='savematrix')

Aliases:

save_matrix, SaveMatrix

Update maps

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

Update any maps that might be changing in the simulation.

[ref.]

Full syntax

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

Aliases:

update_maps, UpdateMaps

Change

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

Change the value of a model parameter during the analysis.

[ref.]

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