Welcome to Underworld3, a mathematically self-describing, finite-element code for geodynamic modelling. This quick-start guide has basic installation instructions and a brief introduction to some of the concepts in the Underworld3 code.
All Underworld3 source code is released under the LGPL-3 open source licence. This covers all files in underworld3 constituting the Underworld3 Python module. Notebooks, stand-alone documentation and Python scripts which show how the code is used and run are licensed under the Creative Commons Attribution 4.0 International License.
main branch
development branch
The full documentation including tutorials, API reference, and developer guides is available at:
- Documentation - tutorials, examples, and API reference
Try Underworld3 in your browser — no installation required:
v0.99 — JOSS publication release (stable)
Use scripts/binder_wizard.py to generate launch URLs for your own repositories using the Underworld3 environment.
The quickest option is not to install anything but try the binder demos above!
git clone https://github.com/underworldcode/underworld3
cd underworld3
./uw setupThe ./uw wrapper handles everything:
- Installs pixi if needed
- Guides you through environment selection
- Installs dependencies and builds underworld3
Underworld3 uses pixi to manage dependencies. The setup wizard will ask you two questions to determine which environment to install:
1. Do you need adaptive mesh refinement (AMR)?
Most users should answer No. This installs PETSc from conda-forge, which takes about 5 minutes.
Answer Yes only if you need anisotropic mesh adaptation tools (pragmatic, mmg, parmmg). This builds a custom PETSc from source with these tools enabled, which takes approximately one hour.
2. What features do you need?
Runtime (recommended): Includes PyVista for 3D visualization and JupyterLab for running tutorial notebooks. This is what most users want.
Minimal: Only the core dependencies needed to build and run underworld3. Use this for production runs on HPC systems or when you have your own visualization workflow.
Developer: Adds code quality tools (black, mypy), documentation tools, and Claude Code support. Use this if you plan to contribute to underworld3 development.
Summary of environments:
| Environment | PETSc Source | Features | Use Case |
|---|---|---|---|
runtime | conda-forge | viz, jupyter | Running tutorials and examples |
default | conda-forge | minimal | HPC production runs |
dev | conda-forge | viz, jupyter, dev tools | Contributing to underworld3 |
amr-runtime | custom build | viz, jupyter, AMR | Adaptive mesh research |
amr | custom build | minimal, AMR | AMR on HPC |
amr-dev | custom build | all features | AMR development |
After installation, open the tutorial index in JupyterLab:
./uw jupyter lab docs/beginner/tutorials/Notebook_Index.ipynbThis opens a guided introduction to underworld3 with links to all beginner tutorials.
./uw # Show status and available environments
./uw setup # (Re)configure environment
./uw build # Rebuild after source changes
./uw test# Run quick tests
./uw jupyter lab # Start JupyterLab
./uw doctor # Diagnose configuration issues
./uw status # Check for updates on GitHub
./uw update # Pull latest changes and rebuild
./uw --help # Full documentationIf you encounter build errors or import failures, run diagnostics:
./uw doctorThis checks your environment configuration and provides specific fixes for common issues like:
- Missing dependencies (PETSc, petsc4py)
- Library version mismatches
- Environment configuration problems
The ./uw build command automatically handles dependency chains—if you're missing petsc4py in an AMR environment, it will build it for you before compiling underworld3.
For more control, see the Installation Instructions
The canonical releases of the code can be found at zenodo.org.
There is a publication in the Journal of Open Source Software (doi:10.21105/joss.07831) that can be cited when using the software.
