JustRelax.jl

Need to solve a large multiphysics problem on many GPUs in parallel? Just Relax!

JustRelax.jl is a Julia package for geodynamic modeling with matrix-free, accelerated pseudo-transient solvers. It supports two- and three-dimensional applications on CPUs and GPUs, including distributed-memory runs with MPI.

JustRelax.jl supports Julia 1.10 through 1.12. Start with the CPU backend, then use the backend guide to configure CUDA, AMDGPU, or MPI workflows.

The package is part of the PTSolvers organisation and was developed within the GPU4GEO project. For an overview of the methods and examples, see the documentation.

Highlights

• Matrix-free iterative solvers for Stokes, thermal, and coupled geodynamic problems.
• CPU and GPU backends, with support for CUDA and AMDGPU through Julia’s package extensions.
• MPI-based domain decomposition via ImplicitGlobalGrid.jl.
• Building blocks for material properties, particle methods, and constitutive models through GeoParams.jl and JustPIC.jl.
• Reproducible benchmark and application examples in miniapps/.

JustRelax.jl builds on:

• ParallelStencil.jl
• ImplicitGlobalGrid.jl
• GeoParams.jl
• JustPIC.jl

Installation

JustRelax.jl is registered in the Julia General registry:

using Pkg
Pkg.add("JustRelax")

To use the latest development version instead:

using Pkg
Pkg.add(url = "https://github.com/PTsolvers/JustRelax.jl", rev = "main")

The package can be loaded with:

using JustRelax

See the installation guide for testing the installation and for running the miniapps, and the backend guide for CUDA, AMDGPU, and MPI setup.

Quick start

Every model allocates the same handful of containers and threads them through the solver calls:

using JustRelax, JustRelax.JustRelax2D

backend = CPUBackend                       # CUDABackend / AMDGPUBackend on GPUs

ni     = 64, 64                            # number of cells
li     = 1.0e6, 5.0e5                      # domain size [m]
grid   = Geometry(ni, li; origin = (0.0, -5.0e5))

stokes    = StokesArrays(backend, ni)      # velocity, pressure, stresses, residuals
thermal   = ThermalArrays(backend, ni)     # temperature, fluxes, heat sources
pt_stokes = PTStokesCoeffs(li, grid.di.center; ϵ_rel = 1.0e-6, CFL = 0.9 / √2.1)

Three-dimensional models use JustRelax.JustRelax3D and a three-element ni/li. From here, a model adds a rheology, boundary conditions, and a time loop calling solve! and heatdiffusion_PT!; the getting-started walkthrough builds one end to end.

Testing

From the Julia package manager, run:

] test JustRelax

For local development, activate the repository and run the same command:

] activate .
] test

Miniapps and examples

The miniapps/ directory contains small, focused examples and benchmark problems covering convection, thermal diffusion, Stokes flow, shear heating, subduction, and more. They are intended as starting points for application codes and as reference cases for performance experiments.

Most examples run on a single node. They can be extended to multiple nodes with MPI.jl and ImplicitGlobalGrid.jl. The documentation also includes guided examples for Blankenbach convection, shear bands, and 2D subduction.

Contributing

Bug reports, documentation improvements, and new solver or benchmark contributions are welcome. Please open an issue or start a discussion. See CONTRIBUTING.md for development guidelines.

Citing

If you use JustRelax.jl, please cite the software release on Zenodo and the JOSS article. The repository also includes a CITATION.cff file for citation tools.

Funding

Development has been supported by the GPU4GEO and δGPU4GEO projects, the PASC project, and the European Research Council through the MAGMA project (ERC Consolidator Grant #771143).