Getting Started

Note: this README page is also the Doxygen main page, the Github readme page, and the Docs main page. You can view it by running make docs in the root directory, then opening docs/doxygen/html/index.html or docs/build/html/index.html in a web browser.

Downloading Alamo

Download alamo using git:

git clone git@github.com:solidsgroup/alamo.git

If you do not have a Github account and/or you have not uploaded your public SSH key, this will probably throw an error. You can download alamo using HTTPS instead,

https://github.com/solidsuccs/alamo.git

Note, however, that you will not be able to push anything using HTTPS authentication. The master branch is the most stable and is what is checked out by default. The develompent branch is generally stable, and includes the latest functionality. To switch to development, in the alamo directory,

git checkout development

Installing dependencies

Alamo depends primarily on AMReX, but has some of its own dependencies, such as Eigen. The two officially supported Linux distributions are currently: the latest version of Ubuntu, and Ubuntu 20.04. (This is subject to change). If you are using Ubuntu (or a debian-based distribution) you can install all necessary dependencies by running the dependencies script:

sudo bash .github/workflows/dependencies.sh

If you are using a non-debian based system such as RedHat, you can install the corresponding packages in dependencies.sh. Windows and Mac OS are not supported.

Configuring

To compile alamo, you must first run the configure script. This is done simply by running the following in the alamo directory (note that AMReX download is triggered by this command, so it may take a couple minutes to complete depending on your internet connection)

./configure

By default, alamo will configure in 3D production mode. To compile in 2D debug mode,

./configure --dim=2 --debug

There are multiple compilation options available for Alamo, and they must all be specified at configure time. For a complete listing of the Alamo configuration options, type

./configure --help

Note

The configure script produces output designed to assist in determining compile issues with Alamo. Whenever you request help with alamo, please always include the complete output of the configure script.

Compiling

Once you have configured Alamo, compile it by

make

If you are on a platform with multiple cores, you can compile in parallel (for instance, with 4 cores) with

make -j4

The alamo exectuable will be stored in ./bin/ and name according to the options specified at configure time. For instance, if you are using GCC to make Alamo in 2D using debug mode, the alamo executable will be ./bin/alamo-2d-debug-g++. You can work with multiple versions of Alamo at the same time without having to re-compile the entire code base. All you need to do is re-run the configure script, and previous versions of Alamo and AMReX will be saved automatically.

Warning

There is an issue with GNU Make that can cause I/O errors during parallel builds. You may get the following error:

make[1]: write error: stdout

To continue the build, just issue the make command again and it should continue normally. You can also add the --output-sync=target option which may help eliminate the issue.

Testing

Upon successful compilation, run tests by

make test

This will run the unit tests and regression tests for all compiled production versions of Alamo. If you have only run in 2D, only 2D tests will be generated. If you are a developer and you are preparing to merge your branch into development, you should perform a complete test via

./configure --dim=2
make
./configure --dim=3
make
make test

For a full description of the Alamo regression test system, please see

Common Error Messages

The following are some common error messages and problems encountered:

  • MLLinOp: grids not coarsenable between AMR levels This is a conflict in the multigrid solver because the grid size is not a power of 2. Solve by changing the domain dimensions (amr.n_cell) so that they are powers of two.

  • static_cast<long>(i) < this->size() failed One common reason this happens is if Dirichlet/Neumann boundaries are specified but no boundary values are provided.

  • error: lvalue required as left operand of assignment This can happen when using the () operator with a Isotropic Matrix4-type object. Because this data structure only stores two constants, it is not possible to define any of the values using indices. (Similarly, you cannot set an Isotropic 4-matrix to a Cubic 4-matrix since the Cubic matrix has lower symmetry). If you get this error, you should use a lower-symmetry 4-matrix.

  • Inconsistent box arrays This is known to happen when using an Operator::Elastic inside an Integrator, e.g. in TimeStepBegin. Typically this happens when the Elastic operator is not initialized within the routine in which it is used - i.e.e if it is declared as a member variable inside the Integrator - derived class. (The reason is that there are AMReX-specific functions that only get called by the constructor.) The fix is to initialize the operator object inside the routine in which it is used - either by making the member variable a pointer and using the new keyword, or by just creating the variable inside the function.

Generating this documentation

Generating documentation requires the following packages:

  • Doxygen (on Ubuntu: sudo apt install doxygen)

  • Sphinx (on Ubuntu: sudo apt install python3-sphinx)

  • Breathe (on Ubuntu: sudo apt install python3-breathe)

  • M2R (on Ubuntu: python3 -m pip install m2r)

  • RTD theme (on Ubuntu: python3 -m pip install sphinx_rtd_theme)

  • GraphViz (on Ubuntu: sudo apt install graphviz)

To generate the documentation, type

make docs

(You do not need to run ./configure before generating documentation.) Documentation will be generated in docs/build/html and can be viewed using a browser.

Compiling on STAMPEDE2

To compile on STAMPEDE2 you must first load the following modules:

module load python3

This will load Python3. The following configure script is recommended:

./configure --build-amrex --get-eigen --comp=icc

where other arguments (e.g. --dim=2) can be added as necessary. Finally, make with

make

Warning

Remember to use good stewardship when compiling and running on a supercomputer. (For instance, do not use make -j16 to build.) Be sure to consult the Stampede2 user guide: https://portal.tacc.utexas.edu/user-guides/stampede2; along with https://solids.uccs.edu/resources/xsede.php for general Stampede2/XSEDE instructions.