🌊 WRM-CLI

Water Resources Modeling CLI

Run EPA SWMM & EPANET simulations in the cloud

Getting Started • Documentation • Example Files • API Reference

---

🎯 Overview

WRM-CLI is a command-line tool for running water resources simulations via the NEER Water Resources Modeling API. Run SWMM and EPANET models in the cloud without installing simulation engines locally.

Features

• 🚀 Cloud Simulation - Run SWMM 5.2 and EPANET 2.3 in the cloud
• 📦 Auto-packaging - Automatically bundle auxiliary files (rainfall, temperature data)
• ⏳ Real-time Tracking - Monitor simulation progress with live log updates
• 📁 Result Download - Easily retrieve output files, reports, and logs
• 🔐 Secure - API key authentication with support for environment variables

Supported Simulation Types

Type	Description	Version
swmm	EPA Storm Water Management Model	5.2.4
epanet	EPA Water Distribution Network Model	2.3.3
hec_ras	HEC-RAS River Analysis	Coming Soon

---

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/neeraip/wrm-cli.git
cd wrm-cli

# Install dependencies
pip install -r requirements.txt

2. Configure API Key

Get your API key from:

• Personal: https://aip.neer.ai/user/keys
• Team: https://aip.neer.ai/teams/?tab=keys

# Option 1: Create .env file (recommended)
cp env.example .env
# Edit .env and add your token

# Option 2: Set environment variable
export WRAPI_TOKEN="your-api-token-here"

# Option 3: Use config command
python wrapi.py config --token "your-api-token-here"

3. Run Your First Simulation

# Run a SWMM model and wait for results
python wrapi.py run "EPASWMM Example Files/EPA/Example1.inp" --type swmm --wait

# Run an EPANET model
python wrapi.py run "EPANET Example Files/epanet-desktop/Net1/Net1.inp" --type epanet --wait

---

📖 Documentation

Running Simulations

# Basic run (local file)
python wrapi.py run model.inp --type swmm --label "My Model"

# Run from URL
python wrapi.py run https://example.com/model.inp --type swmm

# Run with auxiliary files (rainfall, temperature data)
python wrapi.py run model.inp --type swmm --aux rainfall.dat temperature.dat

# Wait for completion (polls logs every 15 seconds)
python wrapi.py run model.inp --type swmm --wait --timeout 600

Checking Status & Results

# Check simulation status
python wrapi.py status <simulation-id>

# View simulation logs
python wrapi.py logs <simulation-id>

# Get result files
python wrapi.py files <simulation-id>

# Download results to local directory
python wrapi.py files <simulation-id> --download ./results

# List recent simulations
python wrapi.py list --type swmm --limit 20

⚠️ Important: Auxiliary Files

If your model references external data files (rainfall, temperature, etc.), you must include them:

# Package model with auxiliary files
python wrapi.py run model.inp --type swmm --aux rainfall.dat temperature.dat

The tool automatically creates a ZIP file containing all files. Make sure your .inp file uses relative paths (just the filename).

# ✅ Correct - relative path
[RAINGAGES]
RG1  VOLUME  0:15  1.0  FILE  "rainfall.dat"  RG1  IN

# ❌ Wrong - absolute path won't work in cloud
[RAINGAGES]
RG1  VOLUME  0:15  1.0  FILE  "C:\Data\rainfall.dat"  RG1  IN

---

📂 Example Files

This repository includes validated and tested example files ready to run:

EPANET Examples (182 files)

EPANET Example Files/
├── asce-tf-wdst/          # ASCE Task Force benchmarks (30 files)
├── collect-epanet-inp/    # Community contributed models (107 files)
├── epanet-desktop/        # Official EPANET examples (2 files)
├── epanet-example-networks/  # EPANET test suite (42 files)
└── L-Town/                # L-Town benchmark network (1 file)

SWMM Examples (813 files)

All files have been validated and tested via API simulations. Source: SWMMEnablement/1729-SWMM5-Models repository. We reviewed over 1,700 SWMM files from the repository, and only 813 were verified working successfully.

EPASWMM Example Files/
├── SWMM5_NCIMM/          # NCIMM test suite (255 files)
├── EPA/                   # Official EPA examples (132 files)
├── Hydraulics/            # Hydraulic model tests (113 files)
├── Hydrology/             # Hydrology model tests (75 files)
├── OWA_EXTRAN/           # Open Water Analytics EXTRAN (67 files)
├── Simon_EPA/             # Community contributed (47 files)
├── LID/                   # Low Impact Development (2 files)
└── ...                    # More categories (122 files)

Run any example:

# EPANET example
python wrapi.py run "EPANET Example Files/epanet-desktop/Net1/Net1.inp" --type epanet --wait

# SWMM example
python wrapi.py run "EPASWMM Example Files/EPA/Example1.inp" --type swmm --wait

---

📚 API Reference

Endpoints

Endpoint	Method	Description
/health	GET	Health check (no auth)
/simulations	POST	Create simulation
/simulations	GET	List simulations
/simulations/{id}	GET	Get simulation details
/simulations/{id}/files	GET	List result files
/simulations/{id}/logs	GET	Get simulation logs

Simulation Status

Status	Description
pending	Created, waiting to start
running	Currently executing
completed	Finished successfully
failed	Encountered errors

Result File Types

Type	Description
input	Original input file (.inp)
output	Binary output file (.out)
report	Text report file (.rpt)

---

⚙️ Configuration

Environment Variables

# Required: API token
WRAPI_TOKEN=your-api-token-here

# Optional: API URL (default: https://wrm.neer.ai)
WRAPI_URL=https://wrm.neer.ai

Config File

Alternatively, use ~/.wrapi_config.json:

{
  "token": "your-api-token",
  "url": "https://wrm.neer.ai"
}

---

🔧 Troubleshooting

Common Errors

Error	Cause	Fix
cannot open rainfall data file	Missing auxiliary file	Include with --aux flag
ERROR 235: invalid infiltration	IMD > 1.0 for GREEN_AMPT	IMD must be 0-1
ERROR 209: undefined object	Missing object definition	Define before referencing
Convergence failure	Network issues	Check connectivity

Debug Steps

# 1. Check API health
curl https://wrm.neer.ai/health

# 2. Verify your token
python wrapi.py config --show

# 3. View simulation logs
python wrapi.py logs <simulation-id>

# 4. Download report for errors
python wrapi.py files <simulation-id> --download ./debug
grep -i error ./debug/*.rpt

---

📚 Resources

• Knowledge Base - Error codes, parameter ranges, troubleshooting
• API Documentation - Full API reference
• EPA SWMM Manual - Official EPA documentation
• EPA EPANET Manual - Official EPA documentation

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🤝 Support

• API Issues: support@neer.ai
• Documentation: https://docs.wrm.neer.io/
• GitHub Issues: Report bugs and feature requests

---

Built with ❤️ by NEER AIP

GitHub • API Docs • Support

🧪 Console model-rail smoke test

scripts/console_model_rail_smoke.py pushes ten models from this corpus through the NEER Console hydraulic-model rail end to end: import the .inp, wait for the parse, change the report step and one cross section through the model data API, read them back, run the simulation through Console, then check that report.json, the Zarr cube and Parquet were produced and that both edits reached the engine. Run it before releasing swmm-utils, lambda-importer or the SWMM task image.

export NEER_API_KEY=nck_...              # Console API key (User settings → API keys)
export PROJECT_ID=<console project id>   # a project in a team that holds a WRM API key
export CONSOLE_BASE=https://aip-dev.neer.ai
python scripts/console_model_rail_smoke.py all

Stages import, edit, run, check can be run on their own, and --only <substring> limits them to matching files. State is kept in scripts/console_model_rail_smoke_state.json (ignored by git); delete an entry's layer_id and model_id to import that file afresh. The final table shows, per model, whether it parsed, took the edits, completed, produced a report and cube, and whether the edited report step is in the .rpt and the edited cross section is in the rendered input the engine ran.

---