Installation

SMRF relies on the Image Processing Workbench (IPW) so it must be installed first. IPW currently has not been tested to run natively on Windows and must use Docker. Check the Windows section for how to run. Please go through and install the dependencies for your system prior to install install IPW and SMRF.

Ubuntu

SMRF is actively developed on Ubuntu 16.04 LTS and has been tested on 14.04 and 18.04 as well. SMRF needs gcc greater than 4.8 and Python compiled with gcc. Install the dependencies by updating, install build-essentials and installing python-dev:

sudo apt-get update
sudo apt-get install build-essential
sudo apt-get install python-dev

Mac OSX

Mac OSX greater than 10.8 is required to run SMRF. Mac OSX comes standard with Python installed with the default compiler clang. To utilize multi-threading and parallel processing, gcc must be installed with Python compiled with that gcc version.

Install the system dependencies using MacPorts or homebrew:

  1. MacPorts install system dependencies
port install gcc5
port install python35
  1. Homebrew install system dependencies
brew tap homebrew/versions
brew install gcc5
brew install python

Note

Ensure that the correct gcc and Python are activated, use gcc --version and python --version. If they are not set, use Homebrew or MacPorts activate features.

Windows

Since IPW has not been tested to run in Window, Docker will have to be used to run SMRF. The docker image for SMRF can be found on docker hub here. The docker image is already setup to run smrf so the following steps do not apply for running out of a docker.

Installing IPW

Clone IPW using the command below and follow the instructions in the Install text file. If you would prefer to read the file in your browser click here.

git clone https://github.com/USDA-ARS-NWRC/ipw.git

Double check that the following environment variables are set and readable by Python

  • $IPW, and $IPW/bin environment variable is set.
  • WORKDIR, the location where temporary files are created and modified which is not default on Linux. Use ~/tmp for example.
  • PATH, is set and readable by Python (mainly if running inside an IDE environment).

Installing SMRF

Once the dependencies have been installed for your respective system, the following will install smrf. It is preferable to use a Python virtual environment to reduce the possibility of a dependency issue.

  1. Create a virtualenv and activate it.
virtualenv -p python3.5 smrfenv
source smrfenv/bin/activate

Tip: The developers recommend using an alias to quickly turn on and off your virtual environment.

  1. Clone SMRF source code from the ARS-NWRC github.
git clone https://github.com/USDA-ARS-NWRC/smrf.git
  1. Change directories into the SMRF directory. Install the python requirements. After the requirements are done, install SMRF.
cd smrf
pip install -r requirements.txt
python setup.py install
  1. (Optional) Generate a local copy of the documentation.
cd docs
make html

To view the documentation use the preferred browser to open up the files. This can be done from the browser by opening the index.rst file directly or by the commandline like the following:

google-chrome _build/html/index.html

  1. Test the installation by running a small example. First to run any of the examples the maxus.nc for distributing wind. This only needs to be done once at the beginning of a new project.

    gen_maxus --out_maxus test_data/topo/maxus.nc test_data/topo/dem.ipw

Once the maxus file is in place run the small example over the Boise River Basin.

run_smrf test_data/testConfig.ini

If everything ran without the SMRF install is totall complete. See examples for specific types of runs. Happy SMRF-ing!