initial commit

.gitignore

@@ -0,0 +1,19 @@
+# file extensions
+**/*.pyc
+**/*.h5
+**/*.p
+!test/test_data/*.p
+*.swp
+.coverage
+
+# folder
+build/*
+dist/*
+neuralhydrology.egg-info/*
+.vscode/*
+.idea/*
+runs/*
+configs/*
+.ipynb_checkpoints/*
+data/*
+docs/build/*

.style.yapf

@@ -0,0 +1,3 @@
+[style]
+column_limit = 120
+based_on_style = google

CODEOWNERS

@@ -0,0 +1 @@
+* @kratzert

README.md

@@ -0,0 +1,118 @@
+![#](docs/source/_static/img/neural-hyd-logo-black.png)
+
+Python library to train neural networks with a strong focus on hydrological applications.
+
+This package has been used extensively in research over the last year and was used in various academic publications. 
+The core idea of this package is modularity in all places to allow easy integration of new datasets, new model 
+architectures or any training related aspects (e.g. loss functions, optimizer, regularization). 
+One of the core concepts of this code base are configuration files, which lets anyone train neural networks without
+touching the code itself. The `NeuralHydrology` package is build on top of the deep learning framework 
+[Pytorch](https://pytorch.org/), since it has proven to be the most flexible and useful for research purposes.
+
+We (AI for Earth Science group at Institute for Machine Learning, Johannes Kepler University, Linz, Austria) are using
+this code in our day-to-day research and will continue to integrate our new research findings into this public repository.
+
+**Note:** We will gradually add more examples/documentation over the next couple of days/weeks.
+
+- Documentation: [neuralhydrology.readthedocs.io](neuralhydrology.readthedocs.io)
+- Research Blog: [neuralhydrology.github.io](neuralhydrology.github.io)
+- Bug reports/Feature requests [https://github.com/neuralhydrology/neuralhydrology/issues](https://github.com/neuralhydrology/neuralhydrology/issues)
+
+# Getting started
+
+## Requirements
+
+We recommend to use Anaconda/Miniconda. With one of the two installed, a dedicated environment with all requirements 
+installed can be set up from the environment files provided in 
+[environments](https://github.com/neuralhydrology/neuralhydrology/environments). 
+
+If you have no CUDA capable GPU available run
+
+```bash
+conda env create -f environments/environment_cpu.yml
+```
+
+With a CUDA capable GPU available, check which CUDA version your GPU supports and then run e.g. (for CUDA 10.2)
+
+```bash
+conda env create -f environments/environment_cuda10_2.yml
+```
+
+If neither Minicoda/Anaconda are available, make sure to Python environment with all packages installed that are listed 
+in one of the environment files.
+
+## Installation
+
+For now download or clone the repository to your local machine and install a local, editable copy. 
+This is a good idea if you want to edit the ``neuralhydrology`` code (e.g., adding new models or datasets).::
+
+```bash
+    git clone https://github.com/neuralhydrology/neuralhydrology.git
+    cd neuralhydrology
+    pip install -e .
+```
+Besides adding the package to your Python environment, it will also add three bash scripts: 
+`nh-run`, `nh-run-scheduler` and `nh-results-ensemble`. For details, see below.
+
+
+## Data
+
+Training and evaluating models requires a dataset.
+If you're unsure where to start, a common dataset is CAMELS US, available at
+[CAMELS US (NCAR)](https://ral.ucar.edu/solutions/products/camels).
+Download the "CAMELS time series meteorology, observed flow, meta data" and place the actual data folder
+(`basin_dataset_public_v1p2`) in a directory.
+This directory will be referred to as the "data directory", or `data_dir`.
+
+## Configuration file
+
+One of the core concepts of this package is the usage of configuration files (`.yml`). Basically, all configurations 
+required to train a neural network can be specified via these configuration files and no code has to be touched.
+Training a model does require a `.yml` file that specifies the run configuration. We will add a detailed explanation
+for within the next weeks that explains the config files and arguments in more detail. For now refer to the 
+[example config](https://github.com/neuralhydrology/neuralhydrology/blob/master/examples/config.yml.example) for a full
+list of all available arguments (with inline documentation). For an example of a configuration file that can be used to 
+train a standard LSTM for a single CAMELS US basin, check 
+[1_basin_config.yml](https://github.com/neuralhydrology/neuralhydrology/blob/master/examples/1_basin_config.yml.example).
+
+## Train a model
+
+To train a model, prepare a configuration file, then run::
+
+```bash
+    nh-run train --config-file /path/to/config.yml
+```
+If you want to train multiple models, you can make use of the ``nh-run-scheduler`` command.
+Place all configs in a folder, then run::
+```bash
+    nh-run-scheduler train --config-dir /path/to/config_dir/ --runs-per-gpu X --gpu-ids Y
+```
+With X, you can specify how many models should be trained on parallel on a single GPU.
+With Y, you can specify which GPUs to use for training (use the id as specified in ``nvidia-smi``).
+
+## Evaluate a model
+
+To evaluate a trained model on the test set, run::
+
+    nh-run evaluate --run-dir /path/to/run_dir/
+
+If the optional argument ``--epoch N`` (where N is the epoch to evaluate) is not specified,
+the weights of the last epoch are used. You can also use ``--period `` if you want to evaluate the model on the 
+train period ``--period train``) or validation period (``--period validation``) 
+
+To evaluate all runs in a specific directory you can, similarly to training, run::
+
+    nh-run-scheduler evaluate --run-dir /path/to/config_dir/ --runs-per-gpu X --gpu-ids Y
+
+
+To merge the predictons of a number of runs (stored in ``$DIR1``, ...) into one averaged ensemble,
+use the ``nh-results-ensemble`` script::
+
+    nh-results-ensemble --run-dirs $DIR1 $DIR2 ... --save-file /path/to/target/file.p --metrics NSE MSE ...
+
+``--metrics`` specifies which metrics will be calculated for the averaged predictions.
+
+# Contact
+
+If you have any questions regarding the usage of this repository, feature requests or comments, please open an issue.
+You can also reach out to Frederik Kratzert (kratzert(at)ml.jku.at) by email.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/api/neuralhydrology.data.basedataset.rst

@@ -0,0 +1,7 @@
+BaseDataset
+===========
+
+.. automodule:: neuralhydrology.data.basedataset
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.data.camelsgb.rst

@@ -0,0 +1,7 @@
+CamelsGB
+========
+
+.. automodule:: neuralhydrology.data.camelsgb
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.data.camelsus.rst

@@ -0,0 +1,7 @@
+CamelsUS
+========
+
+.. automodule:: neuralhydrology.data.camelsus
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.data.caravan.rst

@@ -0,0 +1,7 @@
+Caravan
+=======
+
+.. automodule:: neuralhydrology.data.caravan
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.data.climateindices.rst

@@ -0,0 +1,7 @@
+climateindices
+==============
+
+.. automodule:: neuralhydrology.data.climateindices
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.data.dischargeinput.rst

@@ -0,0 +1,7 @@
+dischargeinput
+==============
+
+.. automodule:: neuralhydrology.data.dischargeinput
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.data.hourlycamelsus.rst

@@ -0,0 +1,7 @@
+HourlyCamelsUS
+==============
+
+.. automodule:: neuralhydrology.data.hourlycamelsus
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.data.pet.rst

@@ -0,0 +1,7 @@
+pet
+===
+
+.. automodule:: neuralhydrology.data.pet
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.data.rst

@@ -0,0 +1,20 @@
+nh.data
+=======
+
+.. automodule:: neuralhydrology.data
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. toctree::
+   :maxdepth: 4
+
+   neuralhydrology.data.basedataset
+   neuralhydrology.data.camelsus
+   neuralhydrology.data.hourlycamelsus
+   neuralhydrology.data.camelsgb
+   neuralhydrology.data.caravan
+   neuralhydrology.data.climateindices
+   neuralhydrology.data.dischargeinput
+   neuralhydrology.data.pet
+   neuralhydrology.data.utils

docs/source/api/neuralhydrology.data.utils.rst

@@ -0,0 +1,7 @@
+utils
+=====
+
+.. automodule:: neuralhydrology.data.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.evaluation.evaluate.rst

@@ -0,0 +1,7 @@
+evaluate
+========
+
+.. automodule:: neuralhydrology.evaluation.evaluate
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.evaluation.metrics.rst

@@ -0,0 +1,7 @@
+metrics
+=======
+
+.. automodule:: neuralhydrology.evaluation.metrics
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.evaluation.plots.rst

@@ -0,0 +1,7 @@
+plots
+=====
+
+.. automodule:: neuralhydrology.evaluation.plots
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.evaluation.rst

@@ -0,0 +1,16 @@
+nh.evaluation
+=============
+
+.. automodule:: neuralhydrology.evaluation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. toctree::
+   :maxdepth: 4
+
+   neuralhydrology.evaluation.evaluate
+   neuralhydrology.evaluation.metrics
+   neuralhydrology.evaluation.plots
+   neuralhydrology.evaluation.signatures
+   neuralhydrology.evaluation.tester

docs/source/api/neuralhydrology.evaluation.signatures.rst

@@ -0,0 +1,7 @@
+signatures
+==========
+
+.. automodule:: neuralhydrology.evaluation.signatures
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.evaluation.tester.rst

@@ -0,0 +1,7 @@
+Tester
+======
+
+.. automodule:: neuralhydrology.evaluation.tester
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.modelzoo.basemodel.rst

@@ -0,0 +1,7 @@
+BaseModel
+=========
+
+.. automodule:: neuralhydrology.modelzoo.basemodel
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.modelzoo.cudalstm.rst

@@ -0,0 +1,7 @@
+CudaLSTM
+========
+
+.. automodule:: neuralhydrology.modelzoo.cudalstm
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.modelzoo.ealstm.rst

@@ -0,0 +1,7 @@
+EALSTM
+======
+
+.. automodule:: neuralhydrology.modelzoo.ealstm
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.modelzoo.embcudalstm.rst

@@ -0,0 +1,7 @@
+EmbCudaLSTM
+===========
+
+.. automodule:: neuralhydrology.modelzoo.embcudalstm
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/neuralhydrology.modelzoo.fc.rst

@@ -0,0 +1,7 @@
+FC
+==
+
+.. automodule:: neuralhydrology.modelzoo.fc
+   :members:
+   :undoc-members:
+   :show-inheritance: