Release v1.1.3

docs/api.rst

@@ -21,6 +21,7 @@ Tools to set-up and run OGGM.
     :nosignatures:
 
     cfg.initialize
+    cfg.initialize_minimal
     cfg.set_logging_config
     cfg.set_intersects_db
     cfg.reset_working_dir
@@ -67,6 +68,7 @@ Input/Output
     utils.get_cru_file
     utils.get_histalp_file
     utils.get_ref_mb_glaciers
+    utils.write_centerlines_to_shape
 
 
 .. _apientitytasks:

docs/conf.py

@@ -402,9 +402,6 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3.6/', None),
-    'pandas': ('http://pandas.pydata.org/pandas-docs/stable/', None),
-    'numpy': ('http://docs.scipy.org/doc/numpy/', None),
 }
 
 

docs/faq.rst

@@ -1,5 +1,7 @@
 .. _faq:
 
+.. currentmodule:: oggm
+
 ***********************
 FAQ and Troubleshooting
 ***********************
@@ -36,20 +38,58 @@ dynamics. For these kind of workflows, we created the
 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 centenial time scales, 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 until today.
+It depends what you mean by "long-term": at centenial 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!
+
+
+Usage
+=====
+
+Can I export OGGM centerlines to a shapefile?
+---------------------------------------------
+
+Yes! There is a function to do exactly that:
+:py:func:`utils.write_centerlines_to_shape`.
+
 Troubleshooting
 ===============
 

docs/ice-dynamics.rst

@@ -169,6 +169,9 @@ 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 :ref:`pitfalls.numerics` for an ongoing discussion about the limitations
+of OGGM's numerical scheme!
+
 
 MUSCLSuperBeeModel
 ~~~~~~~~~~~~~~~~~~

docs/index.rst

@@ -54,6 +54,7 @@ How to use the model, with concrete python code examples.
 * :doc:`practicalities`
 * :doc:`api`
 * :doc:`faq`
+* :doc:`pitfalls`
 * :doc:`whats-new`
 
 .. toctree::
@@ -69,6 +70,7 @@ How to use the model, with concrete python code examples.
     api.rst
     practicalities.rst
     faq.rst
+    pitfalls.rst
     whats-new.rst
 
 Contributing
@@ -97,8 +99,9 @@ Get in touch
 ------------
 
 - View the source code `on GitHub`_.
-- Report bugs or share your ideas on the `issue tracker`_.
-- Improve the model by submitting a `pull request`_.
+- Report bugs or share your ideas on the `issue tracker`_, and improve
+  the model by submitting a `pull request`_.
+
 - Follow us on `Twitter`_.
 - Or you can always send us an `e-mail`_ the good old way.
 

docs/oeps/oep--0003-smb.rst

@@ -1,3 +1,5 @@
+.. _oep0003:
+
 ===========================================
 OEP-0003: Surface mass-balance enhancements
 ===========================================

docs/pitfalls.rst

@@ -0,0 +1,115 @@
+.. _pitfalls:
+
+.. currentmodule:: oggm
+
+************************
+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.
+Hefer to our :ref:`faq` for a general introduction. Here, we discuss
+specific pitfalls in more details.
+
+The default ice dynamics parameter "Glen A" is not calibrated
+=============================================================
+
+Out-of-the box OGGM will uses fixed values for the creep parameter
+:math:`A` and the sliding parameter :math:`f_s`:
+
+.. ipython:: python
+
+   from oggm import cfg
+   cfg.initialize()
+   cfg.PARAMS['glen_a']
+   cfg.PARAMS['fs']
+
+That is, :math:`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 :math:`A` to a
+larger value to compensate for this missing process.
+
+There is a way to calibrate :math:`A` for the ice thickness inversion
+procedure based on observations of ice thickness. This does not mean that this
+:math:`A` can be applied unchanged to the forward model, unfortunately.
+At the global scale, a value in the range of [1.1-1.5] times the default value
+gives estimates close to [Farinotti_etal_2019]_. At regional scale, these
+values can differ, with a value closer to a factor 3 e.g. for the Alps. Note
+that this depends on other variables as well, such as precipitation estimates
+(which affect the mass turnover).
+
+Finally, note that a change in :math:`A` has a very strong influence
+for values close to the default value, but this influences reduces to the
+power of 1/5 for large values of A (in other worlds, there is a big
+difference between values of 1 to 1.3 times the default :math:`A`, but a
+comparatively small difference for values between 3 to 5 times the
+default :math:`A`). This is best shown by this figure from
+[Maussion_etal_2019]_:
+
+.. figure:: _static/global_volume_mau2019.png
+    :width: 100%
+
+    Global volume estimates 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, :math:`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
+
+**How to choose the "best A" for my application?**
+Sorry, but we don't know yet. We are working on it though!
+
+.. _pitfalls.numerics:
+
+The numerical model in OGGM is numerically unstable in some conditions
+======================================================================
+
+See `this github issue <https://github.com/OGGM/oggm/issues/909>`_ for an
+ongoing discussion. We will post and update here soon!
+
+
+The mass-balance model of OGGM is not calibrated with remote sensing data
+=========================================================================
+
+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 our
+`performance monitoring website <https://cluster.klima.uni-bremen.de/~github/crossval/>`_.
+
+This, however, is not really "state of the art" anymore. Other recent
+studies by e.g. [Huss_Hock_2015]_ and [Zekollari_etal_2019]_
+also use geodetic mass-balance estimates
+to calibrate their model.
+
+We are looking for people to help us with this task: join us! See
+e.g. :ref:`oep0003` for a discussion document.
+
+
+References
+==========
+
+.. [Farinotti_etal_2019] 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] 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.
+
+.. [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.
+
+.. [Zekollari_etal_2019] Zekollari, H., Huss, M. and Farinotti, D.: Modelling
+    the future evolution of glaciers in the European Alps under the EURO-CORDEX
+    RCM ensemble, Cryosphere, 13(4), 1125–1146, doi:10.5194/tc-13-1125-2019, 2019.

docs/whats-new.rst

@@ -4,11 +4,14 @@
 Version history
 ===============
 
-v1.2 (unreleased)
------------------
+v1.1.3 (03.01.2020)
+-------------------
 
-Breaking changes
-~~~~~~~~~~~~~~~~
+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 MIT license.
 
 Enhancements
 ~~~~~~~~~~~~
@@ -28,6 +31,12 @@ Enhancements
   the GlacierDirectory level ``get_task_time``) to time the execution of
   entity tasks (:issue:`918`).
   By `Fabien Maussion <https://github.com/fmaussion>`_.
+- Improved performance of numerical core thanks to changes in our calls to
+  `np.clip` (:pull:`873` and :pull:`903`).
+  By `Fabien Maussion <https://github.com/fmaussion>`_.
+- Added a function `cfg.initialize_minimal` to run the flowline model
+  without enforcing a full download of the demo files (:pull:`921`).
+  By `Fabien Maussion <https://github.com/fmaussion>`_.
 
 Bug fixes
 ~~~~~~~~~
@@ -41,7 +50,7 @@ Bug fixes
 v1.1.2 (12.09.2019)
 -------------------
 
-Minor release of the OGGM model, with several substancial improvements, most
+Minor release of the OGGM model, with several substantial improvements, most
 notably:
 
 - update in the inversion procedure for calving glaciers (Recinos et al., 2019)