MAOS
Multithreaded Adaptive Optics Simulator

MAOS provides a few convenient routines to quickly process the simulation results and obtain time averaged wavefront error.
Use the following (see aolib.py
):
res,fds=maos_res(dir[,seeds] [,iframe] [,iframe2]) #gather field averaged WFE. [] indicate optional res,fds=maos_res(dir*) #gather field averaged WFE from multiple folders recursively res,fds=maos_res_each(dir*) #gather results for each field
Use the following:
res=maos_res(dir[,seeds] [,range]) %gather field averaged WFE. [] indicate optional res,fds=maos_reseach(dir[, seeds] [,range]) #gather results for each field
The wavefront error time history can be processed using the built in tool drawres
and plotted using the Gtk based drawdaemon
.
drawres folder1 folder2 ...
If the specified folder contains subfolders with results, they will be plotted together. When using on a text terminal with DISPLAY
not set, if there is monitor
running in a connected computer, it will launch drawdaemon
.
MAOS generates output in binary format .bin
files (which maybe gzipped) as described below. PSFs are written into .fits
files with extensions.
The data are saved to the .bin files in a simple modular way. For a simple matrix (like double matrix or cell matrix), we first write a magic number (4 byte unsigned int) representing the data type, and then x and y dimension (two 8 byte unsigned int), and finally the data itself (if it is cell, recursively write the data contained in the cell with the same method).
Each block of data may optionally be proceeded with a metadata header that describes the data, for example, the sampling of a loc_t
grid. The surf OPD contains header information about the sampling, origin and height of the OPD array.
We use .bin
format instead of .fits
because it can be conveniently memory mapped for best efficiency in reading or saving.
For implementation details, please refer to Bin file format.
There are two MATLAB mex
routines read
and write
that can read and write .bin or
.fits files in MATLAB. The source of these mex routines are located in source subfolder
mex
. If mex
is found in the system, this mex routines will be compiled automatically in the mex
subfolder of the compiling folder. If it doesn't get compiled, please goto the mex
subfolder in the source folder and type ./compile.sh to compile them. Copy write.mexa64
and read.mexa64
into a folder that is in your matlab path, such as $HOME/matlab
. The usage in MATLAB
is as follows:
If there is any problem in compiling read.c
and write.c
, there are also two matlab scripts in the scripts
folder, readbin.m
and writebin.m
, that have most of functionality of read.c
, write.c
albeit a bit slower and cannot handle compressed files conveniently.
There is readbin.py
in scripts
folder for reading .bin or
.fits files in python. Alternatively, it is also possible to call
C
routines in python, including readbin
and writebin
as read
and write
. To do so, first set an environment variable MAOS_AOLIB
poing to the aolib.so
file in the .bin folder in the compiling directory. Then import
scripts/aoslib.py
to your python.
There are two idl scripts in the subfolder script
. They are readbin.pro
for reading .bin files, and
writebin.pro
for writing .bin files.
Certain results (e.g., PSF) are saved in .fits format. Any standard fits reader (e.g.,
fv
, ds9
) should be able to read them. There is also an executable bin2fits
that can convert .bin to
.fits files.
There will be several files created during simulation in the result folder and subfolder extra
(those results are not saved when save.extra=0
). The number after underscore _ is the seed. For example, with seed 1 the following files are produced. Read in these files using provided mex function read
in MATLAB. Notice that the suffix .bin or
.fits has been omitted. You do not need to add the suffix when use
read
.
Res_1:
A binary file containing a cell array that include the main results.res
[0] contains the open loop wavefront variance (WFV in units of \(m^2\)) in row vectors. When sim.rmax=1, the rows are
When sim.rmax>1, the rows are
res
[1] no longer used.res
[2] contains the closed loop wavefront variance in row vectors. The format is the same as res[0]res
[3] (Only in split tomography) contains the closed loop wavefront variance. The rows are (not depend on sim.rmax)Resp_1:
resp:
Results for each direction. Combines the following four files previous saved individually: Resolmp_1, Resclmp_1, Resolep_1, Resclep_1.resp=read
('Resp_1)resp
[0,idir]: Open loop wavefront Zernike modes, for evaluation direction idir, defined on unnormalized coordinate on the aperture, in the Noll's Zernike order of piston/tip/tilt ...resp
[1,idir]: Close loop wavefront Zernike modes, in the same format as resp
[0,idir].resp
[2,idir]: Open loop wavefront variance for each science field point in the same format as res[0].resp
[3,idir]: Closed loop wavefront variance for each science field point in the same format as res[0].Resclemp_1:
LGS/TT/NGS mode wavefront error for each direction.RescleNGSm_1:
contains a row vector array of either the residual NGS modes (in radian like unit) or the applied NGS mode correction if ideal NGS mode correction is made. Mainly used to save the ideal NGS modes applied in skycoverage presimulation.RescleNGSmp_1:
This is NGS mode before averaging over directions.ResoleNGSm_1
and ResoleNGSmp_1:
Like above, but for open loop.maos_
[HOST]_[PID].conf: The final effective configuration for MAOS run with pid PID. Can be used to reproduce the simulation or check the configurations. Lines begin with # are defaults configurations while the rest have been overridden. File for most recent run is linked to maos_recent.conf
run_
[HOST]_[PID].log: Log file. File for most recent run is linked to run_recent.log
sanea_sim_1:
When wavefront sensors are running in physical optics mode, the average gradient measurement error for that wavefront sensor is saved (in order) in a cell in this file. Each cell is a column vector with elements twice the number of subaperture. The first half is for \(x\) (or radial) gradient, and the second half is for \(y\) (or azimuthal) gradient. They are in units of \(rad^2\).The PSF total FOV is evl.wvl/evl
.dx but may be trimmed by setting evl.psfsize
to a smaller number (of pixels). The PSF sampling is usually evl.wvl/(2*aper.d)
but may be evl.wvl/(evl.psfgridsize*evl.dx)
if evl.psfgridsize
is set. The exact number of those can be checked in the fits header.
evlpsfcl_1:
When evl.psfmean
is 1, contains the time averaged science closed loop psf. if is a cell array of \(n_{wvl}\times n_{evl}\). Each cell contains a center cut of the science PSF.evlpsfdl_1:
diffraction limited, PSF.evlpsfol_1:
frame and field averaged open loop science PSF.evlpsfhist_1_ievlx:
When evl.psfhist
is 1, each of these files contains the time history of the complex PSF of evaluation direction \(x\).Resfsmcmd_1:
Each cell contains the FSM tip/tilt command (only none empty for LGS WFS) history in unit of radian.Resfsmerr_1:
Each cell contains the FSM tip/tilt error history in unit of radian.psdcl_1
and psdol_1:
Closed loop and pseudo open loop PSD for high order control obtained from telemetry.ResCG_1
: Tomography and DM Fitting conjugate gradient residual time history.Reszoompos_1
: For LGS only, the trombine position. One cell per WFS.When save.setup=1
, MAOS will save the geometry data created before entering simulation to files in folder setup
. When save.recon=1
, the tomography and DM fitting matrices are also saved, which takes space and are not enabled by save.setup=1
.
The following explains each file. Not all of them may exist, depending on set of options. The suffix of the file names are removed.
File name  Description 

actslave  The slaving operator 
ahst_GM  ad hoc split tomography, model to gradient operator 
ahst_MCC  ahst, model cross coupling matrix. 
ahst_Mdm  ahst, the NGS mode defined on DM grid 
ahst_Pngs  ahst, ngs mode removal operator from DM commands 
ahst_Ptt  ahst, tip/tilt removal operator from DM commands 
ahst_Rngs  ahst, ngs mode reconstructor 
ahst_Wa  ahst, the weighting using science field. 
aloc  DM actuator grid. 
ploc  The coarse sampled grid on aperture for reconstruction 
xloc  The tomography grid. 
TT  The global tip/tilt modes for wfs 
PTT  The global tip/tilt removal operator for wfs 
saneai  The inverse of nea^2 used in tomography (rad^2) 
W0  The W0 weighting defined on ploc. 
W1  The W1 weighting defined on ploc. 
aper_locs  The fine sampled grid on telescope aperture. 
aper_amp  Telescope aperture amplitude defined on aper_locs 
aper_mcc  modal crosscoupling matrix for modes defined on aper_locs 
FLM  Fit left hand side operator, sparse matrix 
FLU  Fit left hand side operator, Low rank U matrix 
FLV  Fit left hand side operator, Low rank V matrix 
FRM  Fit right hand side operator, sparse matrix 
FRU  Fit right hand side operator, Low rank U matrix 
FRV  Fit right hand side operator, Low rank V matrix 
GA  Gradient operator from aloc. 
GP  Gradient operator from ploc. 
GX  Gradient operator from xloc. 
HA  Ray tracing from aloc to ploc along fit directions 
HXF  Ray tracing from xloc to ploc along fit directions 
HXW  Ray tracing from xloc to ploc along wfs directions 
L2  Laplacian regularization on xloc 
NW  Low rank terms in fitting 
NW2  Adjusted low rank terms by slaving. 
powfs0_area  The subaperture area 
powfs0_dtf0_nominal  The nominal of DTF 
powfs0_dtf0_si  The si of DTF 
powfs0_etfprep0_2d  The elongation transfer function 
powfs0_GP  The gradient operator from ploc. 
powfs0_GS0  The gradient operator from aper_locs. 
powfs0_i0  The subaperture time averaged image for matched filter 
powfs0_gx  The pixel by pixel x gradient of i0 
powfs0_gy  The pixel by pixel y gradient of i0 
powfs0_imcc  The inverse of model crosscoupling matrix of piston/tip/tilt modes 
powfs0_loc  The grid for all subapertures (grouped by subapertures) 
powfs0_amp  The amplitude defined on powfs0_loc 
powfs0_llt_loc  The aperture grid of the uplink laser launch telescope (LLT) 
powfs0_llt_amp  The aperture amplitude of LLT defined on powfs0_llt_loc 
powfs0_llt_imcc  The inverse of model crosscoupling matrix of p/t/t modes for LLT 
powfs0_srot  The orientation of each subaperture wrt LLT 
powfs0_srsa  The distance of each subaperture from the LLT 
powfs0_mtche  The matched filter gradient estimator 
powfs0_pts  The lower left grid point of each subaperture. 
powfs0_saloc  The lower left corner of each subaperture 
powfs0_sanea  The subaperture noise equivalent angle(nea) in rad^2 
powfs0_saneaxy  The nea along x/y directions in rad^2 
powfs0_saneaixy  The inverse of nea along x/y directions in rad^2 
powfs0_saneara  The subaperture nea along r/a directions in rad^2 
powfs0_sepsf  The subaperture short exposure psf (tip/tilt removed) 
powfs0_sodium  The sodium layer profile 
powfs0_sprint  which subapertures to print 
powfs0_GS0  The averaging gradient operator from pts. 
powfs1_ZS0  The ztilt best fit gradient operator from pts. 
Depending on parameters enabled, the simulation telemetry data will be saved to files in the simulation folder. The following describes them in detail. Notice that save.grad, save.gradgeom, save.ints and save.wfsopd takes values of 1, 2 or 3, where 1 means saving for all wfs, 2 means saving for only high order wfs and 3 means saving for lower order wfs.
Name convention: the last number after underscore is the seed. The following shows results for seed1. When there are multiple wfs or science fields, we only show the results for the first.
Many of the results contains a cell array of length nsim
(number of simulation steps), whenever that makes sense.
The data regarding the DM commands are all defined on the actuator grid aloc
.
The second column of the tables shows which option in dbg.conf
enables the save of this data.
The suffix of the file names are removed.
File name  Option to enable  Description 

atm_1  save.atm  The atmosphere 
dmerr_hi_1  save.dm  The DM error signal for high order wfs 
dmfit_hi_1  save.dm  The DM fit result for high order wfs 
Merr_lo_1  save.dm  The low order mode error signal (split tomography) 
Mint_lo_1  save.dm  The low order mode integrator output (split tomography) 
dmint_hi_1  save.dm  The DM integrator output of high order wfs output (split integrator only) 
dmint_1  save.dm  The DM integrator output (command integrator for both high/low wfs) 
dmreal_1  save.dm  The real, effective DM commands applied 
dmpttr_1  save.dmpttr  The piston/tip/tilt removed, effective, DM commands. 
evl0_opdcl_1  save.evlopd  The closed loop opd for science fields 
evl0_opdol_1  save.evlopd  The open loop opd for science fields 
gcov_wfs0_5_10_1  save.gcov  The covariance between gradients of wfs 0 and 5 saved at time step 10 
opdr_1  save.opdr  The tomography output, defined on xloc 
opdx_1  save.opdx  The atmosphere projected onto xloc (direct fitting) 
wfs0_gradcl_1  save.grad  The wfs gradient measurement. 
wfs0_gradnf_1  save.grad  The wfs noise free gradient. 
wfs0_gradol_1  save.grad  The wfs pseudo open loop gradient 
wfs0_gradgeom_1  save.gradgeom  The wfs geometric gradient (in physical optics wfs simulations) 
wfs0_intsnf_1  save.ints  The wfs subaperture images (noise free) 
wfs0_intsny_1  save.ints  The wfs subaperture images (noisy) 
wfs0_lltopd_1  save.wfsopd  The wfs laser launch telescope OPD. 
wfs0_opd_1  save.wfsopd  The wfs OPD. 