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}
}