------------------------------------------------------------------------ FINESSE 2.1 o_.-=. (\'".\| Frequency domain INterferomEter Simulation SoftwarE .>' (_--. _=/d ,^\ 05.11.2014 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 post it at the Finesse forums http://www.gwoptics.org/finesse/forums. FINESSE is a 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 `.out'). 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 There are binaries available for several operating systems. After downloading the appropriate package for your operating system from http://www.gwoptics.org/finesse/ you can install FINESSE simply by unpacking the zip (or tar.gz) file. This will create a directory `Finesse2.1' with all the necessary files. ( Alternatively you can build FINESSE directly from the source code. To find more about this, please visit http://kvasir.sr.bham.ac.uk/redmine/projects/finesse ) 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. Becareful 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. In the near future we will continue to use and test these new features for the commissioning of Acvanced LIGO. At the same time we will continue to improve and develop the code. One focus of our activity will be speed improvements, another the development and integration of PyKat (www.gwoptics.org/pykat/). ________________________________________________________________________ 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. Parts of the original FINESSE source and `mkat' have been written by Gerhard Heinzel, the document `sidebands.ps' by Keita Kawabe, the Octave examples and its description by Gabriele Vajente, part of the FINESSE source have been written by Paul Cochrane. The software and documentation is provided as is without any warranty of any kind. Copyright (c) by Andreas Freise 1999 - 2014. 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/.