Skip to content

Commit

Permalink
Merge pull request #33 from IMMM-SFA/feature/tutorial-updates
Browse files Browse the repository at this point in the history
Feature/tutorial updates
  • Loading branch information
thurber authored Apr 7, 2021
2 parents e6769fe + 9522b74 commit a56e722
Show file tree
Hide file tree
Showing 16 changed files with 215 additions and 159 deletions.
36 changes: 36 additions & 0 deletions .github/workflows/build_linux.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
name: linux

on: [push]

jobs:
build:
runs-on: ${{ matrix.os }}

strategy:
matrix:
os: [ubuntu-latest]

env:
OS: ${{ matrix.os }}
PYTHON: '3.9'

steps:

- uses: actions/checkout@v1

- name: Set up Python
uses: actions/setup-python@master
with:
python-version: 3.9

- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
python setup.py install
- name: Test and generate coverage report
run: |
pip install pytest
pip install pytest-cov
pytest --cov=./ --cov-report=xml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: build
name: osx

on: [push]

Expand All @@ -8,7 +8,7 @@ jobs:

strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
os: [macos-latest]

env:
OS: ${{ matrix.os }}
Expand Down
43 changes: 43 additions & 0 deletions .github/workflows/build_windows.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
name: windows

on: [push]

jobs:
build:
runs-on: ${{ matrix.os }}

strategy:
matrix:
os: [windows-latest]

env:
OS: ${{ matrix.os }}
PYTHON: '3.9'

steps:

- uses: actions/checkout@v1

- name: Set up Python
uses: actions/setup-python@master
with:
python-version: 3.9

- name: Install dependencies
run: |
python -m pip install --upgrade pip
curl -O https://download.lfd.uci.edu/pythonlibs/w4tscw6k/numpy-1.20.2+mkl-cp39-cp39-win_amd64.whl
pip install numpy-1.20.2+mkl-cp39-cp39-win_amd64.whl
curl -O https://download.lfd.uci.edu/pythonlibs/w4tscw6k/GDAL-3.2.2-cp39-cp39-win_amd64.whl
pip install GDAL-3.2.2-cp39-cp39-win_amd64.whl
curl -O https://download.lfd.uci.edu/pythonlibs/w4tscw6k/rasterio-1.2.1-cp39-cp39-win_amd64.whl
pip install rasterio-1.2.1-cp39-cp39-win_amd64.whl
pip install -r requirements.txt
python setup.py install
pip install numpy --upgrade
- name: Test and generate coverage report
run: |
pip install pytest
pip install pytest-cov
pytest --cov=./ --cov-report=xml
23 changes: 23 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
[Issues]: https://github.com/IMMM-SFA/mosartwmpy/issues
[new Issue]: https://github.com/IMMM-SFA/mosartwmpy/issues/new/choose
[new Pull Request]: https://github.com/IMMM-SFA/mosartwmpy/compare
[IM3]: https://im3.pnnl.gov/

## How to contribute
___

__I found a bug!__
* Nice sleuthing!
* Check if the bug has already been reported by searching the existing GitHub [Issues]. If you find a match, consider adding additional details to the existing ticket.
* Open a [new Issue], being sure to include a clear title and description along with as much detail as possible; code samples or log messages demonstrating the bug are quite helpful.

__I fixed a bug!__
* First of all, thanks!
* Open a [new Pull Request] with the fix. Ensure the description clearly outlines the bug and the solution. Include the Issue number if applicable.

__I created a new feature!__
* You're the best!
* Consider opening a [new Issue] to describe use cases for the new feature. This will offer a platform for discussion and critique.
* Then, open a [new Pull Request] with clear documentation of the methodology. Be sure to include new unit tests if appropriate.

The [IM3] team truly appreciates and encourages community involvement. We're all in this together!
17 changes: 17 additions & 0 deletions DISCLAIMER
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
mosartwmpy

Copyright (c) 2021, Battelle Memorial Institute

Open source under license BSD 2-Clause

Open Source Disclaimer:

This material was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights.
Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.

PACIFIC NORTHWEST NATIONAL LABORATORY
operated by
BATTELLE
for the
UNITED STATES DEPARTMENT OF ENERGY
under Contract DE-AC05-76RL01830
125 changes: 8 additions & 117 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -1,121 +1,12 @@
Creative Commons Legal Code
mosartwmpy

CC0 1.0 Universal
Copyright (c) 2021, Battelle Memorial Institute

CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
HEREUNDER.
Open source under license BSD 2-Clause

Statement of Purpose
1. Battelle Memorial Institute (hereinafter Battelle) hereby grants permission to any person or entity lawfully obtaining a copy of this software and associated documentation files (hereinafter “the Software”) to redistribute and use the Software in source and binary forms, with or without modification. Such person or entity may use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and may permit others to do so, subject to the following conditions:
• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimers.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Other than as used herein, neither the name Battelle Memorial Institute or Battelle may be used in any form whatsoever without the express written consent of Battelle.

The laws of most jurisdictions throughout the world automatically confer
exclusive Copyright and Related Rights (defined below) upon the creator
and subsequent owner(s) (each and all, an "owner") of an original work of
authorship and/or a database (each, a "Work").

Certain owners wish to permanently relinquish those rights to a Work for
the purpose of contributing to a commons of creative, cultural and
scientific works ("Commons") that the public can reliably and without fear
of later claims of infringement build upon, modify, incorporate in other
works, reuse and redistribute as freely as possible in any form whatsoever
and for any purposes, including without limitation commercial purposes.
These owners may contribute to the Commons to promote the ideal of a free
culture and the further production of creative, cultural and scientific
works, or to gain reputation or greater distribution for their Work in
part through the use and efforts of others.

For these and/or other purposes and motivations, and without any
expectation of additional consideration or compensation, the person
associating CC0 with a Work (the "Affirmer"), to the extent that he or she
is an owner of Copyright and Related Rights in the Work, voluntarily
elects to apply CC0 to the Work and publicly distribute the Work under its
terms, with knowledge of his or her Copyright and Related Rights in the
Work and the meaning and intended legal effect of CC0 on those rights.

1. Copyright and Related Rights. A Work made available under CC0 may be
protected by copyright and related or neighboring rights ("Copyright and
Related Rights"). Copyright and Related Rights include, but are not
limited to, the following:

i. the right to reproduce, adapt, distribute, perform, display,
communicate, and translate a Work;
ii. moral rights retained by the original author(s) and/or performer(s);
iii. publicity and privacy rights pertaining to a person's image or
likeness depicted in a Work;
iv. rights protecting against unfair competition in regards to a Work,
subject to the limitations in paragraph 4(a), below;
v. rights protecting the extraction, dissemination, use and reuse of data
in a Work;
vi. database rights (such as those arising under Directive 96/9/EC of the
European Parliament and of the Council of 11 March 1996 on the legal
protection of databases, and under any national implementation
thereof, including any amended or successor version of such
directive); and
vii. other similar, equivalent or corresponding rights throughout the
world based on applicable law or treaty, and any national
implementations thereof.

2. Waiver. To the greatest extent permitted by, but not in contravention
of, applicable law, Affirmer hereby overtly, fully, permanently,
irrevocably and unconditionally waives, abandons, and surrenders all of
Affirmer's Copyright and Related Rights and associated claims and causes
of action, whether now known or unknown (including existing as well as
future claims and causes of action), in the Work (i) in all territories
worldwide, (ii) for the maximum duration provided by applicable law or
treaty (including future time extensions), (iii) in any current or future
medium and for any number of copies, and (iv) for any purpose whatsoever,
including without limitation commercial, advertising or promotional
purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
member of the public at large and to the detriment of Affirmer's heirs and
successors, fully intending that such Waiver shall not be subject to
revocation, rescission, cancellation, termination, or any other legal or
equitable action to disrupt the quiet enjoyment of the Work by the public
as contemplated by Affirmer's express Statement of Purpose.

3. Public License Fallback. Should any part of the Waiver for any reason
be judged legally invalid or ineffective under applicable law, then the
Waiver shall be preserved to the maximum extent permitted taking into
account Affirmer's express Statement of Purpose. In addition, to the
extent the Waiver is so judged Affirmer hereby grants to each affected
person a royalty-free, non transferable, non sublicensable, non exclusive,
irrevocable and unconditional license to exercise Affirmer's Copyright and
Related Rights in the Work (i) in all territories worldwide, (ii) for the
maximum duration provided by applicable law or treaty (including future
time extensions), (iii) in any current or future medium and for any number
of copies, and (iv) for any purpose whatsoever, including without
limitation commercial, advertising or promotional purposes (the
"License"). The License shall be deemed effective as of the date CC0 was
applied by Affirmer to the Work. Should any part of the License for any
reason be judged legally invalid or ineffective under applicable law, such
partial invalidity or ineffectiveness shall not invalidate the remainder
of the License, and in such case Affirmer hereby affirms that he or she
will not (i) exercise any of his or her remaining Copyright and Related
Rights in the Work or (ii) assert any associated claims and causes of
action with respect to the Work, in either case contrary to Affirmer's
express Statement of Purpose.

4. Limitations and Disclaimers.

a. No trademark or patent rights held by Affirmer are waived, abandoned,
surrendered, licensed or otherwise affected by this document.
b. Affirmer offers the Work as-is and makes no representations or
warranties of any kind concerning the Work, express, implied,
statutory or otherwise, including without limitation warranties of
title, merchantability, fitness for a particular purpose, non
infringement, or the absence of latent or other defects, accuracy, or
the present or absence of errors, whether or not discoverable, all to
the greatest extent permissible under applicable law.
c. Affirmer disclaims responsibility for clearing rights of other persons
that may apply to the Work or any use thereof, including without
limitation any person's Copyright and Related Rights in the Work.
Further, Affirmer disclaims responsibility for obtaining any necessary
consents, permissions or other rights required for any use of the
Work.
d. Affirmer understands and acknowledges that Creative Commons is not a
party to this document and has no duty or obligation with respect to
this CC0 or use of the Work.
2. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BATTELLE OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 changes: 16 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,47 +1,47 @@
![build](https://github.com/IMMM-SFA/mosartwmpy/workflows/build/badge.svg) [![codecov](https://codecov.io/gh/IMMM-SFA/mosartwmpy/branch/main/graph/badge.svg?token=IPOY8984MB)](https://codecov.io/gh/IMMM-SFA/mosartwmpy)
[![linux](https://github.com/IMMM-SFA/mosartwmpy/actions/workflows/build_linux.yml/badge.svg)](https://github.com/IMMM-SFA/mosartwmpy/actions/workflows/build_linux.yml) [![osx](https://github.com/IMMM-SFA/mosartwmpy/actions/workflows/build_osx.yml/badge.svg)](https://github.com/IMMM-SFA/mosartwmpy/actions/workflows/build_osx.yml) [![windows](https://github.com/IMMM-SFA/mosartwmpy/actions/workflows/build_windows.yml/badge.svg)](https://github.com/IMMM-SFA/mosartwmpy/actions/workflows/build_windows.yml) [![codecov](https://codecov.io/gh/IMMM-SFA/mosartwmpy/branch/main/graph/badge.svg?token=IPOY8984MB)](https://codecov.io/gh/IMMM-SFA/mosartwmpy)

## mosartwmpy

`mosartwmpy` is a python translation of MOSART-WM, a model for water routing and reservoir management written in Fortran. The original code can be found at [IWMM](https://github.com/IMMM-SFA/iwmm) and [E3SM](https://github.com/E3SM-Project/E3SM), in which MOSART is the river routing component of a larger suite of earth-science models. The motivation for rewriting is largely for developer convenience -- running, debugging, and adding new capabilities were becoming increasingly difficult due to the complexity of the codebase and lack of familiarity with Fortran. This version aims to be intuitive, lightweight, and well documented, while still being highly interoperable.

## getting started

Install `mosartwmpy` with:
Ensure you have Python >= 3.9 available (consider using a [virtual environment](https://github.com/pyenv/pyenv)), then install `mosartwmpy` with:
```shell
pip install mosartwmpy
```

Download a sample input dataset spanning 1980-1985 by running the following and selecting option `1`. This will download and unpack the inputs to your current directory. Note that this data is about 1.5GB in size.
Download a sample input dataset spanning May 1981 by running the following and selecting option `1` for "tutorial". This will download and unpack the inputs to your current directory. Optionally specify a path to download and extract to instead of the current directory.

```shell
python -m mosartwmpy.download
```

Settings are defined by the merger of the `mosartwmpy/config_defaults.yaml` and a user specified file which can override any of the default settings. Create a `config.yaml` file that defines your simulation:
Settings are defined by the merger of the `mosartwmpy/config_defaults.yaml` and a user specified file which can override any of the default settings. Create a `config.yaml` file that defines your simulation (if you chose an alternate download directory in the step above, you will need to update the paths to point at your data):

> `config.yaml`
> ```yaml
> simulation:
> name: tutorial
> start_date: 1981-05-24
> end_date: 1981-05-26
>
>
> grid:
> path: ./input/domains/MOSART_NLDAS_8th_20160426.nc
> path: ./input/domains/mosart.nc
> land:
> path: ./input/domains/domain.lnd.nldas2_0224x0464_c110415.nc
>
> path: ./input/domains/land.nc
>
> runoff:
> read_from_file: true
> path: ./input/runoff/Livneh_NLDAS_1980_1985.nc
>
> path: ./input/runoff/runoff_1981_05.nc
>
> water_management:
> enabled: true
> demand:
> read_from_file: true
> path: ./input/demand/RCP8.5_GCAM_water_demand_1980_1985.nc
> path: ./input/demand/demand_1981_05.nc
> reservoirs:
> path: ./input/reservoirs/US_reservoir_8th_NLDAS3_updated_20200421.nc
> path: ./input/reservoirs/reservoirs.nc
> ```
`mosartwmpy` implements the [Basic Model Interface](https://csdms.colorado.edu/wiki/BMI) defined by the CSDMS, so driving it should be familiar to those accustomed to the BMI. To launch the simulation, open a python shell and run the following:
Expand Down Expand Up @@ -71,7 +71,7 @@ from datetime import datetime

mosart_wm = Model()
mosart_wm.initialize()

mosart_wm.config['simulation.name'] = 'Tutorial'
mosart_wm.config['simulation.start_date'] = datetime(1981, 5, 24)
mosart_wm.config['simulation.end_date'] = datetime(1985, 5, 26)
Expand All @@ -82,7 +82,7 @@ One can use the usual python plotting libraries to visualize data. Model state a

```python
import xarray as xr
import matplotlib.pyplot as plt
import matplotlib.pyplot as plt
from mosartwmpy import Model

mosart_wm = Model()
Expand Down Expand Up @@ -135,7 +135,7 @@ Several input files in NetCDF format are required to successfully run a simulati
Grid
</td>
<td>
Spatial constants dimensioned by latitude and longitude relating to the physical properties of the river channels
Spatial constants dimensioned by latitude and longitude relating to the physical properties of the river channels
</td>
<td>
<code>grid.path</code>
Expand All @@ -147,7 +147,7 @@ Several input files in NetCDF format are required to successfully run a simulati
Land Fraction
</td>
<td>
Fraction of grid cell that is land (as opposed to i.e. ocean water) dimensioned by latitude and longitude
Fraction of grid cell that is land (as opposed to i.e. ocean water) dimensioned by latitude and longitude
</td>
<td>
<code>grid.land.path</code>
Expand Down Expand Up @@ -228,7 +228,6 @@ By default, key model variables are output on a monthly basis at a daily average

Alternatively, certain model outputs deemed most important can be accessed using the BMI interface methods. For example:
```python
import numpy as np
from mosartwmpy import Model

mosart_wm = Model()
Expand Down
4 changes: 2 additions & 2 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,11 @@
# -- Project information -----------------------------------------------------

project = 'mosartwmpy'
copyright = '2021, Travis B. Thurber'
copyright = '2021, Battelle Memorial Institute'
author = 'Travis B. Thurber'

# The full version, including alpha/beta/rc tags
release = '0.0.1'
release = 'latest'


# -- General configuration ---------------------------------------------------
Expand Down
2 changes: 1 addition & 1 deletion mosartwmpy/config/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
from benedict.dicts import benedict as Benedict


def get_config(config_file_path: str) -> Benedict:
def get_config(config_file_path: str = None) -> Benedict:
"""Configuration object for the model, using the Benedict type.
Args:
Expand Down
Loading

0 comments on commit a56e722

Please sign in to comment.