README.rst 5.34 KB
Newer Older
Daniel Brown's avatar
Daniel Brown committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
PyKat
===========

PyKat is a wrapper for using FINESSE (http://www.gwoptics.org/finesse).
It aims to provide a Python toolset for automating more complex tasks
as well as providing a GUI for manipulating and viewing simulation
setups.

Installation
-------------

The easiest way to install PyKat is through PyPi::

    pip install pykat
    
If you are a Windows user you also have the option to download the installer at https://pypi.python.org/pypi/PyKat.

Daniel Brown's avatar
Daniel Brown committed
18
19
20
21
22
23
24
25
26
27
28
29
30
31
You should now be able to open up a new Python terminal and type `import pykat`, the output should be::
    
    >>> import pykat
                                                  ..-
        PyKat 0.1              _                  '(
                              \`.|\.__...-""""-_." )
           ..+-----.._        /  ' `            .-'
       . '            `:      7/* _/._\    \   (
      (        '::;;+;;:      `-"' =" /,`"" `) /
      L.        \`:::a:f            c_/     n_'
      ..`--...___`.  .    ,
       `^-....____:   +.      www.gwoptics.org/pykat
    >>>

Daniel Brown's avatar
Daniel Brown committed
32
You will also need to ensure that you have a fully working copy of FINESSE installed and setup on your machine.
Daniel Brown's avatar
Daniel Brown committed
33
34
35
36
37
38
More details on this can be found at http://www.gwoptics.org/finesse. 

You must setup 2 environment variables: 'FINESSE_DIR', whose value is the directory that the 'kat' executable is in;
'KATINI', which states the directory and name of the kat.ini file to use by default in FINESSE, more information in the
FINESSE manual can be found about this.

Daniel Brown's avatar
Daniel Brown committed
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

Usage
------

This does not detail how to use FINESSE itself, just PyKat. FINESSE related queries should
be directed at the FINESSE manual or the forum http://kvasir.sr.bham.ac.uk/redmine/projects/finesse/boards.

We highly recommend running PyKat with IPython, it has so far provided the best way to explore the various PyKat objects and output data.
Also of use is IPythons interactive matplotlib mode - or pylab mode - which makes displaying and interacting with multiple plots easy.
You can start pylab mode from a terminal using::

    ipython -pylab

Regardless of which interpreter you use, to begin using PyKat you first need to include the following::

    from pykat import finesse
    from pykat.detectors import *
    from pykat.components import *
    from pykat.commands import *
    from pykat.structs import *

This provides all the various FINESSE components and commands you will typically need.
Running a simulation requires you to already know how to code FINESSE files, which is beyond
Daniel Brown's avatar
Daniel Brown committed
62
63
the scope of this readme. FINESSE commands can be entered in many ways: reading in a previous .kat
file, creating pykat objects representing the various FINESSE commands or by writing blocks of FINESSE code 
Daniel Brown's avatar
Daniel Brown committed
64
65
66
67
as shown next::

    import pylab as pl

Daniel Brown's avatar
Daniel Brown committed
68
    # Here we write out any FINESSE commands we want to process
Daniel Brown's avatar
Daniel Brown committed
69
70
71
72
73
74
75
76
    code = """
    l l1 1 0 0 n1
    s s1 10 1 n1 n2
    m m1 0.5 0.5 0 n2 n3
    s s2 10 1 n3 n4
    m m2 0.5 0.5 0 n4 n5
    s s3 10 1 n5 n6

77
78
    pd pd_cav n4
    xaxis m1 phi lin 0 360 360
Daniel Brown's avatar
Daniel Brown committed
79
80
81
82
83
84
    yaxis abs:deg
    """

    # this kat object represents one single simulation, it containts
    # all the objects and their various states.
    kat = finesse.kat()
Daniel Brown's avatar
Daniel Brown committed
85
    
Daniel Brown's avatar
Daniel Brown committed
86
87
88
    # Currently the kat object is empty. We can fill it using a block
    # string of normal FINESSE commands by parsing them.
    kat.parseCommands(code)
Daniel Brown's avatar
Daniel Brown committed
89
    
Daniel Brown's avatar
Daniel Brown committed
90
91
92
93
94
    # Once we have some simulation built up we can run it simply by calling...
    out = kat.run()

    # This out object contains the results from this run of the simulation.
    # Parameters can then be changed and kat.run() can be called again producing
Daniel Brown's avatar
Daniel Brown committed
95
96
97
98
99
    # another output object. So if we wanted to change the reflectivity of m1 we can do
    kat.m1.R = 0.2
    kat.m1.T = 0.8
    # now run it again...
    out2 = kat.run()
Daniel Brown's avatar
Daniel Brown committed
100
101
102
103
104
105
106
107
108
109
110
111
112
    
    # We can plot the output simply enough using pylab plotting.
    pl.figure()
    pl.plot(out.x, out["pd_cav"])
    pl.xlabel(out.xlabel)
    pl.ylabel("Intensity [W]")
    pl.legend(out.ylabels)
    pl.show()

The above demonstates a way of packaging up a FINESSE simulation - simple or complex - and 
including any post-processing and plotting in one Python script file. Or you can create
kat files separately and produce Python scripts to run and process them, that choice is upto
you, Pykat provides the means to be used in both ways.
Daniel Brown's avatar
Daniel Brown committed
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

To load in a separate FINESSE .kat file we can use the commands::
    
    kat = finesse.kat()
    # load in a separate file in the same directory...
    kat.loadKatFile('test.kat')
    # the kat object has now parsed all the commands in this file.
    
    # We can alter and objects in there, e.g. if there was a mirror called m1
    kat.m1.phi = 45
    
    out = kat.run()
    

    

    
Daniel Brown's avatar
Daniel Brown committed
130
131
132
133
134
135
136
137
138
    
Finesse Test Server
----------------------

A Flask based website that runs the Finesse test suites is included in PyKat. This can be hosted in Apache or run as a development server for quick testing on a system. This is a developer tool for testing FINESSE against a selection of known test cases.

Prerequistes:
    Flask
    Numpy
139
    CodernityDB
Daniel Brown's avatar
Daniel Brown committed
140
141
142
143
144
    
Command to start server:

.. code:: bash

145
  python -m pykat.testing.web_server --path=[path to create website] --port=[HTTP port] --git-bin=[path to git binary]
Daniel Brown's avatar
Daniel Brown committed
146
147

The website can then be accessed in a web browser at the address: localhost:[port]