JOSS paper

.github/workflows/draft-pdf.yml

@@ -0,0 +1,24 @@
+name: Draft PDF
+on: [push]
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: docs/paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: docs/paper/paper.pdf

README.md

@@ -73,4 +73,4 @@ Available miniapps can be found in the [miniapps folder](miniapps) and will be u
 Current (Blankenback2D, Stokes 2D-3D, thermal diffusion, thermal stress) and future benchmarks can be found in the [Benchmarks](miniapps/benchmarks).
 
 ## Funding
-The development of this package is supported by the [GPU4GEO](https://ptsolvers.github.io/GPU4GEO/) [PASC](https://www.pasc-ch.org) project.
+The development of this package is supported by the [GPU4GEO & $\partial$GPU4GEO](https://gpu4geo.org/) [PASC](https://www.pasc-ch.org) project, and the European Research Council through the MAGMA project, ERC Consolidator Grant #771143.

_typos.toml

@@ -3,5 +3,10 @@ Ths = "Ths"
 oly = "oly"
 iy = "iy"
 pn = "pn"
+
+[default]
+extend-ignore-words-re = [
+    "(?i)normale\\s+supérieure"
+]
 nd = "nd"
 Heros = "Heros"

docs/paper/paper.bib

@@ -0,0 +1,242 @@
+@article{bezanson2017julia,
+  author = {Bezanson, Jeff and Edelman, Alan and Karpinski, Stefan and Shah, Viral B.},
+  title = {Julia: A Fresh Approach to Numerical Computing},
+  journal = {SIAM Review},
+  volume = {59},
+  number = {1},
+  pages = {65-98},
+  year = {2017},
+  doi = {10.1137/141000671},
+  URL = {https://doi.org/10.1137/141000671}
+}
+
+@article{GeoParams,
+  author = {Kaus, Boris and de Montserrat, Albert and Medinger, Nils and Aellig, Pascal and Dominguez, Hugo and Riel, Nicolas and Cosarinsky, Matias and Spang, Arne and Berlie, Nicolas and Kiss, Daniel and Ranocha, Hendrik and Fuchs, Lukas and Frasunkiewicz, Jacob and Räss, Ludovic and Lueder, Mona and Seiler, Alexander and Duretz, Thibault},
+  title = {GeoParams.jl: v0.7.4},
+  year = {2025},
+  URL = {https://doi.org/10.5281/zenodo.15719680}
+}
+
+@article{JustPIC,
+  author = {de Montserrat, Albert and Aellig, Pascal and Räss, Ludovic and Duretz, Thibault and Utkin, Ivan and Kaus, Boris and Ranocha, Hendrik},
+  title = {JustPIC.jl: v0.5.10},
+  year = {2025},
+  URL = {https://doi.org/10.5281/zenodo.15704602}
+}
+
+@article{WriteVTK,
+  author = {Polanco, J. I.},
+  title = {WriteVTK.jl: a Julia package for writing VTK XML files (v1.18.0)},
+  year = {2023},
+  URL = {https://doi.org/10.5281/zenodo.7804590}
+}
+@article{Byrne2021, 
+  doi = {10.21105/jcon.00068}, 
+  url = {https://doi.org/10.21105/jcon.00068}, 
+  year = {2021}, 
+  publisher = {The Open Journal}, 
+  volume = {1}, 
+  number = {1}, 
+  pages = {68}, 
+  author = {Simon Byrne and Lucas C. Wilcox and Valentin Churavy}, 
+  title = {MPI.jl: Julia bindings for the Message Passing Interface}, 
+  journal = {Proceedings of the JuliaCon Conferences} 
+} 
+
+@article{besard2018juliagpu,
+  author        = {Besard, Tim and Foket, Christophe and De Sutter, Bjorn},
+  title         = {Effective Extensible Programming: Unleashing {Julia} on {GPUs}},
+  journal       = {IEEE Transactions on Parallel and Distributed Systems},
+  year          = {2018},
+  doi           = {10.1109/TPDS.2018.2872064},
+  ISSN          = {1045-9219},
+  archivePrefix = {arXiv},
+  eprint        = {1712.03112},
+  primaryClass  = {cs.PL},
+}
+
+@article{larionov2017variational,
+  author = {Larionov, Egor and Batty, Christopher and Bridson, Robert}, 
+  title = {Variational stokes: a unified pressure-viscosity solver for accurate viscous liquids}, 
+  year = {2017}, 
+  issue_date = {August 2017}, 
+  publisher = {Association for Computing Machinery}, 
+  address = {New York, NY, USA}, 
+  volume = {36}, 
+  number = {4},  
+  issn = {0730-0301}, 
+  url = {https://doi.org/10.1145/3072959.3073628}, 
+  doi = {10.1145/3072959.3073628},
+}
+
+@article{Harlow1965,
+    title = {{Numerical Calculation of Time‐Dependent Viscous Incompressible Flow of Fluid with Free Surface}},
+    year = {1965},
+    journal = {The Physics of Fluids},
+    author = {Harlow, Francis H. and Welch, J. Eddie},
+    number = {12},
+    month = {12},
+    pages = {2182--2189},
+    volume = {8},
+    publisher = {AIP Publishing},
+    doi = {10.1063/1.1761178},
+    issn = {0031-9171}
+}
+
+@article{Omlin2024,
+  doi = {10.21105/jcon.00137},
+  url = {https://doi.org/10.21105/jcon.00137},
+  year = {2024},
+  publisher = {The Open Journal},
+  volume = {6}, number = {65},
+  pages = {137},
+  author = {Samuel Omlin and Ludovic Räss and Ivan Utkin},
+  title = {Distributed Parallelization of xPU Stencil Computations in Julia},
+  journal = {Proceedings of the JuliaCon Conferences}
+}
+
+@article{i3elvis,
+  title={Robust characteristics method for modelling multiphase visco-elasto-plastic thermo-mechanical problems},
+  author={Gerya, Taras V and Yuen, David A},
+  journal={Physics of the Earth and Planetary Interiors},
+  volume={163},
+  number={1-4},
+  pages={83--105},
+  year={2007},
+  note = {Computational Challenges in the Earth Sciences},
+  issn = {0031-9201},
+  doi = {https://doi.org/10.1016/j.pepi.2007.04.015},
+  url = {https://www.sciencedirect.com/science/article/pii/S0031920107000969},
+  publisher={Elsevier}
+}
+
+@article{gerya2015plate,
+  title={Plate tectonics on the Earth triggered by plume-induced subduction initiation},
+  author={Gerya, Taras V and Stern, Robert J and Baes, Marzieh and Sobolev, Stephan V and Whattam, Scott A},
+  journal={Nature},
+  volume={527},
+  number={7577},
+  pages={221--225},
+  year={2015},
+  doi = {10.1038/nature15752},
+  url = {https://doi.org/10.1038/nature15752},
+  publisher={Nature Publishing Group UK London}
+}
+
+@article{Raess2022,
+  title={Assessing the robustness and scalability of the accelerated pseudo-transient method},
+  author={R{\"a}ss, Ludovic and Utkin, Ivan and Duretz, Thibault and Omlin, Samuel and Podladchikov, Yuri Y},
+  journal={Geoscientific Model Development},
+  volume={15},
+  number={14},
+  pages={5757--5786},
+  year={2022},
+  url = {https://gmd.copernicus.org/articles/15/5757/2022/},
+  doi = {10.5194/gmd-15-5757-2022},
+  publisher={Copernicus Publications G{\"o}ttingen, Germany}
+}
+
+@article{stagyy,
+  title={Modelling compressible mantle convection with large viscosity contrasts in a three-dimensional spherical shell using the yin-yang grid},
+  author={Tackley, Paul J},
+  journal={Physics of the Earth and Planetary Interiors},
+  volume={171},
+  number={1-4},
+  pages={7--18},
+  year={2008},
+  doi = {10.1016/j.pepi.2008.08.005},
+  publisher={Elsevier}
+}
+
+
+@inproceedings{lamem,
+  title={Forward and inverse modelling of lithospheric deformation on geological timescales},
+  author={Kaus, Boris JP and Popov, Anton A and Baumann, T and Pusok, A and Bauville, Arthur and Fernandez, Naiara and Collignon, Marine},
+  booktitle={Proceedings of nic symposium},
+  volume={48},
+  pages={978--983},
+  year={2016},
+  organization={John von Neumann Institute for Computing (NIC), NIC Series}
+}
+
+@article{citcom,
+  title={Role of temperature-dependent viscosity and surface plates in spherical shell models of mantle convection},
+  author={Zhong, Shijie and Zuber, Maria T and Moresi, Louis and Gurnis, Michael},
+  journal={Journal of Geophysical Research: Solid Earth},
+  volume={105},
+  number={B5},
+  pages={11063--11082},
+  year={2000},
+  doi = {https://doi.org/10.1029/2000JB900003},
+  url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2000JB900003},
+  publisher={Wiley Online Library}
+}
+
+@inproceedings{ptatin,
+  title={pTatin3D: High-performance methods for long-term lithospheric dynamics},
+  author={May, Dave A and Brown, Jed and Le Pourhiet, Laetitia},
+  booktitle={SC'14: Proceedings of the International Conference for High Performance Computing, Networking, Storage and Analysis},
+  pages={274--284},
+  year={2014},
+  organization={IEEE},
+  doi={10.1109/SC.2014.28}
+}
+
+
+@article{underworld,
+  title={Computational approaches to studying non-linear dynamics of the crust and mantle},
+  author={Moresi, L and Quenette, Steve and Lemiale, Vincent and Meriaux, C and Appelbe, B and M{\"u}hlhaus, H-B},
+  journal={Physics of the Earth and Planetary Interiors},
+  volume={163},
+  number={1-4},
+  pages={69--82},
+  year={2007},
+  doi = {10.1016/j.pepi.2007.06.009},
+  publisher={Elsevier}
+}
+
+@article{lacode,
+  title={LaCoDe: a Lagrangian two-dimensional thermo-mechanical code for large-strain compressible visco-elastic geodynamical modeling},
+  author={de Montserrat, Albert and Morgan, Jason P and Hasenclever, J{\"o}rg},
+  journal={Tectonophysics},
+  volume={767},
+  pages={228173},
+  year={2019},
+  doi = {10.1016/j.tecto.2019.228173},
+  url = {https://www.sciencedirect.com/science/article/pii/S004019511930280X},
+  publisher={Elsevier}
+}
+
+@misc{aspect,
+  title  = {{{ASPECT}: Advanced Solver for Planetary Evolution, Convection, and Tectonics, User Manual}},
+  author = {Bangerth, Wolfgang and Dannberg, Juliane and Fraters, Menno and Gassmoeller, Rene and Glerum, Anne and Heister, Timo and Myhill, Robert and Naliboff, John},
+  year   = {2024},
+  month  = dec,
+  DOI    = {10.6084/m9.figshare.4865333},
+  URL    = {https://doi.org/10.6084/m9.figshare.4865333}
+}
+
+@article{CUDA.jl,
+  author={Besard, Tim and Foket, Christophe and De Sutter, Bjorn},
+  journal={IEEE Transactions on Parallel and Distributed Systems},
+  title={Effective Extensible Programming: Unleashing Julia on GPUs},
+  year={2019},
+  volume={30},
+  number={4},
+  pages={827-841},
+  keywords={Graphics processing units;Programming;Hardware;High level languages;Libraries;Graphics processors;very high-level languages;code generation;retargetable compilers},
+  doi={10.1109/TPDS.2018.2872064}
+}
+
+@article{MPI.jl,
+  doi = {10.21105/jcon.00068},
+  url = {https://doi.org/10.21105/jcon.00068},
+  year = {2021},
+  publisher = {The Open Journal},
+  volume = {1},
+  number = {1},
+  pages = {68},
+  author = {Simon Byrne and Lucas C. Wilcox and Valentin Churavy},
+  title = {MPI.jl: Julia bindings for the Message Passing Interface},
+  journal = {Proceedings of the JuliaCon Conferences}
+}

docs/paper/paper.md

@@ -0,0 +1,95 @@
+---
+title: '`JustRelax.jl`: A Julia package for geodynamic modeling with matrix-free solvers'
+tags:
+  - Julia
+  - Geosciences
+  - Geodynamics
+  - Tectonics
+  - Geophysics
+  - Computational geosciences
+authors:
+  - name: Albert de Montserrat
+    orcid: 0000-0003-1694-3735
+    affiliation: 1
+  - name: Pascal S. Aellig
+    orcid: 0009-0008-9039-5646
+    affiliation: 2
+  - name: Christian Schuler
+    orcid: 0009-0004-9873-9774
+    affiliation: 2
+  - name: Ivan Navarrete
+    orcid: 0009-0004-9272-511X
+    affiliation: 3
+  - name: Ludovic Räss
+    orcid: 0000-0002-1136-899X
+    affiliation: 4
+  - name: Lukas Fuchs
+    orcid: 0000-0002-9165-6384
+    affiliation: 5
+  - name: Boris J.P. Kaus
+    orcid: 0000-0002-0247-8660
+    affiliation: 2
+  - name: Hugo Dominguez
+    orcid: 0009-0001-8425-0503
+    affiliation: 2
+
+affiliations:
+ - name: ETH Zürich, Switzerland
+   index: 1
+ - name: Johannes Gutenberg-University Mainz, Germany
+   index: 2
+ - name: École Normale Supérieure - PSL University, France
+   index: 3
+ - name: University of Lausanne, Switzerland
+   index: 4
+ - name: Frankfurt University, Germany
+   index: 5
+
+date: 21 October 2025
+bibliography: paper.bib
+---
+
+# Summary
+
+`JustRelax.jl` is an open source, highly portable, and high-performance [Julia](https://julialang.org/) [@bezanson2017julia] package designed for geodynamic modeling. It employs the Accelerated Pseudo-Transient (APT) method —a matrix-free, embarrassingly parallel iterative method— to solve the Stokes and diffusion equations, making it well-suited to exploit Graphics Processing Unit (GPU) hardware accelerators.
+
+`JustRelax.jl` incorporates a wide range of features critical to computational geodynamics, including complex and highly non-linear rheologies, free surface, and a particle-in-cell method to advect material information. Several of the features available in  `JustRelax.jl` are are outsourced to specialized external packages, reducing the core code base, and improving maintainability and reusability.
+
+# Statement of Need
+
+Simulating Earth's thermo-mechanical evolution requires solving coupled, nonlinear Stokes and heat‑diffusion problems across large domains with sharp material contrasts, complex rheologies and long time scales. These calculations are computationally demanding and traditionally rely on monolithic, CPU‑oriented codes built around matrix‑based linear solvers. Such designs are hard to port efficiently to modern heterogeneous HPC systems (e.g. multi‑GPU nodes).
+
+`JustRelax.jl` addresses this gap by providing a compact, modular, GPU‑ready toolkit implemented in Julia. It implements a matrix‑free Accelerated Pseudo‑Transient (APT) solver that reduces global linear‑algebra bottlenecks and ports efficiently to accelerators, while outsourcing some physical calculations, parallalelization, and IO to other packages, shown in \ref{fig:dependencies}. This keeps the core solver as contained as possible and makes the software more flexible. Julia’s high‑level syntax and package manager simplify installation, scripting and extension, lowering the barrier for students and researchers to prototype and test new physics.
+
+![Sketch of the main dependencies of `JustRelax.jl`: a) physics packages: material properties and rheology ([GeoParams.jl](https://github.com/JuliaGeodynamics/GeoParams.jl) [@GeoParams]), Particles-in-Cell based advection ([JustPIC.jl](https://github.com/JuliaGeodynamics/JustPIC.jl) [@JustPIC], where data structures are handled by [CellArrays.jl](https://github.com/omlins/CellArrays.jl)); b) parallelization: domain decomposition and distributed parallelism is handled by [ImplicitGlobalGrid.jl](https://github.com/eth-cscs/ImplicitGlobalGrid.jl) [@Omlin2024] and [MPI.jl](https://github.com/JuliaParallel/MPI.jl) [Byrne2021], and backend abstraction is implemented with [ParallelStencil.jl](https://github.com/omlins/ParallelStencil.jl) [@Omlin2024], which supports Julia's native multi-threading ([Threads.jl](https://docs.julialang.org/en/v1/manual/multi-threading/)), and NVIDIA ([CUDA.jl](https://github.com/JuliaGPU/CUDA.jl) [besard2018juliagpu]) and [AMDGPU.jl](https://github.com/JuliaGPU/AMDGPU.jl) GPU cards; and c) I/O and data visualization: HDF5 binary files ([HDF5.jl](https://github.com/JuliaIO/HDF5.jl) and [JLD2.jl](https://github.com/JuliaIO/JLD2.jl)), and VTK files for visualization ([WriteVTK.jl](https://github.com/JuliaVTK/WriteVTK.jl) [@WriteVTK]). \label{fig:dependencies}](figs/dependencies.png){width=75%}
+
+In short, `JustRelax.jl` delivers a high‑performance, portable alternative to legacy geodynamics codes: it (i) exploits modern GPUs without extensive rewrites; (ii) avoids costly matrix assembly via matrix‑free algorithms; and (iii) promotes modularity, reproducibility, and rapid development. Together with CI, scalable I/O and checkpointing, these features make `JustRelax.jl` practical for both exploratory studies and production‑scale simulations on modern multi-XPU platforms.
+
+# Methods
+
+`JustRelax.jl` solves the (in)compressible Stokes equations, described by the equations of conservation of momentum and mass, as well as the conservation of energy equation. This system of equations is solved using the APT method [@Raess2022], which transforms the elliptic PDEs into damped wave equations by augmenting them with a second order pseudo-time derivative which should vanish upon convergence, thus recovering the original form of the PDE. For an in-depth description of this method, we refer the reader to @Raess2022.
+
+# Package summary
+
+`JustRelax.jl` features:
+
+- **High-performance and scalable matrix-free solver**: `JustRelax.jl` implements the APT method for (in)compressible Stokes and diffusion problems to circumvent the need for computationally expensive linear algebra operations and direct solvers, significantly improving computational efficiency for large-scale simulations. The embarrassingly parallel nature of the APT method makes it an excellent solver to exploit hardware accelerators. The weak scaling curve of the 3D Stokes solver is shown in Fig. \ref{fig:scaling}, where the parallel efficiency is the wall-time of any simulation normalized against the wall-time of a simulation with a single process. Distributed parallelism across multiple CPU/GPU nodes is achieved with [ImplicitGlobalGrid.jl](https://github.com/eth-cscs/ImplicitGlobalGrid.jl) [@Omlin2024].
+
+![GPU weak scaling performance of `JustRelax.jl` of the three-dimensional backend, demonstrating efficient parallelization and scalability of the Stokes solver. \label{fig:scaling}](figs/efficiency_Stokes3D.png){width=50%}
+
+- **Advanced non-linear rheology**: The package supports a comprehensive suite of geologically relevant rheology models, such as visco-elasto-plastic and non-Newtonian constitutive laws, allowing for simulations with complex Earth-like materials, essential for modeling geological processes at a wide range of scales. All the local material physics calculations are computed by [GeoParams.jl](https://github.com/JuliaGeodynamics/GeoParams.jl) [@GeoParams].
+
+- **Portability**: `JustRelax.jl` is designed to run efficiently on multiple hardware architectures, including CPUs, GPUs (CUDA and AMD), and on multi-node clusters. This portability is achieved through Julia's advanced meta-programming capabilities, which generate the code for the specific target hardware during compile or parse time. This abstraction of the hardware backend is implemented in [ParallelStencil.jl](https://github.com/omlins/ParallelStencil.jl) [@Omlin2024].
+
+- **Continuous integration (CI) and testing**: The package is tested and validated against a suite of benchmarks and model examples to ensure correctness and performance on various hardware. The default CI/CD pipeline is implemented using GitHub Actions, automatically running tests on every commit and pull request. Single GPU CI is run on using JuliaGPU Buildkite and multi-GPU CI executes on the Swiss National Supercomputing Centre (CSCS) ALPS supercomputer. This ensures that the package remains robust and reliable across different hardware architectures and Julia versions.
+
+# Examples
+
+An extensive set of benchmarks and model examples are available in the GitHub repository of [`JustRelax.jl`](https://github.com/PTsolvers/`JustRelax.jl`). Some examples such as [shear band localization](https://ptsolvers.github.io/`JustRelax.jl`/dev/man/ShearBands), [2D subduction](https://ptsolvers.github.io/`JustRelax.jl`/dev/man/subduction2D/subduction2D) or the rise of a [3D plume](https://ptsolvers.github.io/`JustRelax.jl`/dev/man/plume3D/plume3D) are described in the [documentation](https://ptsolvers.github.io/`JustRelax.jl`/dev/). Here we limit ourselves to show some snapshots of the results of these examples in Fig. \ref{fig:examples}.
+
+![Model examples from the documentation: a) 2D shear band localization of a visco-elasto-viscoplastic body ($10240 \times 10240$ cells), b) 2D subduction ($512 \times 512$ cells), and c) raising of a hot plume in 3D ($128 \times 128 \times 128$ cells). All models were run on one NVIDIA GH200 Grace Hopper GPU. \label{fig:examples}](figs/models_JOSS.png)
+
+# Acknowledgments
+We acknowledge funding by the Swiss Platform for Advanced Scientific Computing (PASC) as part of the [GPU4GEO & $\partial$GPU4GEO](https://gpu4geo.org/) project, and the European Research Council through the MAGMA project, ERC Consolidator Grant #771143.
+
+# References