# Finesse Syntax Reference

## (the fastest way to recall a Finesse command)

The list below provides a quick online reference for the Finesse syntax. For a more detailed description of the syntax and the program, please download the manual! See also the Finesse cheatsheet which provides answers to frequency asked questions.

Note that, when you start Finesse with kat -h' (from the command line), Finesse will print a short syntax reference. Last updated: 30. April 2016.

Click on the one-line syntax to expand or collapse.

Laser

l name P f [phase] node

• l : laser (input light)
usage : l name P f [phase] node
 P = light power in Watts f = frequency offset to the default frequency (default frequency determined from lambda' in kat.ini') phase = phase

Squeezer

sq name f r angle node

• sq : squeezer vacuum input
usage : sq name f r angle node
 f = frequency offset to the default frequency (default frequency determined from lambda' in kat.ini') r = squeezing in decibels, ([r>0\) angle = squeezing angle in degrees

A squeezed vacuum input source that has variable squeezing in dB and squeezing angle. A squeezing of 20 dB should reduce the noise by a factor of 10.

Mirror

m name R T phi node1 node2

• m : mirror
usage : m name R T phi node1 node2
 R = power reflectivity (0

A positive tuning moves the mirror from node2 towards node1.

• m1 : mirror
usage : m1 name T Loss phi node1 node2
 T = power transmittance (0

Note: the values are not stored as T and L but as R and T with 0 R, T 1. Thus, only R and T can be tuned (e.g. with xaxis).

• m2 : mirror
usage : m2 name R Loss phi node1 node2
 R = power reflectivity (0

Note: the values are not stored as T and L but as R and T with 0 R, T 1. Thus, only R and T can be tuned (e.g. with xaxis).

Space

s name L [n] node1 node2

• s : space
usage : s name L [n] node1 node2
 L = length in metres n = index of refraction
(default is 1.0 or specified with in kat.ini')

Beamsplitter

bs name R T phi alpha node1 node2 node3 node4

• bs : beam splitter
usage : bs name R T phi alpha node1 node2 node3 node4
 R = power reflectivity (0

A positive tuning moves the beam splitter along from node3/node4 towards node1/node2 along a vector perpendicular to the beam splitter surface (i.e. the direction depends upon alpha').

• bs1 : beam splitter
usage : bs1 name T Loss phi alpha node1 node2 node3 node4
 T = power transmittance (0

Note: the values are not stored as T and L but as R and T with 0 R, T 1. Thus only R and T can be tuned (e.g. with xaxis).

• bs2 : beam splitter
usage : bs2 name R Loss phi alpha node1 node2 node3 node4
 R = power reflectivity (0

Note: the values are not stored as T and L but as R and T with 0 R, T 1. Thus only R and T can be tuned (e.g. with xaxis).

Isolator

isol name S node1 node2

• isol : isolator
usage : isol name S node1 node2 [node3]
 S = power suppression in dB

The light passes the isolator unchanged from node1 to node2 but the power of the light going from node2 to node1 will be suppressed: $a_{\rm out}~=~10^{-S/20}~a_{\rm in},$ with a as the field amplitude. When using the optional third node all the suppressed power going from node 2 to 1 is output into node3.

Modulator

mod name f midx order am/pm [phase] node1 node2

• mod : modulator
usage : mod name f midx order am/pm [phase] node1 node2
 f = modulation frequency in Hz midx = modulation index order = number of sidebands (or s' for single sideband) am/pm = amplitude or phase modulation phase = phase of modulation

Phase modulation :
order' sets the order up to which sidebands are produced by the modulator. For example, given an input light with f' equal to zero

mod mo1 10k 0.3 2 pm n1 n2

produces sidebands at -20kHz, -10kHz, 10kHz and 20kHz. The maximum possible order is 6. If order is set to s' then the modulator produces a single sideband.

Amplitude modulation:
order' is always set to 1, and midx must be between 0 and 1.

Lens

lens f node1 node2

• lens : thin lens
usage : lens name f node1 node2
 f = focal length in metres

A lens does not change the amplitude or phase of a passing beam. When Hermite-Gauss modes are used, the beam parameter q is changed with respect to f.

Photodiode

pd[n] name [f1 [phase1 [f2... ]]] node[*]

• pd : photodiode (plus one or more mixers)
usage : pd[n] name [f1 [phase1 [f2 [phase2 [...] ] ] ] ] node[*]
 n = number of demodulation frequencies ($$0\leq n\leq5$$) f1 = demodulation frequency of the first mixer in Hz phase1 = demodulation phase of the first mixer in degrees f2 = demodulation frequency of the second mixer in Hz phase2 = demodulation phase of the second mixer in degrees ...

The photodetector generally computes the laser power in an interferometer output. With the command scale ampere the value can be scaled to photocurrent.

Note: the number of frequencies (n) must be given correctly. The square brackets may be misleading here, since the parameter is not optional but can be omitted only if the number of frequencies is zero. Some likely examples are:

pd detector1 nout1 (or   pd0 detector1 nout1) : DC detector
pd1 detector2 10M 0 nout2 : one demodulation
pd2 detector3 10M 0 100 0 nout2 : two demodulations

All frequencies are with respect to the zero frequency $$f_0$$ set by lambda' in the init file kat.ini'.

The phases are the demodulation phases and describe the phase of the local oscillator at the mixer. If the last phase is omitted the output resembles a network analyser instead of a mixer. This differs from a mixer because the resulting signal does contain phase information. A mixer with a fixed demodulation phase is usually used for calculating error signals whereas one often wants to know the phase of the signal for frequency sweeps, i.e. for calculating transfer functions.

The keyword max' can be used in place of the fixed demodulation phase, e.g.:

pd2 detector1 10M max 200 max nout1

This does use the optimum demodulation phase for each data point independently. This can be useful when the best' demodulation phase is not yet known but in some circumstances it will give strange' output graphs. Note that this kind of calculation does not represent any meaningful way of handling real output signals. It was merely added for convenience.

Again, the optional asterisk behind the node name changes from the default beam to the second beam present at this node.

The positive and negative signal frequency variables, $fs and$mfs, can also be used in the command instead of specifying an exact frequency.

• pdS : shot noise limited sensitivity

Usage is the same as for pd. It calculates the shot noise in the output using the DC photocurrent (equivalent to the shot command output) and divides it by a signal. For example,

pdS2 name 10M 90 100 0 n2

would be :
shot noise(pd n2) / (pd2 name 10M 90 100 0 n2)
i.e. the shot noise at node n2 divided by the signal at 100 Hz (phase = 0 deg) in the photocurrent at n2 demodulated at 10 MHz (phase = 90 deg).

Note: This detector relies on a simple approximation for the shotnoise and only gives the correct result when no modulation sidebands are present.

For this sensitivity output, all demodulation phases have to be set.

If the output is a transfer function and fsig was used to add signals to mirrors or beam splitters it can be further normalised to $$\rm m/ \sqrt{\rm Hz}$$ by scale meter .

• pdN : photocurrent normalised by shot noise

Usage is the same as for pd or pdS. It calculates the inverse of pdS which gives the signal to shot noise ratio.

Note: This detector relies on a simple approximation for the shotnoise and only gives the correct result when no modulation sidebands are present, see sec:shotnoise.

Amplitude detector

ad name [n m] f node[*]

usage : ad name [n m] f node[*]
 n, m = TEM mode numbers. n refers to the x-direction. f = sideband frequency in Hz (as offset to the input light)

The optional asterisk behind the node name changes from the default beam to the second beam present at this node (see the Finesse manual for the definition of the default beam).

The amplitude detector calculates field amplitude and phase of all light fields at one frequency. For correct absolute values you have to set epsilon_c' correctly in kat.ini'. See the command yaxis' for the various possibilities for plotting the computed values.

If higher order modes are used and no indices n and m are given, the amplitude detector tries to compute the value for the phase front' on the optical axis.

qd name f phase node[*]

• qd : quantum quadrature detector
usage : qd name f phase node[*]
 f = sideband frequency in Hz (as offset to the input light) phase = quadrature to measure realtive to the amplitude quadrature (in degrees)

The optional asterisk behind the node name changes from the default beam to the second beam present at this node (see the Finesse manual for the definition of the default beam).

This outputs the amplitude of a quantum quadrature, e.g. amplitude or phase quadrature, for a specific carrier field. The frequency value given should be that of a carrier field or one of its modulated sidebands realtive to the set reference frequency of the simulation.

The phase value determines which quadrature to measure. To output the amplitude quadrature use a phase 0, the phase quadrature is given using a phase of 90.

The units of the output are normalised in units of hf/2, where h is Planck's constant and f is the simulation reference frequency. Thus an output of 1 means the quadrature is the same size of a pure vacuum state, less than 1 is squeezed and more than 1 means an increase in noise.

Note that this is not finalised for use with higher-order modes yet.

Squeezing detector

sd name f [n m] node[*]

• sd : squeezing detector
usage : sd name f [n m] node[*]
 f = sideband frequency in Hz (as offset to the input light) n, m = TEM mode numbers. n refers to the x-direction.

The optional asterisk behind the node name changes from the default beam to the second beam present at this node (see the Finesse manual for the definition of the default beam).

This outputs information regarding the squeezing of the quantum noise state of a given carrier field. The frequency value given should be that of a carrier field or one of its modulated sidebands realtive to the set reference frequency of the simulation. You can also specify which optical mode to view too but this is not finalised for use with higher-order modes yet.

The detector outputs a complex number whose magnitude is the squeezing level in dB rdb. The ‘squeezing factor’ r is related to rdB by: $rdb = 20~r~\log10(e)$ The phase of the complex output is φ the squeezing angle in degrees (use the yaxis command to output phase information). When $$\phi = 0,180$$ and $$r \neq 0$$ then the carrier is purely amplitude squeezed, when $$\phi = \pm90$$ and $$r \neq 0$$, the carrier is purely phase squeezed; any other angle is a mixture.

Shotnoise detector

shot name node[*]

• shot : shot noise
usage : shot name node[*]

It calculates the shot noise in the output using the DC light power as

$\Delta P =\sqrt{\frac{2\,h\,c~}{\lambda_0}P~}.$

Note: This detector relies on a simple approximation for the shotnoise and only gives the correct result when no modulation sidebands are present, see sec:shotnoise.

Photodiode quantum noise

qnoised name n [f1 [phase1 [f2 [phase2 [...] ] ] ] ] node[*]

• qnoised : photodiode quantum noise
usage : qnoised name n [f1 [phase1 [f2 [phase2 [...] ] ] ] ] node
 n = number of demodulation frequencies ($$0\leq n\leq5$$) f1 = demodulation frequency of the first mixer in Hz phase1 = demodulation phase of the first mixer in degrees f2 = demodulation frequency of the second mixer in Hz phase2 = demodulation phase of the second mixer in degrees ...

The optional asterisk behind the node name changes from the default beam to the second beam present at this node (see the Finesse manual for the definition of the default beam).

Will compute the photocurrent noise of a DC or demodulated photodiode output. Demodulations are set exactly the same as the pd commands. However the max phase keyword cannot be used and all demodulation phases must be specified.

For radiation pressure and squeezing effects to be visible you must set the final demodulation frequency to the signal frequency, either using put commands or the $fs or$mfs variables.

The scaling of the output is dependent on the quantum_scaling setting in the kat.ini file. By default it should output amplitude spectral density noise with ￼units of Watts/sqrt(Hz).

The alternative syntax qnoisedS will output the quantum noise-to-signal ratio. It requires a signal injection via fsig. The output is: $$\frac{\textrm{noise}}{\textrm{signal}}$$ where $$\textrm{noise}$$ is computed using a qnoised detector and $$\textrm{signal}$$ with a pd[n] detector. The same number of demodulations are applied to each detector. In this case it is possible to use the max keyword for the phase, as the phase needed to maximize the noise is compute first and applied to both noise and signal detectors. qnoiseN is the reciprocal signal-to-noise output.

Quantum Shotnoise detector

qshot name num_demod f [phase] node[*]

• qshot : photodiode shot noise (inlcudes RF noise)
usage : qshot name n [f1 [phase1 [f2 [phase2 [...] ] ] ] ] node
 n = number of demodulation frequencies ($$0\leq n\leq5$$) f1 = demodulation frequency of the first mixer in Hz phase1 = demodulation phase of the first mixer in degrees f2 = demodulation frequency of the second mixer in Hz phase2 = demodulation phase of the second mixer in degrees ...

The optional asterisk behind the node name changes from the default beam to the second beam present at this node (see the Finesse manual for the definition of the default beam).

This will compute the demodulated noise present in the photocurrent output of a photodiode. This detector assumes only that vacuum noise is present in the optical field. Thus it cannot see radiation pressure effects nor squeezing.

The scaling of the output is dependent on the quantum_scaling setting in the kat.ini file. By default it should output amplitude spectral density noise with ￼units of Watts/sqrt(Hz).

qshotS will output the quantum noise-to-signal ratio and qshotN the signal-to- noise ratio, see also qnoised.

Parametric gain detector

pgaind name component motion

• pgaind : Parametric gain detector
usage : pgaind name component motion
 component = suspended component - mirror or beamsplitter motion = motion degree of freedom

This detector can be used to compute the parametric gain of a particular motion of a suspended mirror or beamsplitter due to its coupling to the optical fields that may drive the motion. The value this detector outputs is: $\mathcal{R}_m = \mathcal{Re}\left\{\frac{\Delta A}{A}\right\}$ Where $$\frac{\Delta A}{A}$$ is the transfer function from a specified motion back into itself. Thus if $$\mathcal{R}_m \gt 1$$ the motion is unstable and will exponentially increase with time. With $$0 \lt \mathcal{R}_m \lt 1$$ the motion will build up but is not necessarily unstable, $$\mathcal{R}_m \lt 0$$ means the motion is being damped and will not resonate. The component specified must be suspended (for either longtudinal or rotational motions) or have a surface motion set. The possible motion values are then: z for longutindinal motion, rx or yaw for yaw motions, ry or pitch for pitch motions, and sN for surface motions, where $$N$$ is the $$(N-1)^\textrm{th}$$ surface motion that is set using the smotion command.

Beam parameter detector

bp name x/y parameter node[*]

• bp : beam parameter detector
usage : bp name x/y parameter node
 x/y = direction for which the parameter should be taken parameter = a parameter derived from the Gaussian beam parameter, see below.

This detector can plot a variety of parameters able to be derived from the Gaussian beam parameter which is set to the respective node:

 w : beam radius in metres w0 : waist radius in metres z : distance to waist in metres zr : Rayleigh range in metres g : Gouy phase in radians r : Radius of curvature (of phase front) in meters q : Gaussian beam parameter

Please note that the Gouy phase as given by bp is not the accumulated Gouy phase up to that node but just the Gouy phase derived from the beam parameter is: $\Psi(z)=\arctan\left(\frac{\myRe{q}}{\myIm{q}}\right).$ The accumulated Gouy phase can be plotted with the detector gouy.

Cavity parameter detector

cp cavity_name x/y parameter

• cp : cavity parameter detector
usage : cp cavity-name x/y parameter
 cavity-name = name of cavity of which the parameter should be taken x/y = direction for which the parameter should be taken parameter = a parameter derived by the cavity trace algorithm, see below.

Please note that this detector type has not a unique name. Instead the name of the respective cavity must be given.

This detector can plot a variety of parameters that are derived by a cavity trace. The cavity must have been specified by the cav command. Please note that these parameters are only filled with meaningful numbers when a cavity trace is executed. You can use the command retrace' to force a trace for each data point. The available parameters are the same that can be printed to the terminal using trace 2':

 w : beam radius at the first cavity node in metres w0 : waist radius at the first cavity node in metres z : distance to waist at the first cavity node in metres r : radius of curvature of beam phase front at the first cavity node in meters q : Gaussian beam parameter at the first cavity node finesse : cavity finesse loss : round trip loss (0<=loss<=1) length : optical path length of the cavity in meters (counting a full round-trip) FSR : free spectral range in Hz FWHM : cavity linewidth as Full Width at Half Maximum in Hz pole : cavity pole frequency in Hz (=0.5*FWHM) g : cavity stability parameter

The cavity stability ranges from -1 to 1 for stable cases. Please note that the direction parameter (x/y) only applies to the parameters related to beam size but must always be given so that the parsing of the cp' command will function.

Gouy phase detector

gouy name x/y space-list

• gouy : gouy phase detector
usage : gouy name x/y space-list
 x/y = direction for which the phase should be taken space-list = a list of names of space' components

This detector can plot the Gouy phase accumulated by a propagating beam. For example:
gouy g1 x s1 s2 s3 s4 sout
plots the Gouy phase that a beam accumulates on propagating through the components s1, s2, s3, s4 and sout.

CCD detector (beam shape)

beam name [f] node[*]

• beam : beam shape detector
usage : beam name [f] node[*]
 f = frequency of the field component in Hz

The optional asterisk behind the node name changes from the default beam to the second beam present at this node (see the Finesse manual for the definition of the default beam).

With the beam analyser one can plot the cross-section of a beam. If no frequency is given the beam detector acts much like a CCD camera, it computes the light intensity per unit area as a function of x and y. The x-axis has to be set to either x' or y'. For example xaxis beam1 x lin -10 10 100 sets the x-axis to tune the position in the x-direction from $$-10 w_0$$ to $$10 w_0$$ in 100 steps (for beam analyser beam1'). A second x-axis can be set to the perpendicular direction in order to plot the two dimensional cross-section of the beam. Thus the axes of the plot are scaled automatically by $$w_0$$, the waist size computed from the Gaussian beam parameter at the beam detector. The values for the waist size are printed to the terminal and given in the plot labels.

If a frequency is given the beam detector outputs the amplitude and phase of the light field at the given frequency (you can use the yaxis command to define whether the amplitude, phase or both should be plotted).

Signal input

fsig name component [type] f phase [amp]

• fsig : signal frequency
usage : fsig name component [type] f phase [amp]

or : fsig name f

or : fsig name component [type] f tf_name
 component = one of the previously defined component names type = type of modulation f = signal frequency phase = signal phase amp = signal amplitude tf_name = transfer function name

Used as the input signal for calculating transfer functions. For example

fsig sig1 m1 10k 0

shakes the previously defined component (e.g. a mirror) m1' at 10 kHz. Only one signal frequency can be used in one calculation but that can be fed to several components, e.g.

fsig sig1 m1 10k 0
fsig sig2 m2 10k 0

inserts the signal at two mirrors (in phase).

For the moment the following types of signal modulation are implemented (default type marked by *):

• mirror: phase*, amplitude, xbeta, ybeta
• beam splitter: phase*, amplitude, xbeta, ybeta
• space: phase*, amplitude
• input: phase, amplitude, frequency*
• modulator: phase*, amplitude

To tune only the signal frequencies one has to be explicitly tuned with xaxis or put, because only one signal frequency is allowed. E.g. in the example above, tuning sig1 will also tune sig2.

Alternatively fsig can be used to only specific a 'signal' or noise' frequency without injecting a signal. The syntax is:
fsig name f
This version is typically used when looking purely at quantum noise computations where no signals are required.

Another alternative syntax for fsig is given as:
fsig name component [type] f tf_name
This is an idential command to the normal fsig input except that the phase and amplitude values are computed from a provided transfer function instead. tf and tf2 commands for defining transfer functions.

Specify vacuum input

vacuum component1 component2 ...

• vacuum : set which quantum noise inputs to use
usage : vacuum component1 component2 ...
 component = Name of component to activate quantum noise input at

This command is used to specify which components should be sources of quantum noise. By default Finesse will find any open port, lossy optic, squeezer or laser input and set it on to include all possible noise sources. If you instead wish to select only specific noise sources you can just specify a list of component names.

Use the printnoises commmand to list all the noise sources Finesse will use in the simulation.

Input power mode coefficients

tem input n m factor phase

• tem : distribute input power to various TEM modes
usage : tem input n m factor phase
 input = name of an input component n, m = $$\rm TEM_{\rm nm}$$ mode numbers factor = relative power factor phase = relative phase in degrees

When an input (component l') is specified, the given laser power is assumed to be in the $$\rm TEM_{00}$$ mode. The command tem can change that. Each tem command can set a relative factor and phase for a given TEM mode at a specified input. Several commands for one input are allowed.

Please note that the tem command is intended to add higher order modes, i.e.:
tem input1 0 1 1.0 0.0
adds a 01 mode to the 00 mode. Both fields have the same amplitude.

In order to create a pure higher order mode the 00 amplitude has to be explicitly set to zero. For example:
tem input1 0 0 0.0 0.0
tem input1 0 1 1.0 0.0
would put all power into the $$\rm TEM_{01}$$ mode.

Another example:
tem input1 0 0 1.0 0.0
tem input2 2 1 1.0 90.0
specifies that exactly the same amount of power as in the $$\rm TEM_{00}$$ mode should be in $$\rm TEM_{21}$$, but with a phase offset of 90 degrees.

Note: tem' does not change the total power of the laser beam.

• mask : mask out certain TEM modes in front of a photodetector or a beam analyser
usage : mask detector n m factor
 detector = name of a photodetector or beam analyser n, m = $$\rm TEM_{\rm nm}$$ mode numbers factor = power factor [0,1]

Several mask commands can be used per detector.

Without this command all photodetectors (for which pdtype' is not used) detect the power of all TEM modes, for example : $S(f_1,f_2)=\sum_{\rm nm}2\Re\left(a_{\rm nm}(f_1)a_{\rm nm}(f_2)\right)=\sum_{\rm nm} S_{\rm nm},$ where $$a_{\rm nm}(f)$$ is the amplitude of the $$\rm TEM_{\rm nm}$$ mode at frequency f. Note that other detectors, like split detectors, quadrant cameras or bulls-eye detectors use a special geometry to detect certain cross-terms. Setting a mask for a $$\rm TEM_{\rm nm}$$ will scale the detected power by the given factor: $S_{\rm nm}(f_1,f_2)=\mbox{\rm factor}~2\Re\left(a_{\rm nm}(f_1)a_{\rm nm}(f_2)\right).$

Set detector type

pdtype detector type-name

• pdtype : defines the type of a photodetector
usage : pdtype detector-name type-name

This command defines the type of a photodetector with respect to the detection of transverse modes. The standard detector is a simple photodiode with a surface larger than the beam width. With pdtype' more complex detectors can be used, like for example, split photodetectors.

In the file kat.ini' a number of different types can be defined by giving scaling factors for the various beat signals between the different Hermite-Gauss modes. For example, if a photodetector will see the beat between the $$\rm TEM_{00}$$ and $$\rm TEM_{01}$$, then the line 0 0 0 1 1.0' (mode factor) should be present in the description. The definitions in the kat.ini' file are given a name. This name can be used with the command pdtype' in the input files. Many different types of real detectors (like split detectors) or (spatially) imperfect detection can be simulated using this feature. The syntax for the type definitions:

PDTYPE name
...
END

Between PDTYPE and END several lines of the following format can be given:

1. 0 1 0 2 1.0', beat between $$\rm TEM_{01}$$ and $$\rm TEM_{02}$$ is scaled with factor 1.0
2. 0 0 * 0 1.0', '*' means any': the beats of $$\rm TEM_{00}$$ with $$\rm TEM_{00}$$, $$\rm TEM_{10}$$, $$\rm TEM_{20}$$, $$\rm TEM_{30}$$,... are scaled with 1.0
3. x y x y 1.0', x' or y' also mean any' but here all instances of x' are always the same number (same for y'). So in this example all beats of a mode with itself are scaled by 1.0

Please note that all beat signals which are not explicitly given are scaled with 0.0. (debug 2' somewhere in the input file will cause to print all non-zero beat signal factors for all defined types.) Please take care when entering a definition, because the parser is very simple and cannot handle extra or missing spaces or extra characters.

The file kat.ini' in the package includes the definitions for split photodetectors.

Set attribute of component

attr component M value Rcx/y value x/ybeta value

• attr : additional (optional) attributes for mirrors, beam splitters and spaces
usage : attr component M value Rc[x/y] value x/ybeta value gx/y value
 component = the component for the attributes to be set to M = mass in kg Rc = radius of curvature, in metres (zero is used for plane surface) Rcx = radius of curvature in vertical plane Rcy = radius of curvature in horizontal plane xbeta = angle of mis-alignment in the interferometer plane in radian ybeta = angle of mis-alignment perpendicular to the interferometer plane in radian g = Gouy phase of a space component in degrees (see sec:gouy) gx = Gouy phase of a space component (horizontal component) gy = Gouy phase of a space component (vertical component) value = numerical value for the specified attribute

Note, in contrast to phases the alignment angles xbeta and ybeta are given in radians.

The various attributes are optional. For example one can simply set the radius of curvature of a mirror m1' to 10 metres with the command:

attr m1 Rc 10

The sign for the radius of curvature is defined as follows: if the surface seen from the first specified node (specified at the respective mirror or beam splitter) is concave, then the number for the radius of curvature is positive.

Please note that when the attributes Rc' or g' are used you cannot tune the parameter itself. Instead, the separate directions i.e. Rcx' and/or Rcy' and gx' and/or gy' must be used for further tuning, e.g. with the xaxis command.

Apply map data to mirror

map component [angle] [mapname] filename

• map : loads and applies a surface map to a mirror or beamsplitter component
usage : map component filename
 component = mirror or beamsplitter name to which the map should be applied filename = name of the file containing the map data

This command reads a file given by filename and searches for a surface map given by a grid. The data must be provided in a special structure, the manual for details. Multiple maps can be applied to the same mirror using separate map commands.

Set surface motion

smotion component map_file transfer_function

• smotion : loads and applies a surface motion map to a mirror component
usage : smotion component map_file transfer_function
 component = mirror to which the motion should be applied. map_file = name of the file containing the map data transfer_function = name of transfer function

This command reads a file given by map_file and searches for a surface motion map. This file describes the normalised motion of a surface for use in radiation pressure computations.

You can apply multiple surface motions to a mirror by repeating the command with the same component. The transfer function should describe how the optical force is converted into motion of this particular shape. Finesse will internally handle the computation of the overlap between each optical mode and the surface motion shape.

Save coupling coefficients

knm component filename_prefix

• knm : specifies a file which the coupling coefficients for a given component generate and saves/loads them from the file
usage : knm component filename_prefix
 component = mirror that a map has been applied with the map command filename_prefix = filename prefix of the file to save/load coupling coefficient data to and from

With knm the user can specify a file which the coupling coefficents for a component with a map applied can save and load the coefficients from. This is primarily used to save computational time as map coefficients can be expensive to compute. The only components this can be applied to at the moment are mirrors. filename_prefix states the filename prefix.

Computational properties

conf component setting value

• conf : used to configure computational properties of a component
usage : conf component setting value
 component = component to change setting on setting = Name of the setting to change value = Value to change setting to

This command is used to configure settings of a component that are not physical simulation parameters. that can be set for each component. Usage:

 Setting/Value: integration_method/integer sets the numerical integration method. Cuba refers to a self-adapting routine which is faster but less robust 1 - Riemann Sum 2 - Cubature - Serial 3 - Cubature - Parallel (default) Setting/Value: interpolation_method/integer set the interpolation method for the numerical integration of surface maps, the (use NN for maps with sharp edges) 1 - Nearest Neighbour (default) 2 - Linear 3 - Spline Setting/Value: interpolation_size/integer sets the size of the interpolation kernel, must be odd and > 0 Setting/Value: knm_flags/integer Sets the knm computation flags which define if coeffs are calculated numerically or analytically if possible. must be > 0 Setting/Value: show_knm_neval/ 0 or 1 Shows the number of integrand evaluations used for the map integration. Setting/Value: save_knm_matrices/ 0 or 1 If true the knm matrices are saved to .mat files for distortion, merged map and the final result Setting/Value: save_knm_binary/ 0 or 1 If true the knm and merged map data is stored in a binary format rather than ascii. See -convert option for kat in -h for converting between the 2 formats Setting/Value: save_interp_file/ 0 or 1 If true then for each knm calculated a file is written to outputting each interpolated point. The output file will have 4 columns: x,y,A,phi. So for each integrand evaluation the interpolated point is plotted

Set maximum mode order

maxtem order

• maxtem : set the maximum order for Hermite-Gauss modes
usage : maxtem order
 order = maximum order, i.e.  for modes.

This defines the maximum order for $$\rm TEM_{\rm nm}$$ and thus the number of light fields used in the calculation. The default order' is 0, the maximum value is 100. For large values the interferometer matrix becomes very large and thus the simulation extremely slow. Please note that the Hermite-Gauss mode is automatically switched on if at least one attribute or command referring to transverse modes is entered. You can explicitly switch off the Hermite-Gauss mode by using maxtem off'.

Set Gaussian beam parameter

gauss name component node w0 z [wy0 zy]

• gauss : setting the parameter for a Gaussian beam
usage : gauss name component node w0 z [wy0 zy]
(alternative: gauss* name component node q [qy] )
 w0 = beam waist size in metres z = distance to waist in metres q = complex beam parameter (given as $$z + i z_R$$', i.e. distance-to-waist Rayleigh-range')

A Gaussian beam at a certain point z' on the optical axis can be characterised by two parameters. The first common method is to specify the waist size $$w_0$$ and the distance to the waist z. In the complex parameter for Gaussian beams is used: $q=z+ i z_R,$ with $$z_R$$ the Rayleigh range and z the distance to the beam waist.

The distance to the waist can be positive or negative. A positive value means the beam has passed the waist, a negative number specifies a beam moving towards the waist. It is clear that the q parameter has to be set for a certain direction of propagation (the other direction then has the parameter $$q'=q^*$$ ). The direction of propagation is set with component'. The node at which the Gauss parameter is to be set has to be connected to the specified component. The direction of propagation is defined as: from the component towards the node.

In general a Gaussian beam may have two different beam parameters for the x- and the y-direction. When two parameter sets are given with gauss the first set is assumed to be valid for the x-direction and the second for the y-direction. If only one set is given then it is used for both directions.

Cavity eigenmode tracing

cav name component1 node component2 node

• cav : tracing a beam through a cavity and compute the q-eigenvalues
usage : cav name component1 node1 component2 node2

The components and nodes specify the start and end point of a beam path through a possible cavity. node1' has to be connected to component1' and node2' to component2'. There are only two possibilities for specifying a cavity in :

• a linear cavity: the start component and end component are two different mirrors.
• a ring cavity: the start component and end component are the same beam splitter and the nodes are either 1 and 2 or 3 and 4, so that the beams are connected to each other via a reflection.

When the cavity is stable (not critical or unstable) the eigenmatrix is computed. The resulting eigenvalues for the Gaussian beam (q parameters) are then set for all cavity nodes.

Use trace' in the input file to see what cavity nodes are found and which q-values are set, see below.

Set startnote for beam tracing

startnode node

• startnode : recomputes the Gaussian parameters at each node for every data point
usage : startnode node

This command allows one to explicitly set the node at which the automatic beam trace algorithm starts. The node must have a beam parameter associated with it. This means the node must be inside a cavity that has been traced with the cav command or the parameter must be explicitly set via the gauss command.

Switch automatic retrace

retrace [off|force]

• retrace [off|force] : recomputes the Gaussian parameters at each node for every data point
usage : retrace

needs to trace the beam through the interferometer in order to set the Gaussian beam parameters (see sec:trace for a detailed description). This is always done once at the start of a simulation if higher-order modes are used. If xaxis or put are used to tune a parameter like a length of a space or the focal length of a lens or the radius of curvature of a mirror the beam parameters are locally changed and the beam tracing should be repeated. Without re-computing a proper base of Gaussian beam parameters such a tuning introduces a virtual mode mismatch which can lead to wrong results.

automatically detects whether a re-tracing is required and if so computes a new set of base parameters for each data point. The retrace command can be used to over-ride the automatic behaviour: retrace will force a retracing and retrace off will prevent it, regardless of the xaxis settings.

Please note that the re-tracing cannot avoiding all unwanted mode-mismatches.

Using 'retrace force' will force the tracing alogorithm to continue tracing even if it comes across an unstable cavity.

Set Gouy phase mode

phase 0-7 (default: 3)

• phase : switches between different modes for computing the light phase
usage : phase number

Four different modes are available:

 0 = no change 1 = the phase for coupling coefficients of $$\rm TEM_{00}$$ is scaled to 0 2 = the Gouy phase for $$\rm TEM_{00}$$ is scaled to 0 3 = combines modes 1 and 2 (default)

The command phase' can be used to change the computation of light field phases in the mode. In general, with higher order modes the spaces are not resonant any more for the $$\rm TEM_{00}$$ mode because of the Gouy phase. Furthermore, the coupling coefficients $$\rm k_{mnmn}$$ contribute to the phase when there is a mode mismatch. For correct analysis these effects have to be taken into account. On the other hand, these extra phase offsets make it very difficult to set a resonance condition or operating point intuitively. In most cases another phase offset would be added to all modes so that the phase of the $$\rm TEM_{00}$$ becomes zero. With the command phase' these phase offsets can be set for the propagation through free space, for the coupling coefficients or both: phase 1' ensures that phases for the coupling coefficients $$\rm k_{0000}$$ ( $$\rm TEM_{00}$$ to $$\rm TEM_{00}$$) are 0, phase 2' ensures that all Gouy phases for $$\rm TEM_{00}$$ are 0 and phase 3' combines both effects. The phases for all higher modes are changed accordingly, so that the relative phases remain correct. Please note that only phase 0 and phase 2 guarantee always correct results, see the Finesse manual for more details.

Xaxis

xaxis[*] component param. lin/log min max steps

• xaxis : -axis definition, i.e. parameter to tune
usage : xaxis component parameter lin / log min max steps
(alternative: xaxis* component parameter lin / log min max steps)
 component = one of the previously defined component names parameter = a parameter of the component e.g. L' for a space lin/log = defines a linear or logarithmic -axis min = start value max = stop value steps = number of steps from min to max

maximum number : 1
The previous definition of the interferometer yields exactly one output value for every detector. To create a plot we have to define a parameter that is changed (tuned/swept) along the -axis of the plot. Exactly one xaxis must be defined. For example,

xaxis s1 L lin 1 10 100

changes the length of space s1 from 1 metre to 10 metres in 100 steps.

Another useful example is to sweep the laser frequency using:

xaxis i1 f lin 0 10k 500

When the optional asterisk is used then the previously defined value for the parameter to tune is used as an offset. For example:

s s1 L 5
xaxis* s1 L lin 1 10 100

tunes the length of space s1 from 6 to 15 metres.
When the axis is logarithmic the min/max values are multiplied to the previously defined value, e.g.

s s1 L 5
xaxis* s1 L log .1 10 100

tunes the length of space s1 from 0.5 to 50 metres. Note that the parameters used as -axis in the output plot are those given in the xaxis* statement, not the computed values which are really used in the calculation. This feature allows one to specify the tunings of the operating point in the interferometer description and then always tune around that operating point by:
min = -max

X2axis (for 3D plots)

x2axis[*] component param. lin/log min max steps

• x2axis : second x-axis definition, creates 3D plot
usage as for xaxis

This command defines a second x-axis. A 3D plot is created. (X-axes refer to parameters tuned turing the simulation, while y-axes refer to simulation outputs).

maximum number : 1

Ignore xaxis command

noxaxis

Constant

const name value

• const : constant definition
usage : const name value
 name = user-defined name, less than 15 characters long value = numerical or string value

The constants are used during pre-processing of the input file. If anywhere in the file the command const name value' is defined, every instance of $name' in the input file is replaced by value'. Variable variable name value • var : variable definition usage : var name value  name = user-defined name, less than 15 characters long value = numerical or string value The variable definition is very similar to the constant' definition via 'const'. However variables can be used with the func, put and xaxis commands during the simulation. The most common use is to define a variable to be tuned with the x-axis which is not directly a parameter of any optical component. Set (access to component parameter) set name component parameter • set : variable definition usage : set name component parameter  name = user defined name, less than 15 characters long component = one of the previously defined component names parameter = a parameter of the component e.g. L' for a space The variables are used for creating input variables that can be used with functions, see below. With set', all tunable parameters in the input file can be accessed with the usual syntax component parameter'. The set command will link the variable $name' to the parameter value of the named component. In addition, the output of any detector can be stored in a variable. The syntax is:

set name detector-name re/im/abs/deg

where re/im/abs/deg indicate which real number to use if the detector output is a complex number. (NOTE: for detectors with a real output, use re' and NOT abs' since abs' will remove the sign!)

The set commands are executed for each data point, i.e. if the component parameter is changed e.g. with the xaxis command the variable $name will change accordingly. In addition to user defined variables, several internal variables have been defined: $x1', $x2' and $x3' have been pre-defined and point to the current value of the xaxis (or x2axis, x3axis respectively). in addition, $mx1', $mx2' and $mx3' are defined as minus the corresponding $x' variable. These predefined names must not be used with set'.

Mathematical function input

func name = function-string

• func : function definition
usage : func name = function-string
 name = user-defined name, less than 15 characters long function-string = a mathematical expression

For example, func y = $Lp+2 defines the new variable y = Lp+2', with Lp' being a previously defined variable. Such previously defined variables are entered with a $' sign. The new variable (i.e. the function result) will be plotted as a new output, like a detector output. Any previously defined variable via set, func or lock (see below) can be used like the function string. The functions are executed for each data point. (Please note that if you use two similar function names like function' and function1' the parser might have problems to distinguish between the two.)

This feature uses the mathematical expression parser Formulc 2.22 by Harald Helfgott. The following functions are available in the function string: exp(), ln(), sin(), cos(), tan(), asin(), acos(), atan(), atan2(), abs(), sqrt(), pi() (with no parameters inside the parentheses) and rnd() (a random number between 0 and 1).

Numbers have to be given numerically, e.g. 3.0E-9' instead of 3n'. Please note that 3.0e-9' does not work. Multiplication with negative numbers requires parentheses, e.g.:

y = (-1)*$x1 Note also that each function will be called initially when other variables and functions are probably not yet initialised. This can lead to a division-by-zero error. For example, the following line will often fail: func myfunc =$var1 / $func2 To mitigate this you can use the following trick: func myfunc =$var1 / ( $func2 + 1E-21 ) For a detailed description of the parser syntax, please see the documentation of Formulc 2.22. Lock (feedback iteration) lock[*] name$var gain accuracy

• lock : control loop definition
usage : lock name $variable gain accuracy  name = user defined name variable = previously defined variable (usually a photodetector output) gain = loop gain accuracy = threshold to decide whether the loop is locked The command will read the variable given by $variable' and write it into the new variable name'. This variable will be also plotted as a new output, like a detector output. lock* stops after the first point so that only the initial lock is found and the rest is computed without locking. (Please note that if you chose two similar lock names like mylock' and mylock1' the parser might have problems to distinguish between the two.)

Finesse will perform an iterative computation for each data point on the x-axis. In fact, it will compute the interferometer iteratively until the condition $\left|(\{\rm variable})\right|<{\rm accuracy}\nonumber$ is fulfilled.

In order to achieve this goal the command tries to mimic a control loop with a simple integrator. The input $variable' serves as the error signal and the output stored in $name' holds the feedback signal (which has to be connected to the interferometer by the user with a put command). In each iterative step it performs the operation:

name = $name + gain *$variable ( or name += gain * $variable ) Several lock commands can be active simultaneously and the lock output variables can be used in func commands located below the lock in the input file. Please note: The order of the commands func' and 'lock' in the input file determines the order of their computation! Of course the lock fails miserably if: • the loop is not closed, • the error signal is not good, • the computation is not started at or close to a good operating point, • the gain is wrong (sign, amplitude) or, • the steps as given by the xaxis command are too large (i.e. moves the interferometer out of the linear range of the error signal). A fine tuning of the gain is useful to minimise the computation time. An example: to lock a cavity to a laser beam we can write: # laser and EOM l i1 1 0 n0 mod eo1 40k 0.3 3 pm n0 n1 # cavity: m m1 0.9 0.1 0 n1 n2 s s1 1200 n2 n3 m m2 .9 0.01 0 n3 n4 # Pound-Drever-Hall signal pd1 pdh 40k 0 n1 # tune xaxis m2 phi lin 0 100 400 # set the error signal to be photodiode output (re' stands # for the real part of the diode output. re' has to be used # with diodes that provide a real output. set err pdh re # Perform the lock! Gain is -10 and the accuracy 10n ( = 1e-8) lock z$err -10 10n
# ... and connect the feedback to the interferometer
put* m1 phi $z  The behaviour of the locking routine can be adjusted by setting some parameters in kat.ini'. For example, the lock iteration can automatically adjust the loop gains. The following parameters in the kat.ini' file can be used: • locksteps (integer, >0, default 10000): maximum number of steps in which the iteration tries to achieve the lock. • autogain (integer, 0,1,2 default 2): switch for the automatic gain control: 0 = Off, 1 = On, 2 = On with verbose output. • autostop (integer, 0,1 default 1): if autostop is switched ON the locking algorithm will stop after it fails to reach the desired accuracy once. • sequential (integer, 0,1,5, default 5): this keyword determines if the feedback signals are computed sequentially or in parallel. The sequential mode is slower but performs much better far away from the operating point or when autogain' is needed. The default 5 uses the sequential mode for the first two data points and then switches to the faster parallel locking. • lockthresholdhigh (double, >0, default=1.5): whether or not a loop is probably oscillating with a too high gain is determined using lockthresholdhigh'. The criterion used is as follows (with y1,y2,... as successive error signal values): the oscillation condition is defined as: if abs((y1+y3-2*y2)/accuracy/y3) > lockthresholdhigh, true=loop oscillates. • lockthresholdlow (double, >0, default=0.01): whether or not a loop gain is too low is determined using lockthresholdlow'. The low-gain condition is defined as: if abs((y1+y3-2*y2)/accuracy/y3) < lockthresholdlow, true=loop gain too low. • locktest1 (integer, >0, default 5) and locktest2 (integer, >0, default 40): locktest1' and locktest2' determine the number of steps that an iteration is allowed to remain in an oscillation' (or low gain'). After locktest1' number of steps the loop state is checked. If for locktest2' number of checks the same error condition persists the loop gain will be reduced or increased by the factor gainfactor'. • gainfactor (double, >0, default 3). Put (update component parameter) put component parameter$var/$x1/$x2

• put[*] : write variable into interferometer parameter
usage : put component parameter $variable  component = one of the previously defined component names parameter = a parameter of the component e.g. L' for a space variable = previously declared variable For example, put space2 L$y writes the content of variable into the length of space2'. (put* always adds to the initially set lengths of space2')

All put commands are executed once before first data point is computed. If photodetector outputs are used in put or func they are set to 0.0 for the first data point calculation.

Transfer function Q,f

tf name factor phase [p or z f1 Q1 [p or z f2 Q2 ...]]

• tf : pole-zero transfer function (Q,f)
usage : tf name factor phase [{p or z} f1 Q1 [{p or z} f2 Q2 ...]]
 factor = overall scaling factor phase = overall phase p,z = add a pole or zero f1,f2,f3,... = frequency of pole or zero in Hz Q1, Q2, Q3, ... = quality factor of pole or zero (Q>0)

This command defines a generic transfer function with respect to frequency. Multiple poles and zeros can be defined at user-defined frequencies and quality factors for the resonances. For example:
tf sus 1 0 p 1 100000 z 10 130 p 20 10M

Transfer function, complex p,z

tf2 name factor phase [p1,p2,...] [z1,z2,...]

• tf2 : pole-zero transfer function (complex p,z)
usage : tf2 name factor phase [{p1,p2,...}] [{z1,z2,...}]
 factor = overall scaling factor phase = overall phase p1,p2,p3,... = complex pole z1, z2, z3, ... = complex zero

This command defines a generic transfer function. Rather than defining the transfer function with set frequencies and quality factors this accepts raw complex values. Each complex value should have a corresponding conjugate value defined. For example:
tf2 pendulum 1 0 {1+100i,1-100i} {-3+10i,-3-10i}

Noplot (suppress trace in plot)

noplot output

• noplot : suppress the plot of an output
usage : noplot output
 output = previously defined output (detector, function, etc.)

Since func and lock create new outputs, the resulting plots might become very cluttered. Therefore the command noplot output has been introduced. It suppresses the plotting of the given output (photodetector, function, lock, ...). The data is stored in the *.out file as before, only the plot command in the respective the *.gnu batch file is changed.

Please note that noplot cannot be used to suppress all plotting. One output must remain to be plotted. If you want to suppress all graphical output please use gnuterm no.

Trace (set verbosity of beam trace)

trace verbosity

• trace : set verbosity for beam tracing
usage : trace n
 n = an integer which sets the verbosity level.

When the trace is set, will print some information while tracing a beam through the interferometer, through a cavity, or during other computation tasks that are connected to the Hermite-Gauss extension. The integer n' is bit coded, i.e. n=2 gives different information to n=4, while n=6 will give both.

 n output 1 list of TEM modes used 2 cavity eigenvalues and cavity parameters like free spectral range, optical length and finesse 4 mode mismatch parameters for the initial setup (mismatch parameter as in [#!bayer!#]) 8 beam parameters for every node, nodes are listed in the order found by the tracing algorithm 16 Gouy phases for all spaces 32 coupling coefficients for all components 64 mode matching parameters during calculation, if they change due to a parameter change, for example by changing a radius of curvature 128 nodes found during the cavity tracing

Yaxis

yaxis [lin/log] abs:deg/db:deg/re:im/abs/db/deg

• yaxis : y-axis definition (optional)
usage : yaxis [lin / log] abs:deg / db:deg / re:im / abs / db / de
 abs:deg = amplitude and phase db:deg = amplitude in dB and phase re:im = real and imaginary part re = real part im = imaginary part abs = amplitude db = amplitude in dB deg = phase

maximum number : 1
This defines the (first plus an optional second) y-axis (y-axes show the simultion output signals while x-axes refer to tuned parameters).

Scale (rescale output)

scale factor [output]

• scale : rescaling of output amplitudes (optional)
usage : scale factor [detector]
 factor = scale factor detector = output name

All or a specified output signal is scaled by factor. (The scaling is done after demodulations.)

If the keyword meter is used instead of a number for factor the output is scaled by $$2\pi/\lambda_0$$ (or $$\lambda_0/2\pi$$ for pdS). In case the output is a transfer function and the signals have been added to mirrors or beam splitters the transfer functions are thus normalised to $${\rm W/m}/\sqrt{\rm Hz}$$ ($${\rm m}/\sqrt{\rm Hz}$$ for pdS).

If the keyword ampere is used instead of a number for factor the output is scaled by $$e~q_{\rm eff}~\lambda_0/(hc)$$. This converts light power (Watt) to photocurrent (Ampere).

If the keyword deg is used the output will be scaled by $$180/\pi$$.

Numerical differentiation

diff component parameter

• diff : differentiation
usage : diff component parameter
 component = one of the previously defined component names parameter = a parameter of the component e.g. L' for a space

maximum number : 3

Instead of the standard result of the calculation, partial differentiation with respect to the specified parameter will be plotted. For a higher order differentiation you can specify the command again with the same parameter. The differentiation is calculated as:

diff = (f(x+h/2) - f(x-h/2))/h

The step size h can be specified via the constant deriv_h in kat.ini', the default is 1e-3. You can also overwrite the value from the kat.ini' file with the command deriv_h in an input file. This is useful when several files which require a different step size are located in the same directory.

Please note that if put is used, the parameter specified in put is linked to the parameter from the xaxis command, so a differentiation with respect to the parameter specified in put is not possible and a differentiation with respect to the parameter stated in xaxis will automatically perform a differentiation with respect to the connection of parameters (which was introduced by put).

Step for num. differentiation

deriv_h value

• deriv_h : overwrites the value for deriv_h given in kat.ini'
usage : deriv_h value
 value = step size for numerical differentiation

This command can be used to overwrite the pre-defined vale for deriv_h. This can be useful especially when you want to differentiate alignment signals in which numerical values of $$10^{-9}$$ are often required.

Print frequency list

printfrequency

• printfrequency : print a list of all frequencies
usage : printfrequency

This will print a table listing all the frequencies used in the simulation: carriers, modulation sidebands and signal/quantum sidebands.

Print quantum noise list

printnoises

• printnoises : print list of quantum noises
usage : printnoises

This will print a list of all the quantum noise sources being considered in the simulation and at which components and nodes it is present.

Wavelength

lambda wavelength

• lambda : overwrite default wavelength
usage : lambda wavelength
 wavelength = new reference wavelength in meters

With this command you set a new reference wavelength value used, overwriting the one set on kat.ini (typically 1064nm).

Gnuterm terminal

gnuterm terminal [filename]

• gnuterm : Gnuplot terminal (optional)
usage : gnuterm terminal [filename]
 terminal = one terminal name specified in kat.ini', default is x11' or windows' respectively filename = name for Gnuplot output file

maximum number : 20

If you do not want a Gnuplot batch file to be written use : gnuterm no'.

Pause

pause

• pause : pauses after plotting
usage : pause

maximum number : 1

Adds a command pause -1' to the Gnuplot batch file after each plot into a screen terminal.

Multiple 3D plots

multi

• multi : switches from a single surface to multiple surfaces in 3D plots
usage : multi

maximum number : 1

By default in a 3D plot only the first output is plotted even if multiple outputs are present. If multi' is set, Gnuplot plots multiple surfaces into the same graph.

Please note that even without setting multi' the data of all outputs is present in the output data file.

Extra Gnuplot commands

GNUPLOT \ ... \ END

• gnuterm : Gnuplot terminal (optional)
usage : gnuterm terminal [filename]
 terminal = one terminal name specified in kat.ini', default is x11' or windows' respectively filename = name for Gnuplot output file

maximum number : 20

If you do not want a Gnuplot batch file to be written use : `gnuterm no'.