Methods, worked examples, benchmarks and design rationale for the Underworld geodynamics code. https://www.underworldcode.org/ 2026-08-12T04:29:16Z scripts/build_feed.py https://doi.org/10.6084/m9.figshare.33193611 2026-06-04T00:00:00Z 2026-06-04T00:00:00Z Louis Moresi

It can be difficult to figure out where you are in an unstructured mesh of triangles or tetrahedra; worse when the mesh is distributed in parallel. We have to solve this problem for particle-in-cell type codes such as Underworld3. This is how we do it.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193599 2026-06-03T00:00:00Z 2026-06-03T00:00:00Z Louis Moresi

Underworld is built around the idea of active Lagrangian tracer particles that carry history and composition information as the material deforms. How do we combine this information with our symbolic mathematical framework ?

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193596 2026-04-16T00:00:00Z 2026-04-16T00:00:00Z Louis Moresi

In Underworld3, the time derivative is a symbolic object. It appears in the solver's strong form as a SymPy expression, alongside the constitutive stress and the body force.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193590 2026-04-13T00:00:00Z 2026-04-13T00:00:00Z Louis Moresi

A constitutive model is a Python class where the relationship between fluxes and gradients is encoded in SymPy. At every stage the mathematics is visible, inspectable, and differentiable. The framework handles Jacobians, C code generation, and PETSc integration. You handle the physics.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193587 2026-04-08T00:00:00Z 2026-04-08T00:00:00Z Louis Moresi Ben Knight

Non-dimensionalisation (rewriting problems to make them re-scalable from lab to the real world) is a specialised task that all modellers confront at some point. It is important for accurate and efficient numerical solutions. Can we take away the pain that comes with the task ?

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193578 2026-04-03T00:00:00Z 2026-04-03T00:00:00Z Louis Moresi

One of the less glamorous but important problems in a finite element framework is this: how does the user assign values to a field variable, and how does the framework ensure that PETSc sees those values correctly, in parallel, without the user needing to keep track themselves?

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193572 2026-04-01T00:00:00Z 2026-04-01T00:00:00Z Louis Moresi John Mansour Julian Giordani

What actually happens between the moment you write a mathematical expression in underworld3's python layer and the moment PETSc receives a finite element term in the form of compiled C code ?

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193566 2026-03-23T00:00:00Z 2026-03-23T00:00:00Z Louis Moresi John Mansour Julian Giordani Romain Beucher

Underworld is a code for geodynamics — mantle convection, lithospheric deformation, subduction, ice flow. We solve coupled, nonlinear PDEs with complex rheologies using Lagrangian particles to track material history. The project has been running for 20 years: why did we start again ?

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193560 2026-03-23T00:00:00Z 2026-03-23T00:00:00Z Louis Moresi

Underworld3 has about 50,000 lines of Python/ Cython wrapping PETSc, SymPy, and a just-in-time compiler. I began a trial of AI coding tools in 2025 and they have gradually become central to the way our team works. This is a story of co-evolution as much as it is about adoption of a new set of tools.

CC-BY-4.0 https://doi.org/10.59350/a085z-qzh60 2025-08-25T00:00:00Z 2025-08-25T00:00:00Z Louis Moresi Julian Giordani John Mansour

The aim of underworld3 is to provide strong support to users in developing sophisticated mathematical models, and provide the ability to interrogate those models during development and at run-time. Underworld3 encodes the mathematical structure of the equations it solves in symbolic form.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193557 2025-08-25T00:00:00Z 2025-08-25T00:00:00Z Neng Lu

Underworld 2's UWGeodynamic module enables the coupling of tectonics and surface processes models, most notably, with Underworld 2 handling the tectonics and Badlands (Salles, Ding, & Brocard, 2018) handling the surface processes.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193554 2025-07-27T00:00:00Z 2025-07-27T00:00:00Z Juan Carlos Graciosa Louis Moresi

Parallel computation puts many CPUs to work on solving a problem much more quickly than one CPU alone. But this only works if the tasks are carefully scheduled and the additional CPUs are not waiting around for something to do. How do we choose the right number of processors for a given problem ?

CC-BY-4.0 https://doi.org/10.59350/8vp5e-6cx59 2025-04-29T00:00:00Z 2025-04-29T00:00:00Z Louis Moresi

You are invited to a full-day workshop on Underworld — a computational Geodynamics / Tectonics modelling framework. This is an excellent opportunity for researchers, students, and professionals interested in computational geodynamics and Earth science modelling to learn about Underworld.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193545 2025-04-09T00:00:00Z 2025-04-09T00:00:00Z Julian Giordani

TL; DR: Underworld is now Singularity-enabled, making it easier and somewhat quicker to use compared to traditional HPC installs. We demonstrate results using over 10,000 CPUs and more than one billion unknowns for solving the Stokes equation with Underworld 2.16

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193533 2024-12-08T00:00:00Z 2024-12-08T00:00:00Z Louis Moresi

Introducing Underworld3: Mathematically Self-Describing Modelling in Python for Desktop, HPC and Cloud.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193530 2024-01-16T00:00:00Z 2024-01-16T00:00:00Z Louis Moresi

CITCOM is a geodynamics modelling code based on the finite element method that is designed for planetary evolution modelling where large spatial variations and strong non-linearities occur in the material properties.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193527 2023-10-04T00:00:00Z 2023-10-04T00:00:00Z Juan Carlos Graciosa

The convection of the Earth’s mantle is usually modelled as an incompressible process, referred to as the Boussinesq approximation. However, in the Earth’s mantle, the pressure increase associated with depth also increases the density due to self-compression (King et al. 2010). In some applications, this compressibility may be non-negligible and modelling it may be desirable. Over the years, sever…

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193518 2023-02-20T00:00:00Z 2023-02-20T00:00:00Z Haibin Yang

Numerical models have become an indispensable tool for understanding and predicting the flow of ice sheets and glaciers. Here we present the full-Stokes software package Underworld to the glaciological community. The code is already well established in simulating complex geodynamic systems. Advantages for glaciology are that it provides a full-Stokes solution for elastic–viscous–plastic materials …

CC-BY-4.0 https://doi.org/10.59350/ng0d5-23959 2022-05-24T00:00:00Z 2022-05-24T00:00:00Z Romain Beucher

In an effort to simplify maintenance and compatibility between Underworld and UWGeodynamics, we have decided to merge the codes into a single repository.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193515 2022-01-20T00:00:00Z 2022-01-20T00:00:00Z Romain Beucher

The Underworld Community has been supporting usage of Docker containers for developing and running Underworld powered scientific models. They provide a good option to control the running environment (dependencies).

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193509 2022-01-20T00:00:00Z 2022-01-20T00:00:00Z Romain Beucher

The following is compatible with Ubuntu 20.04 under Windows 10/11 WSL 2 (Windows Subsystem for Linux). PETSc, the Portable, Extensible Toolkit for Scientific Computation is the main dependency required for building Underworld. In the following, I will describe my current workflow for configuring and installing PETSc on Linux. The instructions are also valid for the Windows Subsystem for Linux (WSL…

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193503 2021-12-03T00:00:00Z 2021-12-03T00:00:00Z Neng Lu

Geodynamic simulations increasingly rely on models with a true free surface to investigate questions of tectonic deformation, mantle convection, and coupling of surface processes and lithosphere dynamics. Historically, most mantle convection simulations have been performed with free-slip boundary conditions at the surface. However, the Earth's surface is a free surface, which implies that both nor…

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193458 2021-09-30T00:00:00Z 2021-09-30T00:00:00Z Julian Giordani John Mansour

How does Underworld scale on a HPC? In this post we showcase how Underworld 2.11 scales across two of Australia's premiere HPC systems.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193455 2021-09-07T00:00:00Z 2021-09-07T00:00:00Z Romain Beucher

The new generation of Apple Mac comes with the new Apple Silicon (M1) chip which has an Arm architecture (as opposed to the older generation that had i386 Intel processor). This brings all manner of troubles and requirements for the development of codes.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193452 2021-03-09T00:00:00Z 2021-03-09T00:00:00Z Julian Giordani Louis Moresi John Mansour

To test scalability we run weak scaling tests on various HPC machines to check the numerical framework remains robust when pushing for higher fidelity models.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193446 2021-01-11T00:00:00Z 2021-01-11T00:00:00Z Haibin Yang

The classical finite element method (FEM) has been widely used to simulate diverse problems in engineering. Unlike most engineering problems, geological simulations are dominated by emergence of geometrical structures due to the non-linear processes involved. For the structurally conforming FEM meshes, the large deformations result in distorted meshes, which often require repeated re-meshing in co…

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193440 2020-11-23T00:00:00Z 2020-11-23T00:00:00Z Romain Beucher

As mentioned, packages can be installed directly from our conda channel. You may however want to build your own package at some point in the future or you may want to fix some of ours by submitting a Pull Request on github (You are more welcome to do so...)

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193434 2020-11-17T00:00:00Z 2020-11-17T00:00:00Z Romain Beucher

The open source community is by definition "open" to suggestions, new code submissions etc. The Underworld group adheres entirely to its philosophy and we aim at developing a broad community of not only users but contributors. We have, however, been quite frustrated to see that very few people do submit pull requests to our code base.. and we would like you to help us fixing this! Submitting fixes…

CC-BY-4.0 https://doi.org/10.59350/4c21r-t7c68 2020-11-16T00:00:00Z 2020-11-16T00:00:00Z Romain Beucher

Sharing a workflow environment is also paramount if we want to make sure that reproducibility can be effectively tested. An environment management system such as conda allows us to do so.

CC-BY-4.0 https://doi.org/10.59350/dwxt3-tgj66 2020-09-04T00:00:00Z 2020-09-04T00:00:00Z Julian Giordani John Mansour

Underworld 2.10 has dropped... kidding this is a benchmark model proposed by Schmalholz, 2011, A simple analytical solution for slab detachment.

CC-BY-4.0 https://doi.org/10.59350/bpy2d-6ww41 2020-08-26T00:00:00Z 2020-08-26T00:00:00Z Ben Mather

Generating Voronoi diagrams and interpolating / smoothing with spline tensions are among a list of new features in Stripy 2.0

CC-BY-4.0 https://doi.org/10.59350/werfa-yd829 2020-07-24T00:00:00Z 2020-07-24T00:00:00Z Louis Moresi

A new study by an international team of scientists found lockdown measures to stop the spread of COVID-19 led to a 50 per cent reduction in seismic noise around the world. The researchers, including Meghan Miller and Louis Moresi from ANU analysed datasets from over 300 seismic stations.

CC-BY-4.0 https://doi.org/10.59350/qpft6-wks47 2020-07-17T00:00:00Z 2020-07-17T00:00:00Z Louis Moresi

Meghan S. Miller (ANU) Louis Moresi (ANU) Our responses to the COVID-19 pandemic have dramatically changed human activity all over the world. Sensitive instruments are detecting far less of the noise and vibration produced by humans in motion.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193428 2020-07-17T00:00:00Z 2020-07-17T00:00:00Z Louis Moresi

How we built a simple dashboard using Github actions with open source software and openly available (FAIR) data.

CC-BY-4.0 https://doi.org/10.59350/1561x-bcp63 2020-07-09T00:00:00Z 2020-07-09T00:00:00Z Julian Giordani

The Underworld team would like to congratulate Bénédicte Cenki-Tok and co-authors at the University of Sydney and the University of Montpellier on their recent publication,

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193422 2020-04-06T00:00:00Z 2020-04-06T00:00:00Z Louis Moresi

We built a cheap-and-cheerful solution with persistent storage and a binder-like access to notebooks in a repository that is aimed at serving a single classroom. The zero-to-server time is just a few minutes and there is minimal manual configuration.

CC-BY-4.0 https://doi.org/10.59350/p0vnx-b9498 2020-04-03T00:00:00Z 2020-04-03T00:00:00Z John Mansour Julian Giordani Romain Beucher Louis Moresi

The Underworld 2.9 release is available from Github, as a docker container and via zenodo (doi:10.5281/zenodo.3964957) it is also available through pip install for the first time

CC-BY-4.0 https://doi.org/10.59350/gbzdq-dtj52 2020-03-11T00:00:00Z 2020-03-11T00:00:00Z John Mansour

A new paper by John Mansour and others has just been published in the Journal of Open Source Software.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193419 2019-11-21T00:00:00Z 2019-11-21T00:00:00Z Rohan Byrne

As the old truism states, the best way to learn is by doing. This guide can get you from zero to hero in 60 seconds - give or take.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193416 2019-10-23T00:00:00Z 2019-10-23T00:00:00Z Louis Moresi

We need to curate all the publications that we can find that use the underworld geodynamics code and provide this information on our website. To avoid needless repetition, we take advantage of the fact that nearly all the information we require is online and automatically construct the bibliography from an online public zotero library.

CC-BY-4.0 https://doi.org/10.59350/90fe7-qqe67 2019-09-03T00:00:00Z 2019-09-03T00:00:00Z John Mansour

Version 2.8 of Underworld has been released recently. As with all major releases, this release brings numerous new features, enhancements and bug fixes. A summary of changes may be found within the usual CHANGES.md file. As is also usually the case, numerous API changes have been necessary or warranted. Most significantly, this release marks a departure from Python2 compatibility, with this and al…

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33191160 2019-08-12T00:00:00Z 2019-08-12T00:00:00Z Rebecca Farrington

Viscoelastic materials exhibit the properies of both solids and liquids, with deformation rates dependent on both the viscous stress and elastic stress rate. In a Maxwell viscoelastic material the strain rate $D$ is proportional to the sum of the stress $\tau$ and the stress rate $\dot\tau$,

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193410 2018-10-12T00:00:00Z 2018-10-12T00:00:00Z Louis Moresi

Making your research reproducible means that you provide the entire workflow from data, through software and post-processing freely available. Not only can somebody repeat your experiments and verify them, they can build upon them. In lab-based disciplines, there are many further challenges, but in research that is predominantly based on data processing, this ought to be an achievable goal.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193404 2018-10-03T00:00:00Z 2018-10-03T00:00:00Z Louis Moresi

Zenodo is a repository for immutable versions of software that are provided with a persistent DOI for the purposes of citation and reproducibility.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193398 2018-04-01T00:00:00Z 2018-04-01T00:00:00Z Louis Moresi

Cratons are anomalously-strong regions of the continents that have largely resisted tectonic forces for billions of years. How such strong zones could be forged in a hot, low-viscosity, low stress, early-Earth has been a long-standing puzzle for geologists. Adam Beall, Katie Cooper and I have recently proposed that cratons were made by the catastrophic switching on of plate tectonics. An event in …

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193386 2017-06-29T00:00:00Z 2017-06-29T00:00:00Z Adam Beall

Within the plate tectonics framework, continents are generally considered to have a much lower density than the asthenosphere below and therefore avoid the kind of recycling that the oceanic crust and lithosphere undergoes. The mantle lithosphere below some continents however can become denser than the asthenosphere when it cools to a steady-state geotherm, which is an unstable configuration. Some…

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193380 2017-05-24T00:00:00Z 2017-05-24T00:00:00Z Romain Beucher

Using physical units and how to appropriately scale a model is a top question users ask when beginning with Underworld. The equations Underworld solves are stated in a physically correct form, they remain valid as long as every material constant, geometry, time, etc., are expressed in the same system. There is no explicit concept of units no scaling in Underworld, the choice is entirely left to th…

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193365 2017-05-05T00:00:00Z 2017-05-05T00:00:00Z Louis Moresi

In honour of Hans Mühlhaus' 70th birthday this month, here are some shear band simulations made with Underworld. We are investigating the role of dilatancy in the geometry of the shear bands for a box of material when a small trapdoor is opened.

CC-BY-4.0 https://doi.org/10.59350/m1brb-ah254 2016-02-29T00:00:00Z 2016-02-29T00:00:00Z John Mansour

We will give a from-scratch overview of the python-based Underworld2 code using examples of interest to the mantle and lithospheric dynamics communities.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193341 2015-09-15T00:00:00Z 2015-09-15T00:00:00Z Julian Giordani Louis Moresi

By the way, before you read this post, catch up with how we use docker by reading part 1

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193329 2015-09-01T00:00:00Z 2015-09-01T00:00:00Z Julian Giordani

While huge improvements in usability have been achieved in Underworld2, the installation process is still unfortunately as painful as ever. This difficulty is in large part due to Underworld's numerous dependencies, and also the multiple platforms we try to support. Compounding this, the legacy of a individual user's machine often conspires against success, rarely in obvious ways. Simply, compilin…

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193233 2015-08-11T00:00:00Z 2015-08-11T00:00:00Z Louis Moresi

Underworld is our parallel, particle-in-cell, finite element geodynamics code [1]. For the past year or so, the Underworld team has been working on a refurbished user interface. We've known for a long time that it needed to be done but we finally bit the bullet.

CC-BY-4.0 https://doi.org/10.6084/m9.figshare.33193179 2014-04-01T00:00:00Z 2014-04-01T00:00:00Z Louis Moresi

In a recent paper [1], we used Underworld models to examine subduction congestion associated with the ingestion of a continental ribbon. The SE Australian geological record turned out to be a wonderful place to study this process. Here is a short summary of the work for a relatively non-technical audience that we put together and some additional figures which I prepared.

CC-BY-4.0