NextGen In A Box (NGIAB)

Run the NextGen National Water Resources Modeling Framework locally with ease.

NGIAB provides a containerized and user-friendly solution for running the NextGen framework, allowing you to control inputs, configurations, and execution on your local machine.

	Funding for this project was provided by the National Oceanic & Atmospheric Administration (NOAA), awarded to the Cooperative Institute for Research to Operations in Hydrology (CIROH) through the NOAA Cooperative Agreement with The University of Alabama (NA22NWS4320003).

Why NextGen In A Box?

• Run NextGen Locally: Experiment with the framework and customize configurations on your local machine.
• Control Over Inputs: Choose specific regions or basins for analysis and modify input data as needed.
• Simplified Setup: Utilize Docker containers for effortless deployment, avoiding complex software installations.
• Open Research Practices: Promote transparency and reproducibility through open-source tools like Git and GitHub.

Repository Information

• This branch specifically for the users of Singularity container image to run simulation on NextGen Framework
• The file structure and brife information of each file:

  .
  ├── guide.sh
  ├── README.md
  └── singularity
      ├── singularity_ngen.def
      └── templates
          ├── guide
              └── HelloNGEN.sh
  

  1. guilde.sh : The guide script to run the simulations on the singularity image
  2. README.md : Documentation of how to run the model and contribute in development on NGIAB
  3. singularity_ngen.def : The singularity definition file to build image
  4. HelloNGEN.sh : This is NGen execution script, which runs when the image is being executed by users.

Prerequisites

Install SigularityCE and validate SigularityCE is up

On Windows

• To install SingularityCE on Windows, first you will need to install WSL
• Install SingularityCE Desktop on Windows
• Once SingularityCE is installed, the singularity command will now be available in your WSL2 environment.
• Type singularity exec library://ubuntu echo "Hello World!" to make sure singularity is working.

On Mac

• To install SingularityCE on Mac, the Sylabs recommend to use Lima, a Linux virtual machine with automatic file sharing and port forwarding (similar to WSL2).
• Install SingularityCE on Mac
• Once Lima is installed, start Lima virtual machine by downloading AlmaLinux 9 based template.

      limactl start ./singularity-ce.yml

• Type limactl shell singularity-ce to start Lima VM with SingularityCE. Here you should be able to access Shell within Lima VM.
• Type singularity --version to make sure singularity is working.

On Linux

[!NOTE] Please make sure you install all the prerequisites of installing SingularityCE on Linux.

• Install docker on Linux

Install WSL on Windows

1. Follow Microsofts latest instructions to install WSL
2. Once this is complete, follow the instructions for linux inside your wsl terminal.

Input Data

• Download Sample Data: Use the provided commands to download sample data for the Sipsey Fork case study.
• To generate your own data: Refer to the NGIAB-datapreprocessor for instructions on generating custom input data.
• To generate your own data and run using NGIAB: Refer to the ngen-datastream repository for instructions on generating custom input data.

This section guides you through downloading and preparing the sample input data for the NextGen In A Box project.

Step 1: Create Project Directory

• Linux/Mac: Open your terminal and go to your desired folder where you want to checkout repo and ngen-data folder and run the following commands:

mkdir -p NextGen/ngen-data

cd NextGen/ngen-data

• WSL (Right click and run as Admin): Open WSL with administrator privileges and execute:

cd /mnt/c/Users/<Folder>

mkdir -p NextGen/ngen-data

cd NextGen/ngen-data

Step 2: Download Sample Data

• Linux/Mac/Windows WSL: Use wget to download the compressed data file:

wget --no-parent https://ciroh-ua-ngen-data.s3.us-east-2.amazonaws.com/AWI-007/AWI_16_2863657_007.tar.gz

Step 3: Extract and Rename

• All Platforms: Extract the downloaded file and optionally rename the folder:

tar -xf AWI_16_2863657_007.tar.gz

Below is Optional: Rename the folder

mv AWI_16_2863657_007 my_data

Now you have successfully downloaded and prepared the sample input data in the NextGen/ngen-data directory. Remember to replace "my_data" with your preferred folder name if you choose to rename it.

Run NextGen In A Box

To run NextGen framework, hydrologist only have to execute the guide script to run simulations on self-contained NextGen framework container image.

• The guide script feature:
  • Determine architecher of the underling system (ARM or x86)
  • Automaticlly download latest Singularity NextGen image from Docker Hub
  • Allow to attach input data by providing relative path of it
  • The options of running image:
    1. Run simulation in Serial mode
    2. Run simulation in Parallel mode
    3. Run image in Interactive shell mode