Getting Started

alamo

Alamo is a high-performance scientific code that uses block-structured adaptive mesh refinement to solve such problems as: the ignition and burn of solid rocket propellant, plasticity, damage and fracture in materials undergoing loading, and the interaction of compressible flow with eroding solid materials. Alamo is powered by AMReX, and provides a set of unique methods, models, and algorithms that enable it to solve solid-mechanics problems (coupled to other physical behavior such as fluid flow or thermal diffusion) using the power of block-structured adaptive mesh refinement.

Alamo documentation

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, 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 is routinely run and tested on Ubuntu and MacOS. You can use the System Install Scripts to install all necessary dependencies for your system.

Setting default MPI

It may be necessary to use a specific MPI distribution. On Ubuntu, you can change the distribution with the following:

$> sudo update-alternatives --config mpi

There are 2 choices for the alternative mpi (providing /usr/bin/mpicc).

  Selection    Path                    Priority   Status
------------------------------------------------------------
* 0            /usr/bin/mpicc.openmpi   50        auto mode
  1            /usr/bin/mpicc.mpich     40        manual mode
  2            /usr/bin/mpicc.openmpi   50        manual mode

Press <enter> to keep the current choice[*], or type selection number:

Do the same thing for mpirun.

$> sudo update-alternatives --config mpirun

Remember to run make realclean every time you switch mpi versions.

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.

Unit 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

Regression Testing

Alamo contains several Regression Tests that are routinely tested and checked with CI. These are checked for Performance and Code Coverage

Citing Alamo

To acknowledge alamo in your publications, please cite the following article.

@article{runnels2025alamo,
  title={The Alamo multiphysics solver for phase field simulations with strong-form mechanics and block structured adaptive mesh refinement},
  author={Runnels, Brandon and Agrawal, Vinamra and Meier, Maycon},
  journal={arXiv preprint arXiv:2503.08917},
  year={2025}
}

System Install Scripts

The Alamo system install scripts automate the setup of all necessary dependencies for running Alamo on supported platforms, including Ubuntu, MacOS, and Windows. The scripts are actively maintained in the repository under .github/workflows and leverage GitHub Actions, a continuous integration (CI) service that automatically builds, tests, and deploys code whenever changes are pushed. For more information about GitHub Actions, see GitHub Actions.

Every commit to the development and master branches triggers these install scripts via GitHub Actions, ensuring that installation works correctly across all supported platforms and that any issues introduced by recent changes are immediately detected. Users can check the current status of these workflows on the Alamo GitHub Actions page. Each page in this documentation also includes status badges that indicate whether the latest workflow for that platform and branch completed successfully, allowing users to quickly verify the health of the scripts.

The scripts themselves include platform-specific workflows as well as shared workflows for common setup tasks, and can be inspected or modified if custom behavior is needed.