INSTALL 18.6 KB
Newer Older
1
------------------------------------------------------------------------
2
                     FINESSE 2.1
3 4 5
       o_.-=.        
      (\'".\|        Frequency domain INterferomEter Simulation SoftwarE
      .>' (_--.
6
   _=/d   ,^\        05.11.2014         http://www.gwoptics.org/finesse/
7 8 9 10 11 12 13 14 15
  ~~ \)-'   '        
     / |             INSTALL 
    '  '             
------------------------------------------------------------------------

  1. Introduction

  2. Installation	

16
  3. Running your first simulation
17

18
  4. Short syntax reference
19

20 21 22
  5. Further development

  6. Copyright and disclaimer
23 24 25 26 27 28 29

________________________________________________________________________


1. Introduction

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

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
62 63
- a file with extension `.gnu' is a batch  file for Gnuplot, or
  a file with '.py' for plotting with Python
64 65 66 67 68 69 70 71
- 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 
72
look at http://www.gnuplot.info. Alternatively you can use the command 
73
`gnuterm no' to prevent FINESSE from starting Gnuplot and use the 
74
Matlab or Python scripts to plot the data instead.
75 76 77 78 79 80 81 82 83 84

________________________________________________________________________


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 
85
`Finesse2.1'  with all the necessary files.
86 87 88 89 90

( 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 )

91
In addition you can download a small collection of simple example files.
92 93 94 95 96 97 98 99
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).

100 101 102 103
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').
104

105
If you want to automatically plot the results you need to have Gnuplot 
106 107 108
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'.
109

110
Unix/OS X:
111 112 113 114
  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:
115

116
  GNUCOMMAND "/usr/local/bin/gnuplot -persist"
117

118 119
  For any queries or problems please post us a quick message in our 
  forums: http://www.gwoptics.org/finesse/forums
120
	 
121
Windows:  
Daniel Brown's avatar
Daniel Brown committed
122
  Firstly you must move the FINESSE folder to a location on
123 124 125 126
  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 
127 128 129 130 131 132 133 134 135 136 137
  `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:  
138
  http://sourceforge.net/projects/gnuplot/files/latest/download
139 140
  If you have a space in the path to gnuplot.exe you need to note use
  of ' and " to encapsulate path and GNUCOMMAND:
141
  GNUCOMMAND '"C:\Program Files\gnuplot\bin\Wgnuplot.exe" --persist $s'
142
  else use:
143 144 145 146 147 148 149 150
  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.
151
	
152
________________________________________________________________________
153
	
154

155 156 157 158 159 160 161
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
162

163 164
To run the first test file, open a terminal window, change into
the FINESSE directory and type:
165

166 167 168 169
$ ./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):
170 171

------------------------------------------------------------------------
172
                     FINESSE v2.0                (build v2.0-7-gf7b41e5)
173
       o_.-=.        Frequency domain INterferomEter Simulation SoftwarE
174
      (\'".\|        17.05.2014         http://www.gwoptics.org/finesse/
175
      .>' (_--.      
176 177 178 179
   _=/d   ,^\        Input file test.kat,
  ~~ \)-'   '        Output file test.out,
     / |             Gnuplot file test.gnu 
    '  '                                        Sun May 18 11:06:48 2014
180
------------------------------------------------------------------------
181 182 183 184 185 186 187 188
 '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)
189
 
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
                   
 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
------------------------------------------------------------------------
                     
216
 writing matlab/python/gnuplot batch files...
217 218
 calling gnuplot...

219 220 221 222 223 224 225 226 227 228 229 230 231

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
Daniel Brown's avatar
Daniel Brown committed
232
  the correct path. On Windows you can use 'where gnuplot' instead.
Andreas Freise's avatar
Andreas Freise committed
233
- with that path you should be able to start Gnuplot manually from the
234 235 236 237
  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/
238 239 240 241

________________________________________________________________________


242
4. Short syntax reference for FINESSE 2.0 :
243 244

------------------------------------------------------------------------
245
  FINESSE v2.0     - Help Screen -                      18.05.2014
246
------------------------------------------------------------------------
247
** Usage (1) kat [options] infile [outfile [gnufile]] 
248
   or    (2) kat [options] basename
249 250
   in (2) e.g. basename 'test' means input filename : 'test.kat', 
   output filename : 'test.out' and Gnuplot file name : 'test.gnu'.
251
** Support :
252 253 254
   User support forums:     http://www.gwoptics.org/finesse/forums/
   Online syntax reference: http://www.gwoptics.org/finesse/reference/
** Available options:
255 256 257 258
 -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
259 260
 -klu-full : switch to KLU solver for parallel frequencies (default)
 -klu      : switch to KLU (Legacy solver)
261 262 263 264
 --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
265 266
 --convert : convert knm files between text and binary formats
** Available interferometer components:
267 268
 l name P f [phase] node                          - laser
 m name R T phi node1 node2                       - mirror
269 270
 (or: m1 name T Loss phi ...          
      m2 name R Loss phi ... )        
271 272
 s name L [n] node1 node2                         - space
 bs name R T phi alpha node1 node2 node3 node4    - beamsplitter
273 274 275
 (or: bs1 name T Loss phi ... 
      bs2 name R Loss phi ... )             
 gr[n] name d node1 node2 [node3 [node4]]         - grating
276
 isol name S node1 node2 [node3]                  - isolator
277 278
 mod name f midx order am/pm [phase] node1 node2  - modulator
 lens f node1 node2                               - thin lens
279
 sq name f r angle node                           - squeezed input
280
** Detectors:
281 282 283 284 285 286 287 288
 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
289 290 291 292 293 294
 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.
295
** Available commands:
296 297 298
 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
299 300
 fadd f1 f2 f3 ... fN                             - add frequencies to list
 tem[*] input n m factor phase                    - input power in HG/LG modes
301 302 303
 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
304
 (alignment angles beta in [rad])
305
 map component filename                           - read mirror map file
306
 knm component_name filename_prefix [flag]        - save coefficients to file
307
 smotion component map_file transfer_function     - set surface motion
308 309 310
 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
311
 gauss** name component node w(z) Rc [wy(z) Rcy]  - set q parameter
312 313
 cav name component1 node component2 node         - trace beam in cavity
 startnode node                                   - startnode of trace
314
 lambda wavelength                                - overwrite wavelength
315
 retrace [off|force]                              - re-trace beam on/off
316
 phase 0-7  (default: 3)                          - change Gouy phases
317 318
 (1: phi(00)=0, 2: gouy(00)=0, 4: switch ad phase)
 conf component_name setting value                - configures component
319
 vacuum components_names                          - specific quantum noise
320 321
 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
322 323
** Plot and Output related commands :
 xaxis[*] component param. lin/log min max steps  - parameter to tune
324
 x2axis[*] component param. lin/log min max steps - second axis for 3D plot
325 326
 noxaxis                                          - ignore xaxis commands
 const name value                                 - constant $name
327
 var name value                                   - tunabel variable $name
328 329 330
 set name component parameter                     - variable $name
 func name = function-string                      - function $name
 lock[*] name $var gain accuracy                  - lock: make $var to 0
331
 put[*] component parameter $var/$x1/$x2/$fs/$mfs - updates parameter
332 333 334 335 336 337 338 339
 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
340
 pyterm terminal                                  - Python terminal
341 342
 pause                                            - pauses after plotting
 multi                                            - plots all surfaces
343
                                                    save/load knm file
344
 GNUPLOT \ ... \ END                              - set of extra commands
345
                                                    for plotting.
346 347 348
________________________________________________________________________


349
5. Further development
350

351 352 353
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.
354
 
355 356 357 358 359
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/).
360

361 362 363 364
________________________________________________________________________


6. Copyright and disclaimer
365 366 367 368 369 370 371 372 373 374 375

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

376 377 378 379 380 381 382
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. 
383

384 385 386
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
387 388
FINESSE source have been written by Paul Cochrane.

389
The software and documentation is provided as is without any warranty
390
of any kind. Copyright (c) by Andreas Freise 1999 - 2014.
391

392 393
The source code for FINESSE is available as open source under the GNU
General Public License version 3 as published by the Free Software
394
Foundation.
395

396 397 398 399
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/.
400