Getting Started

Welcome to Underworld3! This section provides everything you need to start building geodynamic models.

Learning Path

1. Installation

Get Underworld3 running on your system in about 5 minutes:

git clone https://github.com/underworldcode/underworld3
cd underworld3
./uw setup

→ Installation Guide

2. Quick Start

Understand the basics and see your first model.

→ Quick Start Tutorial

3. Script Parameters

Configure your models for notebooks and command-line execution.

→ Parameters Guide

4. XDMF / HDF5 Compatibility

Understand the PETSc output-format change and how to write ParaView-ready XDMF/HDF5.

→ XDMF / HDF5 Compatibility Guide

5. Interactive Tutorials

Work through hands-on notebooks covering all core concepts.

→ Start Tutorials

Tutorial Sequence

Our tutorial notebooks build progressively:

Fundamentals

  1. Meshes — Creating and visualising computational meshes

  2. Variables — Defining fields on meshes and swarms

  3. Symbolic Forms — Mathematical expressions with SymPy

Solvers

  1. Poisson Solver — Solving diffusion problems

  2. Poisson Validation — Validating against analytical solutions

  3. Stokes Flow — Incompressible fluid dynamics

Time Dependence

  1. Timestepping — Advection-diffusion with analytical comparison

  2. Coupled Timestepping — Stokes + thermal convection loop

  3. Unsteady Flow — Navier-Stokes pipe flow

Materials and Particles

  1. Particle Swarms — Lagrangian tracking and swarm variables

  2. Multi-Material Models — SolCx benchmark with index swarms

Units and Scaling

  1. Units System — Physical units with Pint

  2. Non-Dimensional Scaling — Reference quantities and ND solves

  3. Timestepping with Units — Advection-diffusion with physical units

  4. Thermal Convection — Rayleigh-Benard in an annulus

What’s Next?

Once comfortable with the basics, explore:

Getting Help