Getting Started
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.
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.