Hermes-3

Hermes-3 is a multifluid plasma simulation model for transport and turbulence in the edge of magnetically confined plasmas, such as tokamaks. It is built on the BOUT++ framework, and uses a system of reusable components to build models at runtime based on input configuration, in 1D, 2D or 3D curvlinear coordinates. The manual is here on Readthedocs.

Post-processing Hermes-3 is made easy by using the xHermes Python library. xHermes is built on top of xBOUT and Xarray and automatically accounts for the normalisation of Hermes-3 parameters, as well as providing access to many useful xBOUT post-processing functions. Many of these are showcased in the xBOUT examples.

Note Under development, research code, may change without notice.

License

Hermes-3 is released under the GPL-3 license. See LICENSE and NOTICE for details. If you are using Hermes-3, please cite the relevant papers.

All new contributions must be made under the GPLv3 license.

LLNL-CODE-845139

Copyright Hermes-3 contributors 2017-2025
          email: dudson2@llnl.gov

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Installing and testing

Only CMake is supported for building Hermes-3 and running the tests. During configuration BOUT++ will be automatically downloaded as a submodule, together with some dependencies. NetCDF and FFTW are assumed to be installed already; optional dependencies include SUNDIALS and PETSc. The recommended way to build Hermes-3 links to the SUNDIALS library.

1) Configure with cmake, downloading and linking to SUNDIALS:

$ cmake . -B build -DBOUT_DOWNLOAD_SUNDIALS=ON

2) Build, compiling Hermes-3 and all dependencies:

$ cmake --build build

3) Run the unit and integrated tests to check that everything is working:

$ cd build
$ ctest

Note that the integrated tests require MPI, and so may not run on the head nodes of many computing clusters.

The CMake configuration can be customised: See the BOUT++ documentation for examples of using cmake arguments, or edit the compile options interactively before building:

$ ccmake . -B build

If you have already installed BOUT++ and want to use that rather than configure and build BOUT++ again, set HERMES_BUILD_BOUT to OFF and pass CMake the path to the BOUT++ build directory e.g.

$ cmake . -B build -DHERMES_BUILD_BOUT=OFF -DCMAKE_PREFIX_PATH=$HOME/BOUT-dev/build

Note that Hermes-3 currently requires a specific version of BOUT++: https://github.com/boutproject/BOUT-dev/commit/7152948fbde505f6708d5ca4a9c21e5828d1e0a1

Examples

There are example inputs under the examples/ subdirectory. A simple example is a 2D (drift plane) simulation of a plasma blob/filament, similar to the BOUT++ blob2d example:

./hermes-3 -d examples/blob2d

See the examples for more complicated cases.

Publications

• B.Dudson, M.Kryjak, H.Muhammed, P.Hill, J,Omotani Hermes-3: Multi-component plasma simulations with BOUT++ Comp. Phys. Comm. 2023
  1. doi:10.1016/j.cpc.2023.108991. Preprint: arXiv.2303.12131.
• G.K. Holt, A. Keats, S. Pamela, M. Kryjak, A. Agnello, N.C. Amorisco, B.D. Dudson and M. Smyrnakis Tokamak divertor plasma emulation with machine learning 2024 Nucl. Fusion 64 086009 doi:10.1088/1741-4326/ad4f9e
• Thomas Body, Thomas Eich, Adam Kuang, Tom Looby, Mike Kryjak, Ben Dudson, Matthew Reinke Detachment scalings derived from 1D scrape-off-layer simulations Nucl. Mat. Energy 2024 101819 doi:10.1016/j.nme.2024.101819
• Huayi Chang, Ben Dudson, Jizhong Sun, Mike Kryjak, Yang Ye, Mao Li, Weikang Wang Hermes-3 simulation of the low-n X-point mode driven by impurity in tokamak edge plasmas Nucl. Mat. Energy 2025 101913 doi:10.1016/j.nme.2025.101913
• B. D. Dudson, M. Kryjak, H. Muhammed, J. Omotani Validation of Hermes-3 turbulence simulations against the TCV-X21 diverted L-mode reference case 2025 Preprint: arXiv:2506.12180.