PyLith v5.0.1 released

PyLith
1

PyLith v5.0.1 release

I am pleased to announce the release of PyLith 5.0.1, a finite-element code designed to solve dynamic elastic problems and quasi-static viscoelastic problems in tectonic deformation.

You can download the source code and binaries from https://geodynamics.org/resources/pylith

Documentation https://pylith.readthedocs.org/en/v5.0.1

Version 5.0.1 (2026-06-07)

Changed

  • Updated PETSc to 3.25.2.

Fixed

  • Fixed PETSc bug in output of processor rank for materials when running in parallel.
  • Updated `examples/troubleshooting-2d` to match behavior after latest bugfixes.
  • Add missing files for `examples/subduction-3d` to source distribution.
  • Switch from `numpy.atan2()` to `numpy.arctan2()` in `examples/subduction-3d/generate_gmsh.py` for compatibility with numpy 1.x.
  • Additional clean up of parameter files for `reverse-2d` and `subduction-2d` examples.

Version 5.0.0 (2026-06-02)

Changed

  • Updated the nondimensionalization code, moving it from SpatialData to PyLith.
  • Renamed Nondimensional to Scales.
  • Added displacement scale and improve the names of the other scales.
  • The time scale for poroelasticity is derived from the other scales and nominal material properties.
  • Added discussion of nondimensionalization for each of the governing equations.
  • Updated default solver tolerances consistent with the new nondimensionalization scales.
  • Added option to use adaptive time stepping and update examples reverse-2d Steps 7 and 8 and magma-2d Step 1 to demonstrate its use.
  • Updated multi-grid preconditioner solver settings for elasticity for better scalability with problem size.
  • Updated `examples/subduction-3d` to include generation of the finite-element mesh using Gmsh or Cubit using Python scripts. The Gmsh model includes topography and bathymetry.
  • Mesh formats
    • Added support for use of Cubit side sets and Gmsh physical groups with edges (2D) and surfaces (3D). Use of Cubit vertex sets and Gmsh physical groups with vertices are deprecated and support for them will be removed in version 6.0.0.
    • Use of Cubit side sets and Gmsh physical groups with curves (2D) and surfaces (3D) are using
    • ASCII mesh format
    • Changed group to vertex-group; remove group type.
    • Renamed VertexGroup to BoundaryGroup in meshio.gmsh_utils and changed default behavior to not be recursive (generate “face” groups, not “vertex” groups).
    • Added improve_quality() method to meshio.gmsh_utils.GenerateMesh for improving quality in 3D meshes. Used in examples/crustal-strikeslip-3d.
  • Replaced hardcoded steps for initializing meshes (reading mesh, reordering a mesh, inserting cohesive cells, and refining a mesh) with a modular mesh initialization approach.
  • The default mesh initialization implementation reads a mesh in serial, reorders it, distributes it (if necessary), inserts cohesive cells (if necessary), and refines it (if requested).
  • A parallel mesh initiation implementation reads a mesh in parallel, redistributes it (if necessary), inserts cohesive cells (if necessary), and refines it (if requested).
  • Updated error handling to use Pyre journal channels and PyLith exceptions.
  • Add PyLith exceptions.
  • Add C++ backtrace to PyLith exception messages.
  • Reorganized use of Pyre journal channels with names based on use rather than components.
    • The journal info channel ‘application-flow’ is enabled by default in the PyLith application.
    • The journal device is set to color-console in the examples and full-scale tests.
    • Use the VTU (XML) format for VTK files instead of the legacy ASCII format.
  • Material description property is no longer used; a deprecation warning is printed to stdout if it is specified. This feature will be removed in v6.0.
  • Internal labels for meshes and fields are now derived from the Pyre component name and identifier.
  • Updated PETSc to 3.25.1.

Added

  • Improved documentation for pylith_eqinfo and illustrate use in examples/strikdslip-2d, examples/crustal-strikeslip-2d, and examples/crustal-strikeslip-3d.
  • Added pylith_convertmesh for converting Cubit and Gmsh files to the PETSc HDF5 mesh format.
  • Added support for specifying boundary conditions using marked boundaries rather than vertices.
  • MeshIOAscii: Use face-group for specifying boundary conditions via cell and face vertices.
  • MeshIOCubit: Read sidesets from ExodusII files (generated by Cubit).
  • MeshIOPetsc
    • Gmsh: Create physical groups only at the dimension of the boundary.
    • Added compatibility for reading PETSc HDF5 format.
  • Improved the organization of the governing equations section and added documentation for poroelasticity with prescribed fault slip, including governing equations and default PETSc solver settings. Also added a full-scale test.
  • Added performance benchmarks for linear elasticity with prescribed slip in `benchmarks/performance`.

Fixed

  • Account for processes without cells in initial condition patch when verifying configuration.
  • Avoid divide by zero for KinSrcRamp when final slip is zero.
  • Removed solid_bulk_modulus as a spatial database field for poroelasticity; compute it from the other fields.
  • Fixed typos in setting up gravity with poroelasticity.
  • Fixed pythia import in pylith_eqinfo.

Developer Changes

  • Replaced err = PetscFoo(args); PYLITH_CHECK_ERROR(err); with PylithCallPetsc(PetscFoo(args));.
  • Replace assert(arg) in test code with REQUIRE(arg);.

Overview of major changes

Mesh generation

PyLith now supports marking surfaces in CUBIT (sidesets) and Gmsh rather than vertices for boundary conditions and faults. This is now the recommended approach and marking vertices will not be supported starting in version 6.0.0.

Journal channels

We reorganized the names of the Pyre journal channels, which control information written to stdout (terminal window). All high-level information is written to the application-flow journal channel, which is activated by default.

# Old
[pylithapp.journal.info]
pylithapp = 1
timedependent = 1
solution = 1
meshiopetsc = 1

# New
[pylithapp]
# Turn off 'application-flow' channel
show_application_flow = False

# Turn on colorized journal output
journal.device = color-console

Nondimensionalization

We moved the nondimensionalization from SpatialData to PyLith. There are now two different length scales: a displacement scale for nondimensionalizing the deformation and a length scale for nondimensionalizing the geometry. In nearly all cases, the length scale will need to be adjusted from the default value and set to the nominal discretization size.

# Old
[pylithapp.problem]
normalizer = spatialdata.units.NondimElasticQuasistatic
normalizer.length_scale = 1.0*km
normalizer.shear_modulus = 10.0*GPa
normalizer.relaxation_time = 100.0*year

# New
[pylithapp.problem]
scales = pylith.scales.QuasistaticElasticity
scales.length_scale = 100.0*km
scales.displacement_scale = 1.0*m
scales.shear_modulus = 10.0*GPa
scales.time_scale = 100.0*year

Modular mesh initialization

# Old
[pylithapp.problem.mesh_generator]
reader = pylith.meshio.MeshIOPetsc
reader.filename = mesh_hex.msh

# New
[pylithapp.problem.mesh_initializer.phases.read_mesh]
reader = pylith.meshio.MeshIOPetsc
reader.filename = mesh_hex.msh

Known issues

  • The default PETSc options provide a computationally expensive preconditioner when solving incompressible elasticity problems. We expect to have a more optimal preconditioner in the next few months.

Contributors