Developer Documentation¶

This comprehensive documentation provides everything you need to understand, contribute to, and extend the Underworld3 computational geodynamics framework.

What is Underworld3?¶

Underworld3 is a Python library for computational geodynamics and geophysical modeling, built on a foundation of:

PETSc parallel computing for scalable finite element methods
SymPy symbolic mathematics for mathematical self-description
Particle-in-cell methods for Lagrangian tracking
Natural mathematical syntax for intuitive model development

Getting Started¶

Tip

Quick Navigation for Developers

New to UW3? → Start with Development Setup
Working with math expressions? → See Mathematical Objects
Handling data arrays? → Check NDArray System
Need coding standards? → Reference Style Guide

Documentation Authority Map¶

One governing document per topic (this records the UW3 Style Charter §10 authority map — the Charter itself wins on any conflict). Other documents on the same topic are reference or historical material subordinate to the governing document.

Topic	Governing document
Coding style & API conventions	UW3 Style Charter (detailed reference: Style Guide)
Data access	subsystems/data-access.md (internals reference: NDArray System)
Local scattered-point interpolation	subsystems/interpolation.md
Units	design/UNITS_SIMPLIFIED_DESIGN_2025-11.md
Testing tiers	TESTING-RELIABILITY-SYSTEM.md
Branching & releases	guides/branching-strategy.md
Docstring format	NumPy/Sphinx with RST `:math:` — Charter §6 and the Style Guide docstring section
Documentation file format	MyST Markdown (`.md`) for Sphinx — CLAUDE.md “Documentation Requests” section

Documentation Structure¶

This documentation is organized into focused sections:

Getting Started — Development setup and contributing guidelines
Guides — Practical how-to guides for scripts, notebooks, gmsh, code review
Architecture — Mathematical objects and NDArray system internals
Design Documents — Architecture decisions and design rationale
Subsystems — Detailed documentation of each code module
Advanced Topics — Solver development, MPI parallelism, PETSc integration

Development Workflow¶

Underworld3 follows established patterns for maintaining code quality:

Feature Branch → Development → Testing → Documentation → Code Review → Integration

Key Principles¶

Solver Stability: Preserve performance of validated numerical methods
Backward Compatibility: Smooth migration paths for API changes
Mathematical Clarity: Code should look like mathematical equations
Parallel Safety: All operations designed for distributed computing
Progressive Enhancement: New features coexist with legacy patterns

Quick Reference¶

Common Development Tasks¶

Task	Documentation	Quick Link
Set up development environment	Development Setup	Environment configuration
Understand data access patterns	NDArray System	`var.array[...] = values`
Write mathematical expressions	Mathematical Objects	`momentum = density * velocity`
Follow coding standards	Style Guide	Patterns and conventions
Add new functionality	Contributing	Development workflow
Debug parallel issues	MPI Parallelism	Parallel debugging

Build and Test Commands¶

# Build Underworld3 with pixi
pixi run underworld-build

# Run test suite
pixi run underworld-test

# Build documentation
pixi run docs-build

Community and Support¶

Repository: github.com/underworldcode/underworld3
Issues: Report bugs and request features on GitHub
Discussions: Join the community for questions and collaboration
Documentation: Help improve these docs through pull requests

Note

About This Documentation This developer documentation covers Underworld3 version 0.99+. It includes both conceptual guides and practical implementation details for contributing to the Underworld3 ecosystem.