WSL/SLF GitLab Repository

README.rst 5.29 KB
Newer Older
Aschauer's avatar
Aschauer committed
1
2
3
4
5
6
7
8
9
.. image:: https://img.shields.io/badge/Documentation-blue
    :alt: Documentation
    :target: https://aschauer.gitlab-pages.wsl.ch/swe2hs/

.. image:: https://img.shields.io/gitlab/pipeline-status/aschauer/swe2hs?branch=master&gitlab_url=https%3A%2F%2Fgitlabext.wsl.ch&label=Pipeline Status
   :alt: Gitlab pipeline status (self-hosted)
   :target: https://code.wsl.ch/aschauer/swe2hs/-/commits/master

.. image:: https://img.shields.io/pypi/v/swe2hs.svg
10
11
   :alt: PyPI-Server
   :target: https://pypi.org/project/swe2hs/
Aschauer's avatar
Aschauer committed
12
13

.. image:: https://img.shields.io/pypi/pyversions/swe2hs
14
   :alt: PyPI - Python Version
Aschauer's avatar
Aschauer committed
15

16
|
Aschauer's avatar
Aschauer committed
17

Aschauer's avatar
Aschauer committed
18
19
20
swe2hs
======

21
.. start_intro
22

23
24
25
26
SWE2HS is a conceptual snow density model for transferring daily snow water 
equivalent (SWE) of the snow cover to snow depth (HS). Some people informally 
call it JOPACK, which is an acronym for Just density Of the snowPACK.

27
The density model calculates snow depth at a daily resolution and is 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
driven by the daily snow water equivalent of the snow cover only. The 
model creates a new layer with a fixed new snow density :math:`\rho_{new}` for
every increase in SWE such that, over time, a snowpack of individual layers 
builds up. The density of a layer increases exponentially with time towards 
a time-varying maximum density. The maximum density is starting with an initial 
value at creation time of the layer and is subsequently increasing towards 
a higher value based on the overburden a layer has experienced and the 
occurrence of SWE losses in the snow pack. When SWE decreases, the model 
removes SWE from the top of the snowpack. The layer number :math:`n` can thus
undergo changes over time based on the number of SWE increases and losses in 
the snowpack. The model neglects constructive metamorphism, refreezing, and 
is not able to capture rain-on-snow (ROS) events which might lead to an 
increase in SWE but no increase in HS. 

.. TODO: add the following paragraph once the paper is published:
.. For further information on the model and how it was calibrated please refer to the 
.. model description paper:
.. CITATION HERE.
.. end_intro

|

50
.. image:: https://code.wsl.ch/aschauer/swe2hs/-/raw/master/docs/_static/colored_layers_kuhtai_2002.png
51
52
53
54
55
   :alt: Schematic snowpack evolution

|

.. start_figure_caption
56

57
The figure shows the schematic modeled snow pack evolution for the station 
58
Kühtai in the winter 2001/02. The red dotted line is the measured snow depth 
59
60
61
(HS), the black solid line bounding the colored area is the modeled snow depth, 
the thin black lines depict the layer borders within the modeled snowpack, and 
the coloring refers to the modeled layer densities. The bottom panel shows the 
62
63
daily snow water equivalent time series which was used to force the model. The
data for station Kühtai is available from Krajci et al. (2017) [#Krajci2017]_. 
Aschauer's avatar
Aschauer committed
64

65
66
67
.. end_figure_caption

.. start_installation
68

69
70
71
72
73
74
Installation
============

Please create a dedicated environment before you install the package in order 
to avoid dependency issues with other installed Python packages.
You can do this by using virtualenv::  
Aschauer's avatar
Aschauer committed
75

76
77
    virtualenv <PATH TO VENV>
    source <PATH TO VENV>/bin/activate
Aschauer's avatar
Aschauer committed
78

79
or if you use Anaconda/Miniconda::
Aschauer's avatar
Aschauer committed
80

81
82
    conda create -n swe2hs_env
    conda activate swe2hs_env
Aschauer's avatar
Aschauer committed
83

84
85
Afterwards you can install the latest version of ``swe2hs`` to the newly created 
and activated environment by running::
Aschauer's avatar
Aschauer committed
86

87
    pip install swe2hs
Aschauer's avatar
Aschauer committed
88

89
90
91
This will also install all dependencies which are necessary for the package to
work correctly.

92
Verify the installation by running the following commands in a Python console::
93
94
95
96
97
98
99
100

    >>> import swe2hs as jopack
    >>> print(jopack.__version__)

.. end_installation

Installing from source
----------------------
101
If you want to work on the package and make changes, it is recommended to clone a 
102
copy of this repositoy and install the package from source in editable mode. 
Aschauer's avatar
Aschauer committed
103
104
105
106
Clone the repository::

    $ git clone https://gitlabext.wsl.ch/aschauer/swe2hs.git

107
108
A new directory ``swe2hs`` will be created. After navigating to this directory 
with::
Aschauer's avatar
Aschauer committed
109

110
    $ cd swe2hs 
Aschauer's avatar
Aschauer committed
111

112
113
You can install the package in editable mode which allows you to import the 
package under development in the Python REPL::
Aschauer's avatar
Aschauer committed
114

Aschauer's avatar
Aschauer committed
115
    $ pip install -e .
Aschauer's avatar
Aschauer committed
116

117
118
119
120
121
Tests
=====

Testing is done with ``tox`` and ``pytest``. In order to run the tests locally 
on your machine, navigate to the root directory of the project and run::
Aschauer's avatar
Aschauer committed
122

Aschauer's avatar
Aschauer committed
123
    $ tox
Aschauer's avatar
Aschauer committed
124

125
You can also run only the tests from a single module with::
Aschauer's avatar
Aschauer committed
126

Aschauer's avatar
Aschauer committed
127
    $ tox tests/test_module.py
128
129
130
131
132
133

Documentation and Examples
==========================

API documentation as well as examples on how to use the package are 
available at <https://aschauer.gitlab-pages.wsl.ch/swe2hs/>. There 
134
you can also find instructions on how to contribute and a changelog. 
135
136

.. start_help
137

138
139
140
141
142
143
144
145
146
Help
====

If something is not working or you find an error, please get in touch via a 
`new issue`_ on the GitLab repository in case you do not find any relevant 
information in `existing issues`_.

.. _new issue: https://code.wsl.ch/aschauer/swe2hs/-/issues/new
.. _existing issues: https://code.wsl.ch/aschauer/swe2hs/-/issues
147

148
.. end_help
149
150

.. start_bib
151

152
153
154
.. [#Krajci2017] Krajci, P., Kirnbauer, R., Parajka, J., Schöber, J., & Blöschl, G. (2017). The Kühtai 
   data set: 25 years of lysimetric, snow pillow, and meteorological measurements, 
   *Water Resources Research*, 53, 5158-5165, https://doi.org/10.1002/2017WR020445.
Aschauer's avatar
Aschauer committed
155
.. end_bib
156