Basic Usage¶
This section describes how to the simulation for basic cases, that is, using the full end to end code to create and save data which can then be analysed afterwards. Such a scenario is a common one when exploring parameters on conventional AO systems.
Configuration¶
In Soapy, all AO parameters are controlled from the configuration file. This is a python script which contains all the information required to run many AO configurations. A few examples are provided in the conf
directory when you download the code. All parameters are held in one large dictionary, titled simConfiguration
, and are then grouped into relavent sections.
Sim
parameters control simulation wide parameters, such as the filename to save data, the number of simulated phase points, the number of WFSs, DMs and Science cameras as well as the name of the reconstructor used to tie them together. The simName
parameter specifies a directory, which will be created if it does not already exist, where all AO run data will be recorderd. Each run will create a new time-stamped directory within the parent simName
one to save run specific data. Data applying to all runs, such as the interaction and control matrices are stored in the simName
directory.
Atmosphere
parameters are responsible for the structure of the simulated atmosphere. This includes the number of simulated turbulence layers and the integrated seeing strength, r0. Some values in the Atmosphere group must be formatted as a list or array, as they describe parameters which apply to different turbulence layers.
Parameters describing the physical telescope are given in the Telescope
group. These include the telescope and central obscuration diameters, and a pupil mask.
WFSs, LGSs, DMs and Science camera are configured by the WFS
, LGS
, DM
and Science
parameter groups. As multiple instances of each of these components may be present, every parameters in these groups is represented by either a list or numpy array, where each element specifies that component number. For WFSs and DMs, a type
parameter is also given. This is a the name of the python object which will be used to represent that component, and a class of the same name must be present in the WFS.py
or DM.py
module, respectively. Other WFS or DM parameters may then have different behaviours depending on the type which is to be used.
Each parameter that can be set is described in the Configuration section.
Creating Phase Screens¶
For most applications of Soapy, some randomly generated phase screens are required. These can either be created just before the simulation begins, during the initialisation phase, or some existing screens can be specified for the simulation to use. To generate new phase screens with the parameters specified in Atmosphere
each time the simulation is run, set the Atmosphere
parameter, newScreens
to True
.
If instead you wish to used existing phase screens, provide the path to, and filename of each screen in the screenNames
parameter as a list. Screens specified to be loaded must be saved as FITS files, where each file contains a single, 2 dimensional phase screen. The simulation will largely trust that the screen parameters are valid, so other parameters in the Atmosphere
group, such as the wholeScreenSize
, r0
and L0
may be discounted. If you would like the simulation to be able to scale your phase screens such that they adhere to the r0
and screenStrength
values set in the configuration file, then the FITS file header must contain a parameter R0
which is expressed in units of phase pixels.
Running the Simulation¶
Once all the configuration parameters have been set, and you have decided how whether to load or generate phase screens, the simulation is ready to be run. This can be either from the GUI, the command line or from a script.
Graphical User Interface¶
When running Soapy configurations for the first time it can be a good idea to run them in the GUI to sure that components look to be operating as expected. The GUI is shown below running a simple SCAO case, with a tip-tilt mirror and a stack array DM.
If soapy has been installed, or the bin
directory is in the bash PATH, the GUI is started from the command line with the command:
soapy -g path/to/configFile.yaml
The soapy
script can do a few other things as well, use soapy --help
to see all other available options.
Once the GUI has loaded it will begin the initialisation of the simulation. This stage initialises all the simulated components, loads or generates phase screens, allocates data buffers and calculates various required parameters from the parameters given in the configuration file. If any parameters or the configuration file is changed at any point, this initialisation step can be rerun by clicking the “AO Init” button.
The next step in most systems will be to record an interaction matrix, where the effect of each DM influence on the WFS(s) is recorded, and used to calculate a command matrix. From the GUI, this is achieved by clicking the “makeIMat” button. Interaction matrices, command matrices and DM influence functions can be saved in the simName
directory and the simulation checks to see if there are valid ones in that directory it can load instead of making them again. If you would like to force a new interaction matrix to be made, perhaps because you’ve changed parameters which may effect the new interaction matrix, tick the “Force new?” box.
Once this is complete, you can now click “Run!” to run the simulation. You will now see the atmospheric phase moving across the WFS(s), and the resulting measurements on the WFS. This will be recorded, and transformed to DM commands measurements via the reconstructor, and finally, the science phase will be corrected and a better PSF achieved. The loop gain for each DM can be altered using the spin boxes in the top right of the GUI.
Using the GUI significantly slows down the simulation operation, but this can be aleviated by limiting the simulation update rate using the top spin box.
The console in the bottom left of the GUI can be used to either change parameters of the simulation or visualise other data sources. It is a complete python console, provided by the IPython library. To load a new config file into the GUI, go the file>Load Configuration File. You will then have to click “AO Init” to begin initialisation.
Command Line and Scripting¶
To run the simulation from the command line, either use
soapy -i /path/to/configFile.yaml
which will initialise the simulation before dropping you into an interaction ipython prompt, or simply start or python interpretter of choice and run
import soapy #Imports python library
sim = soapy.Sim("/path/to/configFile.yaml") #Loads the configuration file
sim.aoinit() #Initialises all AO simulated objects
The above code would also be used in scripts to run the simulation.
To measure the interaction matrix run:
sim.makeIMat()
or:
sim.makeIMat(forceNew=True)
if you’d like to force the creation of interaction matrices, command matrices and DM influence functions.
Once complete, you’re now ready to run the simulation with:
sim.aoloop()
You should now see a rolling counter of the frame number and current Strehl ratio of each science target.
Retrieving Simulation Data¶
After a simulation run has completed, the resulting data must be retrieved for analysis. The data stored by Soapy depends on the parameters set in the sim
group in the configuration file. Once a aoloop
has completed, the data will be saved into the simName
directory, in a further, time-stamped directory for that particular run. Whithin the simulation, the data is stored in numpy array structures which can be accessed either after the run has completed or during the run (if it is run in the, or in a python thread on the command line).
The strehl ratio of each science target is always stored. Internally, it is kept in the arrays:
sim.instStrehl
and:
sim.longStrehl
Which are the instantaneous and long exposure strehl ratio for each science target. Each of these is of shape sim.config.sim.nSci
by sim.config.sim.nIters
. Note that this is even the case for only a single science target, when the science target Strehl ratios are always accessed with sim.longStrehl[0]
. Strehl ratios may also saved in the simName
directory as instStrehl.fits
and longStrehl.fits
.
There are many other data sources available to save or access from the simulation, these are listed in Data Sources.