ODINN.jl documentation

Welcome to the ODINN.jl documentation, a large-scale scientific machine learning (SciML) glacier model, leveraging differentiable programming in Julia. This documentation provides the necessary information to understand the ecosystem built around ODINN.jl, its APIs, workflows, and some examples of the main usage types of the model(s).

Quick install

ODINN.jl is a registered Julia package, so installing it is as easy as:

julia> using Pkg

julia> Pkg.add("ODINN")

Documentation overview

The documentation, which you can navigate through the left-hand-side panel, is structured in the following way:

• Quick start: Provides a straight-to-the-point example of a simple use-case of ODINN.jl to get an idea of the basic interface and API.
• Ecosystem Packages: Per-package landing pages for each component of the ODINN ecosystem, including scientific role, standalone usage guidance, minimal examples, and developer extension guides.
• Tutorials: They provide clear examples of the main types of simulations and workflows that you can work with in ODINN.jl.
• How to use ODINN: Explains the basic building blocks (i.e. types) used in ODINN.jl simulations, and how they are assembled together.
• API: Full API reference for each package (Sleipnir, Muninn, Huginn, MassBalanceMachine, ODINN), split into separate pages for easy navigation.
• Inversions: Addresses more advanced questions related to inverse modelling, computing gradients, optimization, and machine learning.
• Community: Explains the aspects related to how to contribute to the model(s), code style, building the documentation in local, and the code of conduct.
• Ongoing changes and future plans: Self-explanatory.
• References: List of scientific papers used in this documentation.

Vision

Rather than focusing on global-scale simulations and sea-level rise contributions, ODINN.jl has, for now, a regional and catchment-scale focus, aiming to exploit the latest remote sensing and in situ observations to capture missing or subgrid glacier processes. In order to do so, ODINN.jl leverages Universal Differential Equations (UDEs) combining PDEs describing ice flow dynamics with data-driven regressors, such as neural networks [1]. For this, ODINN.jl relies heavily on the SciML Julia ecosystem and the native automatic differentiation (AD) support. Therefore ODINN.jl has a two-fold goal:

• To advance the application of SciML and differentiable programming for large-scale geoscientific modelling.
• To advance the inference of new parametrizations to characterize key missing or subgrid processes of glaciers to improve large-scale glacier simulations.

Architecture

ODINN.jl is a modular model, split into multiple packages, each one handling a specific task. The packages form a dependency chain from bottom to top: Gungnir → Sleipnir → Muninn/Huginn → ODINN.jl. Each package can be used independently for its specific role, or together through the top-level ODINN.jl interface. Dedicated landing pages for each package describe their role, standalone usage, and extension points in detail.

• Sleipnir.jl is the core package of ODINN, holding all the basic data structures and functions common to the whole ecosystem — glacier geometry (Glacier2D), climate data (Climate2D), simulation parameters, the law abstraction, and VJP infrastructure. It directly reads the files provided by Gungnir. → Sleipnir package page
• Muninn.jl is the surface mass balance module of ODINN. It implements temperature-index models, and defines the MBmodel abstract type that all mass balance models share. → Muninn package page
• MassBalanceMachine.jl is the data-driven surface mass balance module, porting neural network models trained with the Python MassBalanceMachine into Lux.jl as drop-in MBmodels. → MassBalanceMachine package page
• Huginn.jl is the ice flow dynamics module of ODINN. It contains all the information regarding glacier ice flow models, including the 2D Shallow Ice Approximation (SIA2D) and the numerical methods to solve the PDEs using OrdinaryDiffEq.jl. → Huginn package page
• ODINN.jl is the high-level interface to the whole ODINN ecosystem, containing the SciML functionalities related to automatic differentiation and sensitivity of hybrid models mixing differential equations and data-driven regressors. → ODINN package page
• Gungnir is a Python package using OGGM to retrieve all the necessary files (rasters and climate data) for the initial conditions and simulations in the ODINN ecosystem. Pre-built datasets are provided for common glacier regions; running Gungnir yourself is only required for new glaciers or custom climate sources. → Gungnir package page

Developers

ODINN.jl is being developed by Jordi Bolibar (CNRS, IGE), Facundo Sapienza (Stanford University), Alban Gossard (Université Grenoble Alpes, IGE) and Lisa Girod (PhD student, Université Grenoble Alpes, IGE).

Past developers include Mathieu Le Séac'h (Université Grenoble Alpes, IGE), Lucille Gimenes (Université Grenoble Alpes, IGE), and Vivek Gajadhar (TU Delft).

Citing

If you use ODINN.jl for research, teaching or other activities, please use the following citation from our latest publication:

@article{bolibar_sapienza_universal_2023,
	title = {Universal differential equations for glacier ice flow modelling},
	author = {Bolibar, J. and Sapienza, F. and Maussion, F. and Lguensat, R. and Wouters, B. and P\'erez, F.},
	journal = {Geoscientific Model Development},
	volume = {16},
	year = {2023},
	number = {22},
	pages = {6671--6687},
	url = {https://gmd.copernicus.org/articles/16/6671/2023/},
	doi = {10.5194/gmd-16-6671-2023}
}

Funding

The ODINN project has been funded by an ANR TRACCS early career call, an IRGA fellowship from the Multidisciplinary Institute on Artificial Intelligence (Grenoble, France), the Nederlandse Organisatie voor Wetenschappelijk Onderzoek, Stichting voor de Technische Wetenschappen (Vidi grant 016.Vidi.171.063), the National Science Foundation (EarthCube programme under awards 1928406 and 1928374) and a TU Delft Climate Action grant.