Installation

Python Environment Preparation

TopoPyScale is tested for Python 3.13. You may create a new virtual environment using conda prior to installation.

Option 1 (recommended):

conda create -n downscaling python=3.13 ipython
conda activate downscaling

# Recomended way to install dependencies:
conda install -c conda-forge xarray matplotlib scikit-learn pandas numpy netcdf4 h5netcdf rasterio pyproj dask geopandas

# install forked version of Topocalc compatible with Python >3.9 (tested with 3.13)
pip install git+https://github.com/ArcticSnow/topocalc

Latest Release Installation

pip install topopyscale

TopoPyScale has been tested on the OS: - [x] Linux Ubuntu - [x] MacOS - [ ] Windows

Installing CDO

TopoPyScale uses CDO to merge daily netcdf into yearly files. To install CDO, make sure to no install the version 2.5 which has an issue. Either pick an earlier version or >2.5. Installation and documentatino avaialble on the website of the Max Planck Institute

Setting up `cdsapi`

CDS is the Copernicus portal from which TopoPyScale will download the ERA5 data. Accessing these data is free but requires some additional setup. You need to setup your cdsapi with the Copernicus API key system. Follow this tutorial after creating an account with Copernicus. On Linux, create a file nano ~/.cdsapirc with inside:

url: https://cds.climate.copernicus.eu/api/v2
key: {uid}:{api-key}

Once the installation finished, and you are ready to launch your first TopoPyScale job, that will fetch data from CDS. Though, you will have first to accept the terms and conditions of CDS for the two datasets TopoPyScale will download data from : ERA5 Pressure levl hourly, and ERA5 Single level hourly.

Setting up Google Cloud authentification

In order to use the routine to download ERA5 data from the Google Cloud Storage, you will need to setup your system with the google-cloud-cli. Follow Google's instructions: https://cloud.google.com/sdk/docs/install

Development version Installation

Go to Development page

Step 1. Clone the repository

Clone the GitHub repo:

git clone git@github.com:ArcticSnow/TopoPyScale.git
cd TopoPyScale

Step 2. Install it in editable/development mode

This lets you modify the source code and have changes take effect immediately:

pip install -e .

The -e flag means editable — for development work.

Step 3. Verify your setup

Check that Python is using your local copy:

python -m pip show topopyscale

You should see something like:

Location: /home/user/TopoPyScale
Editable project location: /home/user/TopoPyScale

Install Pvlib with SPA C-implementation

By default, TopoPyScale uses the Python Numpy implementatino of Pvlib to compute solar position. The Pvlib library offers multiple method to compute the solar position, with one using a C-implementation. Because of licensing, the C files are not distributed within the Pvlib library. This requries a special manipulation to execute:

Clone the Pvlib repository from github: git clone git@github.com:pvlib/pvlib-python.git
uninstall the pvlib library previously installed: pip uninstall pvlib
Go download the spa.c and spa.h from https://midcdmz.nrel.gov/spa/#register
Place the files into the folder: pvlib-python/pvlib/spa_c_files/

then :

# Install cython:
pip install cython
cd pvlib-python/pvlib/spa_c_files/
python setup.py build_ext --inplace
cd ../../..
pip install .

# test if installation is working correctly:
pyhton pvlib-python/pvlib/spa_c_files/spa_py_example.py

Install FSM2oshd

TopoPyScale incorporates an export option for the snow-canopy model FSM2oshd. This function requires elements that are outside the current scope of TopoPyScale. Missing elements are all the forest structural parameters that require the model CANRAD as well as a number of additional external dataset about forest properties. Nevertheless, the installation of FSM2oshd is as follow:

git clone git@github.com:ArcticSnow/FSM2oshd.git
cd FSM2oshd
sh compile_oshd_txt.sh
mv FSM_OSHD path/to/my/project