New attempts at docs (#1198)

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2020, OGGM e.V. and OGGM Contributors
+Copyright (c) 2014-2021, OGGM e.V. and OGGM Contributors
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.rst

@@ -5,12 +5,14 @@
 
 **OGGM is a modular open source model for glacier dynamics**
 
-The model accounts for glacier geometry (including contributory branches) and
-includes an explicit ice dynamics module. It can simulate past and
-future mass-balance, volume and geometry of (almost) any glacier in the world
-in a fully automated and extensible workflow. We rely exclusively on publicly
-available data for calibration and validation.
+OGGM is 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!
 
 .. image:: docs/_static/ex_tasman.jpg
 

docs/api.rst

@@ -29,6 +29,7 @@ Tools to set-up and run OGGM.
     workflow.init_glacier_directories
     workflow.execute_entity_task
     workflow.gis_prepro_tasks
+    workflow.download_ref_tstars
     workflow.climate_tasks
     workflow.inversion_tasks
     workflow.merge_glacier_tasks
@@ -193,6 +194,21 @@ but might use multiprocessing internally.
     global_tasks.compile_climate_statistics
 
 
+Command line interface (CLI)
+============================
+
+These commands are available:
+
+- ``oggm_netrc_credentials``
+- ``oggm_prepro``
+- ``oggm_benchmark``
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    cli.prepro_levels.run_prepro_levels
+
 Classes
 =======
 

docs/cloud.rst

@@ -9,14 +9,14 @@ to test the model, before you move on to more serious computations.
 
 .. image:: https://gke.mybinder.org/static/logo.svg
     :width: 25%
-    :target: https://mybinder.org/v2/gh/OGGM/binder/master?urlpath=git-pull?repo=https://github.com/OGGM/tutorials%26amp%3Bbranch=master%26amp%3Burlpath=lab/tree/tutorials/notebooks/welcome.ipynb%3Fautodecode
+    :target: https://mybinder.org/v2/gh/OGGM/binder/stable?urlpath=git-pull?repo=https://github.com/OGGM/tutorials%26amp%3Bbranch=master%26amp%3Burlpath=lab/tree/tutorials/notebooks/welcome.ipynb%3Fautodecode
 
 Our `Binder <https://mybinder.org/>`_ 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!
 
 .. image:: https://img.shields.io/badge/Launch-OGGM%20tutorials-579ACA.svg?style=popout&logo=data:image/png;base64,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
-  :target: https://mybinder.org/v2/gh/OGGM/binder/master?urlpath=git-pull?repo=https://github.com/OGGM/tutorials%26amp%3Bbranch=master%26amp%3Burlpath=lab/tree/tutorials/notebooks/welcome.ipynb%3Fautodecode
+  :target: https://mybinder.org/v2/gh/OGGM/binder/stable?urlpath=git-pull?repo=https://github.com/OGGM/tutorials%26amp%3Bbranch=master%26amp%3Burlpath=lab/tree/tutorials/notebooks/welcome.ipynb%3Fautodecode
 
 If you are new to the Jupyter Notebooks or to JupyterLab, you will probably
 find this `introduction to interactive notebooks`_ quite useful.

docs/input-data.rst

@@ -193,6 +193,10 @@ directories from the default urls. Here is a summary of the default configuratio
   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 :py:func:`cli.prepro_levels.run_prepro_levels`
+or this `file on github <https://github.com/OGGM/oggm/blob/master/oggm/cli/prepro_levels.py>`_).
+
 The urls used by OGGM per default are listed here:
 
 `https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.4/ <https://cluster.klima.uni-bremen.de/~oggm/gdirs/oggm_v1.4/>`_ + :

docs/inversion.rst

@@ -63,6 +63,7 @@ glacier at :math:`t^*`. By construction, the flux is maximal at the equilibrium
 zero at the glacier tongue.
 
 .. ipython:: python
+   :okwarning:
 
     @savefig example_plot_massflux.png width=100%
     example_plot_massflux()
@@ -107,6 +108,7 @@ step in OGGM is currently very simple, but provides nice looking maps:
 
 
 .. ipython:: python
+   :okwarning:
 
     tasks.catchment_area(gdir)
     @savefig plot_distributed_thickness.png width=80%

docs/mass-balance.rst

@@ -91,6 +91,7 @@ recommend to use data from 1850 onwards.
 
 
 .. ipython:: python
+   :okwarning:
 
     @savefig plot_temp_ts.png width=100%
     example_plot_temp_ts()  # the code for these examples is posted below
@@ -181,6 +182,7 @@ glacier geometry fixed at the RGI date** (e.g. 2003 for most glaciers in the
 European Alps).
 
 .. ipython:: python
+   :okwarning:
 
     @savefig plot_mu_ts.png width=100%
     example_plot_mu_ts()  # the code for these examples is posted below
@@ -201,6 +203,7 @@ were we have observations. We then compare the model output
 with the expected mass-balance and compute the model bias:
 
 .. ipython:: python
+   :okwarning:
 
     @savefig plot_bias_ts.png width=100%
     example_plot_bias_ts()  # the code for these examples is posted below

oggm/cli/prepro_levels.py

@@ -79,7 +79,7 @@ def run_prepro_levels(rgi_version=None, rgi_reg=None, border=None,
                       add_consensus=False, start_level=None,
                       start_base_url=None, max_level=5, ref_tstars_base_url='',
                       logging_level='WORKFLOW', disable_dl_verify=False):
-    """Does the actual job.
+    """Generate the preprocessed OGGM glacier directories for this OGGM version
 
     Parameters
     ----------

oggm/core/climate.py

@@ -907,9 +907,19 @@ def local_t_star(gdir, *, ref_df=None, tstar=None, bias=None,
     """Compute the local t* and associated glacier-wide mu*.
 
     If ``tstar`` and ``bias`` are not provided, they will be interpolated from
-    the reference t* list.
+    the reference t* list (``ref_df``).
 
-    Note: the glacier wide mu* is here just for indication. It might be
+    If none of these are provided (the default), this list be obtained from
+    the current working directory (``ref_tstars.csv`` and associated params
+    ``ref_tstars_params.json``). These files can either be generated with a
+    call to ``compute_ref_t_stars`` if you know what you are doing, ot you
+    can obtain pre-preprocessed lists from our servers:
+    https://cluster.klima.uni-bremen.de/~oggm/ref_mb_params/
+
+    The best way to fetch them is to use
+    :py:func:`oggm.workflow.download_ref_tstars`.
+
+    Note: the glacier wide mu* is output here just for indication. It might be
     different from the flowlines' mu* in some cases.
 
     Parameters
@@ -934,19 +944,20 @@ def local_t_star(gdir, *, ref_df=None, tstar=None, bias=None,
         # Do our own interpolation
         if ref_df is None:
             # Use the the local calibration
+            msg = ('If `ref_df` is not provided, please put a list of '
+                   '`ref_tstars.csv` and associated params '
+                   '`ref_tstars_params.json` in the working directory. '
+                   'Please see the documentation of local_t_star '
+                   'for more information.')
             fp = os.path.join(cfg.PATHS['working_dir'], 'ref_tstars.csv')
             if not os.path.exists(fp):
-                raise InvalidWorkflowError('If ref_df is not given, provide '
-                                           '`ref_tstars.csv` in the working '
-                                           'directory')
+                raise InvalidWorkflowError(msg)
             ref_df = pd.read_csv(fp)
 
             # Check that the params are fine
             fp = os.path.join(cfg.PATHS['working_dir'], 'ref_tstars_params.json')
             if not os.path.exists(fp):
-                raise InvalidWorkflowError('If ref_df is not given, provide '
-                                           '`ref_tstars_params.json` in the '
-                                           'working directory')
+                raise InvalidWorkflowError(msg)
             with open(fp, 'r') as fp:
                 ref_params = json.load(fp)
             for k, v in ref_params.items():

oggm/params.cfg

@@ -287,7 +287,7 @@ use_shape_factor_for_fluxbasedmodel =
 # This value could need more tuning
 downstream_min_shape = 0.0001
 # Angle defining the trapezoid bed shapes
-# https://docs.oggm.org/en/latest/ice-dynamics.html#bed-shapes
+# https://docs.oggm.org/en/stable/ice-dynamics.html#bed-shapes
 # Lambda = 1 means an angle of 63° (so quite steep)
 # Lambda = 2 means an angle of 45°
 trapezoid_lambdas = 2

oggm/workflow.py

@@ -135,25 +135,29 @@ def execute_entity_task(task, gdirs, **kwargs):
 
     # Should be iterable
     gdirs = utils.tolist(gdirs)
-
-    if len(gdirs) == 0:
+    ng = len(gdirs)
+    if ng == 0:
         log.workflow('Called entity task %s on 0 glaciers. Returning...',
                      task.__name__)
         return
 
     log.workflow('Execute entity task %s on %d glaciers',
-                 task.__name__, len(gdirs))
+                 task.__name__, ng)
 
     pc = _pickle_copier(task, kwargs)
 
     if _have_ogmpi:
         if ogmpi.OGGM_MPI_COMM is not None:
             return ogmpi.mpi_master_spin_tasks(pc, gdirs)
 
-    if cfg.PARAMS['use_multiprocessing']:
+    if cfg.PARAMS['use_multiprocessing'] and ng > 1:
         mppool = init_mp_pool(cfg.CONFIG_MODIFIED)
         out = mppool.map(pc, gdirs, chunksize=1)
     else:
+        if ng > 3:
+            log.workflow('WARNING: you are trying to run an entity task on '
+                         '%d glaciers with multiprocessing turned off. OGGM '
+                         'will run faster with multiprocessing turned on.', ng)
         out = [pc(gdir) for gdir in gdirs]
 
     return out

setup.py

@@ -18,9 +18,10 @@
         'Intended Audience :: Science/Research',
         'License :: OSI Approved :: BSD License',
         'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.5',
         'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',
+        'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
     ]
 
 DESCRIPTION = 'Open Global Glacier Model'
@@ -72,7 +73,7 @@
     # What does your project relate to?
     keywords=['geosciences', 'glaciers', 'climate', 'gis'],
     # We are a python 3 only shop
-    python_requires='>=3.5',
+    python_requires='>=3.6',
     # Find packages automatically
     packages=find_packages(exclude=['docs']),
     # Include package data