INSTALL 14.7 KB
Newer Older
1
------------------------------------------------------------------------
2
                     FINESSE 1.0
3 4 5
       o_.-=.        
      (\'".\|        Frequency domain INterferomEter Simulation SoftwarE
      .>' (_--.
6
   _=/d   ,^\        04.11.2013         http://www.gwoptics.org/finesse/
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
  ~~ \)-'   '        
     / |             INSTALL 
    '  '             
------------------------------------------------------------------------

  1. Introduction

  2. Installation	

  3. Short Syntax Reference

  4. Further development

  5. Copyright and Disclaimer

________________________________________________________________________


1. Introduction

This is a short guide for installing and running FINESSE.  Please see 
28
`Finesse-1.0.pdf' (or later) for the manual and `CHANGES' for the 
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
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
47 48 49
  - writing a Gnuplot file and a Matlab file, which can be
    used for plotting data. FINESSE can further automatically start 
    Gnuplot to plot the data to the specified terminal 
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
    (X11, postscript,...)

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
- 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 
69
look at http://www.gnuplot.info. Alternatively you can use the command 
70
`gnuterm no' to prevent FINESSE from starting Gnuplot and use the 
71
Matlab or Python scripts to plot the data instead.
72 73 74 75 76 77 78 79 80 81

________________________________________________________________________


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 
82
`Finesse1.1'  with all the necessary files.
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102

( 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 automatically plot the results you need to have Gnuplot 
103 104
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'.
105

106 107 108 109 110
Unix:
  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:
111

112
  GNUCOMMAND "/usr/local/bin/gnuplot -persist"
113

114 115
  For any queries or problems please post us a quick message in our 
  forums: http://www.gwoptics.org/finesse/forums
116
	 
117 118 119 120 121
Windows:  
  It is highly recommended that you install Cygwin and its version
  of gnuplot. Instructions on this can be found at the web page below.
  You should then use the Cygwin Bash shell instead of Windows cmd
  to run Finesse (It is much better!).
122
	
123 124 125
  You can also find other tips as well as the gnuplot installation 
  instructions:
  http://kvasir.sr.bham.ac.uk/redmine/projects/finesse/wiki/Hints_for_using_Finesse_on_Windows
126
	
127 128 129 130 131 132 133 134 135 136 137 138 139
  Version 0.99.9 was the first public release of Finesse designed to 
  work with Cygwin rather than just Windows alone, there may still be 
  bugs regarding the workflow or things that just don't make sense. 
  Please help us fix these by posting a quick message in our forum: 
  http://www.gwoptics.org/finesse/forums
	
  You must add the directory where you install Finesse to your 
  environment PATH variable. This is so that cygwin1.dll and cygpath.exe 
  can be found by kat.exe on your system. If you already have cygwin 
  installed it is advisable to remove cygwin1.dll and cygpath.exe that 
  comes with Finesse and use those found in your cygwin/bin folder, which
  should be added to your PATH variable too.

140
Now you should be able to start FINESSE with an example file
141 142
(assuming you have copied the respective files into a
working directory). E.g.:
143 144 145 146 147 148 149

./kat 3D.kat        (for Unix) and
kat.exe 3D.kat      (for Windows)

This starts FINESSE which will print some text to the console that
will look like this:

150
black$ kat 3D.kat
151 152

------------------------------------------------------------------------
153
                     FINESSE 1.0             (build 0.99.9-274-g5a28eb1)
154
       o_.-=.        Frequency domain INterferomEter Simulation SoftwarE
155 156
      (\'".\|        05.06.2013         http://www.gwoptics.org/finesse/
      .>' (_--.      
157 158 159
   _=/d   ,^\        Input file 3D.kat,
  ~~ \)-'   '        Output file 3D.out,
     / |             Gnuplot file 3D.gnu 
160
    '  '                                        Thu Jun  6 00:25:25 2013
161 162 163
------------------------------------------------------------------------
** plotting only one output (use 'multi' to plot all).
100%
164 165
 
 writing matlab/python/gnuplot batch files...
166 167 168 169 170 171 172 173 174
 calling gnuplot...

FINESSE writes the calculated data into the file `3D.out' and a batch file
`3D.gnu'. Then Gnuplot is started and the data from `3D.out' is plotted 
(the plot from this example was used for the cover picture for the manual).

________________________________________________________________________


175
3. Short Syntax Reference for FINESSE 1.1 :
176 177

------------------------------------------------------------------------
178
  FINESSE 1.1     - Help Screen -                      04.11.2013
179
------------------------------------------------------------------------
180
** Usage (1) kat [options] infile [outfile [gnufile]] 
181
   or    (2) kat [options] basename
182 183
   in (2) e.g. basename 'test' means input filename : 'test.kat', 
   output filename : 'test.out' and Gnuplot file name : 'test.gnu'.
184
** Support :
185 186 187
   User support forums:     http://www.gwoptics.org/finesse/forums/
   Online syntax reference: http://www.gwoptics.org/finesse/reference/
** Available options:
188 189 190 191
 -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
192 193
 -klu-full : switch to KLU solver for parallel frequencies (default)
 -klu      : switch to KLU (Legacy solver)
194 195 196 197
 --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
198 199
 --convert : convert knm files between text and binary formats
** Available interferometer components:
200 201
 l name P f [phase] node                          - laser
 m name R T phi node1 node2                       - mirror
202 203
 (or: m1 name T Loss phi ...          
      m2 name R Loss phi ... )        
204 205
 s name L [n] node1 node2                         - space
 bs name R T phi alpha node1 node2 node3 node4    - beamsplitter
206 207 208
 (or: bs1 name T Loss phi ... 
      bs2 name R Loss phi ... )             
 gr[n] name d node1 node2 [node3 [node4]]         - grating
209 210 211
 isol name S node1 node2                          - isolator
 mod name f midx order am/pm [phase] node1 node2  - modulator
 lens f node1 node2                               - thin lens
212
** Detectors:
213 214 215 216 217 218 219 220 221 222 223
 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
 shot name node[*]                                - shot noise
 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
 qshot name num_demod f [phase] node[*]           - quantum shotnoise detector
 qshotS name num_demod f [phase] node[*]          - quantum shotnoise sens.
224
** Available commands:
225
 fsig name component [type] f phase [amp]         - signal
226 227
 fadd f1 f2 f3 ... fN                             - add frequencies to list
 tem[*] input n m factor phase                    - input power in HG/LG modes
228 229 230
 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
231
 (alignment angles beta in [rad])
232
 map component filename                           - read mirror map file
233
 knm component_name filename_prefix [flag]        - save coefficients to file
234 235 236
 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
237
 gauss** name component node w(z) Rc [wy(z) Rcy]  - set q parameter
238 239 240 241
 cav name component1 node component2 node         - trace beam in cavity
 startnode node                                   - startnode of trace
 retrace [off]                                    - re-trace beam on/off
 phase 0-7  (default: 3)                          - change Gouy phases
242 243
 (1: phi(00)=0, 2: gouy(00)=0, 4: switch ad phase)
 conf component_name setting value                - configures component
244 245
** Plot and Output related commands :
 xaxis[*] component param. lin/log min max steps  - parameter to tune
246
 x2axis[*] component param. lin/log min max steps - second axis for 3D plot
247 248 249 250 251 252
 noxaxis                                          - ignore xaxis commands
 const name value                                 - constant $name
 variable name value                              - variable $name
 set name component parameter                     - variable $name
 func name = function-string                      - function $name
 lock[*] name $var gain accuracy                  - lock: make $var to 0
253
 put[*] component parameter $var/$x1/$x2          - updates parameter
254 255 256 257 258 259 260 261 262 263
 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
 pause                                            - pauses after plotting
 multi                                            - plots all surfaces
264
                                                    save/load knm file
265 266 267 268 269 270 271
 GNUPLOT \ ... \ END                              - set of extra commands
                                                    for plotting.
________________________________________________________________________


4. Further development

272 273 274 275 276 277 278 279 280 281 282 283
From Finesse 1.0 to 1.1 we have implemented many of the internal
code changes needed for the implementation of radiation pressure 
effects. In particular, Finesse now computes all frequency components
at the same time (solving one system of equations) rather than
sequentially solving the laser fields, the modulator generated
light and signal sidebands separately.
 
Over the coming months we will continue the implementation of 
radiation pressure effects: we are currently testing the code with
simple examples such as optical springs and optical bars and at the
same time plan the more complex implementation including all 
higher-order modes.
284 285 286 287 288 289 290 291 292 293 294 295 296

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

297 298 299 300 301
FINESSE has been substantially developed further by Daniel Brown during 
the last year (2012 - 2013). Daniel Brown provided significant 
contributions to the code, the manual and the publication of FINESSE 
as open source. Charlotte Bond has carefully tested the new code and 
provided tutorials, examples and documentation.
302

303 304 305
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
306 307
FINESSE source have been written by Paul Cochrane.

308 309
The software and documentation is provided as is without any warranty
of any kind. Copyright (c) by Andreas Freise 1999 – 2013.
310

311 312
The source code for FINESSE is available as open source under the GNU
General Public License version 3 as published by the Free Software
313
Foundation.
314

315 316 317 318
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/.
319