## » Tools for detecting gravitational waves

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

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<R<1)
  T | = | power transmittance (0<T<1)
  phi | = | tuning in degrees

  A positive tuning moves the mirror from node2 towards node1.

- m1 : mirror
  usage : `m1 name T Loss phi node1 node2`

  T | = | power transmittance (0<T<1)
  Loss | = | power loss (0<Loss<1)
  phi | = | tuning in degrees

  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<R<1)
  Loss | = | power loss (0<Loss<1)
  phi | = | tuning in degrees

  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<R<1)
  T | = | power transmittance (0<T<1)
  phi | = | tuning in degrees
  alpha | = | angle of incidence in degrees

  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<T<1)
  Loss | = | power loss (0<Loss<1)
  phi | = | tuning in degrees
  alpha | = | angle of incidence in degrees

  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<R<1)
  Loss | = | power loss (0<Loss<1)
  phi | = | tuning in degrees
  alpha | = | angle of incidence in degrees

  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 o u t = 10−S/20 a i n,a o u t = 10−S/20 a i n,
  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≤n≤5 0≤n≤5 )
  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 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 m/H z‾‾‾√m/H z
  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[*]

- ad : amplitude detector
  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.

Quantum quadrature detector

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:

  r d b=20 r log 10(e)r d b=20 r log⁡10(e)
  The phase of the complex output is φ the squeezing angle in degrees (use the yaxis command to output phase information). When ϕ=0,180 ϕ=0,180
  and r≠0 r≠0
  then the carrier is purely amplitude squeezed, when ϕ=±90 ϕ=±90
  and r≠0 r≠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

  Δ P=2 h c λ 0 P ‾‾‾‾‾‾‾‾√.Δ P=2 h c λ 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≤n≤5 0≤n≤5 )
  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: noise signal noise signal
  where noise noise
  is computed using a `qnoised` detector and signal 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≤n≤5 0≤n≤5 )
  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:

  m=e{Δ A A}R m=R e{Δ A A}
  Where Δ A A Δ A A
  is the transfer function from a specified motion back into itself. Thus if m>1 R m>1
  the motion is unstable and will exponentially increase with time. With 0<m<1 0<R m<1
  the motion will build up but is not necessarily unstable, m<0 R m<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 N
  is the (N−1)th(N−1)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:

  Ψ(z)=arctan(\myRe q\myIm q).Ψ(z)=arctan⁡(\myRe q\myIm q).
  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−10 w 0
  to 10 w 0 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 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 | = | T E M n m T E M n m 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 T E M 00 T E M 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 T E M 01 T E M 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 T E M 00 T E M 00
  mode should be in T E M 21 T E M 21
  , but with a phase offset of 90 degrees.
  Note: `tem' does not change the total power of the laser beam.

Mode mask for detectors

mask detector n m factor

- 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 | = | T E M n m T E M n m 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)=∑n m 2 ℜ(a n m(f 1)a n m(f 2))=∑n m S n m,S(f 1,f 2)=∑n m 2 ℜ(a n m(f 1)a n m(f 2))=∑n m S n m,
  where a n m(f)a n m(f)
  is the amplitude of the T E M n m T E M n m
  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 T E M n m T E M n m
  will scale the detected power by the given factor:
  S n m(f 1,f 2)=\rm factor 2 ℜ(a n m(f 1)a n m(f 2)).S n m(f 1,f 2)=\rm factor 2 ℜ(a n m(f 1)a n m(f 2)).

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 T E M 00 T E M 00
  and T E M 01 T E M 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 T E M 01 T E M 01
     and T E M 02 T E M 02
     is scaled with factor 1.0
  2. `0 0 * 0 1.0', '*' means `any': the beats of T E M 00 T E M 00
     with T E M 00 T E M 00
     , T E M 10 T E M 10
     , T E M 20 T E M 20
     , T E M 30 T E M 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 T E M n m T E M n m
  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 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 w 0
  and the distance to the waist z. In the complex parameter for Gaussian beams is used:

  q=z+i z R,q=z+i z R,
  with z R 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∗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 T E M 00 T E M 00 is scaled to 0
  2 | = | the Gouy phase for T E M 00 T E M 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 T E M 00 T E M 00
  mode because of the Gouy phase. Furthermore, the coupling coefficients k m n m n k m n m n
  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 T E M 00 T E M 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 k 0000 k 0000
  ( T E M 00 T E M 00
  to T E M 00 T E M 00
  ) are 0, `phase 2' ensures that all Gouy phases for T E M 00 T E M 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

  ∣∣($v a r i a b l e)∣∣<a c c u r a c y|($v a r i a b l e)|<a c c u r a c y
  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 π/λ 0 2 π/λ 0
  (or λ 0/2 π λ 0/2 π
  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 W/m/H z‾‾‾√W/m/H z
  (m/H z‾‾‾√m/H z
  for pdS).

  If the keyword ampere is used instead of a number for `factor` the output is scaled by e q e f f λ 0/(h c)e q e f f λ 0/(h c)
  . This converts light power (Watt) to photocurrent (Ampere).

  If the keyword deg is used the output will be scaled by 180/π 180/π
  .

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