SPECFEM3D: seismic wave simulation on hexahedral meshes

Wave propagation on hexahedral meshes

The repository description is the definition of the solver, and it is dense. SPECFEM3D_Cartesian simulates acoustic, which is fluid, elastic, which is solid, coupled acoustic and elastic, poroelastic, or seismic wave propagation in any type of conforming mesh of hexahedra, structured or not.

The mesh requirement is the distinguishing constraint. A hexahedral mesh is a three dimensional grid of brick shaped elements, and it is a much harder meshing problem than a tetrahedral one. Most finite element codes in seismology accept tetrahedra because they can be generated from a surface mesh without effort. Specifying hexahedra means the user has a block structured model, or has the resources to build one, and the payoff is a solver that is efficient on that geometry.

The physics on offer is equally broad within the elastic limit. Acoustic covers fluids, so air and water and the ocean, elastic covers solids, and the coupled case covers the fluid solid interface that matters for ocean bottom seismology and for reservoir simulation. Poroelastic adds the poroelastic coupling of a fluid filled porous medium, which is the regime that applies to the sedimentary basins the code was built for.

The applications the README names are regional seismic wave propagation in sedimentary basins or other geological models following earthquakes, non destructive testing, and ocean acoustics. That is an unusually concrete list for a numerical code, and it tells you the code has been driven by real problems rather than by benchmark problems.

The primary language is Fortran, the licence is GPL-3.0 with the LICENSE file at the root, the homepage is specfem.org, and the project carries a Zenodo DOI, 10.5281/zenodo.10823181, so a specific version of the code can be cited in a paper. The last push to the repository was on 2026-10-09, and the most recent release tags are v4.1.1 from 2024-03-15, v4.1.0 from 2023-12-20 and v4.0.0 from 2023-03-14.

A project with two origins and a large community

The README states that SPECFEM3D was founded by Dimitri Komatitsch and Jeroen Tromp, and is now being developed by a large, collaborative, and inclusive community, with a complete list of authors at the documentation site.

The founder names matter because of what Jeroen Tromp's academic work is, and the shape of the code follows from it. The spectral element method used here is a high order finite element method, and its adoption in global seismology at this scale was largely driven by that group. A solver built on that method is accurate to a degree that the mesh can represent, which is the point when you are trying to distinguish a small change in wave arrival time.

The community framing is not a formality, because the README goes on to say the project lives by the participation of its members, including you, that the goal is to build an inclusive and participatory community, and that guidelines and advice on how to get involved are collected in the project wiki.

There is also an institutional layer. SPECFEM3D is part of the software hosted by the Computational Infrastructure for Geodynamics, the CIG, and the README links to the CIG resources page for SPECFEM3D Cartesian. The CIG is a community infrastructure project for the geosciences, and the arrangement is a good one for a code like this, because it provides compute resources, community meetings and a place where the code outlives any single laboratory.

The practical consequence for a user is that there is a lot of institutional knowledge that is not in the repository, and the documentation is a pointer into it rather than a complete text.

Building it, and the three commands that prove it works

The installation section points at two manuals, a PDF in the doc/USER_MANUAL directory in the repository and the HTML manual at specfem3d.readthedocs.io. The HTML one is the current version.

But the README also gives a three command quick test, and for a code of this size that is the more useful instruction, because a solver that has not run on your machine is not installed:

./configure FC=gfortran CC=gcc
make all
./run_this_example.sh

The output lands in the OUTPUT_FILES directory at the root of the tree, which is worth knowing in advance because a spectral element solver produces a lot of files and it is not obvious afterwards which ones you want.

The configure line sets the Fortran and C compilers explicitly rather than letting the script guess, and passing them is the right habit for a code that has to build on clusters where the default compiler is not the one you want. The build is autotools based, with configure, configure.ac, Makefile.in, a config.guess and config.sub, an m4 directory and a flags.guess script, and the tree also carries an install-sh script.

There is a warning in the README about the build files that is worth repeating, because it is the kind of thing that gets ignored. Do not modify the configure script directly. Modify the configure.ac file instead and generate a new configure script with autoreconf -i. A configure script is generated output, and an edit to it is lost the next time anyone regenerates it, which in a community project is the next person who touches the build.

There is also an install-sh script at the root, and a setup directory, which in autotools projects is usually where the package's own build rules live.

The examples, the benchmarks and the reproducible studies

The EXAMPLES directory is the most substantial part of the tree and it is where the project tells you what it is for.

It contains an applications directory, a benchmarks directory, a notebooks directory and a reproducible_study directory, plus a Python helper called process_DATA_Par_files_to_update_their_parameters_from_a_main_file.py. That last name is a good summary of how the code is configured, because the parameters live in Par files rather than in a command line, and the script exists to propagate a parameter change from one main file into the rest of the set. Parameter files are the convention in this code, and a new user will spend their first hour editing them rather than running flags.

The benchmarks directory matters for anyone comparing solvers, and the notebooks directory suggests the analysis is expected to happen in a notebook environment rather than in a shell. A reproducible_study directory is a stronger signal, because reproducing a study rather than a single run is the discipline that separates a research code from a script.

The DATA directory holds the input data sets, and MESH-default holds a default mesh. That combination, a data directory plus a default mesh plus a run script, is what makes the quick test possible: the example has everything it needs without the user having to supply a mesh.

The rest of the tree is the machinery a Fortran HPC code accumulates. There is src, lib, external_libs, utils, bin, obj, m4, doc, tests, a CUBIT_GEOCUBIT directory, a .docker directory, a .travis directory and an .azure-pipelines directory, along with a .gitmodules file, so some components are pulled in as submodules.

Continuous integration across three providers, and where the release line sits

The development section shows four CI badges, and they are not redundant.

There is a GitHub Actions badge pointing at the specfem3d repository, a Travis badge on the devel branch, an Azure Pipelines badge also on devel and pointing at a geodynamics.specfem3d definition, and a Codecov badge, also on devel. A ReadTheDocs badge covers the documentation build, and the licence badge is GPL v3.

Three CI providers is unusual, and it is explained by the age and the geography of the project. Travis and Azure Pipelines are both configured against the devel branch rather than master, which tells you that the branch the developers work on is devel and that master carries the releases. The two older providers are still running the checks that were set up years ago, and the GitHub Actions workflow is the newer addition rather than a replacement.

The release line is the part that needs care. The tags are v4.1.1 from 2024-03-15, v4.1.0 from 2023-12-20 and v4.0.0 from 2023-03-14, while the last push to the repository was on 2026-10-09. So the branch has moved well past the newest tag, and the most recent published version is more than two years old.

That pattern is normal for a research code, where the tagged version is the citable one and the branch is the working state, but it does mean that an adopter has a choice to make. Pin the tag and get a reproducible, citable, tested state. Track the branch and get the current fixes and the current physics, at the cost of a moving target and no version identifier for a paper.

The Zenodo DOI and the CITATION.cff file in the repository root both point to the first approach, and the file's presence is the reason the DOI resolves to a specific archival record rather than to a moving branch.

Editorial conclusion

Adopt SPECFEM3D if you need a wave propagation solver on a hexahedral mesh, since the Cartesian variant handles structured and unstructured hexahedra and covers the acoustic, elastic, coupled and poroelastic cases in one code. Do not adopt it for an acoustic wave simulation that a lighter tool would do, since this is a heavy research code with a Fortran and autotools build, and do not assume the released version contains the latest work, because the newest tag is v4.1.1 from 2024-03-15 while the branch has moved on since. Verify first which solver variant you need, because the Cartesian version is one of a family and the directory names differ, that your compiler and MPI setup match what configure expects, since the example passes FC=gfortran CC=gcc explicitly, and that the mesh and parameter files you need are in DATA and EXAMPLES, since the inputs are files rather than a command line interface.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. SPECFEM/specfem3d on GitHub