Added linux build and pinned tpl clones to working SHAs in darwin and linux builds.

CMakeLists.txt

@@ -129,7 +129,7 @@ add_subdirectory(src)
 # includes all third party libraries 
 add_library(allium ${SOURCES} ${HEADERS})
 target_link_libraries(allium PUBLIC ${MFEM_LIBRARIES} igraph::igraph 
-	std::mdspan yaml-cpp::yaml-cpp ${LUA_LIBRARIES} sol2::sol2 OpenMP::OpenMP_CXX)
+	mdspan::mdspan yaml-cpp::yaml-cpp ${LUA_LIBRARIES} sol2::sol2 OpenMP::OpenMP_CXX)
 target_include_directories(allium PUBLIC ${MFEM_INCLUDE_DIRS} 
 	${CMAKE_BINARY_DIR}/config ${PROJECT_SOURCE_DIR}/src ${LUA_INCLUDE_DIR})
 
@@ -206,4 +206,4 @@ configure_package_config_file(
 	"${PROJECT_SOURCE_DIR}/data/${PROJECT_NAME}-config.cmake.in"
 	"${PROJECT_BINARY_DIR}/${PROJECT_NAME}-config.cmake"
 	INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}-${PROJECT_VERSION}
-)
+)

README.md

@@ -1,23 +1,73 @@
-# Overview
-* `exe/`:
-	* `chive.cpp`: driver for steady-state, mono-energetic, neutral particle transport supporting 
-		* P1, Local Discontinuous Galerkin, and Modified Interior Penalty diffusion synthetic acceleration preconditioners for fixed-point and Krylov solvers
-		* Independent Local Discontinuous Galerkin Second Moment Method 
-		* arbitrary material descriptions and mesh composition 
-		* Lua input system 
-		* parallel decomposition with full upwind sweep 
-		* output is YAML-parsable 
-	* `scallion.cpp`: gray thermal radiative transfer 
-		* backward Euler time integration 
-		* Picard, Newton, one Newton algorithms 
-	* `green.cpp`: gray thermal radiative transfer with consistent second moment methods
-	* `spring.cpp`: gray diffusion thermal radiative transfer 
-	* `garlic.cpp`: Lagrange hydro + radiation diffusion (under development)
-* `inputs/`: example inputs for `chive` and `scallion` 
-* `tests/`: collection of tests using the GoogleTest framework. Run with `ctest`. 
-* `scripts/`: post-processing python files, build scripts 
+# allium: a high-performance library for deterministic thermal radiative transfer
+*allium* is a software framework designed to facilitate the development and analysis of numerical algorithms relevant to radiation transport. Built on top of the MFEM finite element library, this package integrates a range of third-party dependencies, such as hypre, SUNDIALS, igraph, Lua, YAML, and GoogleTest, to provide an agile environment capable of rapid prototyping. The package is designed to scale well on massively parallel, CPU-based computer architectures through the utilization of MPI, OpenMP, and the high-performance implementations provided by the dependent packages. This allows testing novel algorithms at a computational scale not typically investigated in traditional academic literature. *allium* is comprised of a robust build system, core source code implementing both established and novel numerical methods, a suite of drivers that accept Lua-based input files and exercise the solution algorithms, and python scripts that facilitate the processing of the output from the drivers for publication in journal articles. In addition, a comprehensive set of tests ensures reliability and supports ongoing research and application development. Through its modular design and use of high-quality third party libraries, this package is uniquely suited to support academic research into the mathematical algorithms that underpin the simulation of radiation transport. 
+<div align="center">
+  <img src="doc/star.png" width="400"/>
+  <br/>
+  <em>Material temperature of Marshak problem on a star-shaped domain</em>
+</div>
+
+# Project Overview
+*allium* is a software framework providing
+* CMake build system
+* suite of unit and integral tests driven by CTest and GoogleTest 
+* Lua-based input system 
+* YAML-compatible terminal output system 
+* upwind Discontinuous Galerkin transport discretization with **MPI-parallel fully upwind sweep** and OpenMP threading 
+* a variety of diffusion-based acceleration and preconditioning techniques 
+* support for fixed-point, Krylov solvers, and advanced nonlinear solvers 
+* thermal radiative transfer physics components such as opacities, Planck emission, etc  
+* support for arbitrary meshes in 1, 2, and 3 dimensions 
+* visualization via VisIt, Paraview, and GLVis 
+
+This package has been designed under the following design philosophies: 
+* separation of concerns: the library is designed so that its components, such as input/output, data structures, and computations, are weakly coupled. 
+* single responsibility principle: code units (classes, free functions, etc) do only one of input/output, storage of data, or computations, further separating concerns and reducing edge cases.  
+* dependency injection/inversion: objects accept fully configured dependencies enabling access to low-level configuration without exposing low-level details. 
+* composition over inheritance: functionality is assembled from small, focused components. Modularity is achieved through shallow inheritance hierarchies from simple and generic base classes. 
+
+These design principles have resulted in a focused core library where the user has the control to compose core capabilities together to achieve a wide spectrum of functionality. 
+This approach has allowed significant control of and access to low-level details important for academic research while keeping the scope creep of a globally accessible design at bay. 
+In addition, weakly coupling components has allowed testing components independently and enables the ability to quickly create new physics drivers. 
+In general, *allium* has been designed to have all input/output, configuration, management of data lifetime, and execution flow within the `main` of the driver allowing the core library to be simple and extensible. 
+This design allows unexpected and out-of-scope concepts to be implemented with changes primarily restricted to the `main` function, reducing implementation burden. 
+
+## Drivers 
+Physics capabilities are organized into a suite of drivers in the `exe/` directory. Example inputs and tests for each driver are provided in the correspondingly named directory in `inputs/` and `tests/`, respectively. Drivers are named after members of the allium genus. 
+
+### chive
+`chive` is a driver for steady-state, one-group, fixed-source transport problems often used as a proxy application for thermal radiative transfer. `chive` supports a variety of acceleration and preconditioning techniques including 
+* "fully consistent" P1 diffusion synthetic acceleration (DSA)
+* Local Discontinuous Galerkin (LDG) DSA 
+* Modified Interior Penalty (MIP) DSA 
+* Interior Penalty and LDG-based Second Moment Methods (SMMs)
+
+Both fixed-point iteration and Krylov-based solvers are available. 
+
+### scallion 
+`scallion` is a driver for multigroup, time-dependent thermal radiative transfer. Backward Euler time integration is used. `scallion` implements Picard, linearized, and full Newton solution algorithms. The linearized and Newton algorithms can be solved with Krylov or fixed-point iteration preconditioned with a subset of the algorithms implemented in `chive`. `scallion` supports
+* trace plots (output solution at a point in space plotted over time)
+* restarting from a previous simulation 
+* analytic and tabular opacity data 
+* implicit and explicit treatment of opacities 
+* variable time steps defined by a function or table
+
+### green 
+`green` is a variant of `scallion` that uses the Second Moment Method (SMM) to solve the equations of thermal radiative transfer. Where `scallion` evolves the intensity and material temperature, `green` evolves the intensity, low-order moments, and material temperature. This subtle difference motivated separating the two sets of methods into separate drivers. `green` is intended to parallel `scallion` and is thus compatible with all inputs to `scallion`. 
+
+### ramp 
+`ramp` is simplification of `green` which only solves the low-order system (e.g. radiation diffusion). 
+
+## Scripts
+Post-processing scripts are provided in `scripts/`
+* `inspect`: opens a YAML-compatible terminal output file and indexes into the YAML tree 
+* `gridfunction.py`: class for loading and plotting 1D `mfem::GridFunction` 
+* `plot_tracer.py`: plots tracers over time 
+* `plot_visit.py`: uses `gridfunction.py` to plot MFEM's VisIt output format over time 
+* `darwin/build.sh`: example build script (including all third party libraries) for linux-based systems 
 
 # Building 
+An example build script is provided in [scripts/darwin/build.sh](scripts/darwin/build.sh) for linux-based system. MFEM handles the majority of the often troublesome scientific software dependencies. Thus, please use MFEM's documentation as a starting point. 
+
 ## Required Dependencies 
 * [MFEM](https://github.com/mfem/mfem) built with 
 	* MPI
@@ -38,7 +88,19 @@
 	* [GSLIB](https://github.com/Nek5000/gslib)
 * [GoogleTest](https://github.com/google/googletest.git) 
 
-## Installing 
-### Darwin 
-Steps to build on Darwin are documented in `scripts/darwin/build.sh`. From the root directory run `source scripts/darwin/build.sh`. By default this builds all dependencies in the directory `tpl` though this behavior can be changed. 
-An example module file is provided in `scripts/darwin/module_file.lua`. Change the path to allium's build directory and copy into a place where Lmod knows to look for module files. 
+# Authors
+*allium* was written by [Samuel Olivier](https://samolivier.net) while a Nicholas C. Metropolis postdoctoral fellow at the Los Alamos National Laboratory. 
+
+# Peer-Reviewed Journal Articles that Use allium
+1. [Consistent Second Moment Methods with Scalable Linear Solvers for Radiation Transport](https://arxiv.org/abs/2404.17473)
+2. [A Comparison of the Consistent and Independent Second Moment Methods Applied to Thermal Radiative Transfer](https://arxiv.org/abs/2504.21784)
+3. [Implicit Opacities in Thermal Radiative Transfer](https://samolivier.net/wp-content/uploads/pres/mc25_paper.pdf)
+4. [Preconditioning transformations of adjoint systems for evolution equations](https://arxiv.org/abs/2505.21705)
+
+# Release 
+* [GPL 2.0 license](LICENSE.md)
+* LANL code designation: O5022
+
+© 2026. Triad National Security, LLC. All rights reserved.
+
+This program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare. derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.

scripts/darwin/build.sh

@@ -6,6 +6,10 @@
 # NOTE: compilation is done in parallel so allocate 
 # a node with `salloc` first 
 
+## ON OTHER HPC PLATFORMS, COMMENT OUT THE MODULE LOAD COMMAND BELOW AND LOAD 
+## THE EQUIVALENT MODULES ON YOUR SYSTEM.  THIS SCRIPT HAS BEEN TESTED ON
+## OTHER NNSA CPU BASED SYSTEMS
+
 # number of processors to use with make 
 nproc=36 
 ROOT=$(pwd)
@@ -35,9 +39,22 @@ git clone https://github.com/google/googletest.git
 git clone https://github.com/LLNL/sundials.git 
 git clone https://github.com/Nek5000/gslib
 
+# pin all repos to specific SHAs for reproducibility
+git -C hypre        checkout 7e7fc8ce09153c60ae538a52a5f870f93b9608ca
+git -C sundials     checkout aaeab8d907c6b7dfca86041401fdc1448f35f826
+git -C igraph       checkout beebfcdcd707f50a31cf8eb3568cf09f8b7baf54
+git -C mfem         checkout 171eeb403f8d8deadfbd64d547de43c8705e616c
+git -C superlu_dist checkout 4ae28e6f6d38f4f1fd3da88bd040f756d1275844
+git -C libunwind    checkout c19e28b0e8682155482d937131fd5b1553044a66
+git -C mdspan       checkout 80fc772eb812b45097c28fc0a46d8ff006138d69
+git -C yaml-cpp     checkout 8bcadb1509e63248e79c6dc09928f95cfae02b74
+git -C sol2         checkout c1f95a773c6f8f4fde8ca3efe872e7286afe4444
+git -C googletest   checkout 94be250af7e14c58dcbf476972d2d7141551ff67
+git -C gslib        checkout 95acf5b42301d6cb48fda88d662f1d784b863089
+git -C tpls         checkout 486dd7171e67629fc85393479f710e821e0e8b77
+
 # --- build hypre --- 
 cd ${TPL}/hypre/
-git checkout v2.31.0
 cd src/cmbuild
 cmake .. -DCMAKE_BUILD_TYPE=Release
 # installs into hypre/src/hypre/lib64 
@@ -71,7 +88,6 @@ make install -j${nproc}
 
 # --- sundials --- 
 cd ${TPL}/sundials
-git checkout v6.7.0
 mkdir build install 
 cd build 
 cmake .. \
@@ -85,8 +101,7 @@ cd ${TPL}/gslib
 make CC=mpicc 
 
 # --- build mfem --- 
-cd ${TPL}/mfem
-git checkout smsolivier/ldg 
+cd ${TPL}/mfem 
 mkdir build install 
 cd build
 cmake .. \
@@ -180,4 +195,4 @@ export OMP_NUM_THREADS=1
 # run tests in parallel 
 # separating serial vs parallel to not 
 # over prescribe threads 
-ctest -j ${nproc} -L serial && ctest -j 4 -L parallel 
+ctest -j ${nproc} -L serial && ctest -j 4 -L parallel

scripts/linux/build.sh

@@ -0,0 +1,201 @@
+#!/bin/bash
+
+# script to download and install all third party libraries (TPLs)
+# downloads TPLs into the directory specified by TPL variable
+# designed to work on Ubuntu Linux
+# NOTE: compilation is done in parallel so allocate
+# a node with `salloc` first
+
+# number of processors to use with make
+nproc=1
+ROOT=$(pwd)
+# where to download and build all third party libraries
+# this location can be external to allium
+TPL=${ROOT}/tpl
+
+# --- install system prerequisites (Ubuntu) ---
+# --- install system prerequisites (Ubuntu) ---
+sudo apt-get update
+sudo apt-get install -y \
+  build-essential cmake git \
+  mpich libmpich-dev \
+  autoconf automake libtool \
+  liblapack-dev libblas-dev \
+  zlib1g-dev \
+  lua5.3 liblua5.3-dev
+
+# architecture string used in ParMETIS build output paths
+ARCH=$(uname -m)
+
+# create directory for tpls
+mkdir -p ${TPL}
+
+# --- clone dependencies into project source ---
+cd ${TPL}
+
+git clone https://github.com/mfem/mfem.git
+git clone https://github.com/hypre-space/hypre.git
+git clone https://github.com/mfem/tpls.git
+git clone https://github.com/libunwind/libunwind.git
+git clone https://github.com/xiaoyeli/superlu_dist.git
+git clone https://github.com/igraph/igraph.git
+git clone https://github.com/kokkos/mdspan.git
+git clone https://github.com/jbeder/yaml-cpp.git
+git clone https://github.com/ThePhD/sol2.git
+git clone https://github.com/google/googletest.git
+git clone https://github.com/LLNL/sundials.git
+git clone https://github.com/Nek5000/gslib
+
+git -C hypre        checkout 7e7fc8ce09153c60ae538a52a5f870f93b9608ca
+git -C sundials     checkout aaeab8d907c6b7dfca86041401fdc1448f35f826
+git -C igraph       checkout beebfcdcd707f50a31cf8eb3568cf09f8b7baf54
+git -C mfem         checkout 171eeb403f8d8deadfbd64d547de43c8705e616c
+git -C superlu_dist checkout 4ae28e6f6d38f4f1fd3da88bd040f756d1275844
+git -C libunwind    checkout c19e28b0e8682155482d937131fd5b1553044a66
+git -C mdspan       checkout 80fc772eb812b45097c28fc0a46d8ff006138d69
+git -C yaml-cpp     checkout 8bcadb1509e63248e79c6dc09928f95cfae02b74
+git -C sol2         checkout c1f95a773c6f8f4fde8ca3efe872e7286afe4444
+git -C googletest   checkout 94be250af7e14c58dcbf476972d2d7141551ff67
+git -C gslib        checkout 95acf5b42301d6cb48fda88d662f1d784b863089
+git -C tpls checkout 486dd7171e67629fc85393479f710e821e0e8b77
+
+# --- build hypre ---
+cd ${TPL}/hypre/
+cd src/cmbuild
+cmake .. -DCMAKE_BUILD_TYPE=Release
+# installs into hypre/src/hypre/lib
+make install -j${nproc}
+
+# --- build parmetis ---
+cd ${TPL}
+# unpack from mfem tpl repo
+tar -xvf tpls/parmetis-4.0.3.tar.gz
+PMROOT=${TPL}/parmetis-4.0.3/
+cd ${PMROOT}
+make config prefix=install
+make install -j${nproc}
+
+# --- build libunwind ---
+cd ${TPL}/libunwind
+autoreconf -i
+./configure --prefix=$(pwd)/install
+make install -j${nproc}
+
+# --- build superlu ---
+cd ${TPL}/superlu_dist
+mkdir build install
+cd build
+cmake .. \
+ -DCMAKE_BUILD_TYPE=Release \
+ -DCMAKE_INSTALL_PREFIX=../install \
+ -DTPL_PARMETIS_INCLUDE_DIRS="${PMROOT}/include;${PMROOT}/metis/include/" \
+ -DTPL_PARMETIS_LIBRARIES="${PMROOT}/build/Linux-${ARCH}/libparmetis/libparmetis.a;${PMROOT}/build/Linux-${ARCH}/libmetis/libmetis.a"
+make install -j${nproc}
+
+# --- sundials ---
+cd ${TPL}/sundials
+mkdir build install
+cd build
+cmake .. \
+ -DENABLE_MPI=ON \
+ -DCMAKE_BUILD_TYPE=Release \
+ -DCMAKE_INSTALL_PREFIX=../install
+make install -j${nproc}
+
+# --- gslib ---
+cd ${TPL}/gslib
+make CC=mpicc
+
+# --- build mfem ---
+cd ${TPL}/mfem
+mkdir build install
+cd build
+cmake .. \
+ -DMFEM_USE_MPI=TRUE \
+ -DHYPRE_DIR=${TPL}/hypre/src/hypre/ \
+ -DMETIS_DIR=${PMROOT}/build/Linux-${ARCH}/libmetis \
+ -DMETIS_INCLUDE_DIR=${PMROOT}/metis/include \
+ -DMFEM_USE_LIBUNWIND=TRUE \
+ -DLIBUNWIND_DIR=${TPL}/libunwind/install \
+ -DMFEM_USE_SUPERLU=TRUE \
+ -DSuperLUDist_DIR=${TPL}/superlu_dist/install \
+ -DParMETIS_DIR=${PMROOT}/build/Linux-${ARCH}/libparmetis/ \
+ -DParMETIS_INCLUDE_DIR=${PMROOT}/include/ \
+ -DMFEM_USE_SUNDIALS=TRUE \
+ -DSUNDIALS_DIR=${TPL}/sundials/install/ \
+ -DMFEM_USE_GSLIB=ON \
+ -DGSLIB_DIR=${TPL}/gslib/build \
+ -DMFEM_USE_OPENMP=TRUE \
+ -DCMAKE_INSTALL_PREFIX=../install \
+ -DCMAKE_BUILD_TYPE=Release
+make install -j${nproc}
+# test linker by building examples
+make examples -j${nproc}
+
+# --- build igraph ---
+cd ${TPL}/igraph
+mkdir build install
+cd build
+cmake .. \
+ -DCMAKE_BUILD_TYPE=Release \
+ -DCMAKE_INSTALL_PREFIX=../install
+make install -j${nproc}
+
+# --- mdspan ---
+cd ${TPL}/mdspan
+mkdir build install
+cd build
+cmake .. \
+ -DCMAKE_INSTALL_PREFIX=../install
+make install
+
+# --- yaml ---
+cd ${TPL}/yaml-cpp
+mkdir build install
+cd build
+cmake .. \
+ -DCMAKE_BUILD_TYPE=Release \
+ -DCMAKE_INSTALL_PREFIX=../install
+make install
+
+# --- sol2 ---
+cd ${TPL}/sol2
+mkdir build install
+cd build
+cmake .. \
+ -DCMAKE_BUILD_TYPE=Release \
+ -DCMAKE_INSTALL_PREFIX=../install \
+ -DSOL2_BUILD_LUA=FALSE \
+ -DSOL2_LUA_VERSION=5.3
+make install
+
+# --- googletest ---
+cd ${TPL}/googletest
+mkdir build install
+cd build
+cmake .. \
+ -DCMAKE_INSTALL_PREFIX=../install \
+ -DCMAKE_BUILD_TYPE=Release
+make install
+
+# --- finally build allium ---
+cd ${ROOT}
+mkdir build
+cd build
+cmake .. \
+ -Dmfem_DIR=${TPL}/mfem/install/lib/cmake/mfem \
+ -Digraph_DIR=${TPL}/igraph/install/lib/cmake/igraph \
+ -Dmdspan_DIR=${TPL}/mdspan/install/lib/cmake/mdspan \
+ -Dyaml-cpp_DIR=${TPL}/yaml-cpp/install/lib/cmake/yaml-cpp \
+ -Dsol2_DIR=${TPL}/sol2/install/share/cmake/sol2 \
+ -DGTest_ROOT=${TPL}/googletest/install/lib/cmake/GTest \
+ -DENABLE_UNIT_TESTS=TRUE \
+ -DENABLE_CHIVE_TESTS=TRUE \
+ -DCMAKE_BUILD_TYPE=Release
+make -j${nproc}
+# -- run tests --
+# explicitly set threads so SuperLU doesn't slow to a crawl
+export OMP_NUM_THREADS=1
+# run tests in parallel
+# separating serial vs parallel to not over-prescribe threads
+ctest -j ${nproc} -L serial && ctest -j 4 -L parallel