Skip to content

Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public. license

rillgen2d

Code, example data, and manuscript supplemental materials which accompany Pelletier, JD, XXX

Lead Author: Jon D Pelletier

Co-Authors: Jacob van der Leeuw , Tyson Lee Swetnam

Contents

The repository is organized (in the attempt) to enable reproducible research as part of the FAIR data principles.

You can (re)run these analyses using your own computer, on commercial cloud, or a data science workbench CyVerse Discovery Environment.

Installation

Dependencies

rillgen2d is written in C, but uses geospatial data input layers, such as GeoTiff. These require open-source geospatial software packages such as GDAL, GEOS, and PROJ to manage their projection information. The Graphic User Inferface (GUI) is written in Python3 using Tkinter.

Prerequisites

Regardless of Operating System, we suggest you install Miniconda (recommended) or full Anaconda prior to running the scripts below. The Docker option does not require conda installation.

ImageMagick -- the ImageMagick package is not available in Windows conda package management, which handles the other dependencies.

Setup on Windows 10

We have tested these options for running the platform on Windows 10.

Cygwin

note: requires conda installation

Install Cygwin

Install Miniconda

Run the Miniconda installer select the Cygwin installation path for the miniconda

C:\cygwin64\home\your_username\miniconda

Select the 'add to path' option in the installation step.

Download the Source Code Windows v0.3 zip and unzip (you can rename the folder to whatever you want, our example below uses rillgen2d-windows).

Open the Cygwin terminal, change directory to the rillgen2d installation folder.

cd rillgen2d-windows
Set up the conda environment

run conda using the environment_windows.yml instead of _linux.yml file:

# create environment for rillgen2d
conda env create -f environment_windows.yml

# activate conda environment
conda activate rillgen2d

If conda has errors, you may need to add it to the PATH, or set up the ~/.bashrc and ~/bash_profile for your user in Cygwin

Run the Rillgen2d GUI

Once the Python environment has been created and activated, you can start the GUI from the Terminal or Command Prompt:

python3 rillgen2d.py

Run with Docker Desktop (Windows)

Install the Windows Subsystem for Linux (WSL) v2.0 installation with the Ubuntu flavor and enable it.

Install Docker Desktop for Windows

note: does not require conda installation

Download the image from DockerHub tswetnam/rillgen2d:latest tag

The image is very large - because it contains an entire remote desktop in addition to miniconda and the rillgen2d conda environment (geospatial packages).

Run the image and open the Optional Settings and select Local Host Port - the container runs port 9876 but you can select any port you choose.

Select a Host Path - this is necessary to ensure that the data you input and output from Rillgen will be saved back to your host.

Select a Container Path - the host folder will be renamed inside the container; suggest loading into the /home/user/workspace folder name. When you run rillgen, you can look for that workspace folder.

Open in Browser - select the open in browser option once the container is running. The remote desktop can also be found at localhost:<port> that you defined in the Host Port setting.

Run from Windows Subsystem for Linux

TBA

Install for Linux and Mac OS X

We have provided two environment.yml files which can be used with Conda to install the stack on Linux and Mac OS X, or Windows10.

Make sure to add conda to your PATH environmental variables.

Open a Terminal:

# create environment for rillgen2d
conda env create -f environment_linux.yml

# activate conda environment
conda activate rillgen2d

If you have an older installation of conda you may need to update

# update conda
conda update -n base -c defaults conda

# update conda existing environment 
conda env update --prefix ./env --file environment_linux.yml  --prune

# or remove old rillgen2d environment
conda remove --name rillgen2d --all

Once the appropriate Python environment has been created, you can start the GUI from the Terminal or Command Prompt:

python3 rillgen2d.py

Download Source Code

The RillGen2D uses a combination of opensource python libraries for visualization in the Graphic User Interface (GUI). To install these tools we recommend that you use the conda environment and package manager.

First, download the latest .zip or .tar.gz from our Releases

Source Code Windows v0.3 zip

Source Code Linux/MaOSX v0.2 zip

Source Code Linux/MacOSX v0.2 tar.gz

Next, unpack the Zip or Tar file and put them somewhere you can find them from the command prompt or terminal.

If you want to pull from source, clone this repository to your local computer:

git clone https://github.com/jdpellet/rillgen2d
cd rillgen2d

The main branch has the latest features. The develop branch is where testing is taking place.

Debugging

# check your python version (should be +3.7.*)
python3 --version

If conda has errors, you may need to add it to the PATH, or set up the ~/.bashrc and ~/bash_profile for your user in Cygwin

Set the conda path to wherever you installed it - in linux, this is typically in /opt in Windows it may be in C:/cygwin64/miniconda/

echo ". /opt/conda/etc/profile.d/conda.sh" >> ~/.bashrc
echo "conda activate base" >> ~/.bashrc
source ~/.bashrc

We provide an example bash_profile in the /test sub-folder in this repository.

If you have an older installation of conda you may need to update

# update conda
conda update -n base -c defaults conda

# update conda existing environment 
conda env update --prefix ./env --file environment_linux.yml  --prune

# or remove old rillgen2d environment
conda remove --name rillgen2d --all

Note: In Linux the Parameters tab number values may appear with a newline character \n at the end of their boxes, leave these present and update the values as needed.

Building a Docker container

git clone https://github.com/jdpellet/rillgen2d
cd rillgen2d
docker build -t rillgen2d .

Docker run commands:

On Linux:

use the volume flag to mount a folder with input data: -e DISPLAY -v /home/<username/<data-folder>/:/inputs 

# Install X11 server utils
sudo apt-get install x11-xserver-utils
# set display
export DISPLAY=:0
# allow X11
xhost +
# Run docker with host display settings and data volume
docker run -it --rm -v /home/tswetnam/Downloads/:/inputs -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=unix$DISPLAY rillgen2d:latest