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 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