Hydrological Modeling Pipeline¶

Calculate runoff, recharge, and other hydrological parameters for watershed management and water resource planning.

Overview¶

graph TB
    subgraph "Inputs"
        A[DEM]
        B[Rainfall Data]
        C[LULC Map]
        D[Soil Data]
    end

    subgraph "Processing"
        E[Watershed Delineation]
        F[Curve Number Calculation]
        G[Runoff Model]
        H[Water Balance]
    end

    subgraph "Outputs"
        I[Runoff Volume]
        J[Peak Discharge]
        K[Recharge]
        L[Time of Concentration]
    end

    A --> E
    B --> G
    C --> F
    D --> F

    E --> G
    F --> G
    G --> H

    H --> I
    H --> J
    H --> K
    H --> L

The hydrology pipeline uses the SCS-CN (Soil Conservation Service Curve Number) method for runoff estimation, the industry standard for watershed hydrology.

SCS-CN Method¶

graph LR
    A[Rainfall] --> B{Runoff<br/>Calculation}
    C[Curve Number] --> B
    D[Initial<br/>Abstraction] --> B

    B --> E[Runoff Depth]
    E --> F[Runoff Volume]

Key Equations¶

Potential Maximum Retention:

S = (25400 / CN) - 254

Runoff Depth:

Q = (P - Ia)² / (P - Ia + S)    for P > Ia
Q = 0                             for P ≤ Ia

Where: - Q = Runoff depth (mm) - P = Rainfall depth (mm) - Ia = Initial abstraction (typically 0.2S) - S = Potential maximum retention (mm) - CN = Curve Number (0-100)

Input Requirements¶

graph TB
    A[Hydrology Model] --> B[DEM 10-30m]
    A --> C[Rainfall mm/year]
    A --> D[LULC Classes]
    A --> E[Soil Types]
    A --> F[MWS Boundaries]

    B --> G[Elevation<br/>Slope<br/>Flow Direction]
    C --> H[Event/Annual<br/>Rainfall]
    D --> I[Land Cover<br/>Classes]
    E --> J[HSG A/B/C/D]
    F --> K[Analysis Units]

Required Parameters¶

{
  "state": "karnataka",
  "district": "raichur",
  "block": "devadurga",
  "mws_id": "mws_12345",
  "rainfall_mm": 850,
  "rainfall_type": "annual",
  "cn_method": "scs",
  "model": "runoff"
}

Curve Number Determination¶

The Curve Number depends on land cover and hydrologic soil group.

Hydrologic Soil Groups¶

graph LR
    A[Soil Types] --> B[HSG A]
    A --> C[HSG B]
    A --> D[HSG C]
    A --> E[HSG D]

    B --> F[High Infiltration<br/>Sand/Loam<br/>CN: 30-60]
    C --> G[Moderate Infiltration<br/>Silt Loam<br/>CN: 50-75]
    D --> H[Low Infiltration<br/>Clay Loam<br/>CN: 65-85]
    E --> I[Very Low Infiltration<br/>Clay<br/>CN: 75-95]

CN Lookup Table¶

Processing Workflow¶

sequenceDiagram
    participant U as User
    participant A as API
    participant W as Watershed Tool
    participant C as CN Calculator
    participant R as Runoff Model
    participant S as Storage

    U->>A: Submit Request
    A->>W: Delineate Watershed
    W->>A: MWS Boundaries

    A->>C: Calculate CN
    C->>C: LULC × Soil = CN
    C->>A: Weighted CN

    A->>R: Run SCS-CN
    R->>R: Q = f(P, CN)
    R->>R: Volume = Q × Area

    A->>R: Calculate Peak Flow
    R->>R: Rational Method

    A->>S: Store Results
    S->>U: JSON Report

1. Watershed Delineation¶

graph LR
    A[DEM] --> B[Fill Sinks]
    B --> C[Flow Direction]
    C --> D[Flow Accumulation]
    D --> E[Stream Network]
    E --> F[Watershed<br/>Boundaries]

Algorithms used: - D8 flow routing - Contributing area thresholding - Pour point snapping

2. Curve Number Calculation¶

# Calculate area-weighted CN
for mws in micro_watersheds:
    cn_values = []
    areas = []

    for lulc_class, soil_group in zip(lulc, soils):
        cn = lookup_cn(lulc_class, soil_group)
        area = get_area(lulc_class)
        cn_values.append(cn * area)
        areas.append(area)

    weighted_cn = sum(cn_values) / sum(areas)

3. Runoff Calculation¶

def calculate_runoff(precipitation_mm, curve_number):
    """Calculate runoff depth using SCS-CN method."""
    if curve_number == 0:
        return 0

    # Maximum retention
    S = (25400 / curve_number) - 254

    # Initial abstraction
    Ia = 0.2 * S

    # Runoff depth
    if precipitation_mm <= Ia:
        return 0

    numerator = (precipitation_mm - Ia) ** 2
    denominator = precipitation_mm - Ia + S

    return numerator / denominator

4. Peak Discharge¶

Using the Rational Method:

Qp = CiA

Where: - Qp = Peak discharge (m³/s) - C = Runoff coefficient - i = Rainfall intensity (mm/hr) - A = Catchment area (km²)

Output Products¶

Hydrological Report¶

{
  "mws_id": "mws_12345",
  "area_km2": 12.45,
  "rainfall_input": {
    "annual_mm": 850,
    "seasonal_mm": 650,
    "storm_mm": 75
  },
  "curve_number": 72,
  "runoff_results": {
    "runoff_depth_mm": 245.5,
    "runoff_volume_m3": 3056475,
    "runoff_coefficient": 0.29,
    "peak_discharge_m3s": 42.8
  },
  "recharge_results": {
    "recharge_depth_mm": 420.3,
    "recharge_volume_m3": 5232735,
    "recharge_coefficient": 0.49
  },
  "water_balance": {
    "precipitation_m3": 10582500,
    "evapotranspiration_m3": 2293275,
    "runoff_m3": 3056475,
    "recharge_m3": 5232735
  },
  "time_parameters": {
    "time_of_concentration_hr": 2.5,
    "lag_time_hr": 1.5,
    "time_to_peak_hr": 3.0
  }
}

Visual Outputs¶

graph LR
    A[Hydrology Results] --> B[Runoff Map]
    A --> C[CN Map]
    A --> D[Watershed Map]
    A --> E[Flow Network]

    B --> F[Thematic Raster]
    C --> G[Classified Raster]
    D --> H[Vector Polygons]
    E --> I[Stream Lines]

API Usage¶

Request¶

curl -X POST "https://geoserver.core-stack.org/api/v1/hydrology_fortnightly/" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "karnataka",
    "district": "raichur",
    "block": "devadurga",
    "start_year": 2022,
    "end_year": 2023,
    "gee_account_id": 1
  }'

Response¶

{
  "Success": "Successfully initiated"
}

Batch Processing¶

Calculate hydrology for all MWS in a block:

graph TB
    A[Block Request] --> B[Get All MWS]
    B --> C[Process MWS 1]
    B --> D[Process MWS 2]
    B --> E[Process MWS N]

    C --> F[Aggregate Results]
    D --> F
    E --> F

    F --> G[Block Summary]

Use repeated block-level requests through the current hydrology routes in computing/urls.py until batch behavior is documented as a first-class public endpoint.

Applications¶

Water Resource Planning¶

graph TB
    A[Hydrology Data] --> B[Water Budget]
    A --> C[Storage Sizing]
    A --> D[Recharge Zones]

    B --> E[Supply Planning]
    C --> F[Structure Design]
    D --> G[Priority Areas]

Flood Risk Assessment¶

Watershed Prioritization¶

quadrantChart
    title Watershed Prioritization Matrix
    x-axis Low Runoff --> High Runoff
    y-axis Low Recharge --> High Recharge

    "MWS-001": [0.3, 0.7]
    "MWS-002": [0.8, 0.2]
    "MWS-003": [0.5, 0.5]
    "MWS-004": [0.2, 0.3]
    "MWS-005": [0.7, 0.8]

Accuracy & Validation¶

Comparison with Gauged Data¶

Limitations¶

• Requires accurate rainfall estimates
• Assumes uniform CN across MWS
• Does not model baseflow
• Event-scale accuracy varies

Troubleshooting¶

High CN Values (>90)¶

Zero Runoff¶

Unrealistic Peak Flow¶

Best Practices¶

1. Calibrate CN values using local gauged data
2. Use multiple storm events for design
3. Validate with field measurements where possible
4. Consider climate change for future scenarios