Metadata-Version: 2.4
Name: odinn-gungnir
Version: 0.1.0
Summary: A Python library for preprocessing of topographical and climate data for ODINN.jl using OGGM.
Author: Alban Gossard, Jordi Bolibar, Facundo Sapienza
Author-email: alban.gossard@univ-grenoble-alpes.fr, jordi.bolibar@univ-grenoble-alpes.fr, sapienza@stanford.edu
License: BSD 3-Clause License
Keywords: tools,glaciology
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tqdm
Dynamic: license-file

[![Build Status](https://github.com/ODINN-SciML/Gungnir/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/ODINN-SciML/Gungnir/actions/workflows/CI.yml?query=branch%3Amain)
[![Coverage](https://codecov.io/gh/ODINN-SciML/Gungnir/branch/main/graph/badge.svg)](https://app.codecov.io/gh/ODINN-SciML/Gungnir)

<img src="https://github.com/ODINN-SciML/Gungnir/blob/main/data/gungnir_logo.png" width="250">

Preprocessing of topographical and climate data for [ODINN.jl](https://github.com/ODINN-SciML/ODINN.jl) using [OGGM](https://github.com/OGGM/oggm).

Gungnir uses OGGM to generate all necessary files for the initial state and climate forcings to run simulations with ODINN.jl. Before running any simulations for specific glaciers with ODINN.jl, Gungnir needs to initialize those glaciers. We will progressively initialize glacier regions and store them in a server so they are readily available to all users. If you find that some glaciers or a region is missing, please contact us!

## Installation

All the notebooks inside this notebook can be executed after properly setting the environment. The `environment.yml` file can be used to
install all the required dependencies. Beside some standard Python dependencies, the `environment.yml` file include the installation of the module `gungnir` (included in this repository). The package `gungnir` includes all the code required to download the glacier data using OGGM.

In order to install the environment, you can use conda or mamba (see [Managing Environments](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) for more information) with `conda env create -f environment.yml`. Once the environment is created, you can create the associated iPython kernel with
```
python -m ipykernel install --user --name oggm_env_gungnir --display-name "IPython - Gungnir"
```
This will allow you to execute this environment directly from Jupyter notebooks.

Alternatively, we included a `Makefile` that creates the conda environment and installs the associated iPython kernel so this environment can be accessible though Jupyter notebooks all at once. In order to use the Makefile, you need to open a terminal where the repository is located and enter
```
make env
```

Alternatively, if you just want to install the `gungnir` module, you can clone this repository and do
```
pip install -e .
```
to install the package.

Note: the PyPI distribution name for this package is `odinn-gungnir` (not `gungnir`). There is another, unrelated package on PyPI named `gungnir`, so running `pip install gungnir` will install that different package instead of this one. Once published, this project should be installed with `pip install odinn-gungnir`.

## Usage

We included an example notebook of how to retrieve data using OGGM data in `notebooks/Example.ipynb`

You can also use Gungnir directly from the terminal. If you are using the remote OGGM cluster as working directory, in a new terminal after doing `conda activate oggm_env_gungnir`, proceed with
```bash
python gungnir/preprocessing.py glaciers.txt
```
If no working directory is provided, data is written to `~/.ODINN/ODINN_prepro` (the default location expected by Sleipnir).

You can still provide any explicit local/custom output directory:
```bash
python gungnir/preprocessing.py glaciers.txt --working_dir <working-dir>
```

Note: if `<working-dir>` is set to `~/.ODINN` or `~/.ODINN/per_glacier`, Gungnir automatically normalizes it to `~/.ODINN/ODINN_prepro` to avoid path mismatches with Sleipnir.

## Reproducibility

The versions of `oggm`, `massbalance-sandbox` and `pytest-mpl` are pinned in `environment.yml`. When updating them, make sure to also regenerate and validate the preprocessed data.

Each run writes a `gungnir_manifest.toml` file in the working directory. It records the options used (OGGM data URL, years, ERA5 mode and date) and the versions of the main packages, including the commit of `massbalance-sandbox`. It should be kept together with each release of the preprocessed data.

By default, the level 2 OGGM glacier directories are downloaded from the `oggm_v1.6` files of the OGGM cluster. A different location can be given with `--base_url`, and Gungnir warns if the OGGM release in the URL is not the installed one.

ERA5T is the preliminary version of ERA5 for the most recent months, which ECMWF can still update. For the monthly ERA5 files, Gungnir warns if the requested years include ERA5T months and lists them as `era5t_months` in the manifest. To generate a reproducible dataset, use `--years` to end before them.

## Climate Sources

Gungnir prepares climate files compatible with Sleipnir for two independent sources:

- **W5E5**: default OGGM daily climate file.
- **ERA5**: fully independent ERA5-Land climate file downloaded from the [CDS API](https://cds.climate.copernicus.eu/).

Both sources are always generated for each glacier, allowing selection via Sleipnir's `climate_data_source` parameter.

## ERA5 Download Modes

### Monthly (Default — Lightweight)
By default, Gungnir downloads **monthly averaged** ERA5-Land data from CDS and keeps it at monthly resolution. This is significantly more lightweight in terms of data volume.

Monthly data is:
- **Downloaded**: From `reanalysis-era5-land-monthly-means`
- **Stored**: As `climate_historical_monthly_ERA5.nc` for downstream monthly workflows (Sleipnir/MassBalanceMachine)

### Daily (Optional — High Resolution)
To enable hourly→daily aggregation, use the `use_daily` option:

```python
python gungnir/preprocessing.py glaciers.txt --working_dir <working-dir> --use_daily
```

Hourly data is downloaded from `reanalysis-era5-land` (24 timesteps/day) and resampled to daily.

## ERA5 Output

Gungnir writes one of the following, depending on mode:
- `climate_historical_monthly_ERA5.nc` (default monthly mode)
- `climate_historical_daily_ERA5.nc` (`use_daily` option)

Both files contain:
- `temp` — 2m temperature (°C)
- `prcp` — total precipitation (m)
- `gradient` — temperature lapse rate (K/m, constant −0.0065)
- `fal` — forecast albedo (0–1)
- `slhf` — surface latent heat flux (J/m²)
- `sshf` — surface sensible heat flux (J/m²)
- `ssrd` — surface solar radiation downwards (J/m²)
- `str` — surface net thermal radiation (J/m²)

Metadata includes `ref_hgt` (derived from CDS geopotential), `ref_pix_lat/lon`, and `hydro_yr_0/1`.

## CDS API Setup

ERA5 download requires a CDS API key configured in `~/.cdsapirc`. See:
https://cds.climate.copernicus.eu/how-to-api

## Code formatting

We use `black` to format the code of Gungnir.
Please refer to the [Mass Balance Machine documentation](https://massbalancemachine.readthedocs.io/en/latest/contributing.html#formatting-the-code) for instructions on how to install the code formatter locally.

MIT License

Copyright (c) 2025 ODINN

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
