.. currentmodule:: oggm

Getting started
===============

.. ipython:: python
   :suppress:

    import os
    import numpy as np
    np.set_printoptions(threshold=10)

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 :doc:`cloud` for more information.

.. _system-settings:

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:

.. ipython:: python

    from oggm import cfg
    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:

.. ipython:: python

    cfg.CONFIG_FILE

.. 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`_).

.. _oggm sample data: https://github.com/OGGM/oggm-sample-data
.. _reference mass balance data: https://github.com/OGGM/oggm-sample-data/tree/master/wgms
.. _links to the respective RGI polygons: http://fabienmaussion.info/2017/02/19/wgms-rgi-links/

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).

.. _oggm-config:

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.

.. _Least Recently Used (LRU): https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)


OGGM workflow
-------------

For a step by step tutorial of the entire OGGM workflow, download
the
:download:`getting started <https://raw.githubusercontent.com/OGGM/tutorials/master/notebooks/getting_started.ipynb>`
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.

.. _tutorials: https://oggm.org/tutorials