Skip to content

LBL-EESA/alquimia-dev

Repository files navigation

Status

Description

Alquimia provides a generic interface between flow and transport simulators (drivers) and biogeochemical reaction capabilities (engines). Alquimia consists of two parts: an application programming interface, API, and a wrapper library. The API describes in detail how information is exchanged between the driver and the engine. This includes the function call signatures and data structures required for implementing alquimia in a mixed language (C/C++/Fortran) programming environment. The library is an implementation of the documented API, providing an interface into the biogeochemistry routines supplied by other codes: Alquimia does not do any geochemical calculations. Version 1.x provides interfaces to the open source codes (BSD) CrunchFlow/CrunchTope and (LGPL) PFLOTRAN. Version 1.x meets the policies set forth by (and is part of) the Extreme-scale Scientific Software Development Kit, xSDK version 0.6.0.

Originally developed as part of the DOE ASCEM project, it is now mantained and developed under the U.S. Department of Energy's IDEAS Watersheds project

Currently, the geochemical engines suported are CrunchFlow and PFLOTRAN.

Legal

Alquimia Copyright (c) 2013-2021, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.

If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Intellectual Property Office at IPO@lbl.gov.

NOTICE. This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit others to do so.

Citing Alquimia

Andre, B., Molins, S., Johnson, J., and Steefel, C.I. Alquimia. Computer Software. https://github.com/LBL-EESA/alquimia-dev. USDOE. 01 Aug. 2013. Web. doi:10.11578/dc.20210416.49.

Building

You'll need working C and Fortran compilers and CMake installed on your system. For UNIX and UNIX-like operating systems, you'll need GNU Make or another capable version of Make installed as well. To build on Windows, you'll need some recent version of Visual Studio and a decent Fortran compiler such as Intel's.

Required packages and versions

Currently, to be built, Alquimia requires PETSc and at least one of the two geochemical engines, either PFLOTRAN or CrunchFlow.

Alquimia is part of the Extreme-scale Scientific Software Development Kit (xSDK), along with PETSc and PFLOTRAN. xSDK releases ensure that certain version of these software packages will build together. In addition to the instructions that follow, note that Alquimia -like the other xSDK packages- may also be built using the package manager Spack.

To build Alquimia, use the version of the packages in the latest release of the xSDK to ensure compatibility. Currently:

  Version
xSDK 1.0.0
Alquimia 1.1.0
PETSc 3.20.0
PFLOTRAN 5.0.0
CrunchFlow dev

CrunchFlow is currently not part of the xSDK but generally the development branch in CrunchFlow will work.

PETSc

PETSc is a suite of data structures and routines for the scalable (parallel) solution of scientific applications modeled by partial differential equations. The PETSc requirement in Alquimia stems from the fact that both engines, PFLOTRAN or CrunchFlow, require PETSc.

To download and install PETSc, please follow the instructions in petsc.org or in pflotran.org. At the end of the installation, the PETSC_DIR and PETSC_ARCH environment variables must set properly.

PFLOTRAN engine

PFLOTRAN is an open source, state-of-the-art massively parallel subsurface flow and reactive transport code. Alquimia provides access to the geochemical capabilities of PFLOTRAN; more speficically, the geochemical capabilities available under the operator splitting mode.

Follow the instruction to download and build PFLOTRAN found here, Do not build the pflotran target rather pflotran_rxn:

cd $PFLOTRAN_DIR/src/pflotran
make pflotran_rxn

To build PFLOTRAN on Windows, see the instructions here.

CrunchFlow engine

CrunchFlow is a powerful software package for simulating reactive transport developed by Carl Steefel and co-workers and applied since 1988 to a variety of problems in the earth and environmental sciences. Alquimia provides access to the geochemical capabilities of CrunchFlow; more speficically, the geochemical capabilities available under the operator splitting mode.

Download the master branch of CrunchFlow, apply the makefile patch and build the libcrunchchem.a target:

cd $CRUNCHFLOW_DIR/source
git apply MakefileForAlquimia.patch
make libcrunchchem.a

More detailed instructions for building CrunchFlow will be forthcoming.

Alquimia interface

When you have built all the desired chemistry engines, you can build the Alquimia interface. On UNIX and UNIX-like systems, you can use the following command, which assumes you have set ALQUIMIA_DIR to the top of your Alquimia source tree. Note that you will need to create a build tree from which to invoke CMake.

cd $ALQUIMIA_DIR
mkdir build ; cd build
cmake .. \
  -DCMAKE_INSTALL_PREFIX=<installation prefix> \
  -DCMAKE_C_COMPILER=<C compiler> \
  -DCMAKE_CXX_COMPILER=<C++ compiler> \
  -DCMAKE_Fortran_COMPILER=<Fortran compiler> \
  -DXSDK_WITH_PFLOTRAN=ON \
  -DTPL_PFLOTRAN_LIBRARIES=$PFLOTRAN_DIR/src/pflotran/libpflotranchem.a \
  -DTPL_PFLOTRAN_INCLUDE_DIRS=$PFLOTRAN_DIR/src/pflotran \
  -DXSDK_WITH_CRUNCHFLOW=ON \
  -DTPL_CRUNCHFLOW_LIBRARIES=$CRUNCHFLOW_DIR/libcrunchchem.a \
  -DTPL_CRUNCHFLOW_INCLUDE_DIRS=$CRUNCHFLOW_DIR
make

NOTE: you can omit either of the engines if you aren't building them both. If you don't specify any chemistry engine, Alquimia will halt and remind you that building it without an engine is pointless. So, for example, to build Alquimia with an install of PFlotran at $PFLOTRAN_DIR using MPI compilers, in Debug mode, to be installed in /usr/local:

cd $ALQUIMIA_DIR
mkdir build ; cd build
cmake .. \
  -DCMAKE_INSTALL_PREFIX=/usr/local \
  -DCMAKE_C_COMPILER=`which mpicc` \
  -DCMAKE_CXX_COMPILER=`which mpicxx` \
  -DCMAKE_Fortran_COMPILER=`which mpif90` \
  -DCMAKE_BUILD_TYPE=Debug \
  -DXSDK_WITH_PFLOTRAN=ON \
  -DTPL_PFLOTRAN_LIBRARIES=$PFLOTRAN_DIR/src/pflotran/libpflotranchem.a \
  -DTPL_PFLOTRAN_INCLUDE_DIRS=$PFLOTRAN_DIR/src/pflotran
make

If you are using a geochemical engine that requires PETSc, and you want to specify the exact locations of its headers, and the method for linking against PETSc's libraries, you can specify these with the -DTPL_PETSC_INCLUDE_DIRS=<list of dirs> and -DTPL_PETSC_LDFLAGS=<link flags> arguments. Normally, these options are omitted and Alquimia automatically detects PETSc's location using the PETSC_DIR and PETSC_ARCH environment variables.

Testing

To run Alquimia's suite of tests from your build directory, just type

make test

See the CMakeLists.txt file for other available build options, including optimization level, shared/static libraries, build prefix, etc. Alquimia supports all xSDK-compliant build options, which can be passed to CMake when configuring your build.

Installation

You can install the Alquimia library and the demo drivers into your desired location, type

make install

This will install libraries into ${CMAKE_INSTALL_PREFIX}/lib, headers into ${CMAKE_INSTALL_PREFIX}/include/alquimia, and the demo drivers into ${CMAKE_INSTALL_PREFIX}/bin. To run some basic sanity checks on these installed drivers, you can type

make test_install

This will run a few benchmark tests to make sure that the executables have been properly linked and installed.