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.

Quick Start:

git clone https://github.com/solidsuccs/alamo.git
cd alamo
./configure --build-amrex --get-eigen
make

Compiling Alamo

This section describes how to compile and install Alamo and its dependencies.

Installing Eigen: You need to have the Eigen3 library installed. You can do this in one of two ways:

1. Install using your package manager. In Ubuntu, you can install using

   sudo apt install libeigen3-dev
   

2. Use the --get-eigen flag in the ./configure script. This will download Eigen into the root alamo directory.

3. Download eigen3 from the website http://eigen.tuxfamily.org. Store it in a directory (e.g. /home/myusername/eigen3/).

Cloning: Clone the repository using the command

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

Configuring: Navigate to the alamo directory, and run the configure script:

./configure

This will download and configure the AMReX repository for use by Alamo. If you are compiling in 2D, add the argument --dim 2 to the command. For a full list of options run ./configure --help.

Note

If amrex is installed and built elsewhere, you can just add --amrex /path/to/amrex to your configure command.

Note

If you used option (3) to obtain Eigen, you need to add --eigen /path/to/eigen to your configure command:

Making: To build the code:

make

This will automatically build the appropriate version of AMReX as well as Alamo. To build in parallel, add the -jN argument where N is the number of processors.

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.

Python Interface See :ref:`building-python`

Testing

Upon successful compilation, run tests by typing

./bin/test-3d-debug-g++

The output will indicate whether the tests pass or fail. If you are committing changes, you should always make sure the tests pass in 2 and 3 dimensions before committing.

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.