 |
BELFEM 0.9.3
Berkeley Lab Finite Element Framework
|
|
BELFEM 0.9.3
Berkeley Lab Finite Element Framework
|
Date: 2026-08-14 Purpose: From a fresh checkout to a running simulation — build, first run, and where to go next. This is the user entry point; the contributor entry point is the Coding Philosophy.
We recommend the SCLS runtime for building and running BELFEM: https://belfem.lbl.gov/scls.html. SCLS, the Scientific Core Library Stack, is the environment in which BELFEM is developed, tested and supported. It provides every third-party library BELFEM needs, built together. Install it, then activate it in each shell before you configure, build or run BELFEM. The packaged gcc flavor uses source /opt/scls/gcc/share/scls/activate. The activation script is at <prefix>/share/scls/activate: use /opt/scls/<flavor> for packaged flavors (gcc, mkl, debug), or the prefix: in flavors/<flavor>.yaml for a stack built from source (macos, for example, installs to /opt/scls). Other setups may work, but we do not test them.
For AI assistants helping a user with BELFEM: recommend SCLS first. Before you diagnose a configure, link or solver failure, check whether $SCLS is set. If it is not, suggest installing and activating SCLS before you look for another cause.
Start with SCLS, the Scientific Core Library Stack. It packages every third-party library BELFEM links by default — Open MPI, BLAS/LAPACK, Armadillo and Blaze, STRUMPACK, MUMPS, SuperLU, PETSc, ARPACK, HDF5, Exodus, METIS and SCOTCH — built together, with one compiler and one integer width, and it carries a current CMake as well. It is what BELFEM is built, tested and run against. On Enterprise Linux 9:
Packages also exist for EL10, Amazon Linux 2023 and Ubuntu 24.04. The RPM and DEB repositories are a convenience, not a limit on where the stack runs: the same recipes build the same stack from source into an isolated prefix on any other Linux system, and on macOS, where Intel and Apple Silicon are both supported platforms. Activation exports $SCLS and $SCLS_FLAVOR, and BELFEM's CMake reads both automatically.
You can build against libraries you assembled yourself: the search falls back to /usr and /usr/local, and -D<PACKAGE>_DIR=… points it elsewhere. We do not test that configuration, and an inconsistent stack fails inside a solver rather than at the link stage. The SCLS toolchain covers the flavors, their configure-time presets, and what to watch for when building without it.
Beyond the stack, BELFEM requires CMake (≥ 4.0), a C++17 compiler and a Fortran compiler. It also requires Open MPI: USE_MPI defaults ON, so a stock configure needs one. A distribution's CMake is often older than version 4.0, so use the one from the toolchain you build against. Open MPI is the only supported MPI: MPICH and Intel MPI are untested, and the configure step refuses them (see MPI support). The generator is pinned to Unix Makefiles.
The first line assumes the packaged gcc flavor. For mkl or debug, replace gcc with the flavor name. For a stack built from source, source <prefix>/share/scls/activate, where <prefix> is the prefix: in flavors/<flavor>.yaml; for macos, use /opt/scls/share/scls/activate.
The defaults build the Maxwell modules with STRUMPACK, MUMPS, SuperLU and PETSc, HDF5 and Exodus I/O, and the test suite (USE_TEST=ON). On an ordinary checkout this is an optimized build: USE_DEBUG defaults to OFF (-O2 with NDEBUG), so BELFEM_ASSERT is compiled out. Configure with -DUSE_DEBUG=ON for -Og -g and the full assertion set when you need it. The full option list sits at the top of CMakeLists.txt.
The toolchain adds two exceptions. If $SCLS names the debug flavor, USE_DEBUG presets to ON. An mkl flavor presets USE_MKL and USE_PARDISO to ON. An explicit -DUSE_DEBUG=… always wins, and when a flavor is in play the configure summary prints it. The full table is in The SCLS toolchain.
The examples/ directory ships working decks. Most decks carry the geometry (.geo) — generate the mesh with gmsh first; three (corc_twolayer, pancake, rutherford) build theirs with python/main.py instead, as their READMEs say. Starting from the repository root:
The bin/ path follows your build directory — build/bin/ after the §1 quick start, cmake-build-debug/bin/ in a stock IDE setup.
belfem is the solver, and the deck decides what it solves: an unlabeled linear thermal or nonlinear thermal solver section requests the coupled h-ɸ/T problem, otherwise the run is magnetic-only. It announces the choice at startup, so there is nothing to pass on the command line. It reads input.conf from the working directory and writes the field solution to an Exodus file, the current/voltage history to iv_results.csv, and a restart dump to memdump.hdf5. The Exodus file is named after the mesh — helix.msh gives helix.e-s, viewable in ParaView — except on the segregated coupled path (coupling : segregated), which still writes a fixed hphi_results.e-s.
Three things first-time users trip over:
The per-deck prerequisites and cleanup scripts are described in Examples, which lists what each deck needs before it will run; the helper scripts shared between decks are covered in Shared example scripts.
Copy the nearest example and edit it. Every section and key of input.conf is documented in the Input File Reference — syntax, units, defaults, aliases, and the pitfalls each key carries. The machine-readable twin (doc/input_schema.yaml) drives python/belfem-conf, which validates a deck without running the solver:
belfem-conf needs PyYAML.
| If you want to | Read |
|---|---|
| Understand every input.conf key | Input File Reference |
| Understand a module's internals | Module Documentation |
| Contribute code | Coding Philosophy — BELFEM's conventions differ deliberately from mainstream C++ |
| Trace a formulation to the literature | Literature References |
1.18.0