 |
MAOS
Multithreaded Adaptive Optics Simulator
|
|
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 sub-folder 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 sub-folder 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 un-normalized 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 pre-simulation.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 cross-coupling 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 cross-coupling 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 cross-coupling 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. |