Skip to content

Move tutorial content to rapid-hub docs site #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
c-h-david merged 2 commits into from
May 28, 2026
Merged

Move tutorial content to rapid-hub docs site #45

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
24ea9f5
Move tutorial content to rapid-hub docs site
riverma May 26, 2026
ddea36c
Use reference-style link to keep TUTORIAL.md within line-length limit
riverma May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 4 additions & 174 deletions TUTORIAL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,178 +1,8 @@
# RAPID2 Tutorial

> ⚠️ DRAFT. Work in progress.
The RAPID2 tutorial has moved to the RAPID Hub documentation site:

This tutorial demonstrates a real scientific workflow using RAPID2. It focuses
on obtaining input data, running the model, and verifying that results match
expectations.
→ **[Running RAPID][URL_HUB]**

All commands below are written in `bash`. This example is intended to serve as
a primary reference for new users.

## 1. Get Started

Create working directories:

``` bash
mkdir -p input/Tutorial
mkdir -p output/Tutorial
```

We'll be using files from a Zenodo repository:

[![DOI:10.5281/zenodo.8248069][SVG_ZENODO]][URL_ZENODO]

Specifically, the following files are needed:

- `rapid_connect_pfaf_ii.zip`
- `coords_pfaf_ii.zip`
- `rapid_coupling_pfaf_ii_GLDAS.zip`

For this tutorial, we use the `pfaf_74` files, corresponding to the Mississippi
River Basin.

## 2. Download Raw Runoff Data with `dgldas2`

Download GLDAS phase `2.1`, model `VIC`, for `2010-01`:

``` bash
dgldas2 \
--phase 2.1 \
--model VIC \
--time 2010-01 \
--land_surface_model \
input/Tutorial/GLDAS_2.1_VIC_2010-01.nc4
```

The new file is placed in `input/Tutorial`. Other files are also automatically
downloaded in that directory and removed after use.

> Note: GLDAS `2.0` is also supported, as are the `CLSM` and `NOAH` models.

## 3. Transform Runoff to RAPID External Inflow with `cpllsm`

Convert the GLDAS runoff file into RAPID external inflow format:

``` bash
cpllsm \
--land_surface_model \
input/Tutorial/GLDAS_2.1_VIC_2010-01.nc4 \
--connectivity \
input/Tutorial/rapid_connect_pfaf_74.csv \
--coordinates \
input/Tutorial/coords_pfaf_74.csv \
--coupling \
input/Tutorial/rapid_coupling_pfaf_74_GLDAS.csv \
--external_inflow \
input/Tutorial/Qext_pfaf_74_GLDAS_2.1_VIC_2010-01.nc4
```

## 4. Create Cold Start File with `zeroqinit`

``` bash
zeroqinit \
--external_inflow \
input/Tutorial/Qext_pfaf_74_GLDAS_2.1_VIC_2010-01.nc4 \
--initial_outflow \
input/Tutorial/Qinit_pfaf_74_GLDAS_2.1_VIC_2010-01.nc4
```

## 5. Run the Routing Model with `rapid2`

Using the following content in a file called `namelist_Tutorial.md`

```yaml
# -----------------------------------------------------------------------------
# Mandatory input files
# -----------------------------------------------------------------------------
Qex_ncf: './input/Tutorial/Qext_pfaf_74_GLDAS_2.1_VIC_2010-01.nc4'
Q00_ncf: './input/Tutorial/Qinit_pfaf_74_GLDAS_2.1_VIC_2010-01.nc4'

con_csv: './input/Tutorial/rapid_connect_pfaf_74.csv'
kpr_csv: './input/Tutorial/k_pfaf_74_nrm.csv'
xpr_csv: './input/Tutorial/x_pfaf_74_nrm.csv'

bas_csv: './input/Tutorial/riv_bas_id_pfaf_74_topo.csv'

# -----------------------------------------------------------------------------
# Mandatory values
# -----------------------------------------------------------------------------
IS_dtR: 900

# -----------------------------------------------------------------------------
# Mandatory output files
# -----------------------------------------------------------------------------
Qou_ncf: './output/Tutorial/Qout_pfaf_74_GLDAS_2.1_VIC_2010-01_tst.nc4'
Qfi_ncf: './output/Tutorial/Qfinal_pfaf_74_GLDAS_2.1_VIC_2010-01_tst.nc4'
```

``` bash
rapid2 --namelist input/Tutorial/namelist_Tutorial.yml
```

## 6. Compare Files to Baseline with `cmpncf`

``` bash
cmpncf \
--previous \
input/Tutorial/Qinit_pfaf_74_GLDAS_2.1_VIC_2010-01_GOLD.nc4 \
--now \
input/Tutorial/Qinit_pfaf_74_GLDAS_2.1_VIC_2010-01.nc4 \
--relative_tolerance 1e-6 \
--absolute_tolerance 1e-3
```

```bash
cmpncf \
--previous \
input/Tutorial/Qext_pfaf_74_GLDAS_2.1_VIC_2010-01_GOLD.nc4 \
--now \
input/Tutorial/Qext_pfaf_74_GLDAS_2.1_VIC_2010-01.nc4 \
--relative_tolerance 1e-6 \
--absolute_tolerance 1e-3
```

``` bash
cmpncf \
--previous \
output/Tutorial/Qout_pfaf_74_GLDAS_2.1_VIC_2010-01_GOLD.nc4 \
--now \
output/Tutorial/Qout_pfaf_74_GLDAS_2.1_VIC_2010-01.nc4 \
--relative_tolerance 1e-6 \
--absolute_tolerance 1e-3
```

```bash
cmpncf \
--previous \
output/Tutorial/Qfinal_pfaf_74_GLDAS_2.1_VIC_2010-01_GOLD.nc4 \
--now \
output/Tutorial/Qfinal_pfaf_74_GLDAS_2.1_VIC_2010-01.nc4 \
--relative_tolerance 1e-6 \
--absolute_tolerance 1e-3
```

## Current Known Challenges to Command Line Interface

The near-term focus is on:

- Clear, consistent runtime options
- Short, intuitive 3-letter flags
- Minimalistic and readable design

At this stage, the tools remain separate commands rather than subcommands
(e.g., like `git commit` or `git clone`). Unifying these under `rapid2` may be
considered in the future.

## Opportunities for Growth

This tutorial is intended to expand over time to include:

- Inspecting input datasets
- Examining model outputs
- Basic interpretation and analysis

<!-- pyml disable-num-lines 30 line-length -->
[SVG_ZENODO]: https://zenodo.org/badge/doi/10.5281/zenodo.8248069.svg

[URL_ZENODO]: https://doi.org/10.5281/zenodo.8248069
<!-- pyml disable-num-lines 5 line-length -->
[URL_HUB]: https://c-h-david.github.io/rapid-hub/user-guide/getting-started/running/
Loading