{"id":22668225,"url":"https://github.com/lanl/singularity-eos","last_synced_at":"2025-08-21T20:32:46.677Z","repository":{"id":37073765,"uuid":"356026328","full_name":"lanl/singularity-eos","owner":"lanl","description":"Performance portable equations of state and mixed cell closures","archived":false,"fork":false,"pushed_at":"2024-11-21T03:30:18.000Z","size":15847,"stargazers_count":27,"open_issues_count":94,"forks_count":8,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-11-21T05:21:54.585Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://lanl.github.io/singularity-eos/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lanl.png","metadata":{"files":{"readme":"README.build.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-08T19:28:58.000Z","updated_at":"2024-11-20T05:37:06.000Z","dependencies_parsed_at":"2023-10-25T23:26:53.206Z","dependency_job_id":"4190fbe5-b478-4b8d-94c3-269f0a56c919","html_url":"https://github.com/lanl/singularity-eos","commit_stats":{"total_commits":1476,"total_committers":37,"mean_commits":"39.891891891891895","dds":0.736449864498645,"last_synced_commit":"2a66420b295843093789a39eb75867ec60a3b361"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fsingularity-eos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fsingularity-eos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fsingularity-eos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fsingularity-eos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lanl","download_url":"https://codeload.github.com/lanl/singularity-eos/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230532448,"owners_count":18240792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-09T15:14:10.556Z","updated_at":"2024-12-20T04:07:49.056Z","avatar_url":"https://github.com/lanl.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Overview \n\nThe `singularity-eos` build system is designed with two goals in mind\n\n1. Portability to a wide range of host codes, system layouts, and underlying hardware\n2. Ease of code development, and flexibility for developers\n\nThese considerations continue to guide development of the tools and workflows \nin working with `singularity-eos`.\n\n## Basics\n\nThe build of `singularity-eos` can take two forms:\n\n1. Submodule mode\n2. Standalone mode\n\nThese will be described in more detail below, but in brief _submodule mode_ is intended \nfor downstream codes that build `singularity-eos` source code directly in the build \n(sometimes referred to as \"in-tree\"), while _standalone mode_ will build `singularity-eos` \nas an independent library that can be installed onto the system.\n\nThe most important distinction between the modes is how dependencies are handled.\n_submodule mode_ will use *internal* source clones of key dependencies (located in \n`utils\\`), effectively building these dependencies as part of the overall `singularity-eos`\nbuild procedure. It should be noted, however, that there are optional dependencies \nthat are not provided internally and must be separately available.\n\nIn _standalone mode_, *all* dependencies must be available in the environment,\nand be discoverable to CMake. While not required, it is encouraged to use the \ndependency management tool `spack` to help facilitate constructing a build environment, \nas well as deploying `singularity-eos`. Example uses of `spack` for these purposes \nare provided below.\n\nA CMake configuration option is provided that allows developers to select a specific \nmode (`SINGULARITY_FORCE_SUBMODULE_MODE`), however this is intended for internal development \nonly. The intended workflow is to let `singularity-eos` decide that appropriate mode, which \nit decides based on inspecting the project directory that the source resides in.\n\n## Options for configuring the build\n\nMost configuration options are the same between the two builds. _standalone_ / _submodule_ specific options are touched on in the sections detailing those build modes.\n\nThe main CMake options to configure building are in the following table: \n\n| Option | Default | Comment |\n|--|--|--|\n| `SINGULARITY_USE_SPINER`            | ON      | Enables EOS objects that use `spiner`.|\n| `SINGULARITY_USE_FORTRAN`           | ON      | Enable Fortran API for equation of state.|\n| `SINGULARITY_USE_KOKKOS`            | OFF     | Uses Kokkos as the portability backend. Currently only Kokkos is supported for GPUs.|\n| `SINGULARITY_USE_EOSPAC`            | OFF     | Link against EOSPAC. Needed for sesame2spiner and some tests.|\n| `SINGULARITY_BUILD_TESTS`           | OFF     | Build test infrastructure.|\n| `SINGULARITY_BUILD_PYTHON`          | OFF     | Build Python bindings.|\n| `SINGULARITY_INVERT_AT_SETUP`       | OFF     | For tests, pre-invert eospac tables.|\n| `SINGULARITY_BETTER_DEBUG_FLAGS`    | ON      | Enables nicer GPU debug flags. May interfere with in-tree builds as a submodule.|\n| `SINGULARITY_HIDE_MORE_WARNINGS`    | OFF     | Makes warnings less verbose. May interfere with in-tree builds as a submodule.|\n| `SINGULARITY_FORCE_SUBMODULE_MODE`  | OFF     | Force build in _submodule_ mode.|\n| `SINGULARITY_USE_SINGLE_LOGS`  | OFF     | Use single precision logarithms (may degrade accuracy).|\n| `SINGULARITY_USE_TRUE_LOG_GRIDDING`  | OFF     | Use grids that conform to logarithmic spacing.|\n\nMore options are available to modify only if certain other options or variables satisfy certain conditions (_dependent options_).\n_Dependent options_ can only be accessed if their precondition is satisfied. \n\nIf the precondition is satisfied, they take on a default value, although they can be changed.\nIf the precondition is *not* satisfied, then their value is fixed and cannot be changed. For instance,\n\n```bash\n# in \u003ctop-level\u003e/build\ncmake .. -DSINGULARITY_USE_KOKKOS=OFF -DSINGULARITY_USE_CUDA=ON\n```\n\nWill have no effect (i.e. `SINGULARITY_USE_CUDA` will be set to `OFF`), because the precondition of `SINGULARITY_USE_CUDA` is for \n`SINGULARITY_USE_KOKKOS=ON`. \n\nGenerally, _dependent options_ should only be used for specific use-cases where the defaults are not applicable.\nFor most scenarios, the preconditions and defaults are logically constructed and the most natural in practice \n(`SINGULARITY_TEST_*` are only available if `SINGLARITY_BUILD_TESTS` is enabled, for instance).\n\nThese options are listed in the following table, along with their preconditions:\n\n|Option|Precondition|Default (condition true/false)| Comment |\n|--|--|--|--|\n| `SINGULARITY_USE_SPINER_WITH_HDF5` | `SINGULARITY_USE_SPINER=ON` | ON/OFF | Requests that `spiner` be configured for `HDF5` support.|\n| `SINGULARITY_USE_CUDA`              | `SINGULARITY_USE_KOKKOS=ON`  | ON/OFF | Target nvidia GPUs for `Kokkos` offloading.|\n| `SINGULARITY_USE_KOKKOSKERNELS`     | `SINGULARITY_USE_KOKKOS=ON`  | ON/OFF |Use Kokkos Kernels for linear algebra. Needed for mixed cell closure models on GPU.|\n| `SINGULARITY_BUILD_CLOSURE` | `SINGULARITY_USE_KOKKOS=ON` `SINGULARITY_USE_KOKKOSKERNELS=ON` | ON/OFF | Mixed cell closure.|\n| `SINGULARITY_BUILD_SESAME2SPINER` | `SINGULARITY_USE_SPINER=ON` `SINGULARITY_USE_SPINER_WITH_HDF5=ON` | ON/OFF | Builds the conversion tool sesame2spiner which makes files readable by SpinerEOS.|\n| `SINGULARITY_BUILD_STELLARCOLLAPSE2SPINER` | `SINGULARITY_USE_SPINER=ON` `SINGULARITY_USE_SPINER_WITH_HDF5=ON` | ON/OFF | Builds the conversion tool stellarcollapse2spiner which optionally makes stellar collapse files faster to read.|\n| `SINGULARITY_TEST_SESAME` | `SINGULARITY_BUILD_TESTS=ON` `SINGULARITY_BUILD_SESAME2SPINER=ON` | ON/OFF | Test the Sesame table readers.|\n| `SINGULARITY_TEST_STELLAR_COLLAPSE` | `SINGULARITY_BUILD_TESTS=ON` `SINGULARITY_BUILD_STELLARCOLLAPSE2SPINER=ON`    | ON/OFF | Test the Stellar Collapse table readers.|\n| `SINGULARITY_TEST_PYTHON`           | `SINGULARITY_BUILD_TESTS=ON` `SINGULARITY_BUILD_PYTHON=ON`    | ON/OFF    | Test the Python bindings.|\n\n## CMake presets\n\nTo further aid the developer, `singularity-eos` is distributed with *Presets*, a list of common build options with naturally named \nlabels that when used can reduce the need to input and remember the many options `singularity-eos` uses.\nFor a general overview of CMake presets, see the [cmake documentation on presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html)\n\n### Predefined presets \n\nPredefined presets are described with a `json` schema in the file `CMakePresets.json`. As an example:\n\n```bash\n# in \u003ctop-level\u003e/build\n$\u003e cmake .. --preset=\"basic_with_testing\"\nPreset CMake variables:\n\n  CMAKE_EXPORT_COMPILE_COMMANDS=\"ON\"\n  SINGULARITY_BUILD_TESTS=\"ON\"\n  SINGULARITY_USE_EOSPAC=\"ON\"\n  SINGULARITY_USE_SPINER=\"ON\"\n\n# ...\n```\n\nAs you can see, CMake reports the configuration variables that the preset has used, and their values. A list of presets can be easily examined with:\n\n```bash\n# in \u003ctop-level\u003e/build\n$\u003e cmake .. --list-presets\nAvailable configure presets:\n\n  \"basic\"\n  \"basic_with_testing\"\n  \"kokkos_nogpu\"\n  \"kokkos_nogpu_with_testing\"\n  \"kokkos_gpu\"\n  \"kokkos_gpu_with_testing\"\n```\n\nWhen using presets, additional options may be readily appended to augment the required build.\nFor example, suppose that the `basic` preset is mostly sufficient, but you would like to enable building the closure models: \n\n```bash\n# in \u003ctop-level\u003e/build\n$\u003e cmake .. --preset=\"basic_with_testing\" -DSINGULARITY_BUILD_CLOSURE=ON\n# ...\n```\n\n### User defined presets \n\nThe CMake preset functionality includes the ability of developers to define local presets in `CMakeUserPresets.json`.\n`singularity-eos` explicitly does not track this file in Git, so developers can construct their own presets. \nAll presets in the predefined `CMakePresets.json` are automatically included by CMake, so developers can \nbuild off of those if needed.\n\nFor instance, suppose you have a local checkout of the `kokkos` and `kokkos-kernels` codes that you're \nusing to debug a GPU build, and you have these installed in `~/scratch/`.\nYour `CMakeUserPresets.json` could look like:\n\n```json\n{\n  \"version\": 1,\n  \"cmakeMinimumRequired\": {\n    \"major\": 3,\n    \"minor\": 19\n  },\n  \"configurePresets\": [\n    {\n      \"name\": \"my_local_build\",\n      \"description\": \"submodule build using a local scratch install of kokkos\",\n      \"inherits\": [\n        \"kokkos_gpu_with_testing\"\n      ],\n      \"cacheVariables\": {\n        \"Kokkos_DIR\": \"$env{HOME}/scratch/kokkos/lib/cmake/Kokkos\",\n        \"KokkosKernels_DIR\": \"$env{HOME}/scratch/kokkoskernels/lib/cmake/KokkosKernels\",\n        \"SINGULARITY_BUILD_PYTHON\": \"ON\",\n        \"SINGULARITY_TEST_PYTHON\": \"OFF\"\n      }\n    }\n  ]\n}\n```\n\nThis inherits the predefined `kokkos_gpu_with_testing` preset, sets the `Kokkos*_DIR` cache variables to point `find_package()` \nto use these directories, and finally enables building the python bindings without including the python tests.\n\n## Building in _submodule mode_\n\nFor _submodule mode_ to activate, a clone of the `singularity-eos` source should be placed\nbelow the top-level of a host project\n\n```bash\n# An example directory layout when using singularity-eos in submodule mode\nmy_project\n|_CMakeLists.txt\n|_README.md \n|_src \n|_include\n|_tpl/singularity-eos\n```\n`singularity-eos` is then imported using the `add_subdirectory()` command in CMake \n\n```cmake\n# In your CMakeLists.txt\ncmake_minimum_required(VERSION 3.19)\nproject(my_project)\n\nadd_executable(my_exec src/main.cc)\ntarget_include_directories(my_exec include)\n\nadd_subdirectory(tpl/singularity-eos)\n\ntarget_link_libraries(my_exec singularity-eos::singularity-eos)\n```\n\nThis will expose the `singularity-eos` interface and library to your code, along with \nthe interfaces of the internal dependencies\n\n```c++\n// in source of my_project \n\n#include\u003csingularity-eos/eos/eos.hpp\u003e\n// from the internal ports-of-call submodule\n#include\u003cports-of-call/portability\u003e\n\n// ...\n\nusing namespace singularity;\n```\n\n`singularity-eos` will build (along with internal dependencies) and be linked directly to your executable.\n\nThe git submoudles may change during development, either by changing the pinned hash, addition or removal of submodules. If you \nhave errors that appear to be the result of incompatible code, make sure you have updated your submodules with \n\n```bash\ngit submodule update --init --recursive\n```\n\n## Building in _standalone mode_ \n\nFor _standalone_ mode, all required and optional dependencies are expected to be discoverable by CMake. This can be done several ways\n\n1. (*preferred*) Use Spack to configure and install all the dependencies needed to build.\n2. Use a system package manager (`apt-get`, `yum`, \u0026t) to install dependencies.\n3. Hand-build to a local filesystem, and configure your shell or CMake invocation to be aware of these installs\n\n_standalone_ mode is the mode used to install `singularity-eos` to a system as a common library. If, for example, you use Spack to to install packages, `singularity-eos` will be built and installed in _standalone_ mode.\n\n### Building with Spack \n\nSpack is a package management tool that is designed specifically for HPC environments, but may be used in any compute environment. It \nis useful for gathering, configuring and installing software and it's dependencies self-consistently, and can use existing software installed \non the system or do a \"full\" install of all required (even system) packages in a local directory.\n\nSpack remains under active development, and is subject to rapid change in interface, design, and functionality. Here we will provide an overview \nof how to use Spack to develop and deploy `singularigy-eos`, but for more in-depth information, please refer to the [official Spack documentation](spack.readthedocs.io).\n\n#### Preperation\n\nFirst, we need to clone the Spack repository. You can place this anywhere, but note that by default Spack will download and install \nsoftware under this directory. This default behavior can be changed, please refer to the documentation for information of customizing \nyour Spack instance.\n\n```bash \n$\u003e cd ~\n$\u003e git clone https://github.com/spack/spack.git\n```\n\nTo start using Spack, we use the provided activation script \n\n```bash\n# equivalent scripts for tcsh, fish are located here as well \n$\u003e source ~/spack/share/spack/setup-env.sh\n```\n\nYou will always need to _activate_ spack for each new shell. You may find it convienant to invoke this Spack setup in your \nlogin script, though be aware that Spack will prepend paths to your environment which may cause conflicts with other \npackage tools and software.\n\nThe first time a Spack command is invoked, it will need to bootstrap itself to be able to start *concretizing package specs*.\nThis will download pre-built packages and create a `${HOME}/.spack` directory. This directory is important and is where \nyour _primary_ Spack configuration data will be located. If at any point this configuration becomes corrupted or \ntoo complicated to easily fix, you may safely remove this directory to restore the default configuration, or just \nto try a new approach. Again, refer to the Spack documentaion for more information.\n\n#### Setup compilers \n\nTo use Spack effectively, we need to configure it for the HPC environment we're using. This can be done manually\n(by editing `packages.yaml`, `compilers.yaml`, and perhaps a few others). This is ideal if you understand how your \nsoftware environment is installed on the HPC system, and you are fluent in the Spack configuration schema.\n\nHowever, Spack has put in a lot of effort to be able to automatically discover the available tools and software on \nany given system. While not perfect, we can get a fairly robust starting point.\n\nAssume we are on an HPC system that has Envionrmental Modules that provides compilers, MPI implementations, and sundry \nother common tools. To help Spack find these, let's load a specific configuration into the active shell environment.\n\n```bash\n$\u003e module load cmake/3.19.2 gcc/11.2.0 openmpi/4.1.1 python/3.10\n$\u003e module list\n\nCurrently Loaded Modules:\n  1) cmake/3.19.2   2) gcc/11.2.0   3) openmpi/4.1.1   4) python/3.10-anaconda-2023.03\n```\n\nFirst, let's find the available compilers. (If this is the first Spack command you've run, it will need to bootstrap)\n\n```bash\n$\u003e spack compiler find\n==\u003e Added 2 new compilers to ${HOME}/.spack/linux/compilers.yaml\n    gcc@4.8.5  gcc@11.2.0\n==\u003e Compilers are defined in the following files:\n    ${HOME}/.spack/linux/compilers.yaml\n```\n\nHere, we find the default system compiler (`gcc@4.8.5`), along with the compiler from the module we loaded. Also notice \nthat the `${HOME}/.spack` directory has been modified with some new YAML config files. These are information on \nthe compilers and how Spack will use them. You are free to modify these files, but for now let's leave them as is.\n\n_NB_: You can repeat this procedure for other compilers and packages, though if you need to use many different \ncombinations of compiler/software, you will find using Spack _environments_ [more convenient](https://spack.readthedocs.io/en/latest/environments.html).\n\n#### Setup system-provided packages \n\nNext, we will try and find system software (e.g. `ncurses`,`git`,`zlib`) that we can use instead of needing to \nbuild our own. This will also find the module software we loaded (`cmake`,`openmpi`,`python`).\n(This command will take a couple minutes to complete).\n\n```bash\n$\u003e spack external find --all --not-buildable\n==\u003e The following specs have been detected on this system and added to ${HOME}/.spack/packages.yaml\nautoconf@2.69       bzip2@1.0.6     coreutils@8.22  dos2unix@6.0.3    gcc@11.2.0        go@1.16.5            hdf5@1.8.12      libfuse@3.6.1         ncurses@6.4.20221231   openssl@1.1.1t     python@3.10.9   sqlite@3.7.17      texlive@20130530\nautomake@1.13.4     bzip2@1.0.8     cpio@2.11       doxygen@1.8.5     gettext@0.19.8.1  go@1.18.4            hdf5@1.10.6      libtool@2.4.2         ninja@1.10.2           perl@5.16.3        rdma-core@22.4  sqlite@3.40.1      which@2.20\nbash@4.2.46         ccache@3.7.7    curl@7.29.0     file@5.11         ghostscript@9.25  go-bootstrap@1.16.5  krb5@1.15.1      lustre@2.12.9         opencv@2.4.5           pkg-config@0.27.1  rsync@3.1.2     subversion@1.7.14  xz@5.2.2\nberkeley-db@5.3.21  cmake@2.8.12.2  curl@7.87.0     findutils@4.5.11  git@2.18.4        go-bootstrap@1.18.4  krb5@1.19.4      m4@1.4.16             openjdk@1.8.0_372-b07  python@2.7.5       ruby@2.0.0      swig@2.0.10        xz@5.2.10\nbinutils@2.27.44    cmake@3.17.5    cvs@1.11.23     flex@2.5.37       git-lfs@2.10.0    gpgme@1.3.2          libfabric@1.7.2  maven@3.0.5           openssh@7.4p1          python@3.4.10      sed@4.2.2       tar@1.26           zip@3.0\nbison@3.0.4         cmake@3.19.2    diffutils@3.3   gawk@4.0.2        gmake@3.82        groff@1.22.2         libfuse@2.9.2    ncurses@5.9.20130511  openssl@1.0.2k-fips    python@3.6.8       slurm@23.02.1   texinfo@5.1\n\n-- no arch / gcc@11.2.0 -----------------------------------------\nopenmpi@4.1.1\n```\n\n*Generally* you will want to use as much system-provided software as you can get away with (in Spack speak, these are called _externals_,\nthough _external packages_ are not limited to system provided ones and can point to, e.g., a manual install). In the above command, \nwe told Spack to mark any packages it can find as `not-buildable`, which means that Spack will never attempt to build that package and \nwill always use the external one. This _may_ cause issues in resolving packages specs when the external is not compatible with \nthe requirements of an downstream package.\n\nAs a first pass, we will use `--not-buildable` for `spack external find`, but if you \nhave any issues with concretizing then start this guide over (remove `${HOME}/.spack` and go back to compilers) and do not use \n`--not-buildable` in the previous command. You may also manually edit the `packages.yaml` file to switch the `buildable` flag \nfor the troublesome package, but you will need to be a least familiar with YAML schema.\n\n#### First install with spack \n\nLet's walk through a simple Spack workflow for installing. First, we want to look at the options available for a package.\nThe Spack team and package developers have worked over the years to provide an impressive selection of packages.\nThis example will use `hypre`, a parallel library for multigrid methods. \n\n```bash\n$\u003e spack info hypre\nAutotoolsPackage:   hypre\n\nDescription:\n    Hypre is a library of high performance preconditioners that features\n    parallel multigrid methods for both structured and unstructured grid\n    problems.\n\nHomepage: https://llnl.gov/casc/hypre\n\nPreferred version:\n    2.28.0     https://github.com/hypre-space/hypre/archive/v2.28.0.tar.gz\n\nSafe versions:\n    develop    [git] https://github.com/hypre-space/hypre.git on branch master\n    2.28.0     https://github.com/hypre-space/hypre/archive/v2.28.0.tar.gz\n\n# ... more versions listed \n\nVariants:\n    Name [Default]              When       Allowed values          Description\n    ========================    =======    ====================    ==============================================\n\n    amdgpu_target [none]        [+rocm]    none, gfx900,           AMD GPU architecture\n                                           gfx1030, gfx90c,\n                                           gfx90a, gfx1101,\n                                           gfx908, gfx1010,\n# ... lots of amd targets listed \n    build_system [autotools]    --         autotools               Build systems supported by the package\n    caliper [off]               --         on, off                 Enable Caliper support\n    complex [off]               --         on, off                 Use complex values\n    cuda [off]                  --         on, off                 Build with CUDA\n    cuda_arch [none]            [+cuda]    none, 62, 80, 90,       CUDA architecture\n                                           20, 32, 35, 37, 87,\n                                           10, 21, 30, 12, 61,\n                                           11, 72, 13, 60, 53,\n                                           52, 75, 70, 89, 86,\n                                           50\n    debug [off]                 --         on, off                 Build debug instead of optimized version\n    fortran [on]                --         on, off                 Enables fortran bindings\n    gptune [off]                --         on, off                 Add the GPTune hookup code\n    int64 [off]                 --         on, off                 Use 64bit integers\n    internal-superlu [off]      --         on, off                 Use internal SuperLU routines\n    mixedint [off]              --         on, off                 Use 64bit integers while reducing memory use\n    mpi [on]                    --         on, off                 Enable MPI support\n    openmp [off]                --         on, off                 Enable OpenMP support\n    rocm [off]                  --         on, off                 Enable ROCm support\n    shared [on]                 --         on, off                 Build shared library (disables static library)\n    superlu-dist [off]          --         on, off                 Activates support for SuperLU_Dist library\n    sycl [off]                  --         on, off                 Enable SYCL support\n    umpire [off]                --         on, off                 Enable Umpire support\n    unified-memory [off]        --         on, off                 Use unified memory\n\nBuild Dependencies:\n    blas  caliper  cuda  gnuconfig  hip  hsa-rocr-dev  lapack  llvm-amdgpu  mpi  rocprim  rocrand  rocsparse  rocthrust  superlu-dist  umpire\n\nLink Dependencies:\n    blas  caliper  cuda  hip  hsa-rocr-dev  lapack  llvm-amdgpu  mpi  rocprim  rocrand  rocsparse  rocthrust  superlu-dist  umpire\n\nRun Dependencies:\n    None\n```\n\nThe `spack info` commands gives us three important data-points we need. First, it tells the versions available. If you do not specify a version, \nthe _preferred_ version is default.\n\nNext and most important are the *variants*. These are used to control how to build the package, i.e. to build with MPI, to build a fortran interface, \nand so on. These will have default values, and in practice you will only need to provide a small number for any particular system.\n\nFinally, we are given the *dependencies* of the package. The dependencies listed are for _all_ configurations, so some dependencies may not \nbe necessary for your particular install. (For instance, if you do not build with `cuda`, then `cuda` will not be necessary to install)\n\nLet's look at what Spack will do when we want to install. We will start with the default configuration (that is, all variants are left to default).\nThe `spack spec` command will try to use the active Spack configuration to determine which packages are needed to install `hypre`, and will print \nthe dependency tree out.\n\n```bash\n$\u003e spack spec hypre\nInput spec\n--------------------------------\n -   hypre\n\nConcretized\n--------------------------------\n -   hypre@2.28.0%gcc@11.2.0~caliper~complex~cuda~debug+fortran~gptune~int64~internal-superlu~mixedint+mpi~openmp~rocm+shared~superlu-dist~sycl~umpire~unified-memory build_system=autotools arch=linux-rhel7-broadwell\n -       ^openblas@0.3.23%gcc@11.2.0~bignuma~consistent_fpcsr+fortran~ilp64+locking+pic+shared build_system=makefile symbol_suffix=none threads=none arch=linux-rhel7-broadwell\n[e]          ^perl@5.16.3%gcc@11.2.0+cpanm+opcode+open+shared+threads build_system=generic patches=0eac10e,3bbd7d6 arch=linux-rhel7-broadwell\n[e]      ^openmpi@4.1.1%gcc@11.2.0~atomics~cuda~cxx~cxx_exceptions~gpfs~internal-hwloc~internal-pmix~java~legacylaunchers~lustre~memchecker~openshmem~orterunprefix+pmi+romio+rsh~singularity+static+vt~wrapper-rpath build_system=autotools fabrics=ofi,psm,psm2 schedulers=slurm arch=linux-rhel7-broadwell\n```\n\nHere, we see the full default Spack *spec*, which as a rough guide is structured as `\u003cpackage\u003e@\u003cversion\u003e%\u003ccompiler\u003e@\u003ccompiler_version\u003e{[+/~]variants} \u003carch_info\u003e`.\nThe `+,~` variant prefixes are used to turn on/off variants with binary values, while variants with a set of values are given similar to keyword values \n(e.g. `+cuda cuda_arch=70 ~shared`)\n\nIf we wanted to install a different configuration, in this case say we want `complex` and `openmp` enabled, but we don't need `fortran`.\n\n```bash\n$\u003e spack spec hypre+complex+openmp~fortran\nInput spec\n--------------------------------\n -   hypre+complex~fortran+openmp\n\nConcretized\n--------------------------------\n -   hypre@2.28.0%gcc@11.2.0~caliper+complex~cuda~debug~fortran~gptune~int64~internal-superlu~mixedint+mpi+openmp~rocm+shared~superlu-dist~sycl~umpire~unified-memory build_system=autotools arch=linux-rhel7-broadwell\n -       ^openblas@0.3.23%gcc@11.2.0~bignuma~consistent_fpcsr+fortran~ilp64+locking+pic+shared build_system=makefile symbol_suffix=none threads=none arch=linux-rhel7-broadwell\n[e]          ^perl@5.16.3%gcc@11.2.0+cpanm+opcode+open+shared+threads build_system=generic patches=0eac10e,3bbd7d6 arch=linux-rhel7-broadwell\n[e]      ^openmpi@4.1.1%gcc@11.2.0~atomics~cuda~cxx~cxx_exceptions~gpfs~internal-hwloc~internal-pmix~java~legacylaunchers~lustre~memchecker~openshmem~orterunprefix+pmi+romio+rsh~singularity+static+vt~wrapper-rpath build_system=autotools fabrics=ofi,psm,psm2 schedulers=slurm arch=linux-rhel7-broadwell\n```\n\nHere, you can see the full spec has out supplied variants. In general, variants can control build options and features, and can change which dependencies are needed.\n\nNotice also the left-aligned string starting each line for a package. \n` - ` indicates that Spack isn't aware that this package is installed (which is expected). \n`[+]` indicates that the package has been previously installed.\n`[e]` indicates that the package has been marked as externally installed.\n\nFinally, we can install it. Because `perl` and `openmpi` are already present, Spack will not need to download, build, and install these packages. This can save lots of time!\nNote, however, that external packages are loosely constrained and may not be correctly configured for the requested package.\n\n*NB*: By default, Spack will try to download the package source from the repository associated with the package. \nThis behavior can be overrided with Spack _mirrors_ , but that is beyond the scope of this doc.\n\n```bash\n\n```\n\nNow, we can use Spack similarly to `module load`,\n\n```bash\n$\u003e spack load hypre\n$\u003e spack find --loaded\n```\n\nOther options are available for integrating Spack installed packages into your environment. For more, head over to [https://spack.readthedocs.io](https://spack.readthedocs.io)\n\n#### Developing `singularigy-eos` using Spack \n\nSpack is a powerful tool that can help develop `singularigy-eos` for a variety of platforms and hardware.\n\n1. Install the dependencies `singularigy-eos` needs using Spack\n\n```bash\n$\u003e spack install -u cmake singularity-eos@main%gcc@13+hdf5+eospac+mpi+kokkos+kokkos-kernels+openmp^eospac@6.4.0\n```\n\nThis command will initiate an install of `singularity-eos` using Spack, but will stop right before \n`singularity-eos` starts to build (`-u cmake` means `until cmake`). This ensures all the necessary \ndependencies are installed and visible to Spack\n\n2. Use Spack to construct an _ad-hoc_ shell environment\n\n```bash\n$\u003e spack build-env singularity-eos@main%gcc@13+hdf5+eospac+mpi+kokkos+kokkos-kernels+openmp^eospac@6.4.0 -- bash\n```\n\nThis command will construct a shell environment in `bash` that has all the dependency information populated \n(e.g. `PREFIX_PATH`, `CMAKE_PREFIX_PATH`, `LD_LIBRARY_PATH`, and so on). Even external packages from \na module system will be correctly loaded. Thus, we can build for a specific combination of dependencies, \ncompilers, and portability strategies.\n\n```bash\n$\u003e salloc -p scaling\n# ...\n$\u003e source ~/spack/share/spack/setup-env.sh\n$\u003e spack build-env singularity-eos@main%gcc@12+hdf5+eospac+mpi+kokkos+kokkos-kernels+openmp^eospac@6.4.0 -- bash\n$\u003e mkdir -p build_gpu_mpi ; cd build_gpu_mpi\n$\u003e cmake .. --preset=\"kokkos_nogpu_with_testing\"\n```\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fsingularity-eos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flanl%2Fsingularity-eos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fsingularity-eos/lists"}