|
1 | | -# Spatial Modeling for Resources Framework |
| 1 | +# Fork of the Spatial Modeling for Resources Framework (SMRF) |
2 | 2 |
|
3 | | -[](https://img.shields.io/badge/stable%20version-v0.9-blue) |
4 | | -[](https://img.shields.io/pypi/v/smrf-dev) |
5 | | -[](https://doi.org/10.5281/zenodo.898158) |
6 | | -[](https://smrf.readthedocs.io) |
7 | | -[](https://coveralls.io/github/USDA-ARS-NWRC/smrf?branch=master) |
8 | | -[](https://codeclimate.com/github/USDA-ARS-NWRC/smrf/maintainability) |
| 3 | +This is a fork of the [USDA-ARS-NWRC SMRF](https://github.com/USDA-ARS-NWRC/smrf) |
| 4 | +repo with the model development state used for publication in |
| 5 | +[Geoscientific Model Development](https://gmd.copernicus.org/). |
9 | 6 |
|
10 | | -Spatial Modeling for Resources Framework (SMRF) was developed by Dr. Scott Havens at the USDA Agricultural Research Service (ARS) in Boise, ID. SMRF was designed to increase the flexibility of taking measured weather data and distributing the point measurements across a watershed. SMRF was developed to be used as an operational or research framework, where ease of use, efficiency, and ability to run in near real time are high priorities. |
11 | | - |
12 | | -Read the [full documentation for SMRF](https://smrf.readthedocs.io) including up to date installation instructions. |
13 | | - |
14 | | -- [Spatial Modeling for Resources Framework](#spatial-modeling-for-resources-framework) |
15 | | - - [Which version to use?](#which-version-to-use) |
16 | | - - [Stable](#stable) |
17 | | - - [Experimental](#experimental) |
18 | | - - [Installation](#installation) |
19 | | - - [System dependencies](#system-dependencies) |
20 | | - - [Topo setup](#topo-setup) |
21 | | - - [Input data](#input-data) |
22 | | - - [Running SMRF](#running-smrf) |
23 | | - - [Docker](#docker) |
24 | | - - [Development](#development) |
25 | | - - [Tests](#tests) |
26 | | - |
27 | | -## Which version to use? |
28 | | - |
29 | | -### Stable |
30 | | - |
31 | | -The stable version of SMRF is currently `v0.9`. The code can be downloaded from the [releases](https://github.com/USDA-ARS-NWRC/smrf/releases) or can be found on the `release-0.9` [branch](https://github.com/USDA-ARS-NWRC/smrf/tree/release-0.9). |
32 | | - |
33 | | -Best for: |
34 | | - |
35 | | -- Applying the model in near real time |
36 | | -- Researchers wanting a ready to use model |
37 | | -- Those wanting the most stable and tested code |
38 | | - |
39 | | -### Experimental |
40 | | - |
41 | | -> :warning: **Use at your own risk!** While this contains the latest code, it is not guaranteed to work with the whole modeling framework. |
42 | | -
|
43 | | -The latest code on `master` contains all the latest development to SMRF. However, this must be used with caution as it can be under active development, may change at any time and is not guaranteed to work with the rest of the modeling framework at that moment. Once the code has been fully tested within the modeling framework, a new release will be created to signal a move to a stable version. |
44 | | - |
45 | | -Best for: |
46 | | - |
47 | | -- Those planning on developing with SMRF |
48 | | -- Model simulations require features only found in the latest code |
49 | | -- Okay with the possibility that SMRF doesn't work with the rest of the modeling system |
50 | | - |
51 | | -## Installation |
52 | | - |
53 | | -```bash |
54 | | -python3 -m pip install smrf-dev |
55 | | -``` |
56 | | - |
57 | | -To install SMRF locally on Linux of MacOSX, first clone the repository and build into a virtual environment. This requires `gcc <= 9.0`. The general steps are as follows and will test the SMRF installation by running the tests. |
58 | | - |
59 | | -Clone from the repository |
60 | | - |
61 | | -```bash |
62 | | -git clone https://github.com/USDA-ARS-NWRC/smrf.git |
63 | | -``` |
64 | | - |
65 | | -And install the requirements, SMRF and run the tests. |
66 | | - |
67 | | -```bash |
68 | | -python3 -m pip install -r requirements_dev.txt .[tests] |
69 | | -python3 setup.py install |
70 | | -``` |
71 | | - |
72 | | -To optionally verify the installation, run the unit tests |
73 | | - |
74 | | -```bash |
75 | | -python3 -m unittest -v |
76 | | -``` |
77 | | - |
78 | | -For Windows, the install method is using [Docker](#Docker). |
79 | | - |
80 | | -### System dependencies |
81 | | - |
82 | | -If using SMRF with gridded weather data from GRIB files, you will need the system dependancy for `eccodes` which is a GRIB file reader. |
83 | | - |
84 | | -## Topo setup |
85 | | - |
86 | | -The topo provides SMRF with the following static layers: |
87 | | - |
88 | | -1. Digital elevation model |
89 | | -2. Vegetation type |
90 | | -3. Vegetation height |
91 | | -4. Vegetation extinction coefficient |
92 | | -5. Vegetation optical transmissivity |
93 | | -6. Basin mask (optional) |
94 | | - |
95 | | -All these layers are stored in a netCDF file, typically referred to the `topo.nc` file. |
96 | | - |
97 | | -While the `topo.nc` file can be generated manually, a great option is to use [basin_setup](https://github.com/USDA-ARS-NWRC/basin_setup) which creates a topo file that is compatible with SMRF and AWSM. |
98 | | - |
99 | | -## Input data |
100 | | - |
101 | | -Input meterological data for SMRF requires the following variables: |
102 | | - |
103 | | -- Air temperature |
104 | | -- Vapor pressure |
105 | | -- Precipitation |
106 | | -- Wind speed and direction |
107 | | -- Cloud factor (percentage between 0 and 1 of incoming solar obstructed by clouds) |
108 | | - |
109 | | -The data can be supplied through the following formats: |
110 | | - |
111 | | -- CSV files |
112 | | -- Weather Research and Forecasting (WRF) outputs |
113 | | -- High Resolution Rapid Refresh (HRRR) |
114 | | -- Generic netCDF |
115 | | - |
116 | | -## Running SMRF |
117 | | - |
118 | | -There are two ways to run SMRF, first is through the `run_smrf` command or through the SMRF API. If SMRF is being used as input to a snow or hydrology model, we recommend to use `run_smrf` as it will generate all the input required. See the full documentation for more details. |
119 | | - |
120 | | -```bash |
121 | | -run_smrf <config_file> |
122 | | -``` |
123 | | - |
124 | | -## Docker |
125 | | - |
126 | | -SMRF is also built into a docker image to make it easy to install on any operating system. The docker images are built automatically from the Github repository and include the latest code base or stable release images. |
127 | | - |
128 | | -The SMRF docker image has a folder meant to mount data inside the docker image at `/data`. |
129 | | - |
130 | | -```bash |
131 | | -docker run -v <path to data>:/data usdaarsnwrc/smrf run_smrf <path to config> |
132 | | -``` |
133 | | - |
134 | | -The `<path to data>` should be the path to where the configuration file, data and topo are on the host machine. This will also be the location to where the SMRF output will go. |
135 | | - |
136 | | -**NOTE:** The paths in the configuration file must be adjusted for being inside the docker image. For example, in the command above the path to the config will be inside the docker image. This would be `/data/config.ini` and not the path on the host machine. |
137 | | - |
138 | | -In a way that ARS uses this, we keep the config, topo and data on one location as the files are fairly small. The output then is put in another location as it file size can be much larger. To facilitate this, mount the input and output data separately and modify the configuration paths. |
139 | | - |
140 | | -```bash |
141 | | -docker run -v <input>:/data/input -v <output>:/data/output usdaarsnwrc/smrf run_smrf <path to config> |
142 | | -``` |
143 | | - |
144 | | -## Development |
145 | | - |
146 | | -### Tests |
147 | | -SMRF relies on class level and integration type testing. |
148 | | -On the class level, tests cover expected structure and ensure proper attribute types. |
149 | | -Example: `tests/data/test_gridded_input.py` |
150 | | - |
151 | | -The integration tests ensure that changes to the code base do not trigger unexpected changes to the model output. |
152 | | -Example: `tests/test_full_smrf.py` |
153 | | - |
154 | | -All required data for integration tests is stored under: `tests/basins/` with two sample areas. |
| 7 | +The original repo README [can be found here](README_smrf.md) |
0 commit comments