![]() |
MAOS
Multithreaded Adaptive Optics Simulator
|
We assume that maos is already in the PATH so we can type maos to launch it.
Use the following command to get the help message:
The general form of the command line is
Options, .conf files, and key=value entries can appear in any order. A value that contains spaces, such as an array [1 2 3], does not need to be quoted: maos joins all the arguments and keeps text inside [] or quotes together. Quote it anyway if your shell would otherwise expand it.
Examples:
| Option | Description |
|---|---|
| -h, --help | Print the help message and exit. |
| -c FILE.conf, --conf=FILE.conf | Use FILE.conf as the baseline (main) configuration instead of default.conf. |
| -o DIR, --output=DIR | Save results to DIR (created if needed). maos changes into DIR before running. Without -o, nothing is saved, and options that require saving (save.setup, save.all, sim.skysim, evl.psfmean, evl.psfhist) cause an error. |
| -n N, --nthread=N | Use N threads. The default is the number of online CPU cores, or OMP_NUM_THREADS if it is smaller. |
| -g i, --gpu=i | Use GPU i (in nvidia-smi order). Repeat to use several GPUs, e.g. -g0 -g2. -g-1 disables the GPU. Default: automatic. |
| -G N, --ngpu=N | Use N GPUs, chosen automatically. When both -g and -G are given, -g takes priority. |
| -d, --detach | Detach from the terminal and run in the background. Requires -o. |
| -f, --force | Start immediately without waiting for the scheduler to allocate CPUs. Jobs running in the foreground always start immediately. |
| -O, --override | Rerun seeds that are already finished (have a Res_<seed>.done file). See Seeds, restarting, and multiple runs. |
| -r host, --run=host | Run the job on another host. Requires the scheduler (scheduler) on that host. |
| -p DIR, --path=DIR | Add DIR to the search path for .conf and data files. |
The help message printed by maos -h also lists a few environment variables. See Environment variables for the complete list.
When maos runs in the foreground (no -d and no -r), it starts right away and reports its progress to the scheduler, which is launched automatically if it is not already running. The monitor program (GTK or the browser interface) connects to the scheduler to show the progress of all jobs and to plot results.
With -d or -r host, maos hands the job to the scheduler, which queues it and launches it when enough CPUs (and GPUs) are free. If the scheduler cannot be reached, maos warns and runs the job by itself in the background. Without -f, such a job still waits until enough CPUs are idle. When maos is built with --disable-scheduler (or --enable-release), detached jobs start immediately.
When maos is compiled with CUDA, it uses the GPUs by default. Without -g or -G, maos uses all usable GPUs that have enough free memory, the least busy ones first. Use -g i (repeatable) to select GPUs by their nvidia-smi index, -G N to use N automatically selected GPUs, or -g-1 to run on CPU only. Setting the environment variable MAOS_GPU_DISABLE_<i>=1 excludes GPU i from use.
Which parts of the simulation run on the GPU is controlled by the gpu.* keys in sim.conf, all enabled (1) by default: gpu.wfs (wavefront sensors), gpu.evl (performance evaluation), gpu.tomo (tomography), gpu.fit (DM fitting), gpu.lsr (least squares reconstruction), gpu.psf (PSF accumulation), and gpu.moao. maos turns off some of them automatically when the configuration is not supported on GPU, for example gpu.evl when evl.rmax>1, or gpu.tomo when tomo.cxxalg is not 0.
sim.seeds is a list of random seeds (default [1]). Each seed is a separate realization of the turbulence and noise, and the seeds are simulated one after another in the same process:
When a seed finishes, maos creates Res_<seed>.done in the output folder. When maos starts, it skips every seed that already has a .done file and every seed that another maos process is running in the same folder (detected with a lock file). Therefore:
sim.start and sim.end (default 0 and 500 in sim.conf) set the first and last (exclusive) time step. sim.dt (default 1/600 s) is the loop time step.
With -o DIR, maos writes the following in DIR:
Other save.* keys in dbg.conf save telemetry such as gradients, DM commands, and OPDs.
The following environment variables are read by maos. Variables starting with MAOS_ can also be given as MAOS_X=value in a .conf file or on the command line, which sets the environment variable before it is used. This does not work for MAOS_CONFIG_PATH, MAOS_PERMISSIVE, and the low level flags at the end of this section, which are read before the configuration is loaded; set them in the shell.
| Variable | Default | Description |
|---|---|---|
| MAOS_CONFIG_PATH | (unset) | Folder that contains the configuration files: $MAOS_CONFIG_PATH/config/maos or $MAOS_CONFIG_PATH/maos. See Search path. |
| MAOS_LOG_LEVEL | 0 | Amount of output, from -5 to 5. -3: errors and warnings only; -2: also the most important information; -1: also useful information; 0: all information; 1, 2, 3: increasing amount of debugging output. |
| MAOS_PERMISSIVE | 0 | Set to 1 to turn the errors for unrecognized keys (or keys used more than once) into warnings. |
| MAOS_PARALLEL | 1 | 1: run WFS, reconstruction, and performance evaluation of each time step in parallel. 0: run them one after another. 2: event driven parallel mode (requires OpenMP; falls back to 1 otherwise). |
| MAOS_NO_WFS | 0 | Set to 1 to skip all WFS calls (for debugging and timing). |
| MAOS_NO_EVL | 0 | Set to 1 to skip performance evaluation calls. |
| MAOS_NO_RECON | 0 | Set to 1 to skip reconstruction calls. |
| MAOS_KEEP_MEM | 0 | Set to 1 to keep some temporary memory between time steps. |
| MAOS_TOMOSCALE | 1e-12 | Scaling applied to the turbulence regularization terms in tomography to keep numbers in range, needed for single precision. |
| MAOS_MEM_DEBUG | 0 (1 in debug builds) | Set to 1 to enable malloc/free accounting, which reports memory leaks at exit. |
| MAOS_MEM_VERBOSE | 0 | Set to 1 or 2 to print every malloc/free call. |
| MAOS_MEM_FUNTRACE | 0 | Set to 1 to record the allocating function name instead of a backtrace in memory accounting. |
| MAOS_GPU_DISABLE_<i> | (unset) | Set to a nonzero value to exclude GPU <i> (nvidia-smi index). |
| MAOS_MISREG_SEQ | 1 | Random seed used to randomize WFS misregistration set by powfs.misregx, powfs.misregy, and powfs.misregc. |
| MAOS_DRAW_NOREUSE | 0 | Set to 1 to start a new drawdaemon window instead of reusing an existing one. |
| OMP_NUM_THREADS | (unset) | When smaller than the number of CPU cores, limits the default number of threads (see -n). |
| CUDA_LAUNCH_BLOCKING | (unset) | When nonzero, maos uses only the default CUDA stream. |
| MAOS_DIRECT_LAUNCH | (internal) | Set by the scheduler when it launches a job. Do not set it. |
The following variables are for testing and developing maos: MAOS_PYWFS_DEBUG, MAOS_PYWFS_TT_DUAL, MAOS_PYWFS_PSIZE (default 3), MAOS_PYWFS_FULL (pyramid WFS), MAOS_LGS_SPH_PSD, MAOS_SODIUM_FIT, MAOS_DITHER_ND, MAOS_DITHER_MD2, MAOS_DITHER_MD3, and the low level flags MAOS_PROP_GRID_MAP_OPTIM, MAOS_LOC_MAP_EXTEND, MAOS_SVD_SDD_THRES, and MAOS_CN2EST_NO_NEGATIVE.
All user modifiable options are configured through config files with suffix .conf or key=value entries on the command line. The supplied default setup files are stored in sub-folder config/maos. The config files are organized in a modular way. One .conf file can include another .conf file with include=filename.conf. The .conf files in config/maos are self-documented. Config File List lists all of them.
All the options are in the form of key=value. The usual convention is: if the entry in parms is called parms->wfs.thetax, the entry in the .conf file will be in the form wfs.thetax=value.
Old key names that have been renamed are listed in changes.conf and are converted automatically, with a warning if the key was renamed with =>.
Configuration is read in three levels, from low to high priority:
A value from a higher level always overrides a lower one, no matter in which order they appear on the command line. Within the same level, the value read last wins.
maos checks that every supplied key is used:
The full list of keys and values actually used is saved to maos_done.conf in the output folder (see Output folder).
The configuration folder is the first of the following that exists:
.conf files and data files named in them (e.g. aper.fnamp) are searched in the folder where maos is launched (before changing into the -o folder), then in the configuration folder and its bin, atm, and examples sub-folders, then in folders added by -p or path=. An absolute path is used as is.
Without -c, the main file is ~/.aos/default.conf if it exists, otherwise default.conf found through the search path (so a default.conf in the launch folder takes precedence).
The recommended way to organize config files for a specific problem is to keep a baseline .conf file that specifies all the necessary key=value entries, usually by including other .conf files. The default entry is default.conf unless -c file.conf is supplied on the command line.
Put the values you want to change on the command line (quote them if your shell requires it) or in one or more overriding .conf files in the simulation folder.
The .conf files in the config/maos folder are only modified during code development and should not be modified by the end user. Use overriding .conf files in simulation folders or embed configurations on the command line to modify the values.
In the config/maos folder, there are a few baseline .conf files that are complete for each configuration:
Each of these files includes a few other .conf files by specifying include=filename.conf. For example, all of them include the following common .conf files that are independent of the simulation mode or geometry.
The following list the exclusive .conf files used to specify a particular set of configurations. Each group should only appear once.
For example, the default configuration mcao_lgs.conf includes mcao_base.conf and wfs_lgs_ttf_tt.conf. mcao_base.conf includes sim.conf, dm_dual.conf for a dual DM system, atm/atm_mk13n50p.conf for the Maunakea 13N median seeing turbulence profile, fov_sq34.conf for the science FoV (evl_sq34.conf, Simpson weighting on 3x3 points in the square 34x34" FoV) and the DM fitting FoV (\ref fit_sq34, the same points), \ref recon, and \ref dbg. \ref wfs_lgs_ttf_tt defines six LGS WFS, one tip/tilt/focus NGS WFS, and two tip/tilt NGS WFS. For an MCAO configuration, the DM fitting FoV can be larger than the science FoV in order to sharpen diffraction limited TTF NGS. For an LTAO configuration, use \ref fit_oa to set only on axis DM fitting FoV. A GLAO system can be simulated by having a single DM but with a wide DM fitting FoV, as an alternative to setting <tt>recon.glao=1</tt> which averages WFS measurements before reconstruction. See \ref page33_example for more detailed explanations. @subsection sect-config-params Guide to the main parameters The table below lists the most frequently changed keys in each group. The defaults are in the listed file; the comment next to each key in that file describes it. <table class="markdownTable"> <tr class="markdownTableHead"> <th class="markdownTableHeadNone"> Group
File
Main keys
aper
sim.conf, examples/keck.conf
aper.d (outer and inner diameter, [11.0 2.4] from keck.conf), aper.fnamp (pupil amplitude map), aper.rotdeg
sim
sim.seeds, sim.end (500), sim.dt (1/600), sim.zadeg (30), sim.closeloop (1), sim.ephi (0.5, high order integrator gain), sim.alhi (extra latency), sim.eplo, sim.fcfocus, sim.idealtomo, sim.evlol, sim.skysim
atm
sim.conf, atm/atm_*.conf
atm.r0z (0.186 m in atm/atm_mk13n50p.conf), atm.L0 (30 m), atm.ht, atm.wt, atm.ws, atm.wddeg, atm.frozenflow, atm.size, atm.dx (1/64 m)
atmr
atmr.ht, atmr.wt (reconstructed layers, default follow atm), atmr.os
dm
sim.conf, dm_*.conf
dm.ht, dm.dx (0.5 m actuator pitch), dm.offset, dm.iac, dm.stroke, dm.actstuck, dm.actfloat
powfs
powfs_*.conf, powfs_common.conf
per WFS type: powfs.type (0: SHWFS, 1: pyramid), powfs.dsa, powfs.nwfs, powfs.hs, powfs.wvl, powfs.dtrat, powfs.siglev, powfs.bkgrnd, powfs.rne, powfs.noisy, powfs.phystep, powfs.phytype_recon, powfs.pixtheta, powfs.pixpsa, powfs.nearecon, powfs.neasim, powfs.fnllt
wfs
powfs_*.conf
per WFS: wfs.thetax, wfs.thetay (arcsec, concatenated for all WFS types), wfs.siglev
llt
laser launch telescope and sodium layer: llt.d, llt.ox, llt.oy, llt.fnprof, llt.fnrange
evl
sim.conf, evl_*.conf
evl.thetax, evl.thetay, evl.wt, evl.fov, evl.wvl, evl.psfmean, evl.psfisim, evl.psfsize, evl.psfgridsize
fit
recon.conf, fit_*.conf
fit.thetax, fit.thetay, fit.wt, fit.fov, fit.alg, fit.actslave
recon, tomo, lsr
recon.alg (0: MVR, 1: LSR), recon.split (1), recon.glao, recon.mvm, recon.modal, recon.psd, tomo.alg, tomo.precond, tomo.maxit, lsr.alg, lsr.actslave
ncpa
ncpa.surf, ncpa.calib (1), ncpa.thetax, ncpa.thetay
moao
moao.dx, moao.gdm, evl.moao, powfs.moao
gpu
gpu.wfs, gpu.evl, gpu.tomo, gpu.fit, gpu.lsr, gpu.psf, gpu.moao (see GPU selection)
save, plot, load, dbg
save.setup, save.run, save.all, save.extra, plot.all, plot.setup, plot.run, load.*
Values that have physical units use SI units unless noted otherwise. Angles such as wfs.thetax and evl.thetax are in arcsec. When evl.fov (or fit.fov) is not 0 or 1, evl.thetax and evl.thetay are given in units of evl.fov (the full width in arcsec) and scaled by it. Similarly, when powfs.astscale is not 0 or 1, wfs.thetax and wfs.thetay of that powfs are multiplied by it, so the asterism is given with a radius of 0.5 and powfs.astscale is its diameter in arcsec (maos checks the radius unless all WFS of the powfs are on axis).
To run predefined AO modes:
To run simulation for sample AO systems (in config/maos/examples):
The default case starts with default.conf, which includes mcao_lgs.conf. Put your own ~/.aos/default.conf to change the default (see Search path).
To customize the number of components
Change aperture
When aper.fnamp is given, its diameter must agree with aper.d (within 1 m), otherwise the amplitude map is not used. Set aper.d=[0] to take the diameter from the amplitude map.
Change turbulence
Configuring WFS. Adjust the number of elements depending on how many powfs are in use. A powfs is a type of WFS. Each type can have multiple WFS. The default configuration has three: LGS, TTF NGS, and TT NGS.
Adjust the controller
There are options to allow probing for error budget items, such as DM fitting error, tomography error, etc.
Note that the option sim.closeloop=0 atm.frozenflow=1 uses open loop correction (no servo lag) with frozen flow turbulence. The option sim.idealtomo=1 enables DM fitting directly from turbulence rather than from tomography output. For open loop simulations, truth WFS should not be included or should be disabled with sim.eptwfs=0, and non-iterative solvers (tomo.alg=0, fit.alg=0) usually work better than CG.
The following error budget items are computed:
Other keys in sim.conf that help isolate error terms:
We can optionally set up one or more static surfaces that cover science fields and/or wavefront sensors. Each surface file must contain a 2-d array of the OPD with a header specifying the following keys. If dx is missing, it is computed from D (the diameter) or assumed to be 1/64 m. If ox or oy is missing, the OPD is centered on the pupil.
Optionally, the header can also include the following keys to indicate its coverage
Use the write mex routine, writebin.m, or aolib.writebin to write the bin file:
Or simply use fits format. Put the list of surface file names in key ncpa.surf (surf is an accepted alias).
It is also possible to generate a surface on the fly with an inline description. The keys are r0 (in m) or rms (in nm), slope (PSD power law, default -11/3), L0 (default nx*dx), nx (default 2048), ny, dx (default 1/64), seed, ht, vx, vy, plus the coverage keys above. mode=n generates the Zernike mode n with the given rms instead.
The double quote is necessary here to group the single quoted entries together.
The amplitude map of the telescope can be specified with aper.fnamp=aper.bin with a similar data format, with OPD replaced by amplitude map between 0 and 1. By default, NCPA are calibrated (ncpa.calib=1 uses all DMs, 2 uses only the ground DM). Use ncpa.calib=0 to disable calibration.
The WFS configuration is mostly supplied in powfs, which applies to all the wfs belonging to this type. For wfs specific parameters, use wfs. If there is a single number in powfs.[key], it applies to all powfs. The following lists a few common options
WFS specific parameters usually include WFS coordinates
MAOS only computes RMS averaged wavefront errors by default, which are saved to Res_[seed].bin and Resp_[seed].bin. When desired, PSF computation can be enabled for some or all of the science evaluation directions (evl.psf). Modify evl.thetax , evl.thetay , and evl.wt to modify evaluation directions and relative weighting for field averaging. Notice that this will significantly slow down the simulation. Use the following parameters to enable PSF computation.
evl.psfsize and evl.psfgridsize take one value for all wavelengths or one value per wavelength in evl.wvl.
Due to pupil obscuration, there may be actuators that are not sensed by the WFS and therefore cannot be accurately reconstructed. The actuator coupling coefficient, computed using DM fitting ray tracing (HA in minimum variance reconstruction) or gradient interaction matrix (GA in least squares reconstruction), is used to determine how accurately an actuator is sensed/controlled. Activated by
lsr.actslave=1 #or 2, for lsr (default 1) fit.actslave=1 #or 2, for mvr (default 1)
actslave=1 enables implementation with threshold .actthres (lsr.actthres=0.7, fit.actthres=0.1 by default). When an actuator is outside of the pupil, its coupling coefficient is usually very small. When it is below the threshold, its value is slaved to its neighboring actuators.actslave=2 in addition enables implementation with threshold .actthres2 (lsr.actthres2=0.8, fit.actthres2=0.7). When an actuator is hidden by secondary mirror support struts, it may still have relatively strong coupling, but regions separated by the struts may have different piston values, the so called island effect. The mitigation method is to limit the value gap around such actuators whose coupling is below .actthres2.The sodium range variation is specified through the LLT configuration key llt.fnrange in llt_CL.conf or llt_SL.conf, which is selected by powfs.fnllt. To override it, use powfs0_llt.fnrange, where 0 is the index of the LGS powfs. The file should contain additional change (wrt fnprof) of sodium height in meters with dimension nx1 or nxnLGS where n can be less than, equal to or greater than the length of simulation and nLGS is the number of LGS in this powfs (6 for NFIRAOS).
The range variation is simulated by adding corresponding focus mode to LGS WFS wavefront.
The Rayleigh backscatter effect can be introduced using powfs.bkgrndfn=[filename,] which contains the background level for each pixel per frame, defined at sim.dtref. The file contains a cell array of nsa*1 (shared by all WFS) or nsa*nwfs, where nwfs is the number of wfs for this powfs, and each cell contains a npixpsax*npixpsay numerical array. The subapertures are ordered as in powfs0_saloc.bin. powfs.bkgrndfnc specifies the part that is subtracted (calibrated).
The sky coverage simulation is done in two parts. maos is run first to prepare NGS mode and WFS PSF time series:
maos -c nfiraos_lgs.conf skyc_10.conf -o 50p_za0_ncpa
The second step is to run skyc in the sky sim folder cd 50p_za0_ncpa/skysim skyc -d -o APD_JHKs_typeImr
The results are stored in Res1_1.bin for maos seed 1, skyc seed 1. There are skyc.nsky (500 by default) columns with the following row definitions:
maos simulations) error in NGS modesRes1_1_aster.bin.See Sky Coverage for details and Simulation Results for further explanation and results interpretation.