.. currentmodule:: oggm

Monthly temperature index model calibrated on geodetic MB data
==============================================================

As of OGGM v1.6, the simplest and standard mass balance model available
in OGGM is a monthly temperature index model that can be calibrated on
any mass balance product (the default is `Hugonnet et al., 2021`_,
see :ref:`shop-geod`).

.. _Hugonnet et al., 2021: https://www.nature.com/articles/s41586-021-03436-z

The monthly mass balance :math:`B_i` at elevation :math:`z` is computed as:

.. math::

    B_i(z) = P_i^{Solid}(z) - d_f \, max \left( T_i(z) - T_{Melt}, 0 \right)

where :math:`P_i^{Solid}` is the monthly solid precipitation, :math:`T_i`
the monthly temperature and :math:`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. Total precipitation is obtained from
the climate dataset, multiplied by a precipitation correction factor :math:`P_f`.
The parameter :math:`d_f` indicates the temperature sensitivity of the
glacier, and it needs to be calibrated. :math:`d_f` is called ``melt_f`` (melt factor) in the OGGM code.
The model needs to compute the temperature and precipitation at the altitude :math:`z` of the glacier
grid points. The default is to use a fixed lapse rate of
-6.5K km :math:`^{-1}` and no gradient for precipitation.

Precipitation gradient
~~~~~~~~~~~~~~~~~~~~~~

Optionally, precipitation can increase with elevation (switched off by
default). The approach follows `Huss and Hock, 2015`_ (GloGEM): the gradient
is relative to the precipitation at the reference height :math:`z_{ref}` of
the climate data, with a lower bound :math:`f_{min}`:

.. math::

    P_i(z) = P_f \, P_i^{clim} \, max \left( 1 + \gamma_P (z - z_{ref}), f_{min} \right)

with :math:`\gamma_P` = ``prcp_default_gradient`` (m :math:`^{-1}`, e.g.
1.5 10 :math:`^{-4}` for 1.5% per 100 m, the GloGEM default) and
:math:`f_{min}` = ``prcp_gradient_min_fac`` (default: 0.8). For glaciers
with an elevation range larger than 1000 m, the precipitation decreases again
over the uppermost 25% of the elevation range (reduced air moisture and wind
erosion at high elevations, down to 87.5% of the value at the threshold
elevation with the default parameters, as in GloGEM). This elevation range
is the one of the reference geometry (the inversion flowlines): it does not
change during a run. See the ``prcp_*`` parameters in ``params.cfg`` for the
details.

.. _Huss and Hock, 2015: https://doi.org/10.3389/feart.2015.00054

.. _mb-calib:

Calibration
-----------

.. admonition:: **New in version 1.6!**

   A major change from previous OGGM versions, the calibration is now much
   more flexible, explicit, and adaptable. We recommend all users to
   spend some time in getting familiar with the calibration procedure in
   order to adapt it for their own purposes.

Visit the new `mass balance calibration tutorial <https://tutorials.oggm.org/master/notebooks/tutorials/massbalance_calibration.html>`_
for a complete overview.

Notes
-----

Although the 1.6 mass balance model is a clear improvement to previous OGGM versions
(mostly, for better using observations and for getting rid of the
residual parameter :math:`\epsilon`), more physical approaches are possible.

More exigent users might have a look at
`PyGEM <https://github.com/PyGEM-Community/PyGEM>`_
or the `OGGM dev branch <https://github.com/OGGM/oggm/tree/dev>`_
(which includes features from the `OGGM massbalance-sanbox <https://github.com/OGGM/massbalance-sandbox>`_)
which are offering clever ways to deal with daily data, snow cover processes, etc.

Avalanche maps have recently been added to the new OGGM glacier directories, to be able to account for the contribution
of avalanches to glacier mass balance - check out the `new OGGM tutorial <https://github.com/OGGM/tutorials/tree/master/notebooks/tutorials>`_
or directly the `OGGM avalanche repo <https://github.com/OGGM/Snowslide>`_ to get more insights on this!
