A modular open source glacier model in Python

OGGM is an open source modelling framework able to simulate past and future mass-balance, volume and geometry of (almost) any glacier in the world, in a fully automated and extensible workflow.

The model accounts for glacier geometry (including contributory branches) and includes an explicit ice dynamics module. We rely exclusively on publicly available data for calibration and validation. OGGM is modular and supports novel modelling workflows: it LOVES to be remixed and reused!

This webpage is for the software documentation: for general information about the OGGM project and related news, visit oggm.org.

Warning

This is the model documentation for users and developers as of version 1.4.0. For the documentation of the latest (cutting-edge) repository version, visit docs.oggm.org/en/latest.

IARPC presentation (April 2020)

If you are new to OGGM would like a short introduction, here is a recent 15’ presentation about the project:

Slides available here

Principles

Physical principles implemented in the model and their underlying assumptions. For more detailed information, we recommend to read the OGGM description paper.

• Introduction
• Glacier flowlines
• Mass-balance
• Ice dynamics
• Bed inversion
• Frontal ablation

Introduction

We illustrate with an example how the OGGM workflow is applied to the Tasman Glacier in New Zealand (see figure below). Here we describe shortly the purpose of each processing step, while more details are provided in other sections:

Preprocessing

The glacier outlines are extracted from a reference dataset (RGI) and projected onto a local gridded map of the glacier (Fig. a). Depending on the glacier location, a suitable source for the topographical data is downloaded automatically and interpolated to the local grid. The spatial resolution of the map depends on the size of the glacier.

Flowlines

The glacier centerlines are computed using a geometrical routing algorithm (Fig. b), then filtered and slightly modified to become glacier “flowlines” with a fixed grid spacing (Fig. c).

Catchment areas and widths

The geometrical widths along the flowlines are obtained by intersecting the normals at each grid point with the glacier outlines and the tributaries’ catchment areas. Each tributary and the main flowline has a catchment area, which is then used to correct the geometrical widths so that the flowline representation of the glacier is in close accordance with the actual altitude-area distribution of the glacier (Fig. d).

Climate data and mass-balance

Gridded climate data (monthly temperature and precipitation) are interpolated to the glacier location and corrected for altitude at each flowline’s grid point. A carefully calibrated temperature-index model is used to compute the mass-balance for any month in the past.

Ice thickness inversion

Using the mass-balance data computed above and relying on mass-conservation considerations, an estimate of the ice flux along each glacier grid point cross-section is computed by making assumptions about the shape of the cross-section (parabolic, rectangular or trapezoid). Using the physics of ice flow and the shallow ice approximation, the model then computes the thickness of the glacier along the flowlines and the total volume of the glacier (Fig. e).

Glacier evolution

A dynamical flowline model is used to simulate the advance and retreat of the glacier under preselected climate time series. Here (Fig. f), a 120-yrs long random climate sequence leads to a glacier advance.

New in version 1.4!

Since v1.4, OGGM now has another way to compute flowlines via binned elevation bands [Huss_Farinotti_2012]. See Glacier flowlines for more details.

Glacier flowlines

Computing the flowlines is the first task to run after the definition of the local map and topography.

OGGM is a “flowline model”, which means that the glacier ice flow is assumed to happen along a representative “1.5D” flowline, as in the image below. “1.5D” here is used to emphasize that although glacier ice can flow only in one direction along the flowline, each point of the glacier has a geometrical width. This width means that flowline glaciers are able to match the observed area-elevation distribution of true glaciers, and can parametrize the changes in glacier width with thickness changes.

Example of a glacier flowline. Background image from http://www.swisseduc.ch/glaciers/alps/hintereisferner/index-de.html

New in version 1.4!

Since v1.4, OGGM now has two different ways to convert a 2D glacier into a 1.5 flowline glacier:

1. via geometrical centerlines, which are computed from the glacier geometry and routing algorithms. This was the single option in OGGM before v1.4.
2. via binned elevation bands flowlines, which are computed by the binning and averaging of 2D slopes into a “bulk” flowline glacier. This is the method first developed and applied by [Huss_Farinotti_2012].

Both methods have strengths and weaknesses, which we discuss in more depth below. First, let’s have a look at how they work.

Geometrical centerlines

Centerline determination

Our algorithm is an implementation of the procedure described by Kienholz et al., (2014). Appart from some minor changes (mostly the choice of some parameters), we stay close to the original algorithm.

The basic idea is to find the terminus of the glacier (its lowest point) and a series of centerline “heads” (local elevation maxima). The centerlines are then computed with a least cost routing algorithm minimizing both (i) the total elevation gain and (ii) the distance to the glacier terminus:

In [1]: graphics.plot_centerlines(gdir)

The glacier has a major centerline (the longest one), and tributary branches (in this case: two). The Hintereisferner glacier is a good example of a wrongly outlined glacier: the two northern glacier sub-catchments should have been classified as independant entities since they do not flow to the main flowline (more on this below).

At this stage, the centerlines are still not fully suitable for modelling. Therefore, a rather simple procedure converts them to “flowlines”, which now have a regular grid spacing (which they will keep for the rest of the workflow). The tail of the tributaries are cut of before reaching the flowline they are tributing to:

In [2]: graphics.plot_centerlines(gdir, use_flowlines=True)

This step is needed to better represent glacier widths at flowline junctions. The empty circles on the main flowline indicate the location where the respective tributaries are connected (i.e. where the ice flux that is originating from the tributary will be added to the main flux when running the model dynamic).

Downstream lines

For the glacier to be able to grow, we need to determine the flowlines downstream of the current glacier geometry:

In [3]: graphics.plot_centerlines(gdir, use_flowlines=True, add_downstream=True)

The downsteam lines area is also computed using a routing algorithm minimizing the distance between the glacier terminus and the border of the map as well as the total elevation gain, therefore following the valley floor.

Catchment areas

Each flowline has its own “catchment area”. These areas are computed using similar flow routing methods as the one used for determining the flowlines. Their purpose is to attribute each glacier pixel to the right tributary in order to compute mass gain and loss for each tributary. This will also influence the later computation of the glacier widths:

In [4]: tasks.catchment_area(gdir)

In [5]: graphics.plot_catchment_areas(gdir)

Flowline widths

Finally, the flowline widths are computed in two steps.

First, we compute the geometrical width at each grid point. The width is drawn from the intersection of a line perpendicular to the flowline and either (i) the glacier outlines or (ii) the catchment boundaries:

In [6]: tasks.catchment_width_geom(gdir)

In [7]: graphics.plot_catchment_width(gdir)

Then, these geometrical widths are corrected so that the altitude-area distribution of the “flowline-glacier” is as close as possible as the actual distribution of the glacier using its full 2D geometry. This correction is responsible for the large widths of the main red flowline in its upper part. This width increase comes from the two northern glacier sub-catchments that are not included in the main flowline.

In [8]: tasks.catchment_width_correction(gdir)

In [9]: graphics.plot_catchment_width(gdir, corrected=True)

Note that a perfect match is not possible since the sample size is not the same between the “1.5D” and the 2D representation of the glacier, but it’s close enough.

Elevation bands flowlines

The “elevation bands flowlines” method is another way to transform a glacier into a flowline. The implementation is considerably easier as the geometrical centerlines, and is used in [Huss_Farinotti_2012], [Huss_Hock_2015] as well as [Werder_et_al_2019]. We follow the exact same methodology.

The elevation range of the glacier is divided into N equal bands, each spanning an elevation difference of \(\Delta z\) = 30 m (this parameter can be changed). The area of each band is calculated by summing the areas of all cells in the band. A representative slope angle for each band is needed for estimating the ice flow. This calculation is also critical as it will determine the horizontal length of an elevation band and hence the overall glacier length. This slope is computed as the mean of all cell slopes over a certain quantile range (see [Werder_et_al_2019] for details), chosen to remove outliers and to return a slope angle that is both representative of the main trunk of the glacier and somewhat consistent with its real length.

The flowlines obtained this way have an irregular spacing, dependant on the bin size and slope. For OGGM, we then convert this first flowline to a regularly space one by interpolating to the target resolution, which is the same as the geometrical centerlines (default: 2 dx of the underlying map).

The resulting glacier flowlines can be understood as a “bulk” representation of the glacier, representing the average size and slope of each elevation band.

Compatibility within the OGGM framework

Both methods are creating a “1.5D” glacier. After computation, both representations are programmatically equivalent for the ice thickness inversion and ice dynamics models. They are both stored as a list of Centerline objects. Glaciers can have only one elevation-band flowline per glacier, while there can be several geometrical centerlines. The downstream lines are computed the same way for both the elevation-band and geometrical flowlines.

Both flowline types are available for download and for use in the OGGM framework. The plot below has been obtained from the centerlines versus elevation-band flowlines comparison tutorial.

Cross-sections of the two flowline types at the example Hintereisferner with OGGM version 1.4. Note the different lengths. The main flowline in the geometrical centerline case does not reach as high here because other flowlines (tributaries) are higher for this glacier.

Pros and cons of both methods

Since the flowline representation of the glacier is always a simplification, it is impossible to say which method “is best”.

This list below tries to be as objective as possible and can help you decide on which to pick. At the individual glacier scale, the impact on the results can be large, but our own quick assessment shows that at the global scale the differences are rather small (yet to be quantified with more precision).

Geometrical centerlines

• Pros:

  • Closer to the “true” length of the glacier.
  • Grid points along the centerlines preserve their geometrical information, i.e. one can compute the exact location of ice thickness change.
  • It is possibile to have different model parameters for each flowline (e.g. different mass-balance models), although this is comming with its own challenges.
  • Arguably: better suitability for mass-balance parameterizations taking glacier geometry and exposition into account.
  • Arguably: better representation of the main glacier flow?

• Cons:

  • Complex and error prone: considerably more code than the elevation band flowlines.
  • Less robust: more glaciers are failing in the preprocessing than with the simpler method. When glaciers are badly outlined (or worse, when ice caps are not properly divided), or with bad DEMs, the geometrical flowline can “look” very ugly.
  • Computationally expensive (more grid points on average, more prone to numerical instabilities).
  • Complex handling of mass-balance parameters for tributaries at the inversion (leading to multiple temperature sensitivity parameters for large glaciers).

Summary

When to use: when geometry matters, and when length is a important variable. For mountain glaciers (e.g. Alps, Himalayas).

When not to use: for ice caps, badly outlined glaciers, very large and flat glaciers, for global applications where geometrical details matters less.

Elevation-band flowlines

• Pros:

  • Robust approach: much less sensitive to DEM and outline errors. This is probably its best attribute, and makes it very interesting for large-scale applications.
  • Computationally cheap and simple: less error prone.
  • Arguably: better representation of the main glacier flow?

• Cons:

  • Geometry is lost, glaciers cannot be plotted on a map anymore.
  • Glacier length is not the “true” length.
  • Somewhat arbitrary: it’s not clear why averaging the slopes with subjectively chosen quantiles is a good idea.
  • Only one flowline.

Summary

When to use: when “true” geometry does not matter. When doing simulations at large scales, and when robustness to bad / uncertain boundary conditions is important.

When not to use: when glacier geometry or (absolute) length matters.

As of OGGM v1.4, the OGGM developers use both representations: elevation bands at the global scale, and geometrical centerlines for simulations in mountain regions where geometry matters (e.g. hazards assessments).

References

[Huss_Farinotti_2012]

(1, 2) Huss, M. and Farinotti, D.: Distributed ice thickness and volume of all glaciers around the globe, J. Geophys. Res. Earth Surf., 117(4), F04010, doi:10.1029/2012JF002523, 2012.

[Huss_Hock_2015]

Huss, M. and Hock, R.: A new model for global glacier change and sea-level rise, Front. Earth Sci., 3(September), 1–22, doi:10.3389/feart.2015.00054, 2015.

[Werder_et_al_2019]

(1, 2) Werder, M. A., Huss, M., Paul, F., Dehecq, A. and Farinotti, D.: A Bayesian ice thickness estimation model for large-scale applications, J. Glaciol., 1–16, doi:10.1017/jog.2019.93, 2019.

Implementation details

Shared setup for these examples:

import geopandas as gpd
import oggm
from oggm import cfg, tasks
from oggm.utils import get_demo_file, gettempdir

cfg.initialize()
cfg.set_intersects_db(get_demo_file('rgi_intersect_oetztal.shp'))
cfg.PATHS['dem_file'] = get_demo_file('hef_srtm.tif')

base_dir = gettempdir('Flowlines_Docs')
cfg.PATHS['working_dir'] = base_dir
entity = gpd.read_file(get_demo_file('Hintereisferner_RGI5.shp')).iloc[0]
gdir = oggm.GlacierDirectory(entity, base_dir=base_dir, reset=True)

tasks.define_glacier_region(gdir)
tasks.glacier_masks(gdir)
tasks.compute_centerlines(gdir)
tasks.initialize_flowlines(gdir)
tasks.compute_downstream_line(gdir)

Mass-balance

The mass-balance (MB) model implemented in OGGM is an extended version of the temperature-index model presented by Marzeion et al., (2012). While the equation governing the mass-balance is that of a traditional temperature-index model, our special approach to calibration requires that we spend some time describing it.

Note

OGGM v1.4 will probably be the last model version relying on this mass-balance model only. Considerable development efforts are made to give more options to the user (see e.g. the mass-balance sandbox or PyGem, which is close to be fully compatible with OGGM).

Climate data

The MB model implemented in OGGM needs monthly time series of temperature and precipitation. The current default is to download and use the CRU TS data provided by the Climatic Research Unit of the University of East Anglia.

CRU (default)

If not specified otherwise, OGGM will automatically download and unpack the latest dataset from the CRU servers.

Warning

While the downloaded zip files are ~370mb in size, they are ~5.6Gb large after decompression!

The raw, coarse (0.5°) dataset is then downscaled to a higher resolution grid (CRU CL v2.0 at 10’ resolution) following the anomaly mapping approach described by Tim Mitchell in his CRU faq (Q25). Note that we don’t expect this downscaling to add any new information than already available at the original resolution, but this allows us to have an elevation-dependent dataset based on a presumably better climatology. The monthly anomalies are computed following [Harris_et_al_2010] : we use standard anomalies for temperature and scaled (fractional) anomalies for precipitation.

ERA5 and CERA-20C

Since OGGM v1.4, users can also use reanalysis data from the ECMWF, the European Centre for Medium-Range Weather Forecasts based in Reading, UK. OGGM can use the ERA5 (1979-2019, 0.25° resolution) and CERA-20C (1900-2010, 1.25° resolution) datasets as baseline. One can also apply a combination of both, for example by applying the CERA-20C anomalies to the reference ERA5 for example (useful only in some circumstances).

HISTALP

If required by the user, OGGM can also automatically download and use the data from the HISTALP dataset (available only for the European Alps region, more details in [Chimani_et_al_2012]. The data is available at 5’ resolution (about 0.0833°) from 1801 to 2014. However, the data is considered spurious before 1850. Therefore, we recommend to use data from 1850 onwards.

In [1]: example_plot_temp_ts()  # the code for these examples is posted below

User-provided climate dataset

You can provide any other dataset to OGGM. See the HISTALP_oetztal.nc data file in the OGGM sample-data folder for an example format.

GCM data

OGGM can also use climate model output to drive the mass-balance model. In this case we still rely on gridded observations (e.g. CRU) for the reference climatology and apply the GCM anomalies computed from a preselected reference period. This method is often called the delta method. Visit our online tutorials to see how this can be done (OGGM run with GCM tutorial).

Elevation dependency

OGGM needs to compute the temperature and precipitation at the altitude of the glacier grid points. The default is to use a fixed lapse rate of -6.5K km \(^{-1}\) and no gradient for precipitation. However, OGGM also contains an optional algorithm which computes the local gradient by linear regression of the 9 surrounding grid points. This method requires that the near-surface temperature lapse-rates provided by the climate dataset are good (i.e. in most cases, you should probably use the simple fixed gradient instead).

Temperature-index model

The monthly mass-balance \(B_i\) at elevation \(z\) is computed as:

\[B_i(z) = P_i^{Solid}(z) - \mu ^{*} \, max \left( T_i(z) - T_{Melt}, 0 \right) + \epsilon\]

where \(P_i^{Solid}\) is the monthly solid precipitation, \(T_i\) the monthly temperature and \(T_{Melt}\) is the monthly mean air temperature above which ice melt is assumed to occur (-1°C per default). Solid precipitation is computed out of the total precipitation. The fraction of solid precipitation is based on the monthly mean temperature: all solid below temp_all_solid (default: 0°C) and all liquid above temp_all_liq (default: 2°C), linear change in between.

The parameter \(\mu ^{*}\) indicates the temperature sensitivity of the glacier, and it needs to be calibrated. \(\epsilon\) is a residual, to be determined at the calibration step.

Calibration

We will start by making two observations:

• the sensitivity parameter \(\mu ^{*}\) is depending on many parameters, most of them being glacier-specific (e.g. avalanches, topographical shading, cloudiness…).
• the sensitivity parameter \(\mu ^{*}\) will be affected by uncertainties and systematic biases in the input climate data.

As a result, \(\mu ^{*}\) can vary greatly between neighboring glaciers. The calibration procedure introduced by Marzeion et al., (2012) and implemented in OGGM makes full use of these apparent handicaps by turning them into assets.

The calibration procedure starts with glaciers for which we have direct observations of the annual specific mass-balance SMB. We use the WGMS FoG (shipped with OGGM) for this purpose.

For each of these glaciers, time-dependent “candidate” temperature sensitivities \(\mu (t)\) are estimated by requiring that the average specific mass-balance \(\overline{B_{31}}\) is equal to zero. \(\overline{B_{31}}\) is computed for a 31-year period centered around the year \(t\) and for a constant glacier geometry fixed at the RGI date (e.g. 2003 for most glaciers in the European Alps).

In [2]: example_plot_mu_ts()  # the code for these examples is posted below

Around 1900, the climate was cold and wet. As a consequence, the temperature sensitivity required to maintain the 2003 glacier geometry is high. Inversely, the recent climate is warm and the glacier must have a small temperature sensitivity in order to preserve its 2003 geometry.

Note that these \(\mu (t)\) are just hypothetical sensitivities necessary to maintain the glacier in equilibrium in an average climate at the year \(t\). We call them “candidates”, since one (or more) of them is likely to be close to the “real” sensitivity of the glacier.

This is when the mass-balance observations come into play: each of these candidates is used to compute the mass-balance during the period were we have observations. We then compare the model output with the expected mass-balance and compute the model bias:

In [3]: example_plot_bias_ts()  # the code for these examples is posted below

The residual bias is positive when \(\mu\) is too low, and negative when \(\mu\) is too high. Here, the residual bias crosses the zero line twice. The two dates where the zero line is crossed correspond to approximately the same \(\mu\) (but not exactly, as precipitation and temperature both have an influence on it). These two dates at which the \(\mu\) candidates are close to the “real” \(\mu\) are called \(t^*\) (the associated sensitivities \(\mu (t^*)\) are called \(\mu^*\)). For the next step, one \(t^*\) is sufficient: we pick the one which corresponds to the smallest absolute residual bias.

At the glaciers where observations are available, this detour via the \(\mu\) candidates is not necessary to find the correct \(\mu^*\). Indeed, the goal of these computations are in fact to find \(t^*\), which is the actual value interpolated to glaciers where no observations are available.

The benefit of this approach is best shown with the results of a cross-validation study realized by Marzeion et al., (2012) and confirmed by OGGM:

Benefit of spatially interpolating \(t^{*}\) instead of \(\mu ^{*}\) as shown by leave-one-glacier-out cross-validation (N = 255). Left: error distribution of the computed mass-balance if determined by the interpolated \(t^{*}\). Right: error distribution of the mass-balance if determined by interpolation of \(\mu ^{*}\).

This substantial improvement in model performance is due to several factors:

• the equilibrium constraint applied on \(\mu\) implies that the sensitivity cannot vary much during the last century. In fact, \(\mu\) at one glacier varies far less in one century than between neighboring glaciers, because of all the factors mentioned above. In particular, it will vary comparatively little around a given year \(t\) : errors in \(t^*\) (even large) will result in small errors in \(\mu^*\).
• the equilibrium constraint will also imply that systematic biases in temperature and precipitation (no matter how large) will automatically be compensated by all \(\mu (t)\), and therefore also by \(\mu^*\). In that sense, the calibration procedure can be seen as a empirically driven downscaling strategy: if a glacier is here, then the local climate (or the glacier temperature sensitivity) must allow a glacier to be there. For example, the effect of avalanches or a negative bias in precipitation input will have the same impact on calibration: \(\mu^*\) should be reduced to take these effects into account, even though they are not resolved by the mass-balance model.

The most important drawback of this calibration method is that it assumes that two neighboring glaciers should have a similar \(t^*\). This is not necessarily the case, as other factors than climate (such as the glacier size) will influence \(t^*\) too. Our results (and the arguments listed above) show however that this is an approximation we can cope with.

In a final note, it is important to mention that this procedure is primarily a calibration method, and as such it can be statistically scrutinized (for example with cross-validation). It can also be noted that the MB observations play a relatively minor role in the calibration: they could be entirely avoided by fixing a \(t^*\) for all glaciers in a region (or even worldwide). The resulting changes in calibrated \(\mu^*\) will be comparatively small (again, because of the local constraints on \(\mu\)). The MB observations, however, play a major role for the assessment of model uncertainty.

Regional calibration

New in version 1.4!

As of version 1.4, we now also offer to calibrate the mass-balance at the regional level (RGI regions) based on geodetic mass-balance products ([Zemp_et_al_2019] or [Hugonnet_et_al_2020]). This is done by correcting (shifting) the residual for each glacier (\(\epsilon\) in the equation above) by a constant value so that the regional estimates match the observations. This is not applied per default, as it might lead to unrealistic results at the single glacier scale (but it is very useful for global studies). An overview of the regional shifts for all regions and presently available set-ups can be assessed via this notebook.

References

[Chimani_et_al_2012]

Chimani, B., Matulla, C., Böhm, R., Hofstätter, M.: A new high resolution absolute Temperature Grid for the Greater Alpine Region back to 1780, Int. J. Climatol., 33(9), 2129–2141, DOI 10.1002/joc.3574, 2012.

[Harris_et_al_2010]

Harris, I., Jones, P. D., Osborn, T. J., & Lister, D. H. (2014). Updated high-resolution grids of monthly climatic observations - the CRU TS3.10 Dataset. International Journal of Climatology, 34(3), 623–642. https://doi.org/10.1002/joc.3711

[Hugonnet_et_al_2020]

Hugonnet et al., accepted.

[Zemp_et_al_2019]

Zemp, M., Huss, M., Thibert, E., Eckert, N., McNabb, R., Huber, J., Barandun, M., Machguth, H., Nussbaumer, S. U., Gärtner-Roer, I., Thomson, L., Paul, F., Maussion, F., Kutuzov, S. and Cogley, J. G.: Global glacier mass changes and their contributions to sea-level rise from 1961 to 2016, Nature, 568(7752), 382–386, doi:10.1038/s41586-019-1071-0, 2019.

Implementation details

If you had the courage to read until here, it means that you have concrete questions about the implementation of the mass-balance model in OGGM. Here are some more details:

• the mass-balance in OGGM is computed from the altitudes and widths of the flowlines grid points (see Glacier flowlines). The easiest way to let OGGM compute the mass-balance for you is to use the core.massbalance.PastMassBalance.
• the interpolation of \(t^*\) is done with an inverse distance weighting algorithm (see tasks.local_t_star())
• if more than one \(t^*\) is found for some reference glaciers, than the glaciers with only one \(t^*\) will determine the most likely \(t^*\) for the other glaciers (see tasks.compute_ref_t_stars())
• yes, the temperature gradients and the precipitation scaling factor will have an influence on the results, but it is small since any change will automatically be compensated by \(\mu^*\). We are currently quantifying these effects more precisely.

Code used to generate these examples:

import os
import geopandas as gpd
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import xarray as xr

import oggm
from oggm import cfg, tasks, graphics
from oggm.core.climate import (mb_yearly_climate_on_glacier,
                               t_star_from_refmb,
                               local_t_star, mu_star_calibration)
from oggm.core.massbalance import (ConstantMassBalance)
from oggm.utils import get_demo_file, gettempdir
from oggm.shop import histalp

cfg.initialize()
cfg.set_intersects_db(get_demo_file('rgi_intersect_oetztal.shp'))
cfg.PATHS['dem_file'] = get_demo_file('hef_srtm.tif')
histalp.set_histalp_url('https://cluster.klima.uni-bremen.de/~oggm/'
                        'test_climate/histalp/')

base_dir = gettempdir('Climate_docs')
cfg.PATHS['working_dir'] = base_dir
entity = gpd.read_file(get_demo_file('Hintereisferner_RGI5.shp')).iloc[0]
gdir = oggm.GlacierDirectory(entity, base_dir=base_dir, reset=True)

tasks.define_glacier_region(gdir)
tasks.glacier_masks(gdir)
tasks.compute_centerlines(gdir)
tasks.initialize_flowlines(gdir)
tasks.compute_downstream_line(gdir)
tasks.catchment_area(gdir)
tasks.catchment_width_geom(gdir)
tasks.catchment_width_correction(gdir)
cfg.PARAMS['baseline_climate'] = 'HISTALP'
tasks.process_histalp_data(gdir)
mu_yr_clim = tasks.glacier_mu_candidates(gdir)

mbdf = gdir.get_ref_mb_data()
res = t_star_from_refmb(gdir, mbdf=mbdf.ANNUAL_BALANCE)
local_t_star(gdir, tstar=res['t_star'], bias=res['bias'], reset=True)
mu_star_calibration(gdir, reset=True)

# For flux plot
tasks.prepare_for_inversion(gdir)

# For plots
years, temp_yr, prcp_yr = mb_yearly_climate_on_glacier(gdir)

# which years to look at
selind = np.searchsorted(years, mbdf.index)
temp_yr = np.mean(temp_yr[selind])
prcp_yr = np.mean(prcp_yr[selind])

# Average oberved mass-balance
ref_mb = mbdf.ANNUAL_BALANCE.mean()
mb_per_mu = prcp_yr - mu_yr_clim * temp_yr

# Diff to reference
diff = mb_per_mu - ref_mb
pdf = pd.DataFrame()
pdf[r'$\mu (t)$'] = mu_yr_clim
pdf['bias'] = diff
res = t_star_from_refmb(gdir, mbdf=mbdf.ANNUAL_BALANCE)

# For the mass flux
cl = gdir.read_pickle('inversion_input')[-1]
mbmod = ConstantMassBalance(gdir)
mbx = (mbmod.get_annual_mb(cl['hgt']) * cfg.SEC_IN_YEAR *
       cfg.PARAMS['ice_density'])
fdf = pd.DataFrame(index=np.arange(len(mbx))*cl['dx'])
fdf['Flux'] = cl['flux']
fdf['Mass balance'] = mbx

# For the distributed thickness
tasks.mass_conservation_inversion(gdir, glen_a=2.4e-24 * 3, fs=0)
tasks.distribute_thickness_per_altitude(gdir)


# plot functions
def example_plot_temp_ts():
    d = xr.open_dataset(gdir.get_filepath('climate_historical'))
    temp = d.temp.resample(time='12MS').mean('time').to_series()
    temp.index = temp.index.year
    try:
        temp = temp.rename_axis(None)
    except AttributeError:
        del temp.index.name
    temp.plot(figsize=(8, 4), label='Annual temp')
    tsm = temp.rolling(31, center=True, min_periods=15).mean()
    tsm.plot(label='31-yr avg')
    plt.legend(loc='best')
    plt.title('HISTALP annual temperature, Hintereisferner')
    plt.ylabel(r'degC')
    plt.tight_layout()
    plt.show()


def example_plot_mu_ts():
    mu_yr_clim.plot(figsize=(8, 4), label=r'$\mu (t)$')
    plt.legend(loc='best')
    plt.title(r'$\mu$ candidates Hintereisferner')
    plt.ylabel(r'$\mu$ (mm yr$^{-1}$ K$^{-1}$)')
    plt.tight_layout()
    plt.show()


def example_plot_bias_ts():
    ax = pdf.plot(figsize=(8, 4), secondary_y='bias')
    plt.hlines(0, 1800, 2015, linestyles='-')
    ax.set_ylabel(r'$\mu$ (mm yr$^{-1}$ K$^{-1}$)')
    ax.set_title(r'$\mu$ candidates HEF')
    plt.ylabel(r'bias (mm yr$^{-1}$)')
    yl = plt.gca().get_ylim()
    plt.plot((res['t_star'], res['t_star']), (yl[0], 0),
             linestyle=':', color='grey')
    plt.ylim(yl)
    plt.tight_layout()
    plt.show()


def example_plot_massflux():
    fig, ax = plt.subplots(figsize=(8, 4))
    fdf.plot(ax=ax, secondary_y='Mass balance', style=['C1-', 'C0-'])
    plt.axhline(0., color='grey', linestyle=':')
    ax.set_ylabel('Flux [m$^3$ s$^{-1}$]')
    ax.right_ax.set_ylabel('MB [kg m$^{-2}$ yr$^{-1}$]')
    ax.set_xlabel('Distance along flowline (m)')
    plt.title('Mass flux and mass balance along flowline')
    plt.tight_layout()
    plt.show()

Ice dynamics

The glaciers in OGGM are represented by a depth-integrated flowline model. The equations for the isothermal shallow ice are solved along the glacier centerline, computed to represent best the flow of ice along the glacier (see for example antarcticglaciers.org for a general introduction about the various types of glacier models).

Ice flow

Let \(S\) be the area of a cross-section perpendicular to the flowline. It has a width \(w\) and a thickness \(h\) and, in this example, a parabolic bed shape.

Example of a cross-section along the glacier flowline. Background image from http://www.swisseduc.ch/glaciers/alps/hintereisferner/index-de.html

Volume conservation for this discrete element implies:

\[\frac{\partial S}{\partial t} = w \, \dot{m} - \nabla \cdot q\]

where \(\dot{m}\) is the mass-balance, \(q = u S\) the flux of ice, and \(u\) the depth-integrated ice velocity ([Cuffey_Paterson_2010], p 310). This velocity can be computed from Glen’s flow law as a function of the basal shear stress \(\tau\):

\[u = u_d + u_s = f_d h \tau^n + f_s \frac{\tau^n}{h}\]

wehere u_d and u_s are respectively the speed of ice coming from its deformation and sliding (n is equal to 3). Thus, the first term is for ice deformation and the second term is to account for basal sliding, see e.g. [Oerlemans_1997] or [Golledge_Levy_2011]. It introduces an additional free parameter \(f_s\) and will therefore be ignored in a first approach. The deformation parameter \(f_d\) is better constrained and relates to Glen’s temperature‐dependent creep parameter \(A\):

\[f_d = \frac{2 A}{n + 2}\]

The basal shear stress \(\tau\) depends for example on the geometry of the bed [Cuffey_Paterson_2010]. Currently it is assumed to be equal to the driving stress \(\tau_d\):

\[\tau_d = \alpha \rho g h\]

where \(\alpha\) is the slope of the flowline, \(\rho\) the density of ice and g the Earth gravity acceleration. Both the FluxBasedModel and the MUSCLSuperBeeModel solve for these equations, but with different numerical schemes.

Bed shapes

OGGM implements a number of possible bed-shapes. Currently the shape has no direct influence on the shear stress (i.e. Cuffey and Paterson’s “shape factor” is not considered), but the shape will still have a considerable influence on glacier dynamics:

• the width change as a result of mass transport will be different for each shape, thus influencing the mass-balance term \(w \, \dot{m}\).
• with all other things held constant, a change in the cross-section area \(\partial S / \partial t\) due to mass convergence/divergence will result in a different \(\partial h / \partial t\) and thus in different shear stress computation at the next time step.

Rectangular

The simplest shape. The glacier width does not change with ice thickness.

Trapezoidal

Trapezoidal shape with two degrees of freedom. The width change with thickness depends on \(\lambda\). The angle \(\beta\) of the side wall (as defined from the horizontal plane, i.e. \(\lambda = 0 \rightarrow \beta = 90^{\circ}\)) is defined by:

\[\beta = atan \frac{2}{\lambda}\]

[Golledge_Levy_2011] uses \(\lambda = 2\) (a 45° wall angle) which is the default in OGGM as of version 1.4 (it used to be \(\lambda = 1\), a 63° wall angle).

Parabolic

Parabolic shape with one degree of freedom, which makes it particularly useful for the bed inversion. If \(S\) and \(w\) are known:

\[h = \frac{3}{2} \frac{S}{w}\]

The parabola is defined by the bed-shape parameter \(P_s = 4 h / w^2\) [1]. Very small values of this parameter imply very flat shapes, unrealistically sensitive to changes in \(h\). For this reason, the default in OGGM is to use the mixed flowline model described below.

[1]	the local thickness \(y\) of the parabolic bed can be described by \(y = h − P_s x^2\). At \(x = w / 2\), \(y = 0\) and therefore \(P_s = 4 h / w^2\).

Mixed

A combination of rectangular, trapezoidal and parabolic shapes.

Note

The default in OGGM is to used mixed flowlines, following these rules:

• elevation-band flowlines have a trapezoid bed everywhere, except on the glacier forefront where the bed is parabolic (computed from the valley topography).

• geometrical centerlines have a parabolic bed shape, with two exceptions:

  • if the glacier section touches an ice-divide or a neighboring tributary catchment outline, the bed is considered to be rectangular;
  • if the parabolic shape parameter \(P_s\) is below a certain threshold, a trapezoidal shape is used. Indeed, flat parabolas tend to be very sensitive to small changes in \(h\), which is undesired.

Numerics

“Flux-based” model

Most flowline models treat the volume conservation equation as a diffusion problem, taking advantage of the robust numerical solutions available for this type of equations. The problem with this approach is that it implies developing the \(\partial S / \partial t\) term to solve for ice thickness \(h\) directly, thus implying different diffusion equations for different bed geometries (e.g. [Oerlemans_1997] with a trapezoidal bed).

The OGGM “flux based” model solves for the \(\nabla \cdot q\) term (hence the name). The strong advantage of this method is that the numerical equations are the same for any bed shape, considerably simplifying the implementation. Similar to the “diffusion approach”, the model is not mass-conserving in very steep slopes [Jarosch_etal_2013].

The numerical scheme implemented in OGGM is tested against Alex Jarosch’s MUSCLSuperBee Model (see below) and Hans Oerleman’s diffusion model for various idealized cases. For all cases but the steep slope, the model performs very well.

In order to increase the stability and speed of the computations, we solve the numerical equations on a forward staggered grid and we use an adaptive time stepping scheme.

See The numerical model in OGGM v1.2 and below was numerically unstable in some conditions for an ongoing discussion about the limitations of OGGM’s numerical scheme!

MUSCLSuperBeeModel

A shallow ice model with improved numerics ensuring mass-conservation in very steep walls [Jarosch_etal_2013]. The model is currently used only as reference benchmark for the “Flux-Based” model.

Glacier tributaries

Glaciers in OGGM have a main centerline and, sometimes, one or more tributaries (which can themselves also have tributaries, see Glacier flowlines). The number of these tributaries depends on many factors, but most of the time the algorithm works well.

The main flowline and its tributaries are all modelled individually. At the end of a time step, the tributaries will transport mass to the branch they are flowing to. Numerically, this mass transport is handled by adding an element at the end of the flowline with the same properties (width, thickness …) as the last grid point, with the difference that the slope \(\alpha\) is computed with respect to the altitude of the point they are flowing to. The ice flux is then computed as usual and transferred to the downlying branch.

The computation of the ice flux is always done first from the lowest order branches (without tributaries) to the highest ones, ensuring a correct mass-redistribution. The use of the slope between the tributary and main branch ensures that the former is not dynamical coupled to the latter. If the angle is positive or if no ice is present at the end of the tributary, no mass exchange occurs.

References

[Cuffey_Paterson_2010]

(1, 2) Cuffey, K., and W. S. B. Paterson (2010). The Physics of Glaciers, Butterworth‐Heinemann, Oxford, U.K.

[Golledge_Levy_2011]

(1, 2) Golledge, N. R., and Levy, R. H. (2011). Geometry and dynamics of an East Antarctic Ice Sheet outlet glacier, under past and present climates. Journal of Geophysical Research: Earth Surface, 116(3), 1–13.

[Jarosch_etal_2013]

(1, 2) Jarosch, a. H., Schoof, C. G., & Anslow, F. S. (2013). Restoring mass conservation to shallow ice flow models over complex terrain. Cryosphere, 7(1), 229–240. http://doi.org/10.5194/tc-7-229-2013

[Oerlemans_1997]

(1, 2) Oerlemans, J. (1997). A flowline model for Nigardsbreen, Norway: projection of future glacier length based on dynamic calibration with the historic record. Journal of Glaciology, 24, 382–389.

Bed inversion

To compute the initial ice thickness \(h_0\), OGGM follows a methodology largely inspired from [Farinotti_et_al_2009], but fully automated and relying on different methods for the mass-balance and the calibration.

Basics

The principle is simple. Let’s assume for now that we know the flux of ice \(q\) flowing through a cross-section of our glacier. The flowline physics and geometrical assumptions can be used to solve for the ice thickness \(h\):

\[q = u S = \left(f_d h \tau^n + f_s \frac{\tau^n}{h}\right) S\]

With \(n=3\) and \(S = h w\) (in the case of a rectangular section) or \(S = 2 / 3 h w\) (parabolic section), the equation reduces to solving a polynomial of degree 5 with one unique solution in \(\mathbb{R}_+\). If we neglect sliding (the default in OGGM and in [Farinotti_et_al_2009]), the solution is even simpler.

Ice flux

If we consider a point on the flowline and the catchment area \(\Omega\) upstream of this point we have:

\[q = \int_{\Omega} (\dot{m} - \rho \frac{\partial h}{\partial t}) \ dA = \int_{\Omega} \widetilde{m} \ dA\]

with \(\dot{m}\) the mass balance, and \(\widetilde{m} = \dot{m} - \rho \partial h / \partial t\) the “apparent mass-balance” after [Farinotti_et_al_2009]. If the glacier is in steady state, the apparent mass-balance is equivalent to the the actual (and observable) mass-balance. Unfortunately, that is rarely the case, hence \(\partial h / \partial t\) is not known and there is no easy way to compute it. In order to continue, we have to make the assumption that our geometry is in equilibrium.

This however has a very useful consequence: indeed, for the calibration of our Mass-balance model it is required to find a date \(t^*\) at which the glacier would be in equilibrium with its average climate while conserving its modern geometry. Thus, we have \(\widetilde{m} = \dot{m}_{t^*}\), where \(\dot{m}_{t^*}\) is the 31-yr average mass-balance centered at \(t^*\) (which is known since the mass-balance model calibration).

The plot below shows the mass flux along the major flowline of Hintereisferner glacier at \(t^*\). By construction, the flux is maximal at the equilibrium line and zero at the glacier tongue.

In [1]: example_plot_massflux()

Calibration

A number of climate and glacier related parameters are fixed prior to the inversion, leaving only one free parameter for the calibration of the bed inversion procedure: the inversion factor \(f_{inv}\). It is defined such as:

\[A = f_{inv} \, A_0\]

With \(A_0\) the standard creep parameter (\(2.4^{-24}\)). Currently, there is no “optimum” \(f_{inv}\) parameter in the model. There is a high uncertainty in the “true” \(A\) parameter as well as in all other processes affecting the ice thickness. Therefore, we cannot make any recommendation for the “best” parameter. Global sensitivity analyses show that the default value is a good compromise [Maussion_et_al_2019], but very likely leads to overestimated ice volume [Farinotti_et_al_2019].

New in version 1.4!

As of OGGM v1.4, the user can choose to calibrate \(A\) to match the consensus volume estimate from [Farinotti_et_al_2019] on any number of glaciers. We recommend to use a large number of glaciers (we match at the regional level) in order to allow some freedom to the model (it is not guaranteed that the consensus really is better for each glacier), but we assume that it is more accurate at large scales.

Distributed ice thickness

To obtain a 2D map of the glacier ice thickness and bed, the flowline thicknesses need to be interpolated to the glacier mask. The current implementation of this step in OGGM is currently very simple, but provides nice looking maps:

In [2]: tasks.catchment_area(gdir)

In [3]: graphics.plot_distributed_thickness(gdir)

References

[Farinotti_et_al_2009]

(1, 2, 3) Farinotti, D., Huss, M., Bauder, A., Funk, M., & Truffer, M. (2009). A method to estimate the ice volume and ice-thickness distribution of alpine glaciers. Journal of Glaciology, 55 (191), 422–430.

[Farinotti_et_al_2019]

(1, 2) Farinotti, D., Huss, M., Fürst, J. J., Landmann, J., Machguth, H., Maussion, F. and Pandit, A.: A consensus estimate for the ice thickness distribution of all glaciers on Earth, Nat. Geosci., 12(3), 168–173, doi:10.1038/s41561-019-0300-3, 2019.

[Maussion_et_al_2019]

Maussion, F., Butenko, A., Champollion, N., Dusch, M., Eis, J., Fourteau, K., Gregor, P., Jarosch, A. H., Landmann, J., Oesterle, F., Recinos, B., Rothenpieler, T., Vlug, A., Wild, C. T. and Marzeion, B.: The Open Global Glacier Model (OGGM) v1.1, Geosci. Model Dev., 12(3), 909–931, doi:10.5194/gmd-12-909-2019, 2019.

Frontal ablation

OGGM has a simple parameterisation for frontal ablation that can be used during the ice volume estimation and for dynamical runs. These features are still in the testing phase and are switched off per default.

Visit our turotials if you are interested and would like to give them a go.

Illustration of the water-depth – calving-rate feedbacks. See the tutorials for more details.

Using OGGM

How to use the model, with concrete code examples and links to the tutorials.

• Try OGGM online
• Installing OGGM
• Getting started
• OGGM Shop
• Tutorials
• Performance, cluster environments and reproducibility
• API Reference
• FAQ and Troubleshooting
• Pitfalls and limitations
• Assets & downloads
• OGGM-Hub
• Version history

Try OGGM online

You can try OGGM in your web browser without having to install anything! This is the best way to run the tutorials or even do exploratory research to test the model, before you move on to more serious computations.

Our Binder test space is available to anyone, with no registration necessary. Using it is very simple. Just click on the link below to get you started!

If you are new to the Jupyter Notebooks or to JupyterLab, you will probably find this introduction to interactive notebooks quite useful.

Warning

Binder environments are only temporary! Perfect for trying and learning, but not suitable for development work. Remember to download your notebooks at the end of a session if you want to keep them for later.

If you want to use OGGM for more serious and permanent work, we recommend to either install OGGM on your computer or use OGGM-Hub, an online service similar to Binder but persistent and with access to more resources.

Installing OGGM

Important

Did you know that you can try OGGM in your browser before installing it on your computer? Visit Try OGGM online for more information.

OGGM itself is a pure Python package, but it has several dependencies which are not trivial to install. The instructions below provide all the required details and should work on Linux and Mac OS. See Installation troubleshooting if something goes wrong.

OGGM is fully tested with Python version 3.6, 3.7 and 3.8 on Linux. OGGM doesn’t work with Python 2. We do not test OGGM automatically on Mac OSX, but it should probably run fine there as well.

Warning

OGGM does not work on Windows. If you are using Windows 10, we recommend to install the free Windows subsytem for Linux and install and run OGGM from there.

For most users we recommend to install Python and the package dependencies with the conda package manager. Linux users with experience with pip can follow these instructions to install OGGM in a pyenv environment with pip.

Dependencies

Here is a list of all dependencies of the OGGM model. If you want to use OGGM’s numerical models only (i.e. no GIS or preprocessing tools), refer to Install a minimal OGGM environment below.

Standard SciPy stack:

• numpy
• scipy
• scikit-image
• pillow
• matplotlib
• pandas
• xarray
• dask
• joblib

Configuration file parsing tool:

• configobj

I/O:

• netcdf4
• pytables

GIS tools:

• shapely
• pyproj
• rasterio
• geopandas

Testing:

• pytest
• pytest-mpl (OGGM fork required)

Other libraries:

• salem
• motionless

Optional:

• progressbar2 (displays the download progress)
• bottleneck (might speed up some xarray operations)
• python-colorspace (applies HCL-based color palettes to some graphics)

Install with conda (all platforms)

This is the recommended way to install OGGM for most users.

Note

If you are not familiar with Python and its way too many package management systems, you might find all of this quite confusing and overwhelming. Be patient, read the docs and stay hydrated.

Prerequisites

You should have a recent version of the conda package manager. You can get conda by installing miniconda (the package manager alone - recommended) or anaconda (the full suite - with many packages you won’t need).

Conda environment

We recommend to create a specific environment for OGGM. In a terminal window, type:

conda create --name oggm_env python=3.X

where 3.X is the Python version shipped with conda (currently 3.8). You can of course use any other name for your environment.

Don’t forget to activate it before going on:

source activate oggm_env

Feeling adventurous? Try mamba (optional)

The conda package manager has recently been criticized for being slow (it is quite slow to be honest). A new, faster tool is now available to replace conda: mamba. Mamba is a drop-in replacement for all conda commands. If you feel like it, install mamba in your conda environment (conda install -c conda-forge mamba) and replace all occurrences of conda with mamba in the instructions below.

Install dependencies

Install all OGGM dependencies from the conda-forge and oggm conda channels:

conda install -c oggm -c conda-forge oggm-deps

The oggm-deps package is a “meta package”. It does not contain any code but will install all the packages OGGM needs automatically.

Important

The conda-forge channel ensures that the complex package dependencies are handled correctly. Subsequent installations or upgrades from the default conda channel might brake the chain. We strongly recommend to always use the the conda-forge channel for your installation.

You might consider setting conda-forge as your default channel:

conda config --add channels conda-forge

No scientific Python installation is complete without installing a good testing framework, as well as IPython and Jupyter:

conda install -c conda-forge pytest ipython jupyter

Install OGGM itself

First, choose which version of OGGM you would like to install:

• stable: this is the latest version officially released and has a fixed version number (e.g. v1.4).
• dev: this is the development version. It might contain new features and bug fixes, but is also likely to continue to change until a new release is made. This is the recommended way if you want to use the latest changes to the code.
• dev+code: this is the recommended way if you plan to explore the OGGM codebase, contribute to the model, and/or if you want to use the most recent model updates.

‣ install the stable version:

If you are using conda, you can install stable OGGM as a normal conda package:

conda install -c oggm oggm

If you are using pip, you can install OGGM from PyPI:

pip install oggm

‣ install the dev version:

For this to work you’ll need to have the git software installed on your system. In your conda environment, simply do:

pip install --upgrade git+https://github.com/OGGM/oggm.git

With this command you can also update an already installed OGGM version to the latest version.

‣ install the dev version + get access to the OGGM code:

For this to work you’ll need to have the git software installed on your system. Then, clone the latest repository version:

git clone https://github.com/OGGM/oggm.git

Then go to the project root directory:

cd oggm

And install OGGM in development mode (this is valid for both pip and conda environments):

pip install -e .

Note

Installing OGGM in development mode means that subsequent changes to this code repository will be taken into account the next time you will import oggm. You can also update OGGM with a simple git pull from the root of the cloned repository.

Testing OGGM

You can test your OGGM installation by running the following command from anywhere (don’t forget to activate your environment first):

pytest --pyargs oggm

The tests can run for about 10 minutes (we are trying to reduce this). If everything worked fine, you should see something like:

================================ test session starts ================================
platform linux -- Python 3.8.5, pytest-6.0.2, py-1.9.0, pluggy-0.13.1
Matplotlib: 3.3.2
Freetype: 2.6.1
rootdir: /home/mowglie/disk/Dropbox/HomeDocs/git/oggm-fork, configfile: pytest.ini
plugins: mpl-0.122
collected 297 items

oggm/tests/test_benchmarks.py .......                                         [  2%]
oggm/tests/test_graphics.py ...................X                              [  9%]
oggm/tests/test_minimal.py ...                                                [ 10%]
oggm/tests/test_models.py ..........................sss.......ssss..s.ss..sss [ 27%]
sss..sss                                                                      [ 29%]
oggm/tests/test_numerics.py .sssssssssss.ssss...s..ss.s                       [ 39%]
oggm/tests/test_prepro.py .................s........................s........ [ 56%]
........s....s............                                                    [ 64%]
oggm/tests/test_shop.py .......                                               [ 67%]
oggm/tests/test_utils.py .................................................... [ 84%]
ss.ss..sssss.ssssss..sss...s.ss.ss.ss..                                       [ 97%]
oggm/tests/test_workflow.py ssssss                                            [100%]

================================= warnings summary ==================================
(warnings are mostly ok)
======== 223 passed, 73 skipped, 1 xpassed, 9 warnings in 771.11s (0:12:51) =========

You can safely ignore deprecation warnings and other messages (if any), as long as the tests end without errors.

This runs a minimal suite of tests. If you want to run the entire test suite (including graphics and slow running tests), type:

pytest --pyargs oggm --run-slow --mpl

Congrats, you are now set-up for the Getting started section!

Installation troubleshooting

We try to do our best to avoid issues, but experience shows that the installation of the necessary packages can be difficult. Typical errors are often related to the pyproj, fiona and GDAL packages, which are heavy and (for pyproj) have changed a lot in the recent past and are prone to platform specific errors.

If the tests don’t pass, a diagnostic of which package creates the errors might be necessary. Errors like segmentation fault or Proj Error are frequent and point to errors in upstream packages, rarely in OGGM itself.

If you are having troubles, installing the packages manually from a fresh environment might help. At the time of writing (20.01.2021), creating an environment from the following environment.yml file used to work:

name: oggm_env
channels:
  - conda-forge
dependencies:
  - python=3.8
  - jupyter
  - jupyterlab
  - numpy
  - scipy
  - pandas
  - shapely
  - matplotlib
  - Pillow
  - netcdf4
  - scikit-image
  - scikit-learn
  - configobj
  - xarray
  - pytest
  - dask
  - bottleneck
  - pyproj
  - cartopy
  - geopandas
  - rasterio
  - descartes
  - seaborn
  - pytables
  - pip
  - pip:
    - joblib
    - progressbar2
    - motionless
    - git+https://github.com/fmaussion/salem.git
    - git+https://github.com/retostauffer/python-colorspace
    - git+https://github.com/OGGM/pytest-mpl
    - git+https://github.com/OGGM/oggm

See the conda docs for more information about how to create an environment from a yml file, OR you can do what I usually do (much faster): install mamba first, then run mamba env create -f environment.yml.

Install with pyenv (Linux)

Note

We recommend our users to use conda instead of pip, because of the ease of installation with conda. If you are familiar with pip and pyenv, the instructions below work as well: as of Sept 2020 (and thanks to pip wheels), a pyenv installation is possible without major issue on Debian/Ubuntu/Mint systems.

Linux packages

Run the following commands to install the required linux packages.

For building python and stuff:

$ sudo apt-get install --no-install-recommends make build-essential git \
    libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget \
    curl llvm libncurses5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
    libffi-dev liblzma-dev

For NetCDF and HDF:

$ sudo apt-get install netcdf-bin ncview hdf5-tools libhdf5-dev

Pyenv and pyenv-virtualenv

Install pyenv and create a new virtual environment with a recent python version (3.7+) using pyenv-virtualenv.

Python packages

Be sure to be on the working environment:

$ pyenv activate oggm_env

Update pip (important!):

$ pip install --upgrade pip

Install some packages one by one:

$ pip install numpy scipy pandas shapely matplotlib pyproj \
    rasterio Pillow geopandas netcdf4 scikit-image configobj joblib \
    xarray progressbar2 pytest motionless dask bottleneck toolz descartes \
    tables

A pinning of the NetCDF4 package to 1.3.1 might be necessary on some systems (related issue).

Finally, install the pytest-mpl OGGM fork, salem and python-colorspace libraries:

$ pip install git+https://github.com/OGGM/pytest-mpl.git
$ pip install git+https://github.com/fmaussion/salem.git
$ pip install git+https://github.com/retostauffer/python-colorspace.git

Install OGGM and run the tests

Refer to Install OGGM itself above.

Install a minimal OGGM environment

If you plan to use only the numerical core of OGGM (that is, for idealized simulations or teaching), you can skip many dependencies and only install this shorter list:

• numpy
• scipy
• pandas
• matplotlib
• shapely
• requests
• configobj
• netcdf4
• xarray
• pytables

Installing them with pip or conda should be much easier. Install OGGM itself then as above.

Running the tests in this minimal environment works the same. Simply run from a terminal:

pytest --pyargs oggm

The number of tests will be much smaller!

Getting started

Although largely automated, OGGM model still requires some python scripting to prepare and run a simulation. This section will guide you through several examples to get you started.

Important

Did you know that you can try OGGM in your browser before installing it on your computer? Visit Try OGGM online for more information.

First step: system settings for input data

OGGM needs various input data files to run. Currently, we rely exclusively on open-access data that are all downloaded automatically for the user. OGGM implements a bunch of tools to make access to input data as painless as possible for you, including the automated download of all the required files. This requires you to tell OGGM where to store these data. Let’s start by opening a python interpreter and type:

In [1]: from oggm import cfg

In [2]: cfg.initialize()

At your very first import, this will do two things:

1. It will download a small subset of data used for testing and calibration. Those data are located in your home directory, in a hidden folder called .oggm.
2. It will create a configuration file in your home folder, where you can indicate where you want to store further input data. This configuration file is also located in your home directory under the name .oggm_config.

To locate this config file, you can type:

In [3]: cfg.CONFIG_FILE
Out[3]: '/home/docs/.oggm_config'

Important

The default settings will probably work for you, but we recommend to have a look at this file and set the paths to a directory where enough space is available: a minimum of 8 Gb for all climate data and glacier outlines is necessary. Pre-processed glacier directories can quickly grow to several tens of Gb as well, even for regional runs.

Calibration data and testing: the ~/.oggm directory

At the first import, OGGM will create a cached .oggm directory in your $HOME folder. This directory contains all data obtained from the oggm sample data repository. It contains several files needed only for testing, but also some important files needed for calibration and validation (e.g. the reference mass-balance data from WGMS with links to the respective RGI polygons).

The ~/.oggm directory should be updated automatically when you update OGGM, but if you encounter any problems with it, simply delete the directory (it will be re-downloaded automatically at the next import).

All other data: auto-downloads and the ~/.oggm_config file

Unlike runtime parameters (such as physical constants or working directories), input data are shared across runs and even across computers if you want to. Therefore, the paths to previously downloaded data are stored in a configuration file that you’ll find in your $HOME folder: the ~/.oggm_config file.

The file should look like:

dl_cache_dir = /path/to/download_cache
dl_cache_readonly = False
tmp_dir = /path/to/tmp_dir
rgi_dir = /path/to/rgi_dir
test_dir = /path/to/test_dir
has_internet = True

Some explanations:

• dl_cache_dir is a path to a directory where all the files you downloaded will be cached for later use. Most of the users won’t need to explore this folder (it is organized as a list of urls) but you have to make sure to set this path to a folder with sufficient disk space available. This folder can be shared across compute nodes if needed (it is even recommended for HPC setups). Once a file is stored in this cache folder (e.g. a specific DEM tile), OGGM won’t download it again.
• dl_cache_readonly indicates if writing is allowed in this folder (this is the default). Setting this to True will prevent any further download in this directory (useful for cluster environments, where this data might be available on a readonly folder): in this case, OGGM will use a fall back directory in your current working directory.
• tmp_dir is a path to OGGM’s temporary directory. Most of the files used by OGGM are downloaded and cached in a compressed format (zip, bz, gz…). These files are extracted in tmp_dir before use. OGGM will never allow more than 100 .tif (or 100 .nc) files to exist in this directory by deleting the oldest ones following the rule of the Least Recently Used (LRU) item. Nevertheless, this directory might still grow to quite a large size. Simply delete it if you want to get this space back.
• rgi_dir is the location where the RGI shapefiles are extracted.
• test_dir is the location where OGGM will write some of its output during tests. It can be set to tmp_dir if you want to, but it can also be another directory (for example a fast SSD disk). This folder shouldn’t take too much disk space but here again, don’t hesitate to delete it if you need to.

Note

For advanced users or cluster configuration: the user’s tmp_dir and rgi_dir settings can be overridden and set to a specific directory by defining an environment variable OGGM_EXTRACT_DIR to a directory path. Similarly, the environment variables OGGM_DOWNLOAD_CACHE and OGGM_DOWNLOAD_CACHE_RO override the dl_cache_dir and dl_cache_readonly settings.

OGGM workflow

For a step by step tutorial of the entire OGGM workflow, download the getting started jupyter notebook (right-click -> “Save link as”) and run it using the following command (from the directory where you downloaded the tutorial):

$ jupyter-notebook getting_started.ipynb

Alternatively, you can try OGGM directly in your browser without having to install anything! Visit our tutorials for more info.

OGGM tutorials

Refer to our tutorials for real-world applications.

OGGM Shop

OGGM needs various data files to run. We rely exclusively on open-access data that can be downloaded automatically for the user. We like to see this service as a “shop”, allowing users to define a shopping list of data that they wish to add to their Glacier directories.

This page describes the various products you will find in the shop.

Important

Don’t forget to set-up or check your First step: system settings for input data before downloading new data! (you’ll need to do this only once per computer)

Pre-processed directories

The simplest way to run OGGM is to rely on Glacier directories which have been prepared for you by the OGGM developers. Depending on your use case, you can start from various stages in the processing chain, map sizes, and model set-ups.

The default directories have been generated with the default parameters of the current stable OGGM version (and a few alternative combinations). If you want to change some of these parameters, you may have to start a run from a lower processing level and re-run the processing tasks. Whether or not this is necessary depends on the stage of the workflow you’d like your computations to diverge from the defaults (this will become more clear a we provide example use cases below).

To start from a pre-processed state, simply use the workflow.init_glacier_directories() function with the from_prepro_level and prepro_border keyword arguments set to the values of your choice. This will fetch the default directories: there are more options to these, which we explain below.

Processing levels

Currently, there are six available levels of pre-processing:

• Level 0: the lowest level, with directories containing the glacier outlines only.
• Level 1: directories now contain the glacier topography data as well.
• Level 2: at this stage, the flowlines and their downstream lines are computed and ready to be used.
• Level 3: adding the baseline climate timeseries (CRU or ERA5, see below) to the directories. Adding all necessary pre-processing tasks for a dynamical run, including the mass-balance calibration, bed inversion, up to the tasks.init_present_time_glacier() task included. These directories still contain all data that was necessary for the processing, i.e. they are the largest in size. They are also the most flexible since the processing chain can be re-run from any stage in them.
• Level 4: same as level 3 but with all intermediate output files removed. The strong advantage of level 4 files is that their size is considerably reduced, at the cost that certain operations (like plotting on maps or running the bed inversion algorithm again) are not possible anymore.
• Level 5: on top of level 4, an additional historical simulation is run from the RGI date to the last possible date of the baseline climate file (for example end of 2019 for CRU and ERA5). The state of the glacier as month 01, (hydrological) year 2020 can then be used for future projections.

In practice, most users are going to use level 2, level 3 or level 5 files. Here are some example use cases:

1. Running OGGM from GCM / RCM data with the default settings: start at level 5
2. Using OGGM’s flowlines but running your own baseline climate, mass-balance or ice thickness inversion models: start at level 2 (and maybe use OGGM’s workflow again for the ice dynamics?). This is the workflow used by associated model PyGEM for example.
3. Run sensitivity experiments for the ice thickness inversion: start at level 3 (with climate data available) and re-run the inversion steps.

Glacier map size: the prepro_border argument

The size of the local glacier map is given in number of grid points outside the glacier boundaries. The larger the map, the largest the glacier can become. Here is an example with Hintereisferner in the Alps:

In [1]: f, axs = plt.subplots(2, 2, figsize=(8, 6))

In [2]: for ax, border in zip(np.array(axs).flatten(), [10, 40, 80, 160]):
   ...:     gdir = workflow.init_glacier_directories('RGI60-11.00897',
   ...:                                              from_prepro_level=1,
   ...:                                              prepro_border=border)
   ...:     graphics.plot_domain(gdir, ax=ax, title='Border: {}'.format(border),
   ...:                          add_colorbar=False,
   ...:                          lonlat_contours_kwargs={'add_tick_labels':False})
   ...: 

In [3]: plt.tight_layout(); plt.show()

Users should choose the map border parameter depending on the expected glacier growth in their simulations. For simulations into the 21st century, a border value of 40 is sufficient, but 80 is safer in case temperature is stabilizing or cooling in certain regions / scenarios. For runs into the Little Ice Age, a border value of 160 is recommended.

Users should be aware that the amount of data to download isn’t small, especially for full directories at processing level 3. Here is an indicative table for the total amount of data with ERA5 centerlines for all 19 RGI regions:

Level	B 10	B 40	B 80	B 160
L0	927M	927M	927M	927M
L1	3.2G	7.3G	17G	47G
L2	11G	23G	51G	144G
L3	13G	26G	54G	147G
L4		3.5G	3.7G	4.1G
L5		7.2G	7.5G	8.3G

L4 and L5 data are not available for border 10 (the domain is too small for the downstream lines).

Certain regions are much smaller than others of course. As an indication, with prepro level 3 and a map border of 160, the Alps are 2.1G large, Greenland 21G, and Iceland 664M.

Therefore, it is recommended to always pick the smallest border value suitable for your research question, and to start your runs from level 5 if possible.

Note

The data download of the preprocessed directories will occur one single time only: after the first download, the data will be cached in OGGM’s dl_cache_dir folder (see First step: system settings for input data).

Available pre-processed configurations

New in version 1.4!

OGGM now has several configurations and directories to choose from, and the list is getting larger. Don’t hesitate to ask us if you are unsure about which to use, or if you’d like to have more configurations to choose from!

To choose from a specific model configuration, use the prepro_base_url argument in your call to workflow.init_glacier_directories(), and set it to one of the urls listed below.

See this tutorial for an example.

Default

If not provided with a specific prepro_base_url argument, workflow.init_glacier_directories() will download the glacier directories from the default urls. Here is a summary of the default configuration:

• model parameters as of the oggm/params.cfg file at the published model version
• flowline glaciers computed from the geometrical centerlines (including tributaries)
• baseline climate from CRU (i.e. not available for Antarctica)
• baseline climate quality checked with tasks.historical_climate_qc() with N=3
• mass-balance parameters calibrated with the standard OGGM procedure. No calibration against geodetic MB (see options below for regional calibration)
• ice volume inversion calibrated to match the ice volume from [Farinotti_etal_2019] at the RGI region level, i.e. glacier estimates might differ. If not specified otherwise, it’s also the precalibrated paramaters that will be used for the dynamical run.
• frontal ablation by calving (at inversion and for the dynamical runs) is switched off

To see the code that generated these directories (for example if you want to make your own, visit cli.prepro_levels.run_prepro_levels() or this file on github).

The urls used by OGGM per default are listed here:

https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.4/ + :

• L1-L2_files/centerlines for level 1 and level 2
• L3-L5_files/CRU/centerlines/qc3/pcp2.5/no_match for level 3 to 5

If you are new to this, I recommend to explore these directories to familiarize yourself to their content. Of course, when provided with an url such as above, OGGM will know where to find the respective files automatically, but is is good to understand how they are structured. The summary folder (example) folder contains diagnostic files which can be useful as well.

Option: Geometrical centerlines or elevation band flowlines

The type of flowline to use (see Glacier flowlines) can be decided at level 2 already. Therefore, the two configurations available at level 2 from these urls:

• L1-L2_files/centerlines for centerlines
• L1-L2_files/elev_bands for elevation bands

The default pre-processing set-ups are also available with each of these flowline types. For example with CRU:

• L3-L5_files/CRU/centerlines/qc3/pcp2.5/no_match for centerlines
• L3-L5_files/CRU/elev_bands/qc3/pcp2.5/no_match for elevation bands

Baseline climate data

For the two most important default configurations (CRU or ERA5 as baseline climate), we provide all levels for both the geometrical centerlines or the elevation band flowlines:

• L3-L5_files/CRU/centerlines/qc3/pcp2.5/no_match for CRU + centerlines
• L3-L5_files/CRU/elev_bands/qc3/pcp2.5/no_match for CRU + elevation bands
• L3-L5_files/ERA5/centerlines/qc3/pcp1.6/no_match for ERA5 + centerlines
• L3-L5_files/ERA5/elev_bands/qc3/pcp1.6/no_match for ERA5 + elevation bands

Further set-ups

Here is the current list of available configurations at the time of writing (explore the server for more!):

• L3-L5_files/CERA+ERA5/elev_bands/qc3/pcp1.6/no_match for CERA+ERA5 + elevation bands
• L3-L5_files/CERA+ERA5/elev_bands/qc3/pcp1.6/match_geod for CERA+ERA5 + elevation bands + matched on regional geodetic mass-balances
• L3-L5_files/CRU/elev_bands/qc3/pcp2.5/match_geod for CRU + elevation bands + matched on regional geodetic mass-balances
• L3-L5_files/ERA5/elev_bands/qc3/pcp1.6/match_geod for ERA5 + elevation bands + matched on regional geodetic mass-balances
• L3-L5_files/ERA5/elev_bands/qc3/pcp1.8/match_geod for ERA5 + elevation bands flowlines + matched on regional geodetic mass-balances + precipitation factor 1.8
• L3-L5_files/CRU/elev_bands/qc0/pcp2.5/match_geod for CRU + elevation bands flowlines + matched on regional geodetic mass-balances + no climate quality check
• L3-L5_files/CRU/elev_bands/qc0/pcp2.5/no_match for CRU + elevation bands flowlines + no climate quality check

Note: the additional set-ups might not always have all map sizes available. Please get in touch if you have interest in a specific set-up.

RGI-TOPO

The RGI-TOPO dataset provides a local topography map for each single glacier in the RGI. It was generated with OGGM, and can be used very easily from the OGGM-Shop (visit our Tutorials if you are interested!).

Example of the various RGI-TOPO products at Malaspina glacier

ITS_LIVE

The ITS_LIVE ice velocity products can be downloaded and reprojected to the glacier directory (visit our Tutorials if you are interested!).

Example of the reprojected ITS_LIVE products at Malaspina glacier

Ice thickness

The Farinotti et al., 2019 ice thickness products can be downloaded and reprojected to the glacier directory (visit our Tutorials if you are interested!).

Example of the reprojected ice thickness products at Malaspina glacier

Raw data sources

These data are used to create the pre-processed directories explained above. If you want to run your own workflow from A to Z, or if you would like to know which data are used in OGGM, read further!

Glacier outlines and intersects

Glacier outlines are obtained from the Randolph Glacier Inventory (RGI). We recommend to download them right away by opening a python interpreter and type:

from oggm import cfg, utils
cfg.initialize()
utils.get_rgi_intersects_dir()
utils.get_rgi_dir()

The RGI folders should now contain the glacier outlines in the shapefile format, a format widely used in GIS applications. These files can be read by several softwares (e.g. qgis), and OGGM can read them too.

The “RGI Intersects” shapefiles contain the locations of the ice divides (intersections between neighboring glaciers). OGGM can make use of them to determine which bed shape should be used (rectangular or parabolic). See the rgi tools documentation for more information about the intersects.

The following table summarizes the attributes from the RGI used by OGGM. It can be useful to refer to this list if you use your own glacier outlines with OGGM.

RGI attribute	Equivalent OGGM variable	Comments
RGIId	gdir.rgi_id	[1]
GLIMSId	gdir.glims_id	not used
CenLon	gdir.cenlon	[2]
CenLat	gdir.cenlat	[2]
O1Region	gdir.rgi_region	not used
O2Region	gdir.rgi_subregion	not used
Name	gdir.name	used for graphics only
BgnDate	gdir.rgi_date	[3]
Form	gdir.glacier_type	[4]
TermType	gdir.terminus_type	[5]
Status	gdir.status	[6]
Area	gdir.rgi_area_km2	[7]
Zmin	glacier_statistics.csv	recomputed by OGGM
Zmax	glacier_statistics.csv	recomputed by OGGM
Zmed	glacier_statistics.csv	recomputed by OGGM
Slope	glacier_statistics.csv	recomputed by OGGM
Aspect	glacier_statistics.csv	recomputed by OGGM
Lmax	glacier_statistics.csv	recomputed by OGGM
Connect	not included
Surging	not included
Linkages	not included
EndDate	not included

For Greenland and Antarctica, OGGM does not take into account the connectivity level between the Glaciers and the Ice sheets. We recommend to the users to think about this before they run the task: workflow.init_glacier_directories.

Comments

[1]	The RGI id needs to be unique for each entity. It should resemble the RGI, but can have longer ids. Here are example of valid IDs: RGI60-11.00897, RGI60-11.00897a, RGI60-11.00897_d01.

[2]	(1, 2) CenLon and CenLat are used to center the glacier local map and DEM.

[3]	The date is the acquisition year, stored as an integer.

[4]	Glacier type: 'Glacier', 'Ice cap', 'Perennial snowfield', 'Seasonal snowfield', 'Not assigned'. Ice caps are treated differently than glaciers in OGGM: we force use a single flowline instead of multiple ones.

[5]	Terminus type: 'Land-terminating', 'Marine-terminating', 'Lake-terminating', 'Dry calving', 'Regenerated', 'Shelf-terminating', 'Not assigned'. Marine and Lake terminating are classified as “tidewater” in OGGM and cannot advance - they “calve” instead, using a very simple parameterisation.

[6]	Glacier status: 'Glacier or ice cap', 'Glacier complex', 'Nominal glacier', 'Not assigned'. Nominal glaciers fail at the “Glacier Mask” processing step in OGGM.

[7]

The area of OGGM’s flowline glaciers is corrected to the one provided by the RGI, for area conservation and inter-comparison reasons. If you do not want to use the RGI area but the one computed from the shape geometry in the local OGGM map projection instead, set cfg.PARAMS['use_rgi_area'] to False. This is useful when using homemade inventories.

Topography data

When creating a Glacier directories a suitable topographical data source is chosen automatically, depending on the glacier’s location. OGGM supports a large number of datasets (almost all of the freely available ones, we hope). They are listed on the RGI-TOPO website.

The current default is to use the following datasets:

• NASADEM: 60°S-60°N
• COPDEM: Global, with missing regions (islands, etc.)
• GIMP, REMA: Regional datasets
• TANDEM: Global, with artefacts / missing data
• MAPZEN: Global, when all other things failed

These data are chosen in the provided order. If a dataset is not available, the next on the list will be tested: if the tested dataset covers 75% of the glacier area, it is selected. In practice, NASADEM and COPDEM are sufficient for all but about 300 of the world’s glaciers.

These data are downloaded only when needed (i.e.: during an OGGM run) and they are stored in the dl_cache_dir directory. The gridded topography is then reprojected and resampled to the local glacier map. The local grid is defined on a Transverse Mercator projection centered over the glacier, and has a spatial resolution depending on the glacier size. The default in OGGM is to use the following rule:

\[\Delta x = d_1 \sqrt{S} + d_2\]

where \(\Delta x\) is the grid spatial resolution (in m), \(S\) the glacier area (in km\(^{2}\)) and \(d_1\), \(d_2\) some parameters (set to 14 and 10, respectively). If the chosen spatial resolution is larger than 200 m (\(S \ge\) 185 km\(^{2}\)) we clip it to this value.

Important: when using these data sources for your OGGM runs, please refer to the original data provider of the data! OGGM adds a dem_source.txt file in each glacier directory specifying how to cite these data. We reproduce this information here.

Warning

A number of glaciers will still suffer from poor topographic information. Either the errors are large or obvious (in which case the model won’t run), or they are left unnoticed. The importance of reliable topographic data for global glacier modelling cannot be emphasized enough, and it is a pity that no consistent, global DEM is yet available for scientific use. Visit rgitools for a discussion about our current efforts to find “the best” DEMs.

Note

In this blogpost we talk about which requirements a DEM must fulfill to be helpful to OGGM. And we also explain why and how we preprocess certain DEMs before we make them available to the OGGM workflow.

Climate data

The MB model implemented in OGGM needs monthly time series of temperature and precipitation. The current default is to download and use the CRU TS data provided by the Climatic Research Unit of the University of East Anglia.

‣ CRU (default)

If not specified otherwise, OGGM will automatically download and unpack the latest dataset from the CRU servers. To download them you can use the following convenience functions:

from oggm.shop import cru
cru.get_cl_file()
cru.get_cru_file(var='tmp')
cru.get_cru_file(var='pre')

Warning

While each downloaded zip file is ~200mb in size, they are ~2.9Gb large after decompression!

The raw, coarse (0.5°) dataset is then downscaled to a higher resolution grid (CRU CL v2.0 at 10’ resolution) following the anomaly mapping approach described by Tim Mitchell in his CRU faq (Q25). Note that we don’t expect this downscaling to add any new information than already available at the original resolution, but this allows us to have an elevation-dependent dataset based on a presumably better climatology. The monthly anomalies are computed following Harris et al., (2010): we use standard anomalies for temperature and scaled (fractional) anomalies for precipitation. At the locations where the monthly precipitation climatology is 0 we fall back to the standard anomalies.

When using these data, please refer to the original provider:

Harris, I., Jones, P. D., Osborn, T. J., & Lister, D. H. (2014). Updated high-resolution grids of monthly climatic observations - the CRU TS3.10 Dataset. International Journal of Climatology, 34(3), 623–642. https://doi.org/10.1002/joc.3711

‣ ECMWF (ERA5, CERA, ERA5-Land)

The data from ECMWF are used “as is”, i.e. without any further downscaling. We propose several datasets (see oggm.shop.ecmwf.process_ecmwf_data()) and, with the task oggm.tasks.historical_delta_method(), also allow for combinations of them.

When using these data, please refer to the original provider:

For example for ERA5:

Hersbach, H., Bell, B., Berrisford, P., Biavati, G., Horányi, A., Muñoz Sabater, J., Nicolas, J., Peubey, C., Radu, R., Rozum, I., Schepers, D., Simmons, A., Soci, C., Dee, D., Thépaut, J-N. (2019): ERA5 monthly averaged data on single levels from 1979 to present. Copernicus Climate Change Service (C3S) Climate Data Store (CDS). (Accessed on < 01-12-2020 >), 10.24381/cds.f17050d7

‣ User-provided dataset

You can provide any other dataset to OGGM by setting the climate_file parameter in params.cfg. See the HISTALP data file in the sample-data folder for an example.

‣ GCM data

OGGM can also use climate model output to drive the mass-balance model. In this case we still rely on gridded observations (CRU) for the baseline climatology and apply the GCM anomalies computed from a preselected reference period. This method is sometimes called the delta method.

Currently we can process data from the CESM Last Millenium Ensemble project (see tasks.process_cesm_data()), and CMIP5/CMIP6 (tasks.process_cmip_data()).

Mass-balance data

In-situ mass-balance data is used by OGGM to calibrate and validate the mass-balance model. We rely on mass-balance observations provided by the World Glacier Monitoring Service (WGMS). The Fluctuations of Glaciers (FoG) database contains annual mass-balance values for several hundreds of glaciers worldwide. We exclude water-terminating glaciers and the time series with less than five years of data. Since 2017, the WGMS provides a lookup table linking the RGI and the WGMS databases. We updated this list for version 6 of the RGI, leaving us with 268 mass balance time series. These are not equally reparted over the globe:

Map of the RGI regions; the red dots indicate the glacier locations and the blue circles the location of the 254 reference WGMS glaciers used by the OGGM calibration. From our GMD paper.

These data are shipped automatically with OGGM. All reference glaciers have access to the timeseries through the glacier directory:

In [4]: gdir = workflow.init_glacier_directories('RGI60-11.00897',
   ...:                                          from_prepro_level=3,
   ...:                                          prepro_border=10)[0]
   ...: 

In [5]: mb = gdir.get_ref_mb_data()

In [6]: mb[['ANNUAL_BALANCE']].plot(title='WGMS data: Hintereisferner')
Out[6]: <AxesSubplot:title={'center':'WGMS data: Hintereisferner'}, xlabel='YEAR'>

Tutorials

The best way to learn OGGM is to run our tutorials, available in the form of Jupyter Notebooks.

You will find them online at: https://oggm.org/tutorials

To launch an interactive session on MyBinder and run the tutorials without having to install anything, visit Try OGGM online!

API Reference

This page lists all available functions and classes in OGGM. It is a hard work to keep everything up-to-date, so don’t hesitate to let us know (see Get in touch) if something’s missing, or help us (see Contributing to OGGM) to write a better documentation!

Workflow

Tools to set-up and run OGGM.

cfg.initialize	Read the configuration file containing the run’s parameters.
cfg.initialize_minimal	Same as initialise() but without requiring any download of data.
cfg.set_logging_config	Set the global logger parameters.
cfg.set_intersects_db	Set the glacier intersection database for OGGM to use.
cfg.reset_working_dir	Deletes the content of the working directory.
cfg.add_to_basenames	Add an entry to the list of BASENAMES.
workflow.init_glacier_directories	Initializes the list of Glacier Directories for this run.
workflow.execute_entity_task	Execute a task on gdirs.
workflow.gis_prepro_tasks	Run all flowline preprocessing tasks on a list of glaciers.
workflow.download_ref_tstars	Downloads and copies the reference list of t* to the working directory.
workflow.climate_tasks	Run all climate related entity tasks on a list of glaciers.
workflow.inversion_tasks	Run all ice thickness inversion tasks on a list of glaciers.
workflow.merge_glacier_tasks	Shortcut function: run all tasks to merge tributaries to a main glacier
workflow.calibrate_inversion_from_consensus	Fit the total volume of the glaciers to the 2019 consensus estimate.
workflow.match_regional_geodetic_mb	Regional shift of the mass-balance residual to match observations.

Troubleshooting

utils.show_versions

Prints the OGGM version and other system information.

Input/Output

utils.get_demo_file	Returns the path to the desired OGGM-sample-file.
utils.get_rgi_dir	Path to the RGI directory.
utils.get_rgi_region_file	Path to the RGI region file.
utils.get_rgi_glacier_entities	Get a list of glacier outlines selected from their RGI IDs.
utils.get_rgi_intersects_dir	Path to the RGI directory containing the intersect files.
utils.get_rgi_intersects_region_file	Path to the RGI regional intersect file.
utils.get_rgi_intersects_entities	Get a list of glacier intersects selected from their RGI IDs.
utils.get_ref_mb_glaciers	Get the list of glaciers we have valid mass balance measurements for.
utils.copy_to_basedir	Copies the glacier directories and their content to a new location.
utils.gdir_to_tar	Writes the content of a glacier directory to a tar file.
utils.base_dir_to_tar	Merge the directories into 1000 bundles as tar files.
global_tasks.write_centerlines_to_shape	Write the centerlines in a shapefile.
global_tasks.compile_glacier_statistics	Gather as much statistics as possible about a list of glaciers.
global_tasks.compile_run_output	Merge the output of the model runs of several gdirs into one file.
global_tasks.compile_climate_input	Merge the climate input files in the glacier directories into one file.
global_tasks.compile_task_log	Gathers the log output for the selected task(s)
global_tasks.compile_task_time	Gathers the time needed for the selected task(s) to run
global_tasks.compile_fixed_geometry_mass_balance	Compiles a table of specific mass-balance timeseries for all glaciers.
global_tasks.compile_climate_statistics	Gather as much statistics as possible about a list of glaciers.

OGGM Shop

shop.cru.get_cru_file	Returns a path to the desired CRU baseline climate file.
shop.cru.process_cru_data	Processes and writes the CRU baseline climate data for this glacier.
shop.cru.process_dummy_cru_file	Create a simple baseline climate file for this glacier - for testing!
shop.ecmwf.get_ecmwf_file	Returns a path to the desired ECMWF baseline climate file.
shop.ecmwf.process_ecmwf_data	Processes and writes the ECMWF baseline climate data for this glacier.
shop.histalp.get_histalp_file	Returns a path to the desired HISTALP baseline climate file.
shop.histalp.process_histalp_data	Processes and writes the HISTALP baseline climate data for this glacier.
shop.gcm_climate.process_gcm_data	Applies the anomaly method to GCM climate data
shop.gcm_climate.process_cesm_data	Processes and writes CESM climate data for this glacier.
shop.gcm_climate.process_cmip_data	Read, process and store the CMIP5 and CMIP6 climate data for this glacier.
shop.bedtopo.add_consensus_thickness	Add the consensus thickness estimate to the gridded_data file.
shop.its_live.velocity_to_gdir	Reproject the its_live files to the given glacier directory.
shop.rgitopo.init_glacier_directories_from_rgitopo	Initialize a glacier directory from an RGI-TOPO DEM.
shop.rgitopo.select_dem_from_dir	Select a DEM from the ones available in an RGI-TOPO glacier directory.
shop.rgitopo.dem_quality_check	Run a simple quality check on the rgitopo DEMs

Entity tasks

Entity tasks are tasks which are applied on single glaciers individually and do not require information from other glaciers (this encompasses the majority of OGGM’s tasks). They are parallelizable.

tasks.define_glacier_region	Very first task after initialization: define the glacier’s local grid.
tasks.process_dem	Reads the DEM from the tiff, attempts to fill voids and apply smooth.
tasks.glacier_masks	Makes a gridded mask of the glacier outlines that can be used by OGGM.
tasks.simple_glacier_masks	Compute glacier masks based on much simpler rules than OGGM’s default.
tasks.rasterio_glacier_mask	Writes a 1-0 glacier mask GeoTiff with the same dimensions as dem.tif
tasks.gridded_attributes	Adds attributes to the gridded file, useful for thickness interpolation.
tasks.gridded_mb_attributes	Adds mass-balance related attributes to the gridded data file.
tasks.gridded_data_var_to_geotiff	Writes a NetCDF variable to a georeferenced geotiff file.
tasks.compute_centerlines	Compute the centerlines following Kienholz et al., (2014).
tasks.compute_downstream_line	Computes the Flowline along the unglaciated downstream topography
tasks.compute_downstream_bedshape	The bedshape obtained by fitting a parabola to the line’s normals.
tasks.catchment_area	Compute the catchment areas of each tributary line.
tasks.catchment_intersections	Computes the intersections between the catchments.
tasks.initialize_flowlines	Computes more physical Inversion Flowlines from geometrical Centerlines
tasks.catchment_width_geom	Compute geometrical catchment widths for each point of the flowlines.
tasks.catchment_width_correction	Corrects for NaNs and inconsistencies in the geometrical widths.
tasks.terminus_width_correction	Sets a new value for the terminus width.
tasks.elevation_band_flowline	Compute “squeezed” or “collapsed” glacier flowlines from Huss 2012.
tasks.fixed_dx_elevation_band_flowline	Converts the “collapsed” flowline into a regular “inversion flowline”.
tasks.glacier_mu_candidates	Computes the mu candidates, glacier wide.
tasks.process_climate_data	Adds the selected climate data to this glacier directory.
tasks.process_custom_climate_data	Processes and writes the climate data from a user-defined climate file.
tasks.historical_delta_method	Applies the anomaly method to historical climate data.
tasks.historical_climate_qc	Check the “quality” of the baseline climate data and correct if needed.
tasks.local_t_star	Compute the local t* and associated glacier-wide mu*.
tasks.mu_star_calibration	Compute the flowlines’ mu* and the associated apparent mass-balance.
tasks.apparent_mb_from_linear_mb	Compute apparent mb from a linear mass-balance assumption (for testing).
tasks.apparent_mb_from_any_mb	Compute apparent mb from an arbitrary mass-balance profile.
tasks.fixed_geometry_mass_balance	Computes the mass-balance with climate input from e.g.
tasks.process_cru_data	Processes and writes the CRU baseline climate data for this glacier.
tasks.process_dummy_cru_file	Create a simple baseline climate file for this glacier - for testing!
tasks.process_histalp_data	Processes and writes the HISTALP baseline climate data for this glacier.
tasks.process_ecmwf_data	Processes and writes the ECMWF baseline climate data for this glacier.
tasks.process_gcm_data	Applies the anomaly method to GCM climate data
tasks.process_cesm_data	Processes and writes CESM climate data for this glacier.
tasks.process_cmip5_data	Renamed to process_cmip_data.
tasks.process_cmip_data	Read, process and store the CMIP5 and CMIP6 climate data for this glacier.
tasks.prepare_for_inversion	Prepares the data needed for the inversion.
tasks.mass_conservation_inversion	Compute the glacier thickness along the flowlines
tasks.filter_inversion_output	Filters the last few grid points after the physically-based inversion.
tasks.get_inversion_volume	Small utility task to get to the volume od all glaciers.
tasks.compute_velocities	Surface velocities along the flowlines from inverted ice thickness.
tasks.distribute_thickness_per_altitude	Compute a thickness map by redistributing mass along altitudinal bands.
tasks.distribute_thickness_interp	Compute a thickness map by interpolating between centerlines and border.
tasks.find_inversion_calving	Optimized search for a calving flux compatible with the bed inversion.
tasks.find_inversion_calving_from_any_mb	Optimized search for a calving flux compatible with the bed inversion.
tasks.init_present_time_glacier	Merges data from preprocessing tasks.
tasks.flowline_model_run	Runs a model simulation with the default time stepping scheme.
tasks.run_random_climate	Runs the random mass-balance model for a given number of years.
tasks.run_from_climate_data	Runs a glacier with climate input from e.g.
tasks.run_constant_climate	Runs the constant mass-balance model for a given number of years.
tasks.copy_to_basedir	Copies the glacier directories and their content to a new location.
tasks.gdir_to_tar	Writes the content of a glacier directory to a tar file.

Global tasks

Global tasks are tasks which are run on a set of glaciers (most often: all glaciers in the current run). They are not parallelizable at the user level but might use multiprocessing internally.

global_tasks.gis_prepro_tasks	Run all flowline preprocessing tasks on a list of glaciers.
global_tasks.climate_tasks	Run all climate related entity tasks on a list of glaciers.
global_tasks.inversion_tasks	Run all ice thickness inversion tasks on a list of glaciers.
global_tasks.calibrate_inversion_from_consensus	Fit the total volume of the glaciers to the 2019 consensus estimate.
global_tasks.match_regional_geodetic_mb	Regional shift of the mass-balance residual to match observations.
global_tasks.merge_glacier_tasks	Shortcut function: run all tasks to merge tributaries to a main glacier
global_tasks.compute_ref_t_stars	Detects the best t* for the reference glaciers and writes them to disk
global_tasks.get_ref_mb_glaciers	Get the list of glaciers we have valid mass balance measurements for.
global_tasks.write_centerlines_to_shape	Write the centerlines in a shapefile.
global_tasks.compile_run_output	Merge the output of the model runs of several gdirs into one file.
global_tasks.compile_climate_input	Merge the climate input files in the glacier directories into one file.
global_tasks.compile_task_log	Gathers the log output for the selected task(s)
global_tasks.compile_task_time	Gathers the time needed for the selected task(s) to run
global_tasks.compile_glacier_statistics	Gather as much statistics as possible about a list of glaciers.
global_tasks.compile_fixed_geometry_mass_balance	Compiles a table of specific mass-balance timeseries for all glaciers.
global_tasks.compile_climate_statistics	Gather as much statistics as possible about a list of glaciers.

Command line interface (CLI)

These commands are available:

• oggm_netrc_credentials
• oggm_prepro
• oggm_benchmark

cli.prepro_levels.run_prepro_levels

Generate the preprocessed OGGM glacier directories for this OGGM version

Classes

Listed here are the classes which are relevant at the API level (i.e. classes which are used and re-used across modules and tasks).

GlacierDirectory	Organizes read and write access to the glacier’s files.
Centerline	Geometry (line and widths) and flow rooting properties, but no thickness
Flowline	A Centerline with additional properties: input to the FlowlineModel
MassBalanceModel	Interface and common logic for all mass balance models used in OGGM.
FlowlineModel	Interface to OGGM’s flowline models
FileModel	Duck FlowlineModel which actually reads data out of a nc file.

Glacier directories

Glacier directories (see also: GlacierDirectory) are folders on disk which store the input and output data for a single glacier during an OGGM run. The data are on disk to be persistent, i.e. they won’t be deleted unless you ask OGGM to. You can start a run from an existing directory, avoiding to re-do unnecessary computations.

Initialising a glacier directory

The easiest way to initialize a glacier directory is to start from a pre-processed state available on the OGGM servers:

In [1]: import os

In [2]: import oggm

In [3]: from oggm import cfg, workflow

In [4]: from oggm.utils import gettempdir

In [5]: cfg.initialize()  # always initialize before an OGGM task

# The working directory is where OGGM will store the run's data
In [6]: cfg.PATHS['working_dir'] = os.path.join(gettempdir(), 'Docs_GlacierDir')

In [7]: gdirs = workflow.init_glacier_directories('RGI60-11.00897',
   ...:                                           from_prepro_level=1,
   ...:                                           prepro_border=10)
   ...: 

In [8]: gdir = gdirs[0]  # init_glacier_directories always returns a list

We just downloaded the minimal input for a glacier directory. The GlacierDirectory object contains the glacier metadata:

In [9]: gdir
Out[9]: 
<oggm.GlacierDirectory>
  RGI id: RGI60-11.00897
  Region: 11: Central Europe
  Subregion: 11-01: Alps                            
  Name: Hintereisferner
  Glacier type: Glacier
  Terminus type: Land-terminating
  Area: 8.036 km2
  Lon, Lat: (10.7584, 46.8003)
  Grid (nx, ny): (139, 94)
  Grid (dx, dy): (50.0, -50.0)

In [10]: gdir.rgi_id
Out[10]: 'RGI60-11.00897'

It also points to a specific directory in disk, where the files are written to:

In [11]: gdir.dir
Out[11]: '/tmp/OGGM/Docs_GlacierDir/per_glacier/RGI60-11/RGI60-11.00/RGI60-11.00897'

In [12]: os.listdir(gdir.dir)
Out[12]: 
['glacier_grid.json',
 'outlines.tar.gz',
 'log.txt',
 'diagnostics.json',
 'dem_source.txt',
 'dem.tif',
 'intersects.tar.gz']

Users usually don’t have to care about where the data is located. GlacierDirectory objects help you to get this information:

In [13]: fdem = gdir.get_filepath('dem')

In [14]: fdem
Out[14]: '/tmp/OGGM/Docs_GlacierDir/per_glacier/RGI60-11/RGI60-11.00/RGI60-11.00897/dem.tif'

In [15]: import xarray as xr

In [16]: xr.open_rasterio(fdem).plot(cmap='terrain');

This persistence on disk allows for example to continue a workflow that has been previously interrupted. Initialising a GlacierDirectory from a non-empty folder won’t erase its content:

In [17]: gdir = workflow.init_glacier_directories('RGI60-11.00897')[0]

In [18]: os.listdir(gdir.dir)  # the directory still contains the data
Out[18]: 
['glacier_grid.json',
 'outlines.tar.gz',
 'log.txt',
 'diagnostics.json',
 'dem_source.txt',
 'dem.tif',
 'intersects.tar.gz']

For more information about how to use GlacierDirectories, visit our tutorial on the topic.

cfg.BASENAMES

This is a list of the files that can be found in the glacier directory or its divides. These data files and their names are standardized and listed in the oggm.cfg module. If you want to implement your own task you’ll have to add an entry to this file too.

catchments_intersects.shp

The intersections between catchments (shapefile) in the local map projection (Transverse Mercator).

centerlines.pkl

A list of oggm.Centerline instances, sorted by flow order.

climate_historical.nc

The historical monthly climate timeseries stored in a netCDF file.

climate_historical_daily.nc

The historical daily climate timeseries stored in a netCDF file.(only temperature is really changing on daily basis,precipitation is just assumed constant for every day

climate_info.json

Some information (dictionary) about the mass balance parameters for this glacier.

climate_monthly.nc

Deprecated: old name for climate_historical.

dem.tif

A geotiff file containing the DEM (reprojected into the local grid).This DEM is not smoothed or gap files, and is the closest to the original DEM source.

dem_source.txt

A text file with the source of the topo file (GIMP, SRTM, …).

diagnostics.json

A dictionary containing runtime diagnostics useful for debugging.

downstream_line.pkl

A dictionary containing the downstream line geometry as well as the bed shape computed from a parabolic fit.

elevation_band_flowline.csv

A table containing the Huss&Farinotti 2012 squeezed flowlines.

flowline_catchments.shp

Each flowline has a catchment area computed from flow routing algorithms: this shapefile stores the catchment outlines (in the local map projection (Transverse Mercator).

gcm_data.nc

The monthly GCM climate timeseries stored in a netCDF file.

geometries.pkl

A dictionary containing the shapely.Polygons of a glacier. The “polygon_hr” entry contains the geometry transformed to the local grid in (i, j) coordinates, while the “polygon_pix” entry contains the geometries transformed into the coarse grid (the i, j elements are integers). The “polygon_area” entry contains the area of the polygon as computed by Shapely. The “catchment_indices” entrycontains a list of len n_centerlines, each element containing a numpy array of the indices in the glacier grid which represent the centerlines catchment area.

glacier_grid.json

A salem.Grid handling the georeferencing of the local grid.

glacier_mask.tif

A glacier mask geotiff file with the same extend and projection as the dem.tif. This geotiff has value 1 at glaciated grid points and value 0 at unglaciated points.

gridded_data.nc

A netcdf file containing several gridded data variables such as topography, the glacier masks, the interpolated 2D glacier bed, and more.

hypsometry.csv

A hypsometry file computed by OGGM and provided in the same format as the RGI (useful for diagnostics).

intersects.shp

The glacier intersects in the local map projection (Transverse Mercator).

inversion_flowlines.pkl

A “better” version of the Centerlines, now on a regular spacing i.e., not on the gridded (i, j) indices. The tails of the tributaries are cut out to make more realistic junctions. They are now “1.5D” i.e., with a width.

inversion_input.pkl

List of dicts containing the data needed for the inversion.

inversion_output.pkl

List of dicts containing the output data from the inversion.

linear_mb_params.pkl

When using a linear mass-balance for the inversion, this dict stores the optimal ela_h and grad.

local_mustar.json

A dict containing the glacier’s t*, bias, and the flowlines’ mu*

model_diagnostics.nc

A netcdf file containing the model diagnostics (volume, mass-balance, length…).

model_flowlines.pkl

List of flowlines ready to be run by the model.

model_run.nc

A netcdf file containing enough information to reconstruct the entire flowline glacier along the run (can be data expensive).

outlines.shp

The glacier outlines in the local map projection (Transverse Mercator).

Mass-balance

Mass-balance models found in the core.massbalance module.

They follow the MassBalanceModel interface. Here is a quick summary of the units and conventions used by all models:

Units

The computed mass-balance is in units of [m ice s-1] (“meters of ice per second”), unless otherwise specified (e.g. for the utility function get_specific_mb). The conversion from the climatic mass-balance ([kg m-2 s-1] ) therefore assumes an ice density given by cfg.PARAMS['ice_density'] (currently: 900 kg m-3).

Time

The time system used by OGGM is a simple “fraction of year” system, where the floating year can be used for conversion to months and years:

In [19]: from oggm.utils import floatyear_to_date, date_to_floatyear

In [20]: date_to_floatyear(1982, 12)
Out[20]: 1982.9166666666667

In [21]: floatyear_to_date(1.2)
Out[21]: (1, 3)

Interface

MassBalanceModel	Interface and common logic for all mass balance models used in OGGM.
MassBalanceModel.get_monthly_mb	Monthly mass-balance at given altitude(s) for a moment in time.
MassBalanceModel.get_annual_mb	Like self.get_monthly_mb(), but for annual MB.
MassBalanceModel.get_specific_mb	Specific mb for this year and a specific glacier geometry.
MassBalanceModel.get_ela	Compute the equilibrium line altitude for this year

Models

LinearMassBalance	Constant mass-balance as a linear function of altitude.
PastMassBalance	Mass balance during the climate data period.
ConstantMassBalance	Constant mass-balance during a chosen period.
RandomMassBalance	Random shuffle of all MB years within a given time period.
UncertainMassBalance	Adding uncertainty to a mass balance model.
MultipleFlowlineMassBalance	Handle mass-balance at the glacier level instead of flowline level.

Model Flowlines

Flowlines are what represent a glacier in OGGM. During the preprocessing stage of a glacier simulation these lines evolve from simple topography following lines to more abstract objects within the model.

This chapter provides an overview on the different line types, how to access the model flowlines and their attributes.

Hierarchy

First a short summary of the evolution or the hierarchy of these different flowline stages:

geometrical centerlines

These lines are calculated following the algorithm of Kienholz et al., (2014). They determine where the subsequent flowlines are situated and how many of them are needed for one glacier. The main task for this calculation is compute_centerlines(). These lines are not stored within a specific OGGM class but are stored within the GlacierDirectory as shapely objects.

inversion flowlines

To use the geometrical lines within the model they are transformed to Centerline objects. This is done within initialize_flowlines() where the lines are projected onto a xy-grid with regular spaced line-points. This step also takes care of tributary junctions. These lines are then in a later step also used for the bed inversion, hence their name.

downstream line

This line extends the glacier’s centerline along the unglaciated glacier bed which is necessary for advancing glaciers. This line is calculated along the valley floor to the end of the domain boundary within compute_downstream_line().

model flowlines

The dynamical OGGM model finally uses lines of the class Flowline for all simulations. These flowlines are created by init_present_time_glacier(), which combines information from several preprocessing steps, the downstream line and the bed inversion. From a user perspective, especially if preprocessed directories are used, these model flowlines are the most important ones and further informations on the class interface and attributes are given below.

Access

The easiest and most common way to access the model flowlines of a glacier is with its GlacierDirectory. For this we initialize a minimal working example including the model flowlines. This is achieved by choosing preprocessing level 4.

In [22]: import os

In [23]: import oggm

In [24]: from oggm import cfg, workflow

In [25]: from oggm.utils import gettempdir

In [26]: cfg.initialize()  # always initialize before an OGGM task

# The working directory is where OGGM will store the run's data
In [27]: cfg.PATHS['working_dir'] = os.path.join(gettempdir(), 'Docs_GlacierDir2')

In [28]: gdirs = workflow.init_glacier_directories('RGI60-11.00897',
   ....:                                           from_prepro_level=5,
   ....:                                           prepro_border=80)
   ....: 

In [29]: gdir = gdirs[0]  # init_glacier_directories always returns a list

In [30]: fls = gdir.read_pickle('model_flowlines')

In [31]: fls
Out[31]: 
[<oggm.core.flowline.MixedBedFlowline at 0x7f69d689d2e8>,
 <oggm.core.flowline.MixedBedFlowline at 0x7f69d68688d0>,
 <oggm.core.flowline.MixedBedFlowline at 0x7f69d689dd30>]

In [32]: [fl.order for fl in fls]
Out[32]: [0, 0, 1]

This glacier has three flowlines of type MixedBedFlowline provided as a list. And the flowlines are ordered by ascending Strahler numbers, where the last entry in the list is always the longest and very often most relevant flowline of that glacier.

Type of model flowlines

Flowline	A Centerline with additional properties: input to the FlowlineModel
MixedBedFlowline	A Flowline which can take a combination of different shapes (default)
ParabolicBedFlowline	A parabolic shaped Flowline with one degree of freedom
RectangularBedFlowline	Simple shaped Flowline, glacier width does not change with ice thickness
TrapezoidalBedFlowline	A Flowline with trapezoidal shape and two degrees of freedom

Important flowline functions

centerlines.initialize_flowlines	Computes more physical Inversion Flowlines from geometrical Centerlines
centerlines.compute_centerlines	Compute the centerlines following Kienholz et al., (2014).
centerlines.compute_downstream_line	Computes the Flowline along the unglaciated downstream topography
flowline.init_present_time_glacier	Merges data from preprocessing tasks.

Performance, cluster environments and reproducibility

If you plan to run OGGM on more than a handful of glaciers, you might be interested in using all processors available to you, whether you are working on your laptop or on a cluster: see Parallel computations for how to do this.

For regional or global computations you will need to run OGGM in Cluster environments. Here we provide a couple of guidelines based on our own experience with operational runs.

In Reproducibility with OGGM, we discuss certain aspects of scientific reproducibility with OGGM, and how we try to ensure that our results are reproducible (it’s not easy).

Parallel computations

OGGM is designed to use the available resources as well as possible. For single nodes machines but with more than one processor (e.g. for personal computers) OGGM ships with a multiprocessing approach which is fairly simple to use. For cluster environments with more than one machine, you can use MPI.

Multiprocessing

Most OGGM computations are embarrassingly parallel: they are standalone operations to be realized on one single glacier entity and therefore independent from each other (they are called entity tasks, as opposed to the non-parallelizable global tasks).

When given a list of Glacier directories on which to apply a given task, the workflow.execute_entity_task() will distribute the operations on the available processors using Python’s multiprocessing module. You can control this behavior with the use_multiprocessing config parameter and the number of processors with mp_processes. The default in OGGM is:

In [1]: from oggm import cfg

In [2]: cfg.initialize()

In [3]: cfg.PARAMS['use_multiprocessing']  # whether to use multiprocessing
Out[3]: False

In [4]: cfg.PARAMS['mp_processes']  # number of processors to use
Out[4]: 1

-1 means that all available processors will be used.

The following environment variables will override these settings:

• OGGM_USE_MULTIPROCESSING can be set to 1/True or 0/False to override the param files at initialisation
• OGGM_TEST_MULTIPROC is used to run the workflow tests with or without multiprocessing (default: False)

MPI

OGGM can be run in a cluster environment, using standard mpi features.

Note

In our own cluster deployment (see below), we chose not to use MPI, for simplicity. Therefore, our MPI support is currently untested: it should work, but let us know if you encounter any issue.

OGGM depends on mpi4py in that case, which can be installed either via conda:

conda install -c conda-forge mpi4py

or pip:

pip install mpi4py

mpi4py itself depends on a working mpi environment, which is usually supplied by the maintainers of your cluster. On conda, it comes with its own copy of mpich, which is nice and easy for quick testing, but maybe undesirable for the performance of actual runs.

For an actual run, invoke any script using oggm via mpiexec, and pass the --mpi parameter to the script itself:

mpiexec -n 10 python ./run_rgi_region.py --mpi

Be aware that the first process with rank 0 is the manager process, that by itself does not do any calculations and is only used to distribute tasks. So the actual number of working processes is one lower than the number passed to mpiexec/your clusters scheduler.

Cluster environments

Here we describe some of the ways to use OGGM in a cluster environment. We provide examples of our own set-up, but your use case might vary depending on the cluster type you are working with, who is administrating the cluster, etc.

Installation

The installation procedure explained in Installing OGGM should also work in cluster environments. If you don’t have admin rights, installing with conda in your $HOME probably is the easiest option. Once OGGM is installed, you can use your scripts (like the ones provided in the Tutorials). But you probably want to check if the tests pass and our Data storage section below first!

If you are lucky, your cluster might support singularity containers, in which case we highly recommend their usage.

Singularity and docker containers

For those not familiar with this concept, containers can be seen as a lightweight, downloadable operating system which can run programs for you. They are highly configurable, and come in many flavors.

Important

Containers may be unfamiliar to some of you, but they are the best way to ensure traceable, reproducible results with any numerical model. We highly recommend their use.

The OGGM team (mostly: Timo) provides, maintains and updates a Docker container. You can see all OGGM containers here. Our most important repositories are:

• untested_base is a container based on Ubuntu 18.04 and shipping with all OGGM dependencies installed on it. OGGM is not guaranteed to run on these, but we use them for our tests on Travis.
• base is built upon untested_base, but is pushed online only after the OGGM tests have run successfully on it. Therefore, is provides a a more secure base for the model, although we cannot guarantee that past or future version of the model will always work on it.
• oggm is built upon base each time that a new change is made to the OGGM codebase. They have OGGM installed, and are guaranteed to run the OGGM version they ship with. We cannot guarantee that past or future version of the model will always work on it.

To ensure reproducibility over time or different machines (and avoid dependency update problems), we recommend to use base or oggm for your own purposes. Use base if you want to install your own OGGM version (don’t forget to test it afterwards!), and use oggm if you know which OGGM version you want.

As an example, here is how we run a given fixed version of OGGM on our own cluster, using singularity to pull from docker hub:

# All commands in the EOF block run inside of the container
singularity exec docker://oggm/oggm:20200708 bash -s <<EOF
  set -e
  # Setup a fake home dir inside of our workdir, so we don't clutter the
  # actual shared homedir with potentially incompatible stuff
  export HOME="$OGGM_WORKDIR/fake_home"
  mkdir "\$HOME"
  # Create a venv that _does_ use system-site-packages, since everything is
  # already installed on the container. We cannot work on the container
  # itself, as the base system is immutable.
  python3 -m venv --system-site-packages "$OGGM_WORKDIR/oggm_env"
  source "$OGGM_WORKDIR/oggm_env/bin/activate"
  # OPTIONAL: make sure latest pip is installed
  pip install --upgrade pip setuptools
  # OPTIONAL: install another OGGM version (here provided by its git commit hash)
  pip install "git+https://github.com/OGGM/oggm.git@ce22ceb77f3f6ffc865be65964b568835617db0d"
  # Finally, you can test OGGM with `pytest --pyargs oggm`, or run your script:
  YOUR_RUN_SCRIPT_HERE
EOF

Some explanations:

• singularity exec uses Singularity to execute a series of commands in a singularity container, which here simply is taken from our Docker container base (singularity can run docker containers). Singularity is preferred over Docker in cluster environments, mostly for security and performance reasons. On our cluster, we use the SLURM manager, so we specify the number of nodes and CPU’s we’d like to use and run singularity with srun -n 1 -c X singularity exec docker://…. This might vary on your cluster.
• we fix the container version we want to use to a certain tag. With this, we are guaranteed to always use the same software versions across runs.
• it follows a number of commands to make sure we don’t mess around with the system settings. Here we use an $OGGM_WORKDIR variable which is probably not available in your case: it points to a directory you can write to, and where OGGM will work (for example, it might also be the directory you are working on with OGGM (cfg.PATHS[‘working_dir’]). We suggest to replace this variable with what works for you.
• the oggm docker images ship whith an OGGM version guaranteed to work on this container. Sometimes, you may want to use another OGGM version, for example whith newer developments on it. You might also add your own flavor or parameterization to OGGM into the environment. For this you can use pip and install the version you want. Here we show an example where we install a specific OGGM version, here specified by its git hash (you can use a git tag as well). If you do that, you might want to run the tests once first to make sure that it works as expected. You can do that by replacing YOUR_RUN_SCRIPT_HERE with pytest –pyargs oggm –run-slow!
• Finally, the YOUR_RUN_SCRIPT_HERE is the actual command you want to run from this container! Most of the time, it will be a call to your python script.

We recommend to keep these scripts alongside our code and data, so that you can trace them later on.

Data storage

‣ Input

OGGM needs a certain amount of data to run (see OGGM Shop). Regardless if you are using pre-processed directories or raw data, you will need to have access to them from your environment. The default in OGGM is to download the data and store it in a folder, specified in the $HOME/.oggm_config file (see dl_cache_dir in First step: system settings for input data).

The structure of this folder is following the URLs from which the data is obtained. You can either let OGGM fill it up at run time by downloading the data (recommended if you do regional runs, i.e. don’t need the entire data set), but you might also want to pre-download everything using wget or equivalent. OGGM will use the data as long as the url structure is OK.

System administrators can mark this folder as being “read only”, in which case OGGM will run only if the data is already there and exit with an error otherwise.

‣ Output

Warning

An OGGM run can write a significant amount of data. In particular, it writes a very large number of folder and files. This makes certain operations like copying or even deleting working directory folders quite slow.

Therefore, there are two ways to reduce the amount of data (and data files) you have to deal with:

• the easiest way is to simply delete the glacier directories after a run and keep only the aggregated statistics files generated with the compile_ tasks (see Input/Output). A typical workflow would be to start from pre-processed directories, do the run, aggregate the results, copy the aggregated files for long term storage, and delete the working directory.
• the method above does not allow to go back to a single glacier for plotting or restarting a run, or to have a more detailed look at the glacier geometry evolution. If you want to do these things, you’ll need to store the glacier directories as well. In order to reduce the number of files you’ll have to deal with in this case, you can use the utils.gdir_to_tar() and utils.base_dir_to_tar() functions to create compressed, aggregated files of your directories. You can later initialize new directories from these tar files with the from_tar keyword argument in workflow.init_glacier_directories(). See our dedicated Tutorials on the topic.

Run per RGI region, not globally

For performance and data handling reasons, we recommend to run the model on single RGI regions independently (or smaller regional entities). This is a good compromise between performance (parallelism) and output file size as well as other workflow considerations.

On our cluster, we use the following parallelization strategy: we use an array of jobs to submit as many jobs as RGI regions (or experiments, if you are running experiments on a single region for example), and each job is run on one node only. This way, we avoid using MPI and do not require communication between nodes, while still using our cluster at near 100%.

Reproducibility with OGGM

Reproducibility has become an important topic recently, and we scientists have to do our best to make sure that our research findings are “findable, accessible, interoperable, and reusable” (FAIR).

Within OGGM, we do our best to follow the FAIR principles.

Source code and version control

The source code of OGGM is located on GitHub. All the history of the codebase (and the tests and documentation) are documented in the form of git commits.

When certain development milestones are reached, we release a new version of the model using a so-called “tag” (version number). We will try to follow our own semantic versioning convention for release numbers. We use MAJOR.MINOR.PATCH, with:

1. PATCH version number increase when the changes to the codebase are small increments or harmless bug fixes, and when we are confident that the model output is not affected by these changes.
2. MINOR version number increase when we add functionality or bug fixes which are not affecting the model behavior in a significant way. However, it is possible that the model results are affected in some unpredictable ways, that we estimated to be “small enough” to justify a minor release instead of major one. Unlike the original convention, we cannot always guarantee backwards compatibility in the OGGM syntax yet, because it is too costly. We’ll try not to brake things at each release, though
3. MAJOR version number increase when we significantly change the OGGM syntax and/or the model results, for example by relying on a new default parametrization.

The current OGGM model version is:

In [5]: import oggm

In [6]: oggm.__version__
Out[6]: '1.4.0'

We document the changes we make to the model on GitHub, and in the Version history.

Dependencies

OGGM relies on a large number of external python packages (dependencies). Many of them have complex dependencies themselves, often compiled binaries (for example rasterio, which relies on a C package: GDAL).

The complexity of this dependency tree as well as the permanent updates of both OGGM and its dependencies has lead to several unfortunate situations in the past: this involved a lot of maintenance work for the OGGM developers that had little or nothing to do with the model itself.

Furthermore, while the vast majority of the dependency updates are without consequences, some might change the model results. As an example, updates in the interpolation routines of GDAL/rasterio can change the glacier topography in a non-traceable way for OGGM. This is an obstacle to reproducible science, and we should try to avoid these situations.

Therefore, we have written a “roadmap” as a tool to guide our decision regarding software dependencies in OGGM. This document also lists some example situations affecting model users and developers.

Important

The short answer is: use our docker/singularity containers for the most reproducible workflows. Refer to Singularity and docker containers for how to do that.

Dependence on hardware and input data

The OGGM model will always be dependant on the input data (topography, climate, outlines…). Be aware that while certain results are robust (like interannual variability of surface mass-balance), other results are highly sensitive to small changes in the boundary conditions. Some examples include:

• the ice thickness inversion at a specific location is highly sensitive to the local slope
• the equilibrium volume of a glacier under a constant climate is highly sensitive to small changes in the ELA or the bed topography
• more generally: growing large glaciers on longer periods are “more sensitive” to boundary conditions than shrinking small glaciers on shorter periods.

We haven’t really tested the dependency of OGGM on hardware, but we expect it to be low, as glaciers are not chaotic systems like the atmosphere.

Tools to monitor OGGM results

We have developed a series of checks to monitor the changes in OGGM. They are not perfect, but we constantly seek to improve them:

FAQ and Troubleshooting

We list here some of the questions we get most often, either on the OGGM Users mailing list or on github.

General questions

What is the difference between OGGM and other glacier models?

There are plenty of established ice dynamics models, and some of them are open-source (e.g. PISM, Elmer/Ice).

The purpose of OGGM is to be an easy to use, fully automated global glacier model, i.e. applicable to any glacier in the world with or without specific tuning or tweaking. Therefore, it does not attempt to replace (and even less compete with) these established ice dynamics models: it can be seen as a “framework”, a set of unified tools with eases the process of working with many mountain glaciers at once.

There is a standard modelling chain in OGGM (with a mass-balance model and a multiple flowline model) but there is no obligation to use all of these tools. For example, we can easily picture a workflow where people will use OGGM to create homogenized initial conditions (topography, climate) but use a higher order dynamical model like PISM instead of the simplified OGGM dynamics. For these kind of workflows, we created the OGGM-contrib example package which should help OGGM users to implement their own physics in OGGM.

Can I use OGGM to simulate <my favourite glacier>?

The short answer is: “yes, but…”

The longer answer is that OGGM has been designed to work with all the world’s glaciers, and calibrated only on a few hundreds of them (and that’s only the mass-balance model…). We are quite confident that OGGM provides reasonable global estimates of glacier mass-balance and glacier change: this is a result of the law of large numbers, assuming that the uncertainty for each single glacier can be large but random and Gaussian.

If you use OGGM for a single or and handful of glaciers, chances are that the outcome is disappointing. For these kind of applications, you’ll probably need to re-calibrate OGGM using local data, for example of mass-balance or observations of past glacier change.

Can I use OGGM to simulate long term glacier evolution?

It depends what you mean by “long-term”: at centennial time scales, probably, yes. At millenial time scales, maybe. At glacial time scales, probably not. The major issue we have to face with OGGM is that it uses a “glacier-centric” approach: it can simulate the mountain glaciers and ice-caps we know from contemporary inventories, but it cannot simulate glaciers which existed before but have disappeared today.

Also, if glaciers grow into large ice complexes and ice caps, the flowline assumption becomes much less valid than for typical valley glaciers found today. For these situations, fully distributed models like PISM are more appropriate.

We are currently in the process of testing and tuning OGGM for post-LIA simulations in the Alps. Reach out if you would like to know more about our progress.

I have a question about OGGM, can we talk about it per email/phone?

Thanks for your interest in OGGM! Usually, we prefer to keep usage questions on github issues so that everybody can learn from all questions and their answers. You can also join our Slack discussion channel if you want a more interactive forum. Keep in touch with us per email if you’d like to join, we are a very open community!

Usage

Can I export OGGM centerlines to a shapefile?

Yes! There is a function to do exactly that: utils.write_centerlines_to_shape(). We also provide some already processed ones in Assets & downloads.

Can I export OGGM’s <special variable> to <another programme>?

Yes! Although it might make you have to write some code. The developers cannot think of all the great ideas/potential applications you have for the model. We also do a lot of work within the OGGM framework, i.e. most of the data we need is already there. Some variables are hidden, see e.g. here and there for discussions on github.

If you need some specific variables, please write on GitHub and we can discuss.

Troubleshooting

Some glaciers exit with errors. What should I do?

Many things can go wrong when simulating all the world glaciers with a single model. We’ve tried our best, but still many glaciers cannot be simulated automatically. Possible reasons include complex glacier geometries that cannot be simulated by flowlines, very cold climates which don’t allow melting to occur, or numerical instabilities during the simulation. Altogether, 4218 glaciers (3.6% of the total area worldwide) could not be modelled by OGGM in the standard global simulations. Some regions experience more errors than others (see the paper).

When you experience errors, you have to decide if they are due to an error in your code or a problem in OGGM itself. The number and type of errors might help you out to decide if you want to act and troubleshoot them (see below). Also, always keep in mind that the number of errors is less important than the glacier area they represent. Plenty or errors on small glaciers is not as bad as one large glacier missing.

Then, you have to carefully consider how to deal with missing glaciers. Most studies will upscale diagnostic quantities using power laws or interpolation: for example, use volume-area-scaling to compute the volume of glaciers that are missing after an OGGM run. Importantly, you have to always be aware that these quantities will be missing from the compiled run outputs, and should be accounted for in quantitative analyses.

What does the “Glacier exceeds domain boundaries” error mean?

This happens when a glacier grows larger than the original map boundaries. We recommend to increase the glacier map in this case, by setting cfg.PARAMS[‘border’] to a larger value, e.g. 100 or 200. The larger this value, the larger the glacier can grow (the drawback is that simulations become slower and hungrier in memory because the number of grid points increases as well). We do not recommend to go larger than 250, however: for these cases it is likely that something else is wrong in your workflow or OGGM itself.

What does the “CFL error” mean?

This happens when the ice dynamics simulation is unstable. In OGGM we use an adaptive time stepping scheme (which should avoid these kind of situations), but we also implemented thresholds for small time steps: i.e. if a simulation requires very small time steps we exit with an error in order to avoid extremely slow runs. There is not much you can do here, unless maybe use a lower CFL value, or set your own thresholds for small time steps (at the cost of computation time).

Can I use my own Glacier inventory and outlines in OGGM?

You will be able to include your own inventory and outlines in OGGM, as long as the format of your shapefile is the same as the RGI file (v5 and v6 are supported). The attribute table should match the RGI format with the same amount of columns and variable names. See Glacier outlines and intersects for more information about the list of glacier attributes needed by OGGM. If you decide to use your own inventory (e.g. maybe because it has a better glacier outline) we encourage you to contact the GLIMPS core team to let them know how your inventory improves the glacier digitalization compared to the current RGI version. If you want to see an example on how to give OGGM a different shapefile than RGI, have a look at our Tutorials!

Pitfalls and limitations

As the OGGM project is gaining visibility and momentum, we also see an increase of potential misuse or misunderstandings about what OGGM can and cannot do. Refer to our FAQ and Troubleshooting for a general introduction. Here, we discuss specific pitfalls in more details.

The default ice dynamics parameter “Glen A” is roughly calibrated

Out-of-the box, non-preprocessed OGGM will use fixed values for the creep parameter \(A\) and the sliding parameter \(f_s\):

In [1]: from oggm import cfg

In [2]: cfg.initialize()

In [3]: cfg.PARAMS['glen_a']
Out[3]: 2.4e-24

In [4]: cfg.PARAMS['fs']
Out[4]: 0.0

That is, \(A\) is set to the standard value for temperate ice as given in [Cuffey_Paterson_2010], and sliding is set to zero. While these values are reasonable, they are unlikely to be the ones yielding the best results at the global scale, and even more unlikely at regional or local scales. In particular, in the absence of sliding parameter, it is recommended to set \(A\) to a higher value to compensate for this missing process (effectively making ice “less stiff”).

New in version 1.4!

Since v1.4, OGGM can now calibrate \(A\) based on the consensus from [Farinotti_etal_2019] on any number of glaciers. We recommend to use a large number of glaciers: OGGM’s default glacier directories are calibrated at the RGI region level. This value is then also used by the forward dynamical model for consistency, according to the parameter use_inversion_params_for_run.

The pre-processed directories at level 3 to 5 are already calibrated to the consensus estimate at the RGI region level, i.e. unless specified otherwise, OGGM will use the pre-calibrated \(A\) value for these glaciers.

There is a way to calibrate \(A\) for the ice thickness inversion procedure based on observations of ice thickness (see this blog post about g2ti for an example). At the global scale, a value in the range of [1.1-1.5] times the default value gives volume estimates close to [Farinotti_etal_2019]. At regional scale, these values can differ, with a value closer to a factor 3, for example for the Alps. Note that this depends on other variables as well, such as our estimates of solid precipitation amounts (i.e mass turnover). This makes things complicated, as regions with overestimated solid precipitation can be compensated by a higher \(A\), and the other way around.

Finally, note that a change in \(A\) has a very strong influence for values close to the default value, but this influence reduces to the power of 1/5 for large values of A (in other words, there is a big difference between values of 1 to 1.3 times the default \(A\), but a comparatively small difference for values between 3 to 5 times the default \(A\)). This is best shown by this figure from [Maussion_etal_2019]:

Global volume estimated as a function of the multiplication factor applied to the ice creep parameter A, with five different setups: defaults, with sliding velocity, with lateral drag, and with rectangular and parabolic bed shapes only (instead of the default mixed parabolic/rectangular). In addition, we plotted the estimates from standard volume–area scaling (VAS, \(V = 0.034 S^{1.375}\)), Huss and Farinotti (2012) (HF2012) and Grinsted (2013) (G2013). The latter two estimates are provided for indication only as they are based on a different glacier inventory

Now, what you are probably asking yourself: how to choose the “best A” for my application?

Sorry, but we don’t know yet. We are working on it though! At the moment, what we recommend to do is to calibrate \(A\) so that the regional (or even local) estimates match the volume consensus of Farinotti et al. (2019) using the workflow.calibrate_inversion_from_consensus() global task. This is what we do for the default pre-processed directories at the RGI region level, so that you don’t have to worry about it.

The numerical model in OGGM v1.2 and below was numerically unstable in some conditions

See this github issue for a discussion pointing this out, and this example.

We now have fixed the most pressing issues. This blog post explains it in detail, for a summary:

• the previous algorithm was flawed, but did not result in significant errors at large scales
• the new algorithm is faster and more likely to be stable
• we don’t guarantee statibility in 100% of the cases, but when the model becomes unstable it should stop

The mass-balance model of OGGM is not calibrated with remote sensing data on individual glaciers

Currently, the values for the mass-balance parameters such as the temperature sensitivity, the precipitation correction factor, etc. are calibrated based on the in-situ measurements provided by the WGMS (traditional mass-balance data). For more information about the procedure, see [Maussion_etal_2019] and Mass-balance.

New in version 1.4!

As of v1.4, OGGM can now also calibrate the mass-balance model at the regional level based on available estimates. See workflow.match_regional_geodetic_mb() for more info.

References

[Farinotti_etal_2019]

(1, 2) Farinotti, D., Huss, M., Fürst, J. J., Landmann, J., Machguth, H., Maussion, F. and Pandit, A.: A consensus estimate for the ice thickness distribution of all glaciers on Earth, Nat. Geosci., 12(3), 168–173, doi:10.1038/s41561-019-0300-3, 2019.

[Maussion_etal_2019]

(1, 2) Maussion, F., Butenko, A., Champollion, N., Dusch, M., Eis, J., Fourteau, K., Gregor, P., Jarosch, A. H., Landmann, J., Oesterle, F., Recinos, B., Rothenpieler, T., Vlug, A., Wild, C. T. and Marzeion, B.: The Open Global Glacier Model (OGGM) v1.1, Geosci. Model Dev., 12(3), 909–931, doi:10.5194/gmd-12-909-2019, 2019.

Assets & downloads

This page lists some datasets that are either generated or used by OGGM and that can be useful to others.

Shapefiles of glacier centerlines, flowlines and widths

These variables are a standard output of OGGM, and can be useful to many. You will find the files here: https://cluster.klima.uni-bremen.de/~oggm/assets/oggm_v1.4/centerlines_shapes.

The following files are available:

• RGIxx_centerlines: the geometrical centerlines
• RGIxx_flowlines: the centerlines converted to “flowlines”, i.e. interpolated to a regular grid and where upslope trajectories are cropped
• RGIxx_geom_widths: the geometrical intersection of the flowlines’ normals with the glacier outlines
• RGIxx_widths: the geometrical widths corrected to reflect the glacier’s elevation-area distribution

If you use these data, please cite Maussion et al., 2019.

Shapefile of OGGM’s flowlines and widths for a subset of RGI region 15

RGI-TOPO

The RGI-TOPO dataset provides a local topography map for each single glacier in the RGI (currently version 6). It was generated with OGGM, and can be used very easily from the OGGM Shop (visit our Tutorials if you want to learn how to use them!).

Example of the various RGI-TOPO products at Malaspina glacier

Useful data tables

These data are tabular summary from available global datasets:

• https://cluster.klima.uni-bremen.de/~oggm/rgi/rgi62_stats.h5: the global RGI stripped from the geometries
• https://cluster.klima.uni-bremen.de/~oggm/g2ti/rgi62_itmix_df.h5: ice volumes from [Farinotti_etal_2019] in tabular form
• an example of OGGM output summary from the pre-processed directories. Useful outputs include terminus position, topographical variables, etc.

HDF files can be read with pandas’ read_hdf function.

OGGM-Hub

hub.oggm.org is our own JupyterHub deployment of OGGM on our servers in Bremen. It works similarly to MyBinder (see Try OGGM online) but it is bound to a username (you’ll need an account) and is therefore persistent (your files are saved between sessions). It also gives you access to more computing resources than MyBinder.

In order to be able to log in, you will need to have a (free) user account. It is super easy, just Get in touch if you want to try it out!

If you are new to the Jupyter Notebooks and JupyterLab, you will probably find this introduction to interactive notebooks quite useful.

Warning

hub.oggm.org is still experimental and we cannot guarantee that your work will always be safe here. We will do our best, but, you know, we are scientists after all. Please, make a copy of your files from time to time!

Hub or Binder?

We provide two solutions to try OGGM online, without local installation. Which is best for you? Here is a quick comparison.

Binder vs. OGGM-Hub

Binder	OGGM-Hub
Files not saved between sessions	Files saved between sessions
Limited computational resources	Dedicated processing and space on OGGM servers
Use cases: quick tests and demos	Use cases: deeper explorations and teaching
No registration required	Contact us to register
Free!	Free!

How does this work?

We use a single compute node located in Bremen to welcome the hub users. Currently—we are still trying things out—each user gets enough CPUs and enough RAM to run OGGM on several glaciers at once. This is not enough to do heavy work, but will get you through the exploratory phase or even small regional runs. Each user also gets a persistent 16Gb disk to save output data, notebooks and scripts. The OGGM-specific input data (i.e. everything that is downloaded automatically between users, see system settings) is shared among users (the shared folder in your $HOME). The first time you run a new glacier, OGGM will first check if the data is available in the shared folder, and if not it will download it for you and the other users.

The environment you have access to has a recent version of OGGM installed in it (updated every few weeks). Starting with OGGM v1.4, we will also provide environments with a pinned OGGM version, which you will be able to choose when logging in.

Accessing the tutorials (and other content) with nbgitpuller

Per default, your user space after logging in should be empty. We recommend using nbgitpuller to automatically download content from our tutorials repository for you.

You can execute this command in your JupyterHub terminal (Launcher -> Start a terminal):

$ gitpuller https://github.com/OGGM/tutorials master tutorials

That will copy the notebooks into the tutorials folder in your home directory (on OGGM-Hub, not your local machine). You can use a similar command to pull content from other repositories as well (e.g. the OGGM-Edu notebooks).

Another way to pull content into your hub is to use a special weblink. Say, for example, that you would like to download the content of Lizz’s glacier course (Spanish notebooks) into your lab as well. You can use the nbgitpuller link generator to create the following links which, once clicked, will open your workspace with the new notebooks in it. Here are some useful links to add notebooks to your hub:

• Add OGGM’s tutorial notebooks to your hub
• Add Lizz’s Clubes de Ciencia Perú 2019 notebooks to your hub

Important

nbgitpuller will never overwrite changes that the user made to the files in the pulled folder. This is very important to remember: sometimes you would like to get an updated version of the notebooks for example, and this will not work if you made changes to the file there. Therefore, it is always a good idea to make a working copy of the original file/folder before working on it (right-click -> rename).

The full set of rules used by nbgitpuller while pulling is explained here.

Top tip: copy-pasting text with the mouse in JupyterLab

Copying to and from JupyterLab can be annoying at times (context). This is one of the most frequent issue hitting users of JupyterLab when working in a terminal or when selecting text from notebook cells.

In these cases, press shift + right click to experience a standard “copy/paste” mouse menu.

Version history

v1.4.0 (17.02.2021)

This a new major update of the OGGM model. It it the result of one year of development, with several non-backwards compatible changes.

We recommend all users to update to this version.

Major new release 1.4!

There have been a large number of additions too long to be summarized, and the list below is far from complete (we have waited way too long for this release). Here are the highlights:

• new option to compute centerlines: “elevation band flowlines”
• new option to calibrate OGGM mass-balance regionally to geodetic estimates
• new option to calibrate the creep parameter Glen A to match the ice thickness to the Farinotti et al. (2019) consensus
• users can now choose from a variety of pre-processed directories, including with new climate data (e.g. ERA5)
• OGGM now has a calving parameterization (switched off per default)
• OGGM shop, to download several new input datasets
• Historical runs (“spin-up”) are now available per default and can be readily used for projections
• and much much more….

Note: not all changes since v1.3.1 are documented below. We’ll try to be better with documenting changes in the future.

Breaking changes

• The dynamical model now has a “real” parameterization for calving (WIP). A blog post explaining it can be found on the website (PR945). By Fabien Maussion
• The calving parameterization has been extended and made more useful by logging its output to compiled files. See PR996 for code changes and watch out for upcoming changes in the documentation and notebooks. By Fabien Maussion
• The new default when applying GCM data to a glacier is to correct for temperature standard deviation (PR978). The previous default was wrong and should not be the default. By Fabien Maussion
• Added a new “glacier directory initialization” global task: init_glacier_directories (PR983, GH965). It replaces init_glacier_regions and covers all its functionality, except that it does not process the DEM data (this was a confusing “feature” of init_glacier_regions). The old task init_glacier_regions is officially deprecated but without warnings for now. Since it is a very widely used task, we prefer to deprecate it in a slow cycle: first, change the documentation, deprecate later. By Fabien Maussion
• More climate datasets are now supported in OGGM (PR1036). A new task (historical_climate_qc) has been added to quality check the climate timeseries. This has not been tested intensively yet and is still a WIP. By Fabien Maussion
• The order of the tasks applied to the preprocessed levels has changed, climate data comes in later (PR1038). By Fabien Maussion
• The default DEMS used for each glacier have changed for more modern ones (PR1073). By Fabien Maussion
• The inversion tasks now can invert for trapezoid shapes (PR1045). This has non-trivial consequences for the model workflow. First and foremost, the decision about using a trapezoid bed (instead of parabolic when the parabola is too “flat”) is taken at the inversion step and not afterwards. The forward model and the inversion are therefore much more consistent. Furthermore, the task filter_inversion_output was simplified to take the estimated downstream bedshapes into account and now preserves glacier area, not volume. This also is a step towards more physical consistency between inverse and forward model. By Fabien Maussion
• The vascaling module has been removed from oggm core (PR1065). It is now available via a separate package (oggm-vas, maintained by Moritz Oberrauch).
• New options to compute the length of a glacier during a run: PARAMS[‘min_ice_thick_for_length’] and PARAMS[‘glacier_length_method’] (PR1069). By Matthias Dusch.
• Several further important changes to be documented later in (PR1099). By Fabien Maussion.

Enhancements

• Added Copernicus DEM GLO-90 as optional DEM. Requires credentials to spacedata.copernicus.eu stored in a local .netrc file. Credentials can be added on the command line via $ oggm_netrc_credentials (PR961). By Matthias Dusch.
• Added NASADEM as optional DEM. This is a improved version of SRTM and could replace the current SRTM (https://lpdaac.usgs.gov/products/nasadem_hgtv001/). (PR971). By Matthias Dusch.
• Added support for “squeezed” flowlines from Huss & Farinotti 2012 (PR1040). The corresponding tasks are tasks.elevation_band_flowline() and tasks.fixed_dx_elevation_band_flowline(). By Fabien Maussion
• Added a calibrate_inversion_from_consensus global task which calibrates Glen A so that the volume of glaciers in a selection is matched (PR1043). By Fabien Maussion
• Added support for writing a NetCDF variable in gridded_data.nc file to a georeferenced GeoTiff file (PR1118). The new task are tasks.gridded_data_var_to_geotiff(). By Li Fei
• Added a find_inversion_calving_from_any_mb task which uses the Recinos et al. approach, but on any mass-balance profile (PR1043). By Fabien Maussion

Bug fixes

• Maintainance updates for upstream libraries and various small bug fixes (PR957, PR967, PR968, PR958, PR974, PR977, PR976, PR1124). By Fabien Maussion, Matthias Dusch and Li Fei.

v1.3.1 (16.02.2020)

Minor release with small improvements but an important and necessary change in multiprocessing.

Enhancements

• After a recent change in multiprocessing, creating a pool of workers became very slow. This change was necessary because of race conditions in GDAL, but these conditions are rarely relevant to users. We now make this change in multiprocessing optional (PR937)
• various improvements and changes in the dynamical model - mass-balance model API. These were necessary to allow compatibility with the PyGEM model (PR938, PR946, PR949, PR953, PR951). By Fabien Maussion and David Rounce.
• added a “flux gate” to allow for precise mass-conservation checks in numerical experiments (PR944). By Fabien Maussion.

v1.3.0 (02.02.2020)

The time stepping scheme of OGGM has been fixed for several flaws. This blog post explains it in detail. We expect some changes in OGGM results after this release, but they should not be noticeable in a vast majority of the cases.

We recommend all users to update to this version.

Breaking changes

• The adaptive time stepping scheme of OGGM has been fixed for several flaws which lead to instable results in certain conditions. See the blog post for a full description. The API didn’t change in the process, but the OGGM results are likely to change slightly in some conditions. (GH731, GH860, PR931). By Fabien Maussion and Alex Jarosch.

Enhancements

• The test_models test module has been refactored to use pytest fixtures instead of unittest classes (PR934 and PR922). By Chris Merrill.

v1.2.0 (04.01.2020)

OGGM is released under a new license. We now use the BSD-3-Clause license.

v1.1.3 (03.01.2020)

Minor release of the OGGM model with several small improvements. We don’t expect major changes in the model results due to this release.

Important: this will be the last release under a GPL license. The next release (v1.2) will be done without modifications but under a BSD-3-Clause License.

Enhancements

• New function cfg.add_to_basenames now allows users to define their own entries in glacier directories (GH731). By Fabien Maussion.
• New function inversion.compute_velocities writes the section and surface veloicites in the inversion output (GH876). By Beatriz Recinos.
• Added ASTER v3 as optional DEM. Requires credentials to urs.earthdata.nasa.gov stored in a local .netrc file. Credentials can be added on the command line via $ oggm_netrc_credentials (PR884). By Matthias Dusch.
• Added a global task (tasks.compile_task_time and the associated method at the GlacierDirectory level get_task_time) to time the execution of entity tasks (GH918). By Fabien Maussion.
• Improved performance of numerical core thanks to changes in our calls to np.clip (PR873 and PR903). By Fabien Maussion.
• Added a function cfg.initialize_minimal to run the flowline model without enforcing a full download of the demo files (PR921). By Fabien Maussion.

Bug fixes

• Small bugs in DEM processing fixed - internal refactoring followed, hopefully for the good (PR890 and PR886). By Fabien Maussion and Matthias Dusch.

v1.1.2 (12.09.2019)

Minor release of the OGGM model, with several substantial improvements, most notably:

• update in the inversion procedure for calving glaciers (Recinos et al., 2019)
• new glacier evolution model based on Marzeion et al., 2012

We don’t expect major changes in the model results due to this release.

Breaking changes

• run_until now makes sure that the years (months) are not crossed by the adaptive time-stepping scheme (GH710). run_until and run_until_and_store should now be consistent. The change is unlikely to affect the majority of users (which used run_until_and_store), but the results or run_until can be affected (PR726). By Matthias Dusch.
• find_inversion_calving has been renamed to find_inversion_calving_loop and will probably be deprecated soon (PR794). By Fabien Maussion.
• use_rgi_area=False now also recomputes CenLon and CenLat on the fly. (GH838). By Fabien Maussion.

Enhancements

• Added new gridded_attributes and gridded_mb_attributes tasks to add raster glacier attributes such as slope, aspect, mass-balance… to the glacier directory (PR725). This can be useful for statistical modelling of glacier thickness. By Matteo Castellani.
• Added support for a new DEM dataset: Mapzen, found on Amazon cloud (GH748, PR759). Also added some utility functions to handle DEMs, to be improved further in the near future. By Fabien Maussion.
• Added support for a new DEM dataset: REMA (PR759). By Fabien Maussion.
• Added an option to pre-process all DEMs at once (PR771). By Fabien Maussion.
• Added support for another evolution model: the volume-area-scaling based model of Marzeion et al., 2012 (PR662). This is a major enhancement to the code base as it increases the number of choices available to users and demonstrates the modularity of the model. By Moritz Oberrauch.
• Changed the way the calving flux is computed during the ice thickness inversion. This no longer relies on an iteration over mu*, but solves for h instead. The new function is likely to replace the “old” calving loop (PR794). By Fabien Maussion.
• compile_climate_input and compile_run_output are now faster for larger numbers of glaciers thanks to temporary files (PR814). By Anouk Vlug. Could be made faster with multiprocessing one day.
• OGGM can now run in “minimal mode”, i.e. without many of the hard dependencies (GH420). This is useful for teaching or idealized simulations, but won’t work in production. By Fabien Maussion.
• the flowline model gives access to new diagnostics such as ice velocity and flux along the flowline. The numerical core code changed in the process, and we will monitor performance after this change (PR853). By Fabien Maussion.

Bug fixes

• Preprocessed directories at the level 3 now also have the glacier flowlines ready for the run (GH736, PR771). By Fabien Maussion.
• Nominal glaciers now error early in the processing chain (GH832). By Fabien Maussion.
• Specific MB (not used operationaly) was wrongly computer for zero ice thickness rectangular or parabolic sections. This is now corrected (GH828). By Fabien Maussion.
• Fixed a bug in model output files where SH glaciers were wrongly attributed with NH calendar dates (GH824). By Fabien Maussion.

v1.1.1 (24.04.2019)

Minor release of the OGGM model, with several bugfixes and some improvements.

We don’t expect any change in the model results due to this release.

Enhancements

• Adapted graphics.plot_domain, graphics.plot_centerlines and graphics_plot_modeloutput_map to work with merged glaciers (PR726). By Matthias Dusch.
• Added (and updated) an official task to find the calving flux based on the mass-conservation inversion (inversion.find_inversion_calving). This is still in experimentation phase! (PR720). By Beatriz Recinos.
• Added a mechanism to add custom MB data to OGGM (GH724). By Fabien Maussion.
• The ALOS Global Digital Surface Model “ALOS World 3D - 30m” DEM from JAXA can now be used as alternative DEM within OGGM. See our tutorial on how to set an alternative DEM (PR734). By Matthias Dusch.
• Switch to setuptools-scm as a version control system (GH727). By Timo Rothenpieler.

Bug fixes

• Fixed several problems with the file download verification algorithm. By Timo Rothenpieler.
• Fixed a timing problem in the benchmark command line tool (PR717). By Fabien Maussion.

v1.1 (28.02.2019)

This is a major new release of the OGGM model, with substantial improvements to version 1. We recommend to use this version from now on. It coincides with the publication of our publication in Geoscientific Model Development.

New contributors to the project:

• Matthias Dusch (PhD student, University of Innsbruck), added extensive cross-validation tools and an associated website.
• Philipp Gregor (Master student, University of Innsbruck), added options to switch on lateral bed stress in the flowline ice dynamics
• Nicolas Champollion (PostDoc, University of Bremen), added GCM data IO routines.
• Sadie Bartholomew (Software Engineer, UK Met Office), added ability to replace colormaps in graphics with HCL-based colors using python-colorspace.

Breaking changes

• The utils.copy_to_basedir() function is changed to being an entity task. In addition gcm_data files, when present, will from now on always be copied when using this task (GH467 & PR468). By Anouk Vlug.
• Accumulation Area Ratio (AAR) is now correctly computed (GH361). By Fabien Maussion.
• The method used to apply CRU and GCM anomalies to the climatology has changed for precipitation: we now use scaled anomalies instead of the standard anomalies (PR393). The previous method might have lead to negative values in some cases. The corresponding reference t* have also been updated (PR407). This change has some consequences on the the model results: cross-validation indicates very similar scores, but the influence on global model output has not been assessed yet. By Fabien Maussion.
• It is now possible to run a simulation with spinup in the standard workflow (PR411). For this to happen it was necessary to clean up the many *filesuffix options. The new names are more explicit but not backwards compatible. The previous filesuffix is now called output_filesuffix. The previous input_filesuffix is now called climate_input_filesuffix. The random_glacier_evolution task is now called run_random_climate for consistency with the other tasks See the PR linked above for more info. By Fabien Maussion.
• RGI version 4 isn’t supported anymore (GH142). By Fabien Maussion.
• Rework of the 2d interpolation tasks for ice thickness in the context of ITMIX2. The new interpolation are better, but not backwards compatible. Aside of me I don’t think anybody was using them (PR465). By Fabien Maussion.
• Diagnostic variables (length, area, volume, ELA) are now stored at annual steps instead of montly steps (PR488). The old behavior can still be used with the store_monthly_step kwarg. Most users should not notice this change because the regionally compiled files were stored at yearly steps anyways. By Fabien Maussion.
• The list of reference t* dates is now generated differently: instead of the complex (and sort of useless) nearest neighbor algorithm we are now referring back to the original method of Marzeion et al. (2012). This comes together with other breaking changes, altogether likely to change the results of the mass-balance model for some glaciers. For more details see the PR: PR509 By Fabien Maussion.
• The ice dynamics parameters (Glen A, N, ice density) are now “real” parameters accessible via cfg.PARAMS (PR520, GH511 and GH27). Previously, they were also accessible via a module attribute in cfg, which was more confusing than helping. Deprecated and removed a couple of other things on the go, such as the dangerous ` optimize_inversion_params task (this cannot be optimized yet) and the useless volume_inversion wrapper (now called mass_conservation_inversion) By Fabien Maussion.
• The temperature sensitivity mu* is now flowline specific, instead of glacier wide. This change was necessary because it now allows low-lying tributaries to exist, despite of too high glacier wide mu*. This change had some wider reaching consequences in the code base and in the mass-balance models in particular: PR539. This will also allow to merge neighboring glaciers in the future. By Fabien Maussion.
• The “human readable” mu* information is now stored in a JSON dict instead of a csv: PR568. By Fabien Maussion.
• The global task glacier_characteristics has been renamed to compile_glacier_statistics (PR571). By Fabien Maussion.
• The process_cesm_data task has been been moved to gcm_climate.py addressing: GH469 & PR582. By Anouk Vlug.
• The shapefiles are now stored in the glacier directories as compressed tar files, addressing GH367 & GH615. This option can be turned off with cfg.PARAMS[‘use_tar_shapefiles’] = False. By Fabien Maussion.

Enhancements

• Added a utility function to easily get intersects files (PR402). By Fabien Maussion.
• The old GlaThiDa file linking the total volume of glaciers (T database) to RGI has been updated to RGI Version 6 (PR403). Generally, we do not recommend to use these data for calibration or validation because of largely unknown uncertainties. By Fabien Maussion.
• The computing efficiency of the 2D shallow ice model has been increased by a factor 2 (PR415), by avoiding useless repetitions of indexing operations. The results shouldn’t change at all. By Fabien Maussion.
• Added optional shape factors for mass-conservation inversion and FluxBasedModel to account for lateral drag dependent on the bed shape (PR429). Accepted settings for shape factors are None, ‘Adhikari’ (Adhikari & Marshall 2012), ‘Nye’ (Nye, 1965; equivalent to Adhikari) and ‘Huss’ (Huss & Farinotti 2012). Thorough tests with applied shape factors are still missing. By Philipp Gregor.
• Some amelioration to the mass-balance models (PR434). Added a repeat kwarg to the PastMassBalance in order to loop over a selected period. Added an UncertainMassBalance model which wraps an existing model and adds random uncertainty to it. By Fabien Maussion.
• The DEM sources are now clearly stated in each glacier directory, along with the original data citation (PR441). We encourage to always cite the original data providers. By Fabien Maussion.
• Added some diagnostic tools which make it easier to detect dubious glacier outlines or DEM errors (PR445). This will be used to report to the RGI authors. By Fabien Maussion.
• Added a new parameter (PARAMS['use_rgi_area']), which specifies whether OGGM should use the reference area provided by RGI or the one computed from the local map and reprojected outlines (PR458, default: True). By Matthias Dusch.
• A new simple_glacier_masks tasks allows to compute glacier rasters in a more robust way than the default OGGM method (PR476). This is useful for simpler workflows or to compute global statistics for external tools like rgitools. This task also computes hypsometry files much like RGI does. By Fabien Maussion.
• Reference glaciers now have mass-balance profiles attached to them, if available. You can get the profiles with gdir.get_ref_mb_profile() (PR493). By Fabien Maussion.
• New process_histalp_data taks to run OGGM with HISTALP data automatically. The task comes with a list of predefined t* like CRU and with different default parameters (see blog). The PR also adds some safety checks at the calibration and computation of the mass-balance to make sure there is no misused parameters (PR493). By Fabien Maussion.
• The process_cesm_data function has been split into two functions, to make it easier to run oggm with the climate of other GCM’s: process_cesm_data reads the CESM files and handles the CESM specific file logic. process_gcm_data is the general task able to handle all kind of data. process_cesm_data can also be used as an example when you plan make a function for running OGGM with another GCM (GH469 & PR582). Anouk Vlug.
• New process_dummy_cru_file task to run OGGM with randomized CRU data (PR603). By Fabien Maussion.
• Colormaps in some graphics are replaced with Hue-Chroma-Luminance (HCL) based improvements when python-colorspace is (optionally) installed (PR587). By Sadie Bartholomew.
• Added a workflow merge_glacier_tasks which merges tributary/surrounding glaciers to a main glacier, allowing mass exchange between them. This is helpful/necessary/intended for growing glacier experiments (e.g. paleoglaciology) (PR624). By Matthias Dusch.
• New oggm_prepro command line tool to run the OGGM preprocessing tasks and compress the directories (PR648). By Fabien Maussion.
• init_glacier_regions task now accepts RGI Ids strings as input instead of only Geodataframes previously (PR656). By Fabien Maussion.
• The entity_task decorator now accepts a fallback-function which will be executed if a task fails and cfg.PARAMS[‘continue_on_error’] = True. So far only one fallback function is implemented for climate.local_t_star (PR663). By Matthias Dusch.
• New process_gcm_data task to handle CMIP5 files. By Nicolas Champollion.

Bug fixes

• Remove dependency to deprecated matplotlib._cntr module (GH418). By Fabien Maussion.
• Fixed a bug in tidewater glaciers terminus position finding, where in some rare cases the percentile threshold was too low (PR444). By Fabien Maussion.
• Fixed a caching bug in the test suite, where some tests used to fail when run for a second time on a modified gdir (PR448). By Fabien Maussion.
• Fixed a problem with netCDF4 versions > 1.3 which returns masked arrays per default. We now prevent netCDF4 to return masked arrays altogether (GH482). By Fabien Maussion.

Internals

• We now use a dedicated server for input data such as modified RGI files (PR408). By Fabien Maussion.
• Test fix for googlemaps. By Fabien Maussion.
• Added a utility function (idealized_gdir()) useful to dow flowline experiments without have to create a local map (PR413). By Fabien Maussion.

v1.0 (16 January 2018)

This is the first official major release of OGGM. It is concomitant to the submission of a manuscript to Geoscientific Model Development (GMD).

This marks the stabilization of the codebase (hopefully) and implies that future changes will have to be documented carefully to ensure traceability.

New contributors to the project:

• Anouk Vlug (PhD student, University of Bremen), added the CESM climate data tools.
• Anton Butenko (PhD student, University of Bremen), developed the downstream bedshape algorithm
• Beatriz Recinos (PhD student, University of Bremen), participated to the development of the calving parametrization
• Julia Eis (PhD student, University of Bremen), developed the glacier partitioning algorithm
• Schmitty Smith (PhD student, Northand College, Wisconsin US), added optional parameters to the mass-balance models

v0.1.1 (16 February 2017)

Minor release: changes in ITMIX to handle the synthetic glacier cases.

It was tagged only recently for long term documentation purposes and storage on Zenodo.

v0.1 (29 March 2016)

Initial release, used to prepare the data submitted to ITMIX (see here).

This release is the result of several months of development (outside of GitHub for a large part). Several people have contributed to this release:

• Michael Adamer (intern, UIBK), participated to the development of the centerline determination algorithm (2014)
• Kévin Fourteau (intern, UIBK, ENS Cachan), participated to the development of the inversion and the flowline modelling algorithms (2014-2015)
• Alexander H. Jarosch (Associate Professor, University of Iceland), developed the MUSCL-SuperBee model (PR23)
• Johannes Landmann (intern, UIBK), participated to the links between databases project (2015)
• Ben Marzeion (project leader, University of Bremen)
• Fabien Maussion (project leader, UIBK)
• Felix Oesterle (Post-Doc, UIBK), develops OGGR and provided the AWS deployment script (PR25)
• Timo Rothenpieler (programmer, University of Bremen), participated to the OGGM deployment script (e.g. PR34, PR48), and developed OGGM installation tools
• Christian Wild (master student, UIBK), participated to the development of the centerline determination algorithm (2014)

Contributing

Do you want to contribute to the model? You are more than welcome to do so and this is the right place to start.

• Citing OGGM
• Adding an external module to OGGM
• OGGM Enhancement Proposals (OEPs)
• Contributing to OGGM

Citing OGGM

Publication

If you want to refer to OGGM in your publications or presentations, please refer to the paper in Geoscientific Model Development.

BibTeX entry:

@Article{gmd-12-909-2019,
AUTHOR = {Maussion, F. and Butenko, A. and Champollion, N. and
          Dusch, M. and Eis, J. and Fourteau, K. and Gregor, P. and
          Jarosch, A. H. and Landmann, J. and Oesterle, F. and
          Recinos, B. and Rothenpieler, T. and Vlug, A. and Wild, C. T. and
          Marzeion, B.},
TITLE = {The Open Global Glacier Model (OGGM) v1.1},
JOURNAL = {Geoscientific Model Development},
VOLUME = {2019},
YEAR = {2019},
PAGES = {909--931},
URL = {https://www.geosci-model-dev.net/12/909/2019/},
DOI = {10.5194/gmd-12-909-2019}
}

Software DOI

If you want to refer to a specific version of the software you can use the Zenodo citation for this purpose. An example BibTeX entry:

@misc{OGGM_v1.1,
author       = {Fabien Maussion and Timo Rothenpieler and
                Matthias Dusch and Beatriz Recinos and Anouk Vlug and
                Ben Marzeion and Johannes Landmann and Julia Eis and
                Sadie Bartholomew and Nicolas Champollion and
                Philipp Gregor and Anton Butenko and Schmitty Smith and
                Moritz Oberrauch},
title        = {OGGM/oggm: v1.1},
month        = feb,
year         = 2019,
doi          = {10.5281/zenodo.2580277},
url          = {https://doi.org/10.5281/zenodo.2580277}
}

Logo

The OGGM logos are free to use!

full logo: pdf, large (2004x856), large (2004x856) with alpha channel, small (502x214), small (502x214) with alpha channel

icon logo: small (135x157), small (135x157) with alpha channel

Adding an external module to OGGM

Thanks for helping us to make the model better!

There are two ways to add a functionality to OGGM:

1. The easiest (and recommended) way for small bugfixes or simple functionalities is to add it directly to the main OGGM codebase. In this case, refer to the Contributing to OGGM page for how to do that.
2. If your endeavor is a larger project (i.e. a fundamental change in the model physics or a new workflow), you can still use option 1 above. However, there might be reasons (explained below) to use a different approach. This is what this page is for.

Why would I add my model to the OGGM set of tools?

We envision OGGM as a modular tool to model glacier behavior. We do not want to force anyone towards a certain set-up or paramaterization that we chose. However, we believe that the OGGM capabilities could be useful to a wide range of applications, and also to you.

Finally, we strongly believe in model intercomparisons. Agreeing on a common set of boundary conditions is the first step towards meaningful comparisons: this is where OGGM can help.

Can I use my own repository/website and my own code style to do this?

Yes you can!

Ideally, we would have your module added to the main codebase: this ensures consistency of the code and continuous testing. However, there are several reasons why making your own repository could be useful:

• complying to OGGM’s strict testing rules can be annoying, especially in the early stages of development of a model
• with you own repository you have full control on it’s development while still being able to use the OGGM workflow and multiprocessing capabilities
• with an external module the users who will use your model will have to download it from here and you can make sure that correct attribution is made to your work, i.e. by specifying that using this module requires a reference to a specific scientific publication
• if your funding agency requires you to have your own public website
• etc.

To help you in this project we have set-up a template repository from which you can build upon.

Before writing your own module we recommend to contact us to discuss the best path to follow in your specific case.

OGGM Enhancement Proposals (OEPs)

OGGM Enhancement Proposals (OEPs) are design documents describing mid- to long term goals of OGGM. Anyone can write or edit OEPs - and anyone is welcome to tackle the implementation of these goals!

See this github issue for a discussion about OEPs.

OEP-0001: Package dependencies and reproducibility in OGGM

Authors:Fabien Maussion, Timo Rothenpieler, Alex Jarosch Status:Largely implemented Created:11.11.2018

Abstract

OGGM relies on a large number of external python packages (dependencies). Many of them have complex dependencies themselves, often compiled binaries (for example rasterio, which relies on a C package: GDAL).

The complexity of this dependency tree as well as the permanent updates of both OGGM and its dependencies has lead to several unfortunate situations in the past: this involved a lot of maintenance work for the OGGM developers that had little or nothing to do with the model itself.

Furthermore, while the vast majority of the dependency updates are without consequences, some might change the model results. As an example, updates in the interpolation routines of GDAL/rasterio can change the glacier topography in a non-traceable way for OGGM. This is an obstacle to reproducible science, and we should try to avoid these situations.

OGGM, as a high level “top of the dependency pyramid” software, does not have the same requirements in terms of being always up-to-date as, say, general purpose libraries like pandas or matplotlib. With this document, the OGGM developers attempt to define a clear policy for handling package dependencies in the OGGM project. This policy can be seen as a set of “rules” or “guidelines” that we will try to follow as much as possible.

Example situations

Here are some example of situations that happened in the past or might happen in the future:

Situation 1

A new user installs OGGM with conda install oggm-deps and the installation fails because one of one of the dependencies. This is a problem in conda (or conda-forge) and has nothing to do with OGGM.

Situation 2

A new user installs OGGM with conda install oggm-deps: the installation succeeds, but the OGGM tests fail to pass. One of our dependencies renamed a functionality or deprecated it, and we didn’t update OGGM in time. This requires action in OGGM itself, but we don’t always have time to fix it quickly enough, leading to an overall bad user experience.

Situation 3

A developer writes a new feature and sends a pull-request: the tests pass on her machine but not on Travis. The failing tests are unrelated to the PR: it is one of our dependency update that broke something in OGGM. This a bad experience for new developers, and it is the job of an OGGM core developer to solve the problem.

Situation 4

A developer writes a quantitative test of the type: “the model simulation should yield a volume of xx.xxx km3 ice”: the test passes locally but fails on Travis. Indeed, the glacier topography is slightly different on Travis because of difference in the installed GDAL version, yielding non-negligible differences in model results.

Situation 5

Worst case scenario: someone tries to replicate the results of a simulation published in a paper, and her results are off by 10% to the published ones. A reason could be that the system and/or package dependencies are different for the new simulation environment. But which results are the correct ones?

These situations are frequent and apply to any project with complex dependencies (not only OGGM). These problems currently do not have a simple, “out-of-the box” solution. This document attempts to prioritize some of the issues and provide guidelines for how to handle software dependencies within the OGGM framework.

Goals

Here is a set of goals that we should always try to follow:

1. Stability is more important than dependency updates.
2. A standard dependency list of the names and fixed version number of the major OGGM dependencies should be defined and documented. The standard dependency list has its own version number which is decoupled from the OGGM one.
3. Updates of the standard dependency list should be rare, well justified and documented. Examples for updates include: a new feature we want to use, a performance increase, or regular updates to keep track with the scientific python stack (e.g. twice a year).
4. It should be possible to use a python environment fixed to the standard dependency list on all these platforms: the Bremen cluster, on Travis, on a local linux machine and on a university cluster with singularity.
5. The latest OGGM code should always run error-free on the latest standard dependency list. Older OGGM versions should have a standard dependency list version number attached to them, and scientific publications as well.
6. As far as possible, OGGM should run on the latest version of all packages as well. This rule is less important than Rule 5 and should not require urgent handling by the OGGM developers.
7. It should be possible for a new user to create a working environment based on the standard dependency list from scratch, either with a meta-package (i.e. conda install oggm-deps) or a file (conda install oggm-deps.yml or pip install requirements.txt).
8. If 7 fails, it should be possible for a user to create a working environment based on the latest dependencies from scratch, either with a meta-package (i.e. conda install oggm-deps-latest) or a file (conda install oggm-deps-latest.yml or pip install requirements-latest.txt).
9. We recommend users to define a fixed environment for OGGM. We do not take responsibility if users update packages on their own afterwards.
10. OGGM should provide tools to quickly and easily test a user installation.
11. OGGM should always work on Linux. Because of these dependency problems, we make no guarantee that OGGM will work on other operating systems (Mac OSX, Windows).

Standard dependency list and updates (goals 1, 2, 3)

The latest and all previous standard dependency lists can be found on the github repository: https://github.com/OGGM/OGGM-dependency-list

Discussions about whether the standard dependency list should be updated or not will take place on this repository or the main OGGM repository.

Docker and Singularity containers (goal 4)

The easiest way to guarantee consistency accross platforms and over longer periods of time are containers. A container image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries and settings.

The most widely used container platform is Docker. For security and preformance reasons, HPC centers prefer to use Singularity. Fortunately, Singularity containers can be built from Docker images.

OGGM maintains an Ubuntu container image that users can download and use for free, and convert it to a singularity image for use on HPC.

The images can be found at: https://hub.docker.com/r/oggm/oggm

The build scripts can be found at https://github.com/OGGM/OGGM-Docker

OGGM releases will point to a specific version of the Docker image for reproducible results over time.

Travis CI (goals 5, 6 and 11)

Travis CI is the tool we use for continuous testing of the OGGM software. The tests should run on the stable Docker image built with the standard dependency list. Optionally, we will monitor the tests on the latest image as well, but the tests are not guaranteed to pass (“allowed failures”).

The main OGGM repository will not test on other platforms than Linux. We might run the tests for other platforms as well, but this is without guarantee and should happen on a separate repository (e.g. on https://github.com/OGGM/OGGM-dependency-list).

pip and conda (goals 7 and 8)

Docker and Singularity containers are the most secure and consistent way to run OGGM. However, they require some knowledge about containers and the command line, and they still do not belong to the standard set of tools of most scientists.

Therefore, we should help and support users in installing OGGM dependencies “the standard way”, i.e. using pip or conda. We can do this by maintaining and testing the standard and latest dependency lists on various platforms as often as possible. When problems arise, we can attempt to fix them but make no guarantee for the problems generated upstream, i.e. problems which are unrelated to OGGM itself.

Check install (goal 10)

The user will have two complementary ways to test the correct installation of OGGM:

• pytest –pyargs oggm –run-slow –mpl will run the test suite. This test suite does not contain quantitative tests, i.e. it does not guarantee consistency of model results across platforms
• oggm.check_install() will be a top level function performing quantitative tests to see if user results are consistent with the benchmark container.

OEP-0002: OGGM on the cloud with JupyterHub and Pangeo

Authors:Fabien Maussion Status:Partly implemented (proof of concept for hub.oggm.org) Created:03.07.2019

Abstract

We plan to set-up and deploy the Open Global Glacier Model in a scalable cloud or HPC environment, and make this computing environment available to our users via a web browser.

We envision an online platform where people can log-in and get access to a fully functional computing environment where they can run the OGGM model. This platform will allow exploratory experimenting and teaching, as well as “serious work” and analyses. The resources will scale according to demand. The user environment will be personalized and persistent, so that our users can prepare some computations, start them, log out, then log back in and still find the computing environment he or she left earlier. The advantages for the users will be important: scalable computing resources, no installation burden, no data download, no version issues, a user-friendly development environment, all that in a web browser.

Glossary

There is quite a few tools and concepts scattered around this proposal, let’s list the most important ones:

• Jupyter Notebooks are an open-source web application that allows you to create and share documents that contain live computer code, equations, visualizations and narrative text.
• JupyterLab is the web development environment where the notebooks can be run and edited.
• JupyterHub is the server which spawns JupyterLab in the containerized environment. It also handles user authentification and many other things.
• MyBinder is a versatile server which automatises the process of providing any kind of environment in a JupyterHub. MyBinder is a free to use deployment of the open-source Binder tool - but anyone can deploy a Binder server (e.g. Pangeo).
• repo2docker is used by MyBinder to specify the environments which need to be “containerized”. It relies on environment files (pip, conda, apt, etc.) and is run as a command line tool.
• docker is the technology we use to create the environments where OGGM can run. Think of it as “software capsules” that you can download an run.
• kubernetes is the tool which does the job of scaling in the background. it needs to be installed on the cluster where JupyterHub is hosted, and somehow it works: when JupyterHub users come in, the cluster grows. Kubernetes is designed for cloud, I wonder if it’s useful on HPC or not.
• Helm is the tool which makes it easier to install things on the kubernetes cluster. It’s not too relevant here.
• Dask is an ecosystem of tools providing parallism tools to python. It is very cool, and sometimes a bit too fancy even.
• Pangeo is a a community of people who build scripts and tools that make is possible to work with all the tools above and do real computations (i.e. with big data and many processors).

Motivation

There is a general trend towards cloud computing in science, and we won’t repeat everything here. Let’s discuss the main use cases here, from the perspective of OGGM:

Big Data

This is the main motivation behind proprietary platforms like Google Earth Engine or the Copernicus Data Store. Huge amounts of data are available on some storage (cloud or HPC), and data providers want the users to work on these data locally (via their browser) rather than download them all. This is also the leitmotiv of the open source project Pangeo. OGGM is not really a “big data problem”. We do however rely on and provide large amount of data, and we could imagine a cloud-workflow where all these data exist on cloud or HPC and are available via JupyterHub.

Reproducible Science

Making results reproducible is not only sharing code, it also means sharing the computing environment that was used to generate these results. This can be achieved via containerization (we already do that), but containers are still new and scary for non specialists (see “User friendlyness” below). There is a growing demand from publishers and society for reproducible computing workflows, and start-ups are flourishing on this new market (e.g. code ocean). In OGGM we would like to use open-source tools, of course.

User friendliness and innovation

This is my main argument for web-based development workflows. Traditional HPC environments require to learn certain skills which aren’t in the portfolio of many researchers: the linux command line, old-fashioned text editors, job schedulers, environment variables… This slows-down interactive, trial-and-error development processes and therefore innovation. Scientists are used to the notebooks and interactive python environments, where most of the development process takes place. If we had a way to combine the friendliness of JupyterLab with the power of HPC/Cloud, it would be a real win for both users and developers.

Environment control

This is closely related with “Reproducible Science”, but from a model developer and HPC provider perspective: with JupyterHub and containers, we have full control on the environment that users are using. This makes debugging and trouble shooting much easier, since we can exclude the usual “flawed set-up” from the user side.

Collaborative Workflows

The self-documenting notebooks are easy to share across users, encouraging team work. Another (rather vague at this point) goal would be to allow “multiple users” environments where people can develop scripts and notebooks collaboratively, but this is not top priority right now.

Status (03 Jul 2019)

• We have two sorts of docker images for OGGM: (1) OGGM-Docker, which is a standard docker image generated from scratch using pip install. These images are ligweight and well tested, we use them on HPC with Singularity. (2) repo2docker images, which we generate for MyBinder and JupyterHub (both need a certain user set-up which is best generated from repo2docker). They are not lightweight at all (because of conda).
• We have a 15k$ grant from Google (about 13k€) for cloud resources, to be used until June 2020. We plan to use this one year period as test phase to see if this endeavor is worth pursuing.
• We use MyBinder for OGGM-Edu’s educational material and tutorials. It works very well. The only drawbacks are performance and the temporary nature of MyBinder environments. This is a real problem for multi-day workshops or classes.
• Thanks to the zero2jupyterhub instructions and with some trial-and-error, we now have our own JupyterHub server running on google cloud: hub.oggm.org which is a vanilla zero2jupyterhub setup with our own images created with repo2docker. The Pangeo organisation folks can log-in as well if you want to play with it.
• I’ve learned that all these things take time. Scattered around several weeks, I still estimate to at least 10 full days of work invested from my side (lower estimate). I learned a lot but I need some help if we want to have this go further.

We have a proof of concept, which allows new users to try the OGGM model without installation burden.

It is not enough to do heavy work. For more advanced use cases we need dask, pangeo, and we need to put our data on cloud as well, or we need to set-up Jupyterhub on HPC (see roadmap).

Big-picture roadmap

Assuming that we want to achieve this goal (a running instance of OGGM in a JupyterHub server for research applications), we can follow two main strategies:

1. Continue on cloud. If we do so, we need pangeo and dask, and we need to re-engineer parts of OGGM to work with dask multiproc and with cloud buckets for the input data.
2. Continue on HPC, once we have access to the big computer in Bremen. The tools in the background would be slightly different, but for the users it would be exact same: “I log in, I request resources, I work”.

The two strategies have many similarities, and are worth discussing. Since we have no HPC yet (and received 15K from google), I’d like to follow-up on the cloud idea a little more.

Detailed roadmap

Scaling. This is relatively independant of cloud or HPC and should be done anyway.

• refactor the multiprocessing workflow of OGGM to use dask. Once OGGM can run in the dask ecosystem, we will have access to all the nice tools that come with it, such as the task scheduler, the jupyterlab extension, and (most importantly) dask.distributed for automated scaling on both HPC and cloud/kubernetes.
• build our docker images from pangeo-base instead. This will come with dask pre-installed and allow a typical pip install workflow, i.e. we can build upon our dockerfiles.
• make hub.oggm.org point to these new images

Data management and I/O. This is the hardest part and the one which will be most different whether we use cloud or HPC resources.

• Input on cloud: we need to put the input data on a read-only bucket. In a first step, we will make only pre-processed directories available. Ideally, OGGM will be able to start from and extract from bucket without downloading the data locally, i.e. the buckets look like a mounted disk and OGGM can read from them. The performance aspect is going to be interesting.
• Output on cloud: probably the biggest issue on cloud, not easy to solve. Disk space is quite expensive and users can easily generate huge amounts of data with OGGM (we are not really optimizing for data volume currently). I.e. we would have to provide tools to reduce the output data amount, force the users to store their data elsewhere, etc. All that is not really attractive currently.
• Input/output on HPC: I imagine something not so different from what we have on HPC already.

User environment. Some things which are nice to have.

• make it possible to install OGGM via pip in JupyterHub. This is already possible but only temporarily - i.e. install is lost at next login. It would be great so that people can use their own development versions to do runs.
• make a better splash screen for hub.oggm.org (see how pangeo is doing it or use the pangeo one)
• documentation: use cases, examples, etc.

OEP-0003: Surface mass-balance enhancements

Authors:Fabien Maussion Status:Draft - not implemented Created:28.08.2019

Abstract

We present a list of possible enhancements to the OGGM mass-balance model(s). Each of them can be tackled separately, but it could make sense to address some of them together, since it is quite an involved endeavor.

Motivation

OGGM’s mass-balance (MB) model is a temperature index model first developed by Marzeion et al. (2012) and adapted for OGGM (e.g. to be distributed according to elevation along the flowlines). The important aspect of our MB model is the calibration of the temperature sensitivity, which is… peculiar to say the least. See Mass-balance for an illustration of the method.

This method is powerful, but also has caveats (some are listed below). Furthermore, it has not changed since 2012, and could make much better use of newly available data: mostly, geodetic mass-balance for a much larger number of glaciers.

Proposed improvements

Varying temperature sensitivities for snow and ice

Rationale

Currently, the temperature sensitivity \(\mu^{*}\) (or “melt factor”, units mm w.e. yr-1 K-1) is the same all over the glacier. There are good reasons to assume that this melt factor should be different for different surface conditions.

One relatively simple way to deal with it would be to define a new model parameter, snow_melt_factor, which defines a temperature sensitivity for snow as \(\mu^{*}_{Snow} = f \, \mu^{*}_{Ice}\) with \(f\) constant and somewhere between 0 and 1 (1 would be the current default).

Implementation

The implementation is not as straightforward as it sounds, but should be feasible. The main culprits are:

• one will need to track snow cover and snow age with time, and transform snow to ice after some years.
• the calibration procedure will become a chicken and egg problem, since snow cover evolution will depend on \(\mu^{*}\), which will itself depend on snow cover evolution. Possibly, this will need to a relatively costly iterative procedure.

Calibration / Validation

This will introduce a new parameter, which should be constrained. Ideally, it would be fit to observations of MB profiles from the WGMS.

Find a sensible algorithm to avoid the interpolation of t*

TODO

Make use of available geodetic MB data

TODO

Use Bayes

TODO

Contributing to OGGM

All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome! OGGM is still in an early development phase, so most things are not written in stone and can probably be enhanced/corrected/ameliorated by anyone!

You can report issues or discuss OGGM on the issue tracker.

Copyright note: this page is a shorter version of the excellent pandas documentation.

Working with the code

Before you contribute, you will need to learn how to work with GitHub and the OGGM code base.

Version control, Git, and GitHub

The code is hosted on GitHub. To contribute you will need to sign up for a free GitHub account. We use Git for version control to allow many people to work together on the project.

Some great resources for learning Git:

• the GitHub help pages.
• the NumPy’s documentation.
• Matthew Brett’s Pydagogue.

Getting started with Git

GitHub has instructions for installing git, setting up your SSH key, and configuring git. All these steps need to be completed before you can work seamlessly between your local repository and GitHub.

Forking

You will need your own fork to work on the code. Go to the OGGM project page and hit the Fork button. You will want to clone your fork to your machine:

git clone git@github.com:your-GitHub-username/oggm.git oggm-yourname
cd oggm-yourname
git remote add upstream git://github.com/OGGM/oggm.git

This creates the directory oggm-yourname and connects your repository to the upstream (main project) oggm repository (with the your-GitHub-username the user name of your GitHub account).

Creating a branch

You want your master branch to reflect only production-ready code, so create a feature branch for making your changes. For example:

git branch shiny-new-feature
git checkout shiny-new-feature

The above can be simplified to:

git checkout -b shiny-new-feature

This changes your working directory to the shiny-new-feature branch. Try to keep any changes in this branch specific to one bug or feature. You can have many shiny-new-features and switch in between them using the git checkout command.

To update this branch, you need to retrieve the changes from the master branch:

git fetch upstream
git rebase upstream/master

This will replay your commits on top of the latest oggm git master. If this leads to merge conflicts, you must resolve these before submitting your pull request. If you have uncommitted changes, you will need to stash them prior to updating. This will effectively store your changes and they can be reapplied after updating.

Creating a development environment

An easy way to create an OGGM development environment is explained in Installing OGGM.

Contributing to the code base

Code standards

OGGM uses the PEP8 standard. There are several tools to ensure you abide by this standard, and some Integrated Development Environment (IDE, for example PyCharm) will warn you if you don’t follow PEP8.

Test-driven development/code writing

OGGM is serious about testing and strongly encourages contributors to embrace test-driven development (TDD). Like many packages, OGGM uses the pytest testing system and the convenient extensions in numpy.testing.

All tests should go into the tests subdirectory of OGGM. This folder contains many current examples of tests, and we suggest looking to these for inspiration.

Running the test suite

The tests can then be run directly inside your Git clone by typing:

pytest .

Running the tests will take several minutes. If everything worked fine, you should see something like:

==== test session starts ====
platform linux -- Python 3.4.3, pytest-3.0.5, py-1.4.31, pluggy-0.4.0
rootdir:
plugins:
collected 92 items

oggm/tests/test_graphics.py ..............
oggm/tests/test_models.py .........s....sssssssssssssssss
oggm/tests/test_prepro.py ...s................s.s...
oggm/tests/test_utils.py ...sss..ss.sssss.
oggm/tests/test_workflow.py ssss

===== 57 passed, 35 skipped in 102.50 seconds ====

You can safely ignore deprecation warnings and other Dynamic Link Library (DLL) messages as long as the tests end with OK.

Often it is worth running only a subset of tests first around your changes before running the entire suite. This is done using one of the following constructs:

pytest oggm/tests/[test-module].py
pytest oggm/tests/[test-module].py:[TestClass]
pytest oggm/tests/[test-module].py:[TestClass].[test_method]

Contributing to the documentation

Contributing to the documentation is of huge value. Something as simple as rewriting small passages for clarity is a simple but effective way to contribute.

About the documentation

The documentation is written in reStructuredText, which is almost like writing in plain English, and built using Sphinx. The Sphinx documentation has an excellent introduction to reST. Review the Sphinx docs to perform more complex changes to the documentation as well.

Some other important things to know about the docs:

• The OGGM documentation consists of two parts: the docstrings in the code itself and the docs in this folder oggm/docs/.

  The docstrings should provide a clear explanation of the usage of individual functions (currently this is not the case everywhere, unfortunately), while the oggm/docs/ folder consists of tutorial-like overviews per topic together with some other information (what’s new, installation, etc).

• The docstrings follow the Numpy Docstring Standard, which is used widely in the Scientific Python community. This standard specifies the format of the different sections of the docstring. See this document for a detailed explanation, or look at some of the existing functions to extend it in a similar manner.

• Some pages make use of the ipython directive sphinx extension. This directive lets you put code in the documentation which will be run during the doc build.

How to build the documentation

Requirements

There are some extra requirements to build the docs: you will need to have sphinx, sphinx_rtd_theme, numpydoc and ipython installed.

If you have a conda environment named oggm_env, you can install the extra requirements with:

conda install -n oggm_env sphinx sphinx_rtd_theme ipython numpydoc

If you use pip, activate your python environment and install the requirements with:

pip install sphinx sphinx_rtd_theme ipython numpydoc

Building the documentation

So how do you build the docs? Navigate to your local oggm/docs/ directory in the console and run:

make html

Then you can find the HTML output in the folder oggm/docs/_build/html/.

The first time you build the docs, it will take quite a while because it has to run all the code examples and build all the generated docstring pages. In subsequent evocations, sphinx will try to only build the pages that have been modified.

If you want to do a full clean build, do:

make clean
make html

Open the following file in a web browser to see the full documentation you just built:

oggm/docs/_build/html/index.html

If you performed some changes in the documentation or even created new pages/sections (the .rst files), you’ll have the satisfaction of seeing your new and improved documentation!

Contributing your changes

Committing your code

Keep style fixes to a separate commit to make your pull request more readable.

Once you’ve made changes, you can see them by typing:

git status

If you have created a new file, it is not being tracked by git. Add it by typing:

git add path/to/file-to-be-added.py

Doing ‘git status’ again should give something like:

# On branch shiny-new-feature
#
#       modified:   /relative/path/to/file-you-added.py
#

Finally, commit your changes to your local repository with an explanatory message:

git commit -a -m 'added shiny feature'

You can make as many commits as you want before submitting your changes to OGGM, but it is a good idea to keep your commits organised.

Pushing your changes

When you want your changes to appear publicly on your GitHub page, push your forked feature branch’s commits:

git push origin shiny-new-feature

Here origin is the default name given to your remote repository on GitHub. You can see the remote repositories:

git remote -v

If you added the upstream repository as described above you will see something like:

origin  git@github.com:yourname/oggm.git (fetch)
origin  git@github.com:yourname/oggm.git (push)
upstream        git://github.com/OGGM/oggm.git (fetch)
upstream        git://github.com/OGGM/oggm.git (push)

Now your code is on GitHub, but it is not yet a part of the OGGM project. For that to happen, a pull request needs to be submitted on GitHub.

Review your code

When you’re ready to ask for a code review, file a pull request. Before you do, once again make sure that you have followed all the guidelines outlined in this document regarding code style, tests, and documentation. You should also double check your branch changes against the branch it was based on:

1. Navigate to your repository on GitHub – https://github.com/your-GitHub-user-name/oggm
2. Click on Branches
3. Click on the Compare button for your feature branch
4. Select the base and compare branches, if necessary. This will be master and shiny-new-feature, respectively.

Finally, make the pull request

If everything looks good, you are ready to make a pull request. A pull request is how code from a local repository becomes available to the GitHub community and can be looked at and eventually merged into the master version. This pull request and its associated changes will eventually be committed to the master branch and available in the next release. To submit a pull request:

1. Navigate to your repository on GitHub
2. Click on the Pull Request button
3. You can then click on Commits and Files Changed to make sure everything looks okay one last time
4. Write a description of your changes in the Preview Discussion tab
5. Click Send Pull Request.

This request then goes to the repository maintainers, and they will review the code. If you need to make more changes, you can make them in your branch, push them to GitHub, and the pull request will be automatically updated. Pushing them to GitHub again is done by:

git push -f origin shiny-new-feature

This will automatically update your pull request with the latest code.

Delete your merged branch (optional)

Once your feature branch is accepted into upstream, you’ll probably want to get rid of the branch. First, merge upstream master into your branch so git knows it is safe to delete your branch:

git fetch upstream
git checkout master
git merge upstream/master

Then you can just do:

git branch -d shiny-new-feature

Make sure you use a lower-case -d, or else git won’t warn you if your feature branch has not actually been merged.

The branch will still exist on GitHub, so to delete it there do:

git push origin --delete shiny-new-feature

Get in touch

• View the source code on GitHub.
• Report bugs or share your ideas on the issue tracker, and improve the model by submitting a pull request.
• Chat with us on Slack! (just send us an e-mail so we can add you)
• Follow us on Twitter.
• Participate to our regular meeting. (reach out if you want to join in)
• Or you can always send us an e-mail the good old way.

License and citation

OGGM is available under the open source 3-Clause BSD License.

OGGM is a free software. This implies that you are free to use the model and copy, modify or redistribute its code at your wish, under certain conditions:

1. When using this software, please acknowledge the original authors of this contribution by using our logo, referring to our website or using an appropriate citation. See Citing OGGM for how to do that.
2. Redistributions of any substantial portion of the OGGM source code must meet the conditions listed in the OGGM license
3. Neither OGGM e.V. nor the names of OGGM contributors may be used to endorse or promote products derived from this software without specific prior written permission. This does not mean that you need our written permission to work with OGGM or publish results based on OGGM: it simply means that the OGGM developers are not accountable for what you do with the tool (more info).

See the OGGM license for more information.

About

Version: Citation: Tests: License: Authors:

See the version history for a list of all contributors.