Commit 29ac5272 authored by Andreas Freise's avatar Andreas Freise

remvoving old install, updating README

parent 448094e8
------------------------------------------------------------------------
FINESSE 2.3
o_.-=.
(\'".\| Frequency domain INterferomEter Simulation SoftwarE
.>' (_--.
_=/d ,^\ 16.12.2019 http://www.gwoptics.org/finesse/
~~ \)-' '
/ | INSTALL
' '
------------------------------------------------------------------------
1. Introduction
2. Installation
3. Running your first simulation
4. Short syntax reference
5. Further development
6. Copyright and disclaimer
________________________________________________________________________
1. Introduction
This is a short guide for installing and running FINESSE. Please see
`Finesse-2.0.pdf' (or later) for the manual and `CHANGES' for the
latest additions (also at http://www.gwoptics.org/finesse/changes).
If you have any problems, suggestions or advice, please don't hesitate
to get in touch.
FINESSE is an interferometer simulation program written in C. It
calculates light amplitudes in a user specified interferometer
configuration. It can generate output signals for various photo
detector types. All calculations are done in the frequency domain
(i.e. a steady state is assumed). This is done (in the following
order) by:
- reading a text input file which describes the interferometer
and the computation task
- generating the set of linear equations which describes the
coupling of the light amplitudes
- solving numerically the linear equation system for each data point
and calculating the output signals
- writing the data into an output file
- writing a Gnuplot file and a Matlab file, which can be
used for plotting data. FINESSE can further automatically start
Gnuplot or Python to plot the data to the specified terminal
(X11, postscript, pdf, png, ...)
To simulate a certain interferometer configuration, the user has
to write an input text file which describes the interferometer
in form of components and connecting nodes. Furthermore, an x-axis
has to be specified, i.e. which parameters are to be tuned. When
starting the program this input file is read and the specified data
is calculated. The program writes several text files:
- the file with extension `.out' contains the calculated data
- a file with extension `.gnu' is a batch file for Gnuplot, or
a file with '.py' for plotting with Python
- similarly a file with extension `.m' is a Matlab script file
- in addition all screen output is stored in a logfile
(extension `.log').
By default Gnuplot is then started to plot the data.
FINESSE uses Gnuplot to generate plots of the calculated data. Gnuplot
is a free program available for different operating systems. If you
don't have Gnuplot installed yet, you should do so. To download it
look at http://www.gnuplot.info. Alternatively you can use the command
`gnuterm no' to prevent FINESSE from starting Gnuplot and use the
Matlab or Python scripts to plot the data instead.
________________________________________________________________________
2. Installation
Installation using Conda:
We generally recommend to install FINESSE and PYKAT (a Python wrapper
for Finesse) together via the Conda package manager as described in
http://www.gwoptics.org/finesse/install
PYKAT allows the easy use of FINESSE from a Jupyter notebook. Our
Conda packages provide a simple installtion procedure to install
all required packages in one go.
Manual installation:
If you prefer to install FINESSE by hand, you can do this without
the need for any package manager or Python. There are binaries
available for several operating systems at:
http://www.gwoptics.org/finesse/.
After downloading the appropriate package for your operating system
you can install FINESSE simply by unpacking the zip (or tar.gz) file.
This will create a directory `Finesse' with all the necessary files.
( Alternatively you can build FINESSE directly from the source code.
To find more about this, please visit:
http://www.gwoptics.org/finesse/#source )
In addition you can download a small collection of simple example files.
These examples should run on any system but probably you won't get any
graphical output without changing some default settings (see below).
You should use FINESSE from a console window. First you need to
change into the working directory which contains all required
files (the FINESSE binary 'kat', the init file 'kat.ini' and
an interferometer input file).
If you call the program by typing `kat' on the console without any
option or filename a short message on the usage will be displayed.
Using the option `-h' a short help screen with a short syntax
reference is printed (i.e. `./kat -h' or `kat.exe -h').
If you want to automatically plot the results you need to have Gnuplot
or Python installed. Furthermore you must tell FINESSE where to find
the Gnuplot or Python executable. This is done by editing the file
`kat.ini'.
Unix/OS X:
You can easily find the Gnuplot executable with the command
`which gnuplot'. This should show the full path, e.g.
`/usr/bin/gnuplot'. Next open `kat.ini' with a text editor and
change the line beginning with `GNUCOMMAND' to:
GNUCOMMAND "/usr/local/bin/gnuplot -persist"
For any queries or problems please post us a quick message in our
forums: http://www.gwoptics.org/finesse/forums
Windows:
Firstly you must move the FINESSE folder to a location on
your computer where you want to store it. Be careful if putting it
in a system wide directory such as 'Program Files' as you will
require adminstrator rights to write to such a location. Once move
to the desired location you should double click the
`install.bat` file. Running this will bring up a command window
to update your PATH variables. After this has been run you must
NOT move this Finesse folder, as the system PATH variable has been
set for this directory only. If you do move the folder then please
re-run install.bat.
Running install.bat will also attempt to find a gnuplot installation
on your computer and set up Finesse to work with it. If it does not
find one you will either have to install it first, and re-run
install.bat, or manually setup the kat.ini file to use you Gnutplot
installation. Please install Gnuplot from:
http://sourceforge.net/projects/gnuplot/files/latest/download
If you have a space in the path to gnuplot.exe you need to note use
of ' and " to encapsulate path and GNUCOMMAND:
GNUCOMMAND '"C:\Program Files\gnuplot\bin\Wgnuplot.exe" --persist $s'
else use:
GNUCOMMAND 'C:\gnuplot\bin\Wgnuplot.exe --persist $s'
From FINESSE version 2.1 and above the Windows version should show
gnuplot plots and allow them plots to be kept open and still use the
terminal. FINESSE will now internally use a combination of both
wgnuplot.exe and gnuplot.exe which it expects to be in the same path
as stated in the GNUCOMMAND, this is irrespective of which binary is
actually stated in the GNUCOMMAND variable.
________________________________________________________________________
3. Running your first simulation
Now you should be able to start FINESSE with an example file, two
dummy example files are included in the zip file: 'test.kat' and
'test_plot.kat'. More examples can be found on the FINESSE web page:
http://www.gwoptics.org/finesse/#download
http://www.gwoptics.org/finesse/#simpleexamples
To run the first test file, open a terminal window, change into
the FINESSE directory and type:
$ ./kat test.kat
This should produce the following text output (if this does not work,
you probably have not downloaded the correct version of FINESSE):
------------------------------------------------------------------------
FINESSE v2.0 (build v2.0-7-gf7b41e5)
o_.-=. Frequency domain INterferomEter Simulation SoftwarE
(\'".\| 17.05.2014 http://www.gwoptics.org/finesse/
.>' (_--.
_=/d ,^\ Input file test.kat,
~~ \)-' ' Output file test.out,
/ | Gnuplot file test.gnu
' ' Sun May 18 11:06:48 2014
------------------------------------------------------------------------
'noxaxis' has been set, ignoring all other xaxis commands
--- cavity tracing
cavity cavity1:
cavity is stable! Eigenvalues:
q=489.898i, w0=12.880974mm z=0m g=-0.714286
finesse : 29.79, round-trip power loss: 0.19
opt. length: 2.4km, FSR: 124.91352kHz
FWHM: 4.1931423kHz (pole: 2.0965712kHz)
writing matlab/python/gnuplot batch files...
The second test file test_plot.kat will attempt to create graphical output.
This only works if you have Gnuplot installed and have set the path
to the Gnuplot binary correctly in the kat.ini file as described above.
To run the second example, type:
$ ./kat test_plot.kat
This should produce the following text output. In addition a Gnuplot
window with a simple plot of the cavity power as a function of cavity
tuning should appear.
------------------------------------------------------------------------
FINESSE v2.0 (build v2.0-7-gf7b41e5)
o_.-=. Frequency domain INterferomEter Simulation SoftwarE
(\'".\| 17.05.2014 http://www.gwoptics.org/finesse/
.>' (_--.
_=/d ,^\ Input file test_plot.kat,
~~ \)-' ' Output file test_plot.out,
/ | Gnuplot file test_plot.gnu
' ' Sun May 18 11:25:40 2014
------------------------------------------------------------------------
writing matlab/python/gnuplot batch files...
calling gnuplot...
If the graphical output fails, you can do a few tests to find out why.
- edit the test_plot.kat file, add the word 'debug' on a new line
and run the file again
- this should produce much more text output and near the end prints
the actual system call used to start Gnuplot, for example:
calling gnuplot...
(using '/usr/local/bin/gnuplot -persist test_plot.gnu')
- copy the system call (text between quotes) and try to run this from the
command window directly. If that fails you can use the command
'which gnuplot' or 'which Gnuplot' in the command window to determine
the correct path. On Windows you can use 'where gnuplot' instead.
- with that path you should be able to start Gnuplot manually from the
command line. Once that works, use the same path for your settings
in the kat.ini file
- if the above does not help, contact us, or post a message at:
http://www.gwoptics.org/finesse/forums/
________________________________________________________________________
4. Short syntax reference for FINESSE 2.0 :
------------------------------------------------------------------------
FINESSE v2.0 - Help Screen - 18.05.2014
------------------------------------------------------------------------
** Usage (1) kat [options] infile [outfile [gnufile]]
or (2) kat [options] basename
in (2) e.g. basename 'test' means input filename : 'test.kat',
output filename : 'test.out' and Gnuplot file name : 'test.gnu'.
** Support :
User support forums: http://www.gwoptics.org/finesse/forums/
Online syntax reference: http://www.gwoptics.org/finesse/reference/
** Available options:
-v : prints version number and build date
-h : prints this help (-hh prints second help screen)
-c : check consistency of interferometer matrix
-max : prints max/min
-klu-full : switch to KLU solver for parallel frequencies (default)
-klu : switch to KLU (Legacy solver)
--server : starts Finesse in server mode
--noheader : suppresses header information in output data files
--perl1 : suppresses printing of banner
--quiet : suppresses almost all screen outputs
--convert : convert knm files between text and binary formats
** Available interferometer components:
l name P f [phase] node - laser
m name R T phi node1 node2 - mirror
(or: m1 name T Loss phi ...
m2 name R Loss phi ... )
s name L [n] node1 node2 - space
bs name R T phi alpha node1 node2 node3 node4 - beamsplitter
(or: bs1 name T Loss phi ...
bs2 name R Loss phi ... )
gr[n] name d node1 node2 [node3 [node4]] - grating
isol name S node1 node2 [node3] - isolator
mod name f midx order am/pm [phase] node1 node2 - modulator
lens f node1 node2 - thin lens
sq name f r angle node - squeezed input
** Detectors:
pd[n] name [f1 [phase1 [f2... ]]] node[*] - photodetector [mixer]
pdS[n] name [f1 phase1 [f2... ]] node[*] - sensitivity
pdN[n] name [f1 phase1 [f2... ]] node[*] - norm. photodetector
ad name [n m] f node[*] - amplitude detector
bp name x/y parameter node[*] - plots beam parameters
cp cavity_name x/y parameter - plots cavity parameters
gouy name x/y space-list - plots gouy phase
beam name [f] node[*] - plots beam shape
qd name f phase node[*] - quantum quadrature detector
sd name f [n m] node[*] - squeezing detector
shot name node[*] - shot noise
qshot[S/N] name n f1 [phase1 [f2...]] node[*] - quantum shotnoise detector
qnoised[S/N] name n f1 [phase1 [f2...]] node[*] - quantum noise detector
pgaind name component motion - open loop param. gain det.
** Available commands:
fsig name component [type] f phase [amp] - apply signal
fsig name component [type] f transfer_func - signal wth transfer function
fsig name f - set signal/noise frequency
fadd f1 f2 f3 ... fN - add frequencies to list
tem[*] input n m factor phase - input power in HG/LG modes
mask detector n m factor - mode mask for outputs
pdtype detector type-name - set detector type
attr component M value Rcx/y value x/ybeta value - attributes of m/bs
(alignment angles beta in [rad])
map component filename - read mirror map file
knm component_name filename_prefix [flag] - save coefficients to file
smotion component map_file transfer_function - set surface motion
maxtem order - TEM order: n+m<=order
gauss name component node w0 z [wy0 zy] - set q parameter
gauss* name component node q [qy] (q as 'z z_R') - set q parameter
gauss** name component node w(z) Rc [wy(z) Rcy] - set q parameter
cav name component1 node component2 node - trace beam in cavity
startnode node - startnode of trace
lambda wavelength - overwrite wavelength
retrace [off|force] - re-trace beam on/off
phase 0-7 (default: 3) - change Gouy phases
(1: phi(00)=0, 2: gouy(00)=0, 4: switch ad phase)
conf component_name setting value - configures component
vacuum components_names - specific quantum noise
tf name factor phase [{p/z f Q [p/z f2 Q2 ...]] - f,Q transfer function
tf2 name factor phase [p1,p2,...] [z1,z2,...] - complex transfer function
** Plot and Output related commands :
xaxis[*] component param. lin/log min max steps - parameter to tune
x2axis[*] component param. lin/log min max steps - second axis for 3D plot
noxaxis - ignore xaxis commands
const name value - constant $name
var name value - tunabel variable $name
set name component parameter - variable $name
func name = function-string - function $name
lock[*] name $var gain accuracy - lock: make $var to 0
put[*] component parameter $var/$x1/$x2/$fs/$mfs - updates parameter
noplot output - no plot for 'output'
trace verbosity - verbose tracing
yaxis [lin/log] abs:deg/db:deg/re:im/abs/db/deg - y-axis definition
scale factor [output] - y-axis rescaling
diff component parameter - differentiation
deriv_h value - step size for diff
** Auxiliary plot commands :
gnuterm terminal [filename] - Gnuplot terminal
pyterm terminal - Python terminal
pause - pauses after plotting
multi - plots all surfaces
save/load knm file
GNUPLOT \ ... \ END - set of extra commands
for plotting.
________________________________________________________________________
5. Further development
With FINESSE 2.0 we have completed the implementation of radiation
pressure effects and have further achieved a full implementation
of quantum noise in the two-photon formalism.
We are currently developing FINESSE 3.0, a complete rewrite of the
software in Python, combining the best practises from FINESSE and
PYKAT in one modern package. This will allow us to implement new
features faster and it will make it easier to collaborate with more
developpers in the community.
________________________________________________________________________
6. Copyright and disclaimer
FINESSE and the accompanying documentation and the example files
have been written by:
Andreas Freise
School of Physics and Astronomy
University of Birmingham
B15 2TT Birmingham
UK
andreas.freise@googlemail.com
FINESSE has been substantially developed further during the last
years with Daniel Brown providing the key contributions, such as
the implementation of mirror maps, radiation pressure effects and
quantum noise. Daniel's work on the code and the manual was essential
for the publication of FINESSE as open source. Charlotte Bond has
carefully tested the new code and provided tutorials, examples and
documentation.
The software and documentation is provided as is without any warranty
of any kind. Copyright (c) by Andreas Freise 1999 - 2020.
The source code for FINESSE is available as open source under the GNU
General Public License version 3 as published by the Free Software
Foundation.
This manual and all FINESSE documentation and examples available from
www.gwoptics. org/finesse and related pages are distributed under a
Creative Commons Attribution-Noncommercial-Share Alike License, see
http://creativecommons.org/licenses/by-nc-sa/2.0/uk/.
Finesse: Frequency domain INterfErometer Simulation SoftwarE
FINESSE: Frequency domain INterfErometer Simulation SoftwarE
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.821363.svg)](https://doi.org/10.5281/zenodo.821363)
......@@ -10,10 +10,10 @@ http://www.gwoptics.org/finesse/
README
------------------------------------------------------------
Finesse [1] is a numeric simulation for laser interferometers
FINESSE [1] is a numeric simulation for laser interferometers
using the frequency domain and Hermite-Gauss modes. It is open
source software distributed for OSX, Linux, and Windows. You
can download the binaries at:
can find installation instructions at:
http://www.gwoptics.org/finesse/
......@@ -22,27 +22,28 @@ The source code is available at:
https://git.ligo.org/finesse/finesse/
This document gives a short overview of the main features of
Finesse. Please see the file INSTALL for information on
installing and running Finesse.
FINESSE. Please see the file Install.md for information on installing
and running FINESSE.
HOW TO CITE FINESSE
How to cite FINESSE
------------------------------------------------------------
For results using Finesse please cite the following DOI:
For results using FINESSE please cite the following DOI:
```
@misc{finesse,
author = {Brown, Daniel David and
Freise, Andreas},
title = {Finesse},
month = may,
year = 2014,
note = {{You can download the binaries and source code at
note = {{The software and source code is available at
\url{http://www.gwoptics.org/finesse}.}},
doi = {10.5281/zenodo.821363},
url = {http://www.gwoptics.org/finesse}
}
```
Table of Contents:
------------------------------------------------------------
......@@ -50,17 +51,16 @@ Table of Contents:
1. Interferometer signals
2. Beam geometry and imaging
3. Documentation, support and examples
4. Examples of the impact of Finesse on commissioning tasks
5. Finesse with Python and MATLAB
4. Examples of the impact of FINESSE on commissioning tasks
5. FINESSE with Python (and Matlab)
6. References
------------------------------------------------------------
7. Copyright and disclaimer
1. Interferometer signals
------------------------------------------------------------
1. Interferometer signals
Finesse can be used to compute a great variety of interferometer
FINESSE can be used to compute a great variety of interferometer
signals for control systems, including longitudinal control,
alignment control and thermal compensation, for example:
......@@ -74,37 +74,37 @@ alignment control and thermal compensation, for example:
- quantum noise and radiation pressure effects such as optical
springs
2. Beam geometry and imaging
------------------------------------------------------------
2. Beam geometry and imaging
One of the main features of Finesse is the extensive integration
One of the main features of FINESSE is the extensive integration
of physics related to the beam shape. This makes it possible to
study interferometer signals in the presence of defects such as
misalignments and mode mismatch, mirror surface defects, thermal
deformations and mis-centred, split photo detectors.
Finesse can also model imaging properties of optical systems,
FINESSE can also model imaging properties of optical systems,
for example, it automatically determines eigenmodes of cavities
and interferometers. Gouy phases and beam waist positions can be
plotted as functions of positions of optical elements.
3. Documentation, support and examples
------------------------------------------------------------
3. Documentation, support and examples
The program is easy to use for students: For the basic use, including
graphical output, no commercial software is required. The implemented
physics is well documented in a 200 pages manual. Simple examples are
provided as well as detailed input files for all main interferometric
gravitational-wave detectors. The manual and examples can be found on
the main Finesse page at http://www.gwoptics.org/finesse/
the main FINESSE page at http://www.gwoptics.org/finesse/
In addition we provide resources and self-study material on laser
interferometry in the form of Jupyter notebooks using Finesse
interferometry in the form of Jupyter notebooks using FINESSE
simulations: http://www.gwoptics.org/learn/
For questions and discussions related to Finesse we are hosting
a mailing in Birmingham and LIGO chat channel. Instructions on how
For questions and discussions related to FINESSE we are hosting
a mailing list and LIGO chat channel. Instructions on how
to join these are provided at:
https://git.ligo.org/finesse/finesse/wikis/home
......@@ -115,12 +115,12 @@ The code is under version control and is executed within a nightly
test-suite to maintain stability during the ongoing development.
4. Examples of Finesse usage for commissioning tasks
------------------------------------------------------------
4. Examples of FINESSE usage for commissioning tasks
The following examples highlight Finesse analyses of pressing problems
in detector commissioning. Finesse predictions have been used to
improve the detector performance and the Finesse results have been
The following examples highlight FINESSE analyses of pressing problems
in detector commissioning. FINESSE predictions have been used to
improve the detector performance and the FINESSE results have been
shown to match experimental results:
- lock acquisition of the power-recycled GEO 600 interferometer:
......@@ -129,21 +129,21 @@ shown to match experimental results:
- thermal compensation of GEO 600: a wrong radius of curvature was
discovered to cause unexpected beam patterns in the dark fringe.
Finesse results for the beam pattern as a function of heater power
FINESSE results for the beam pattern as a function of heater power
were used to find the current operating point of the thermal
compensation. [3]
- detector characterisation of the Virgo arm cavities: Finesse has
- detector characterisation of the Virgo arm cavities: FINESSE has
been used to characterise all details of the Virgo north arm
cavity from the cavity Finesse to the astigmatism of the mode
cavity from the cavity FINESSE to the astigmatism of the mode
matching telescope. [4]
- thermal lensing induced bi-stable operating point in Virgo: Finesse
- thermal lensing induced bi-stable operating point in Virgo: FINESSE
results were crucial in understanding the origins of a double zero
crossing in a longitudinal error signal of Virgo. [5]
- RF modulation induced change in interferometer noise couplings:
Detailed measurements and Finesse simulations were used to
Detailed measurements and FINESSE simulations were used to
understand the laser power noise coupling due to RF sidebands in
higher order modes and how it limits the detector sensitivity. [6]
......@@ -154,19 +154,21 @@ shown to match experimental results:
central beam-splitter [8]
5. Finesse with Python and MATLAB
------------------------------------------------------------
5. FINESSE with Python (and Matlab)
Finesse is a stand-alone executable written in C. It is, however,
well interfaced with Python and MATLAB. A number of MATLAB tools
(m files and mex files) are provided to run Finesse simulations
from MATLAB or to communicate with a running Finesse process from
within MATLAB. In addition a new suite of Python tools called
PyKat (http://www.gwoptics.org/pykat/) is available to interact
with Finesse from Python.
FINESSE is a stand-alone executable written in C. It is, however,
well interfaced with Python using PYKAT (http://www.gwoptics.org/pykat/).
We recommend using FINESSE with PYKAT from Jupyter notebooks, see
Install.md for details.
Previously we used FINESSE together with Matlab. Our old Matlab tools
(`Simtools` a collection of m files and mex files) are provided to
run FINESSE simulations from Matlab or to communicate with a running
FINESSE process from within Matlab.
6. References
------------------------------------------------------------
6. References
[1] A. Freise, G. Heinzel, H. Lueck, R. Schilling, B. Willke and
K. Danzmann, "Frequency-domain interferometer simulation with
......@@ -213,4 +215,39 @@ with Finesse from Python.
future gravitational wave detectors
Ph.D. thesis, University of Birmingham, 2016
https://doi.org/10.5281/zenodo.821380
\ No newline at end of file
------------------------------------------------------------
7. Copyright and disclaimer
FINESSE and the accompanying documentation and the example files
have been written by:
```
Andreas Freise
School of Physics and Astronomy
University of Birmingham
B15 2TT Birmingham
UK
andreas.freise@googlemail.com
```
FINESSE has been substantially developed further during the last
years with Daniel Brown providing the key contributions, such as
the implementation of mirror maps, radiation pressure effects and
quantum noise. Daniel's work on the code and the manual was essential
for the publication of FINESSE as open source. Charlotte Bond has
carefully tested the new code and provided tutorials, examples and
documentation.
The software and documentation is provided as is without any warranty
of any kind. Copyright (c) by Andreas Freise 1999 - 2020.
The source code for FINESSE is available as open source under the GNU
General Public License version 3 as published by the Free Software
Foundation.
This manual and all FINESSE documentation and examples available from
www.gwoptics.org/finesse and related pages are distributed under a
Creative Commons Attribution-Noncommercial-Share Alike License, see
http://creativecommons.org/licenses/by-nc-sa/2.0/uk/.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment