Spack and Uberenv

GEOSX is transitioning to a new Spack and Uberenv system for building our dependencies. We refer the reader to the Spack documentation and Uberenv documentation, in particular the Spack documentation for specs and dependencies, manual compiler configuration and external packages are worth reading.

Building the dependencies can be as simple as running


This will create a directory uberenv_libs in the current working directory, clone Spack into uberenv_libs/spack and install the dependencies into uberenv_libs/system_dependent_path. It will then spit out a host-config file in the current directory which you can use to build GEOSX. While the above command should work on every system, it should never be used. Invoked as such, Spack will ignore any system libraries you have installed and will go down a rabbit hole building dependencies. Furthermore this does not allow you to choose the compiler to build. Both of these are easily solved by creating a directory with a packages.yaml and a compilers.yaml.

To prevent this from happening you’ll need to create a directory with a packages.yaml file and a compilers.yaml file. You can find working examples for commonly used systems in scripts/uberenv/spack_configs. It is worth noting that each LC system type has two such directories, for example there is a toss_3_x85_54_ib and toss_3_x85_54_ib_python directory. This is because when building pygeosx Python needs to be built from scratch, and as such cannot be listed in packages.yaml. However, when not building pygeosx other dependencies depend on python, but an existing system version works just fine, so it can be put in packages.yaml to prevent Spack from building it.

Once you have these files setup you can run Uberenv again and instruct it to use them with. If for instance you added Clang 10.0.1 to the compilers.yaml file the your command would look something like this:

./scripts/uberenv/ --spack-config-dir=/path/to/your/config/directory/ --spec="%[email protected]"


When building pygeosx, Spack will build various python packages, however by default they are not installed in python. There are various ways of accomplishing this, but the recommended approach is to use spack activate. The command would look something like this ./uberenv_libs/spack/bin/spack activate py-numpy py-scipy py-pip py-mpi4py

Build Configuration

The GEOSX Spack package has a lot of options for controlling which dependencies you would like to build and how you’d like them built. The GEOSX Spack package file is at `scripts/uberenv/packages/geosx/ <>`_. The variants for the package are as follows

    variant('shared', default=True, description='Build Shared Libs.')
    variant('caliper', default=True, description='Build Caliper support.')
    variant('mkl', default=False, description='Use the Intel MKL library.')
    variant('essl', default=False, description='Use the IBM ESSL library.')
    variant('suite-sparse', default=True, description='Build SuiteSparse support.')
    variant('trilinos', default=True, description='Build Trilinos support.')
    variant('hypre', default=True, description='Build HYPRE support.')
    variant('hypre-cuda', default=False, description='Build HYPRE with CUDA support.')
    variant('petsc', default=True, description='Build PETSc support.')
    variant('scotch', default=True, description='Build Scotch support.')
            description='Linear algebra interface.',
            values=('trilinos', 'hypre', 'petsc'),
    variant('pygeosx', default=False, description='Build the GEOSX python interface.')

For example if you wanted to build with GCC 8.3.1, without Caliper and with PETSC as the Linear Algebra Interface, your spec would be %gcc@8.3.1 ~caliper lai=petsc.

The GEOSX Spack package lists out the libraries that GEOSX depends ons. Currently these dependencies are

    depends_on('[email protected]:', type='build')
    depends_on('[email protected]:', when='+cuda', type='build')

    # Virtual packages

    # Performance portability
    depends_on('[email protected] +openmp +shared ~examples ~exercises')
    depends_on('raja +cuda', when='+cuda')

    depends_on('[email protected] ~c +shared +openmp ~examples')
    depends_on('umpire +cuda', when='+cuda')

    depends_on('[email protected] +shared +raja ~benchmarks ~examples')
    depends_on('[email protected] +cuda', when='+cuda')

    # IO
    depends_on('[email protected]: +shared +pic +mpi', when='~vtk')

    depends_on('[email protected] +shared ~test ~fortran +mpi +hdf5 ~hdf5_compat')

    depends_on('[email protected]: ~fortran +shared ~silex +pic +mpi ~zlib')

    depends_on('[email protected]: +mpi +shared', when='+caliper')
    depends_on('[email protected]: +shared +adiak +mpi ~callpath ~libpfm ~gotcha ~sampler', when='+caliper')

    depends_on('[email protected]: +shared')

    depends_on('[email protected]: cxxstd=14 +pic')

    # Math
    depends_on('intel-mkl +shared ~ilp64', when='+mkl')

    # depends_on('essl ~ilp64 threads=openmp +lapack +cuda', when='+essl')

    depends_on('[email protected]: +shared +int64')

    depends_on('[email protected]: +mpi +int64', when='+scotch')

    depends_on('superlu-dist +int64 +openmp +shared', when='~petsc')
    depends_on('[email protected] +int64 +openmp +shared', when='+petsc')

    depends_on('[email protected]: +pic +openmp +amd +camd +colamd +ccolamd +cholmod +umfpack', when='+suite-sparse')
    depends_on('suite-sparse +blas-no-underscore', when='%gcc +suite-sparse +essl')

    trilinos_build_options = '~fortran +openmp +shared'
    trilinos_tpls = '~boost ~glm ~gtest ~hdf5 ~hypre ~matio ~metis +mpi ~mumps ~netcdf ~suite-sparse'
    trilinos_packages = '+amesos +aztec +epetra +epetraext +ifpack +kokkos +ml +stk +stratimikos +teuchos +tpetra ~amesos2 ~anasazi ~belos ~exodus ~ifpack2 ~muelu ~sacado ~zoltan ~zoltan2'
    depends_on('[email protected] ' + trilinos_build_options + trilinos_tpls + trilinos_packages, when='+trilinos')
    depends_on('trilinos +blas_lowercase_no_underscore', when='+trilinos +essl')
    # depends_on('trilinos +force-new-lapack', when='+trilinos +essl')

    depends_on('[email protected] +shared +superlu-dist +mixedint +mpi +openmp', when='+hypre')
    depends_on('[email protected] +cuda +shared +superlu-dist +mpi +openmp +unified-memory +cusparse', when='+hypre-cuda')

    petsc_build_options = '+shared +mpi'
    petsc_tpls = '+metis ~hdf5 ~hypre +superlu-dist +int64'
    depends_on('[email protected]: ' + petsc_build_options + petsc_tpls, when='+petsc')

    # Python
    depends_on('python +shared +pic', when='+pygeosx')
    depends_on('[email protected]: +blas +lapack +force-parallel-build', when='+pygeosx')
    depends_on('[email protected]: +force-parallel-build', when='+pygeosx')
    depends_on('[email protected]:', when='+pygeosx')
    depends_on('py-pip', when='+pygeosx')

    # Dev tools
    depends_on('[email protected]:')

    # Documentation
    depends_on('[email protected]:', when='+docs', type='build')
    depends_on('[email protected]:', when='+docs', type='build')

Using the Spack spec syntax you can inturn specify variants for each of the dependencies of GEOSX. So for example if you could modify the spec above to build RAJA in debug by using %gcc@8.3.1 ~caliper lai=petsc ^raja build_type=Debug. When building with Uberenv Spack should print out a table containing the full spec for every dependency it will build. If you would like to look at the variants for say RAJA in more detail you can find the package file at uberenv_libs/spack/var/spack/repos/builtin/packages/raja/

Adding a Dependency (Advanced)

Adding a dependency to GEOSX is straight forward if the dependency already builds with Spack. If that is the case then all you need to do is add a depends_on('cool-new-library') to the GEOSX file. If however the dependency doesn’t have a Spack package, you will have to add one by creating a cool-new-library/package.yaml file in the scripts/uberenv/packages directory and adding the logic to build it there.

Oftentimes (unfortunately), even when a package already exists, it might not work out of the box for your system. In this case copy over the existing file from the Spack repository into scripts/uberenv/packages/cool-new-library/, as if you were adding a new package, and perform your modifications there. Once you have the package working, copy the package back into the Spack repository (running Uberenv should do this for you) and commit+push your changes to Spack.