MAOS
Multithreaded Adaptive Optics Simulator
Loading...
Searching...
No Matches
Development

This section is for developers who want to understand, modify, or extend the code.

  • Fundamentals – C fundamentals, MAOS data types, the bin file format, and coding guidelines.
  • Architecture – library layering, the simulation flow, key data structures, threading, and how to add a parameter.
  • Debugging – debugging, memory checking, code coverage, and profiling.
  • Unit Test Status – results of the unit tests and code coverage.

The physics and numerical algorithms are described in Algorithms.

Build Directories

The code uses autotools and is always built out of the source tree. Several build directories configured with different options can coexist next to the source directory, for example:

cd maos #the source directory
./autogen.sh #needed for a fresh clone or after editing configure.ac or Makefile.am
mkdir ../optim && cd ../optim && ../maos/configure #optimized build
mkdir ../debug && cd ../debug && ../maos/configure --enable-debug #debug build
make -j8 #executables are placed in bin/ of the build directory

Useful configure options for development are --enable-debug, --enable-gcov (code coverage, implies --enable-debug), --disable-double (single precision), --enable-release (portable build without the scheduler), and CC=clang++ (compile the C code as C++). See Compile the Code for all the options.

Unit Tests

The unit tests are in test/cmocka_*.c and use the CMocka framework. Each test includes test/unittest.h, which provides helpers such as a double precision assert_float_equal(). Tests must not read or write temporary files: generate the input data in memory and check the results with assertions. To add a test program, add it to bin_PROGRAMS in test/Makefile.am.

Run the tests from the build directory:

make check #all tests (requires cmocka)
make -C test check TESTS=cmocka_mat #a single test
test/cmocka_mat #run a test program directly

Each run updates the status report docs/unittest_status.md in the build directory. make doc runs the unit tests, generates the report (with the line coverage of sys, math, and lib when configured with --enable-gcov), and builds the manual with doxygen, where the report replaces the placeholder Unit Test Status.

End-to-end Regression

scripts/maos_check.sh runs maos for 100 steps in many configurations (NGS and LGS SCAO, GLAO, LTAO, MOAO, MCAO with various tomography algorithms, pyramid WFS, NCPA calibration, and others) and compares the mean wavefront error with reference values. Run it from the bin folder of a build directory:

cd ../optim/bin
../../maos/scripts/maos_check.sh 5 #5 m telescope
../../maos/scripts/maos_check.sh 5 -g-1 #force CPU

The first argument is the telescope diameter: 30 uses tmt.conf, 10 uses keck.conf, and other values set aper.d. The remaining arguments are passed to maos. A configuration fails if the result differs from the reference by more than about 10%; the script exits with the number of failures. The reference values are the REF_GPU and REF_CPU arrays in the script, one pair per diameter. When a change intentionally alters the results, update these arrays: each run appends a line with the new REF_GPU=(...) or REF_CPU=(...) array to maos_check.ref in the current directory, which can be copied into the script. The results and logs are saved to maos_check_*.* files.

Continuous Integration

The GitHub workflows in .github/workflows run on every push and pull request:

  • linux.yml: builds with gcc (--enable-release with CUDA, without a GPU so that the simulation runs on the CPU), runs make check and make doc, publishes the documentation to the gh-pages branch, builds with clang and runs make check, and runs scripts/maos_check.sh 5.
  • macos.yml: builds on macOS with --enable-release and runs make check.
  • macos-cpp.yml: builds on macOS with CC=clang++ and runs make check. The code must therefore also compile as C++.

Contribution Checklist

  • Follow the guidelines in Guidelines.
  • Add or update unit tests for changes in sys, math, and lib, and run make check.
  • Run scripts/maos_check.sh for changes that affect the simulation, and update its reference values if the change is intended to alter the results.
  • Document new parameters in the .conf files (see Adding a Parameter) and new functions with doxygen comments. make doc builds the manual.