Getting Started#

This guide walks you through setting up and running your first SYMFLUENCE workflow — from creating a configuration file to executing a full hydrological simulation.

—

Quick Start#

Create your configuration

Copy and edit the provided template:

cp src/symfluence/resources/config_templates/config_template.yaml my_project.yaml

Define your study domain

You can specify: - A pour point (latitude/longitude) - A bounding box - An existing shapefile

Example (YAML):

# Pour point coordinates
POUR_POINT_COORDS: 51.1722/-115.5717

# Or bounding box (lat_max/lon_min/lat_min/lon_max)
BOUNDING_BOX_COORDS: 52.0/-116.0/50.0/-114.0

Run the workflow

# Run project setup
symfluence workflow step setup_project --config my_project.yaml

# Run full workflow
symfluence workflow run --config my_project.yaml

# Or run individual steps
symfluence workflow steps setup_project calibrate_model --config my_project.yaml

—

Complete Walkthrough#

This section provides a step-by-step walkthrough of a complete SYMFLUENCE workflow with expected outputs and verification steps.

Example Domain: Bow River at Banff, Alberta, Canada

Prerequisites#

SYMFLUENCE installed (see Installation)
At least 10 GB free disk space
Internet connection for data acquisition
2-4 hours for complete workflow (depending on system)

Step 1: Initialize Project#

# Create project directory
export SYMFLUENCE_DATA_DIR="/path/to/data"
cd $SYMFLUENCE_DATA_DIR

# Initialize configuration from template
symfluence project init bow_river

Expected Output:

✓ Created project directory: bow_river/
✓ Copied configuration template: bow_river/config.yaml
✓ Project initialized successfully

Verification:

ls bow_river/
# Should show: config.yaml

Estimated Time: < 1 minute

Step 2: Configure Your Project#

Edit the configuration file:

nano bow_river/config.yaml

Key parameters to set:

# Domain definition
DOMAIN_NAME: "Bow_at_Banff"
POUR_POINT_COORDS: "51.1722/-115.5717"
DOMAIN_DEFINITION_METHOD: "semidistributed"

# Time period (start small for testing)
EXPERIMENT_TIME_START: "2018-01-01"
EXPERIMENT_TIME_END: "2018-12-31"
SPINUP_PERIOD: "2017-10-01,2017-12-31"

# Model selection
HYDROLOGICAL_MODEL: "SUMMA"

# Forcing data
FORCING_DATASET: "ERA5"

Verification:

# Validate configuration
symfluence config validate --config bow_river/config.yaml

Expected Output:

✓ YAML syntax valid
✓ All required parameters present
✓ Parameter types correct
✓ Date ranges valid
Configuration validation passed

Estimated Time: 5-10 minutes

Step 3: Set Up Project Structure#

symfluence workflow step setup_project --config bow_river/config.yaml

Expected Output:

[INFO] Starting project setup
[INFO] Creating directory structure
[INFO] Initializing logging system
✓ Created: attributes/
✓ Created: forcing/
✓ Created: shapefiles/
✓ Created: settings/
✓ Created: simulations/
✓ Created: results/
✓ Created: _workLog_Bow_at_Banff/
[INFO] Project setup complete

Verification:

ls $SYMFLUENCE_DATA_DIR/domain/Bow_at_Banff/
# Should show: attributes/ forcing/ shapefiles/ settings/ etc.

Estimated Time: < 1 minute

Step 4: Delineate Domain#

symfluence workflow step define_domain --config bow_river/config.yaml

Expected Output:

[INFO] Starting domain delineation
[INFO] Downloading DEM data for region
[INFO] Running TauDEM flow accumulation
[INFO] Identifying stream network (threshold: 7500 cells)
[INFO] Delineating catchment from pour point
✓ Catchment area: 2210 km²
✓ Stream length: 45 km
✓ Mean elevation: 1650 m
[INFO] Saved catchment shapefile: shapefiles/catchment/Bow_at_Banff.shp
[INFO] Domain delineation complete

Verification:

# Check shapefile exists
ls $SYMFLUENCE_DATA_DIR/domain/Bow_at_Banff/shapefiles/catchment/
# Should show: Bow_at_Banff.shp, .shx, .dbf, .prj

# Check catchment statistics in log
tail -20 _workLog_Bow_at_Banff/domain_delineation.log

Estimated Time: 5-15 minutes

Step 5: Discretize Domain#

symfluence workflow step discretize_domain --config bow_river/config.yaml

Expected Output:

[INFO] Starting domain discretization
[INFO] Discretization method: elevation
[INFO] Elevation band size: 400 m
[INFO] Generating elevation bands
✓ Created 8 HRUs
✓ Elevation range: 1300-2900 m
✓ Saved: shapefiles/catchment/Bow_at_Banff_HRUs_elevation.shp
[INFO] Discretization complete

Verification:

# Visualize HRUs (if QGIS installed)
qgis shapefiles/catchment/Bow_at_Banff_HRUs_elevation.shp

# Or check HRU count
ogrinfo -al shapefiles/catchment/Bow_at_Banff_HRUs_elevation.shp | grep "Feature Count"

Estimated Time: 5-10 minutes

Step 6: Acquire Attribute Data#

symfluence workflow step acquire_attributes --config bow_river/config.yaml

Expected Output:

[INFO] Acquiring attribute data
[INFO] Downloading DEM (Copernicus 30m)
✓ Downloaded: attributes/elevation/dem/Bow_at_Banff_elv.tif
[INFO] Downloading land cover (MODIS)
✓ Downloaded: attributes/landclass/Bow_at_Banff_land_classes.tif
[INFO] Downloading soil data (USDA-NRCS)
✓ Downloaded: attributes/soilclass/Bow_at_Banff_soil_classes.tif
[INFO] Attribute acquisition complete

Verification:

ls attributes/*/
# Should show DEM, land cover, and soil files

# Check DEM metadata
gdalinfo attributes/elevation/dem/Bow_at_Banff_elv.tif

Estimated Time: 10-30 minutes (depends on network speed)

Step 7: Acquire Forcing Data#

symfluence workflow step acquire_forcings --config bow_river/config.yaml

Expected Output:

[INFO] Acquiring forcing data: ERA5
[INFO] Time period: 2017-10-01 to 2018-12-31
[INFO] Variables: airtemp, pptrate, spechum, windspd, SWRadAtm, LWRadAtm
[INFO] Downloading data from CDS
✓ Downloaded: forcing/raw_data/ERA5_201710.nc
✓ Downloaded: forcing/raw_data/ERA5_201711.nc
...
✓ Downloaded 15 monthly files
[INFO] Forcing acquisition complete

Verification:

ls forcing/raw_data/
# Should show ERA5_*.nc files

# Check one file
ncdump -h forcing/raw_data/ERA5_201801.nc | head -20

Estimated Time: 20-60 minutes (depends on CDS queue)

Step 8: Preprocess Data#

symfluence workflow step model_agnostic_preprocessing --config bow_river/config.yaml

Expected Output:

[INFO] Starting model-agnostic preprocessing
[INFO] Merging forcing files
[INFO] Spatial remapping to catchment
[INFO] Temporal interpolation
[INFO] Variable unit conversions
✓ Processed: forcing/basin_averaged_forcing/Bow_at_Banff_ERA5_merged.nc
[INFO] Preprocessing complete

Verification:

# Check merged file
ncdump -h forcing/basin_averaged_forcing/Bow_at_Banff_ERA5_merged.nc

# Verify time coverage
ncdump -v time forcing/basin_averaged_forcing/Bow_at_Banff_ERA5_merged.nc | tail -10

Estimated Time: 10-20 minutes

Step 9: Model-Specific Preprocessing#

symfluence workflow step model_specific_preprocessing --config bow_river/config.yaml

Expected Output:

[INFO] Starting SUMMA preprocessing
[INFO] Processing forcing data to SUMMA format
[INFO] Generating attribute files
✓ Created: forcing/SUMMA_input/Bow_at_Banff_forcing.nc
✓ Created: forcing/SUMMA_input/Bow_at_Banff_attributes.nc
[INFO] Creating SUMMA configuration files
✓ Created: settings/SUMMA/fileManager.txt
✓ Created: settings/SUMMA/decisionsFile.txt
✓ Created: settings/SUMMA/outputControl.txt
[INFO] SUMMA preprocessing complete

Verification:

ls forcing/SUMMA_input/
ls settings/SUMMA/

Estimated Time: 5-15 minutes

Step 10: Run Model#

symfluence workflow step run_model --config bow_river/config.yaml

Expected Output:

[INFO] Starting SUMMA execution
[INFO] Running 8 HRUs
HRU 1/8 complete (12.5%)
HRU 2/8 complete (25.0%)
...
HRU 8/8 complete (100%)
[INFO] SUMMA execution complete
[INFO] Adding MIZUROUTE to workflow (dependency of SUMMA)
[INFO] Running MIZUROUTE
✓ Routing complete
[INFO] Model execution complete

Verification:

# Check SUMMA output
ls simulations/*/SUMMA/

# Check mizuRoute output
ls simulations/*/mizuRoute/

Estimated Time: 10-30 minutes

Step 11: Extract Results#

symfluence workflow step postprocess_results --config bow_river/config.yaml

Expected Output:

[INFO] Post-processing SUMMA results
[INFO] Extracting streamflow
✓ Saved: results/baseline_01_results.csv
[INFO] Generating plots
✓ Created: results/streamflow_timeseries.png
[INFO] Calculating baseline metrics
============================================================
BASELINE MODEL PERFORMANCE (before calibration)
============================================================
  SUMMA:
    KGE  = 0.4521
    KGE' = 0.4312
    NSE  = 0.3987
    Bias = +12.3%
    Valid data points: 365
  Note: KGE < 0.5 suggests calibration may significantly improve results
============================================================

Verification:

# View results
head results/baseline_01_results.csv

# View plot
open results/streamflow_timeseries.png  # macOS
# or
xdg-open results/streamflow_timeseries.png  # Linux

Estimated Time: 2-5 minutes

Summary of Expected Outputs#

After completing all steps, your project directory should contain:

domain/Bow_at_Banff/
├── attributes/
│   ├── elevation/dem/Bow_at_Banff_elv.tif
│   ├── landclass/Bow_at_Banff_land_classes.tif
│   └── soilclass/Bow_at_Banff_soil_classes.tif
├── forcing/
│   ├── raw_data/ERA5_*.nc (15 files)
│   ├── basin_averaged_forcing/Bow_at_Banff_ERA5_merged.nc
│   └── SUMMA_input/Bow_at_Banff_forcing.nc
├── shapefiles/
│   ├── catchment/Bow_at_Banff.shp
│   └── catchment/Bow_at_Banff_HRUs_elevation.shp
├── settings/
│   ├── SUMMA/fileManager.txt
│   └── mizuRoute/mizuRoute_control.txt
├── simulations/
│   └── baseline_01/
│       ├── SUMMA/output/
│       └── mizuRoute/output/
├── results/
│   ├── baseline_01_results.csv
│   └── streamflow_timeseries.png
└── _workLog_Bow_at_Banff/
    ├── system.log
    ├── domain_delineation.log
    ├── data_acquisition.log
    └── model_run.log

Total Disk Usage: ~8-10 GB

Total Time: 1.5-3 hours (mostly data acquisition)

Troubleshooting Common Issues#

If you encounter issues, see:

Data acquisition fails: Check internet connection and CDS credentials (Installation)
Domain delineation fails: Verify pour point coordinates and TauDEM installation (Troubleshooting)
Model execution fails: Check log files in _workLog_*/ (Troubleshooting)
Poor baseline performance: Normal before calibration; see Calibration and Optimization

Next Steps#

After completing this walkthrough:

Calibrate your model: See Calibration and Optimization for parameter optimization
Try different models: Change HYDROLOGICAL_MODEL to FUSE, GR, or HYPE
Extend time period: Increase simulation length for longer analysis
Add observation data: Include streamflow observations for validation
Explore examples: See Examples for advanced workflows

—

Example: Bow River Watershed#

Example configuration (excerpt)#

SYMFLUENCE_DATA_DIR: default
SYMFLUENCE_CODE_DIR: default
DOMAIN_NAME: Bow_at_Banff
EXPERIMENT_ID: run_1
EXPERIMENT_TIME_START: 2004-01-01 01:00
EXPERIMENT_TIME_END: 2004-01-31 23:00
CALIBRATION_PERIOD: 2004-01-05, 2004-01-19
EVALUATION_PERIOD: 2004-01-20, 2004-01-30
SPINUP_PERIOD: 2004-01-01, 2004-01-04
MPI_PROCESSES: 1
FORCE_RUN_ALL_STEPS: false
USE_LOCAL_SCRATCH: false
RANDOM_SEED: null
LOG_LEVEL: INFO
LOG_TO_FILE: true
LOG_FORMAT: detailed
POUR_POINT_COORDS: 51.1722/-115.5717
BOUNDING_BOX_COORDS: 51.76/-116.55/50.95/-115.5
DOMAIN_DEFINITION_METHOD: lumped
ROUTING_DELINEATION: lumped
GEOFABRIC_TYPE: na
DELINEATION_METHOD: stream_threshold
CURVATURE_THRESHOLD: 0.0
MIN_SOURCE_THRESHOLD: 100
STREAM_THRESHOLD: 5000
SLOPE_AREA_THRESHOLD: 100.0
SLOPE_AREA_EXPONENT: 2.0
AREA_EXPONENT: 1.0
MULTI_SCALE_THRESHOLDS: 10000,5000,2500,1000,500
USE_DROP_ANALYSIS: false
DROP_ANALYSIS_MIN_THRESHOLD: 100
DROP_ANALYSIS_MAX_THRESHOLD: 10000
DROP_ANALYSIS_NUM_THRESHOLDS: 10
DROP_ANALYSIS_LOG_SPACING: true
LUMPED_WATERSHED_METHOD: TauDEM
CLEANUP_INTERMEDIATE_FILES: false
DELINEATE_COASTAL_WATERSHEDS: false
DELINEATE_BY_POURPOINT: true
MOVE_OUTLETS_MAX_DISTANCE: 200
MIN_GRU_SIZE: 0

This example performs: 1. Domain delineation and forcing data setup 2. Model configuration (e.g., SUMMA, FUSE, NextGen, GR4J, LSTM) 3. Simulation execution 4. Routing using mizuRoute 5. Output evaluation and visualization

—

Understanding the Workflow#

Each SYMFLUENCE run follows a structured pipeline:

Domain Definition — delineate watershed or region
Data Acquisition — retrieve and preprocess forcing datasets (ERA5, Daymet, etc.)
Model Setup — configure supported models
Simulation — execute model runs
Routing & Evaluation — route flows and compute diagnostics
Reporting — generate plots, metrics, and summaries

Each step can be called individually using the workflow command: symfluence workflow step <step_name> (e.g., workflow step setup_project or workflow step calibrate_model).

—

Next Steps#

Explore the Configuration structure in detail
Try the progressive Examples for advanced applications
Visit Troubleshooting for setup or runtime guidance