Methods, worked examples, benchmarks and design rationale for the Underworld geodynamics code. https://www.underworldcode.org/ Wed, 12 Aug 2026 04:29:16 GMT https://www.underworldcode.org/finding-particles-in-a-distributed-unstructured-mesh/ 10.6084/m9.figshare.33193611 Thu, 04 Jun 2026 00:00:00 GMT Louis Moresi Underworld Code development 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. https://www.underworldcode.org/particles-in-underworld3/ 10.6084/m9.figshare.33193599 Wed, 03 Jun 2026 00:00:00 GMT Louis Moresi Underworld Code Documentation development 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 ? https://www.underworldcode.org/symbolic-time-derivatives-in-underworld3/ 10.6084/m9.figshare.33193596 Thu, 16 Apr 2026 00:00:00 GMT Louis Moresi Underworld Code Tricks of the Trade Documentation development 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. https://www.underworldcode.org/constitutive-models-in-symbolic-form/ 10.6084/m9.figshare.33193590 Mon, 13 Apr 2026 00:00:00 GMT Louis Moresi Underworld Code Tricks of the Trade development 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. https://www.underworldcode.org/physical-units-in-computational-geodynamics/ 10.6084/m9.figshare.33193587 Wed, 08 Apr 2026 00:00:00 GMT Louis Moresi Ben Knight Underworld Code development 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 ? https://www.underworldcode.org/mesh-variables-and-petsc-vectors-keeping-arrays-in-sync/ 10.6084/m9.figshare.33193578 Fri, 03 Apr 2026 00:00:00 GMT Louis Moresi Underworld Code development 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? https://www.underworldcode.org/how-underworld3-turns-sympy-into-c/ 10.6084/m9.figshare.33193572 Wed, 01 Apr 2026 00:00:00 GMT Louis Moresi John Mansour Julian Giordani Underworld Code Tricks of the Trade development 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 ? https://www.underworldcode.org/our-journey-from-underworld2-to-underworld3/ 10.6084/m9.figshare.33193566 Mon, 23 Mar 2026 00:00:00 GMT Louis Moresi John Mansour Julian Giordani Romain Beucher Underworld Code Geodynamics Tricks of the Trade 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 ? https://www.underworldcode.org/ai-and-scientific-software-what-we-learned-rebuilding-underworld3/ 10.6084/m9.figshare.33193560 Mon, 23 Mar 2026 00:00:00 GMT Louis Moresi Underworld Code Tricks of the Trade Auscope 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. https://www.underworldcode.org/underworld3-published-in-journal-of-open-source-software/ 10.59350/a085z-qzh60 Mon, 25 Aug 2025 00:00:00 GMT Louis Moresi Julian Giordani John Mansour Underworld Code Python/Jupyter 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. https://www.underworldcode.org/new-features-of-the-surface-coupling-framework-in-underworld-2/ 10.6084/m9.figshare.33193557 Mon, 25 Aug 2025 00:00:00 GMT Neng Lu Underworld Code 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. https://www.underworldcode.org/how-many-processors-should-we-use-to-solve-problem-x/ 10.6084/m9.figshare.33193554 Sun, 27 Jul 2025 00:00:00 GMT Juan Carlos Graciosa Louis Moresi Documentation Tricks of the Trade Underworld Code 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 ? https://www.underworldcode.org/perth-youre-invited-to-the-underworld-geodynamic-modelling-workshop/ 10.59350/8vp5e-6cx59 Tue, 29 Apr 2025 00:00:00 GMT Louis Moresi Underworld Workshops Getting Started Geodynamics 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. https://www.underworldcode.org/underworld-and-singularity/ 10.6084/m9.figshare.33193545 Wed, 09 Apr 2025 00:00:00 GMT Julian Giordani Underworld Code Tricks of the Trade 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 https://www.underworldcode.org/underworld3-come-and-get-it/ 10.6084/m9.figshare.33193533 Sun, 08 Dec 2024 00:00:00 GMT Louis Moresi Underworld Code petsc Introducing Underworld3: Mathematically Self-Describing Modelling in Python for Desktop, HPC and Cloud. https://www.underworldcode.org/30-years-of-citcom-ellipsis-and-underworld/ 10.6084/m9.figshare.33193530 Tue, 16 Jan 2024 00:00:00 GMT Louis Moresi Underworld Code Geophysics Auscope 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. https://www.underworldcode.org/compressible-convection-in-cartesian-coordinates-in-underworld3/ 10.6084/m9.figshare.33193527 Wed, 04 Oct 2023 00:00:00 GMT Juan Carlos Graciosa Geodynamics 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… https://www.underworldcode.org/ismip-hom-benchmark-experiments-using-underworld/ 10.6084/m9.figshare.33193518 Mon, 20 Feb 2023 00:00:00 GMT 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 … https://www.underworldcode.org/uwgeodynamics-and-underworld-merge/ 10.59350/ng0d5-23959 Tue, 24 May 2022 00:00:00 GMT 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. https://www.underworldcode.org/using-python-virtual-environment-for-underworld-development/ 10.6084/m9.figshare.33193515 Thu, 20 Jan 2022 00:00:00 GMT Romain Beucher Documentation development Python/Jupyter 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). https://www.underworldcode.org/setting-up-underworld-dependencies/ 10.6084/m9.figshare.33193509 Thu, 20 Jan 2022 00:00:00 GMT Romain Beucher petsc installation Underworld Code 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… https://www.underworldcode.org/free-surface-in-underworld/ 10.6084/m9.figshare.33193503 Fri, 03 Dec 2021 00:00:00 GMT 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… https://www.underworldcode.org/2-11-scaling/ 10.6084/m9.figshare.33193458 Thu, 30 Sep 2021 00:00:00 GMT Julian Giordani John Mansour Underworld Code Documentation 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. https://www.underworldcode.org/how-to-install-underworld-on-mac-osx-big-sur-apple-silicon-m1/ 10.6084/m9.figshare.33193455 Tue, 07 Sep 2021 00:00:00 GMT Romain Beucher Documentation Tricks of the Trade Underworld Code 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. https://www.underworldcode.org/scaling-in-underworld/ 10.6084/m9.figshare.33193452 Tue, 09 Mar 2021 00:00:00 GMT Julian Giordani Louis Moresi John Mansour Documentation Underworld Code 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. https://www.underworldcode.org/stress-recovery-in-underworld/ 10.6084/m9.figshare.33193446 Mon, 11 Jan 2021 00:00:00 GMT Haibin Yang Geodynamics 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… https://www.underworldcode.org/build-conda-packages/ 10.6084/m9.figshare.33193440 Mon, 23 Nov 2020 00:00:00 GMT Romain Beucher Tricks of the Trade Documentation #editors-pick 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...) https://www.underworldcode.org/getting-started-with-pull-requests/ 10.6084/m9.figshare.33193434 Tue, 17 Nov 2020 00:00:00 GMT Romain Beucher Tricks of the Trade Documentation 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… https://www.underworldcode.org/here-comes-conda/ 10.59350/4c21r-t7c68 Mon, 16 Nov 2020 00:00:00 GMT Romain Beucher Underworld Code Documentation AuScope UW Cloud 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. https://www.underworldcode.org/underworld-2-10/ 10.59350/dwxt3-tgj66 Fri, 04 Sep 2020 00:00:00 GMT Julian Giordani John Mansour Underworld Code Underworld 2.10 has dropped... kidding this is a benchmark model proposed by Schmalholz, 2011, A simple analytical solution for slab detachment. https://www.underworldcode.org/stripy-2-0-released/ 10.59350/bpy2d-6ww41 Wed, 26 Aug 2020 00:00:00 GMT Ben Mather Stripy Python/Jupyter Generating Voronoi diagrams and interpolating / smoothing with spline tensions are among a list of new features in Stripy 2.0 https://www.underworldcode.org/covid-quiet-time/ 10.59350/werfa-yd829 Fri, 24 Jul 2020 00:00:00 GMT Louis Moresi Geophysics Python/Jupyter 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. https://www.underworldcode.org/australian-cities-are-quiet-during-lockdown-earthquake-scientists-are-making-the-most-of-it/ 10.59350/qpft6-wks47 Fri, 17 Jul 2020 00:00:00 GMT Louis Moresi Geodynamics Geophysics 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. https://www.underworldcode.org/self-updating-repositories/ 10.6084/m9.figshare.33193428 Fri, 17 Jul 2020 00:00:00 GMT Louis Moresi AuScope UW Cloud Tricks of the Trade Geophysics Python/Jupyter How we built a simple dashboard using Github actions with open source software and openly available (FAIR) data. https://www.underworldcode.org/publication-news/ 10.59350/1561x-bcp63 Thu, 09 Jul 2020 00:00:00 GMT Julian Giordani Geodynamics 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, https://www.underworldcode.org/underworld-low-fat-cloud/ 10.6084/m9.figshare.33193422 Mon, 06 Apr 2020 00:00:00 GMT Louis Moresi AuScope UW Cloud Underworld Code Python/Jupyter 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. https://www.underworldcode.org/underworld-2-9/ 10.59350/p0vnx-b9498 Fri, 03 Apr 2020 00:00:00 GMT John Mansour Julian Giordani Romain Beucher Louis Moresi Underworld Code 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 https://www.underworldcode.org/joss-publication-underworld-2/ 10.59350/gbzdq-dtj52 Wed, 11 Mar 2020 00:00:00 GMT John Mansour Underworld Code A new paper by John Mansour and others has just been published in the Journal of Open Source Software. https://www.underworldcode.org/getting-started-60-seconds-to-underworld/ 10.6084/m9.figshare.33193419 Thu, 21 Nov 2019 00:00:00 GMT Rohan Byrne Documentation 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. https://www.underworldcode.org/adding-zotero-references-to-a-webpage/ 10.6084/m9.figshare.33193416 Wed, 23 Oct 2019 00:00:00 GMT Louis Moresi Tricks of the Trade 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. https://www.underworldcode.org/underworld-release-2-8/ 10.59350/90fe7-qqe67 Tue, 03 Sep 2019 00:00:00 GMT John Mansour Underworld Code Documentation 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… https://www.underworldcode.org/viscoelasticity/ 10.6084/m9.figshare.33191160 Mon, 12 Aug 2019 00:00:00 GMT Rebecca Farrington Geodynamics Underworld Code #editors-pick 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$, https://www.underworldcode.org/alaska-moho-model-reproducible-research-with-containers/ 10.6084/m9.figshare.33193410 Fri, 12 Oct 2018 00:00:00 GMT Louis Moresi Stripy Geodynamics 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. https://www.underworldcode.org/underworld-on-zenodo/ 10.6084/m9.figshare.33193404 Wed, 03 Oct 2018 00:00:00 GMT Louis Moresi Documentation Zenodo is a repository for immutable versions of software that are provided with a persistent DOI for the purposes of citation and reproducibility. https://www.underworldcode.org/craton-formation-and-the-onset-of-plate-tectonics/ 10.6084/m9.figshare.33193398 Sun, 01 Apr 2018 00:00:00 GMT Louis Moresi Geodynamics Underworld Code 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 … https://www.underworldcode.org/untitled/ 10.6084/m9.figshare.33193386 Thu, 29 Jun 2017 00:00:00 GMT Adam Beall Geodynamics Underworld Code #editors-pick 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… https://www.underworldcode.org/untitled-2/ 10.6084/m9.figshare.33193380 Wed, 24 May 2017 00:00:00 GMT Romain Beucher Underworld Code #editors-pick 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… https://www.underworldcode.org/shear-bands-with-dilatancy-modelled-with-underworld/ 10.6084/m9.figshare.33193365 Fri, 05 May 2017 00:00:00 GMT Louis Moresi Geodynamics Underworld Code 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. https://www.underworldcode.org/underworld2-workshop-at-cig-2016-meeting/ 10.59350/m1brb-ah254 Mon, 29 Feb 2016 00:00:00 GMT John Mansour Underworld Code Underworld Workshops We will give a from-scratch overview of the python-based Underworld2 code using examples of interest to the mantle and lithospheric dynamics communities. https://www.underworldcode.org/underworld-and-docker-part-2/ 10.6084/m9.figshare.33193341 Tue, 15 Sep 2015 00:00:00 GMT Julian Giordani Louis Moresi AuScope UW Cloud By the way, before you read this post, catch up with how we use docker by reading part 1 https://www.underworldcode.org/underworld-and-docker-part-1/ 10.6084/m9.figshare.33193329 Tue, 01 Sep 2015 00:00:00 GMT Julian Giordani AuScope UW Cloud #editors-pick 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… https://www.underworldcode.org/underworld-2/ 10.6084/m9.figshare.33193233 Tue, 11 Aug 2015 00:00:00 GMT Louis Moresi Underworld Code 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. https://www.underworldcode.org/the-dynamics-of-continental-accretion/ 10.6084/m9.figshare.33193179 Tue, 01 Apr 2014 00:00:00 GMT Louis Moresi Geodynamics Underworld Code #editors-pick 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.