API reference

MOBIDICpy provides a comprehensive Python API for distributed hydrological modeling. The API is organized into functional modules for easy navigation and usage.

Overview

The MOBIDICpy public API is designed to be simple and functional, exposing only the essential functions needed for preprocessing, configuration, and model setup.

API modules

Configuration

Load and validate YAML configuration files using Pydantic schemas, and configure logging behavior.

• load_config() - Load and validate configuration from YAML
• MOBIDICConfig - Complete configuration schema
• configure_logger() - Configure logging programmatically
• configure_logger_from_config() - Configure logging from YAML

GIS data I/O

Read and write geospatial data (rasters and vectors).

• grid_to_matrix() - Read raster files (GeoTIFF)
• read_shapefile() - Read vector files (Shapefile)

Grid operations

Process and transform gridded data (resolution decimation, flow direction conversion).

• decimate_raster() - Coarsen raster resolution
• decimate_flow_direction() - Coarsen flow direction grids

River network processing

Build and process river network topology with Strahler ordering and routing parameters.

• process_river_network() - Complete network processing pipeline
• save_network() - Save network to file
• load_network() - Load processed network

Hillslope-reach mapping

Connect hillslope grid cells to river reaches for lateral flow routing.

• compute_hillslope_cells() - Rasterize reaches onto grid
• map_hillslope_to_reach() - Map cells to reaches

Meteorological preprocessing

Convert meteorological data from various formats to CF-compliant NetCDF, and generate synthetic design storm hyetographs.

• MeteoData - Container for meteorological station data
• MeteoRaster - Container for gridded (raster) meteorological forcing
• HyetographGenerator - Generate synthetic hyetographs from IDF parameters
• convert_mat_to_netcdf() - Convert MATLAB to NetCDF

Data I/O

Consolidated I/O for preprocessed MOBIDIC data.

• GISData - Container for all preprocessed data
• save_gisdata() - Save preprocessed data
• load_gisdata() - Load preprocessed data

Preprocessing workflow

High-level workflow orchestrating the complete preprocessing pipeline.

• run_preprocessing() - Complete preprocessing pipeline
• process_reservoirs() - Process reservoir data (polygons, curves, schedules)

Soil water balance

Hillslope water balance with four reservoir model (capillary, gravitational, plants, surface).

• soil_mass_balance() - Main hillslope water balance function

Routing

Hillslope and channel routing algorithms for water propagation.

• hillslope_routing() - Accumulate lateral flow following flow directions
• linear_channel_routing() - Linear reservoir channel routing

Groundwater

Saturated-zone dynamics providing the baseflow contribution to surface runoff.

• groundwater_linear() - Linear-reservoir groundwater model (with optional multi-aquifer averaging via the Mf raster)

Energy Balance

Surface energy budget computing potential evapotranspiration and tracking surface/deep-soil temperatures.

• compute_energy_balance_1l() - Orchestrator for the 1-layer scheme over a model timestep (sunrise/sunset sub-stepping)
• energy_balance_1l() - Analytical Fourier 1-layer solver
• solar_position(), solar_hours() - Solar geometry helpers
• diurnal_radiation_cycle() - Sinusoidal decomposition of daily radiation
• saturation_specific_humidity() - Magnus formula

Simulation

Main simulation engine and time-stepping loop.

• Simulation - Main simulation class
• SimulationState - Container for state variables
• SimulationResults - Container for simulation results

State I/O

Save and load simulation state variables (NetCDF format).

• StateWriter - Incremental state writer with buffering
• load_state() - Load state from NetCDF
• MeteoWriter - Writer for interpolated meteorological data grids

Report I/O

Export discharge and lateral inflow time series.

• save_discharge_report() - Export discharge time series
• save_lateral_inflow_report() - Export lateral inflow time series
• load_discharge_report() - Load discharge time series

Calibration

Model calibration, global sensitivity analysis, and uncertainty quantification using PEST++.

Requires optional dependencies: pip install "mobidicpy[calibration]" && get-pestpp :pyemu

• PestSetup - Orchestrates the complete PEST++ workflow (setup, run, results)
• CalibrationResults - Parses PEST++ output files (parameters, objective function, sensitivities)
• CalibrationConfig - Pydantic model for calibration configuration
• load_calibration_config() - Load calibration configuration from YAML
• compute_metrics() - Hydrological performance metrics (i.e., NSE, KGE, RMSE, and all the metrics in the HydroErr package)
• load_observations() - Load observation time series from CSV

Quick import

All core APIs are available from the top-level mobidic package. The calibration module is under mobidic.calibration:

from mobidic import (
    # Configuration
    load_config,
    MOBIDICConfig,
    configure_logger,
    configure_logger_from_config,
    # GIS I/O
    grid_to_matrix,
    read_shapefile,
    # Grid Operations
    decimate_raster,
    decimate_flow_direction,
    # River Network
    process_river_network,
    save_network,
    load_network,
    # Hillslope-Reach Mapping
    compute_hillslope_cells,
    map_hillslope_to_reach,
    # Meteorological Data
    MeteoData,
    MeteoRaster,
    HyetographGenerator,
    convert_mat_to_netcdf,
    # Data I/O
    GISData,
    save_gisdata,
    load_gisdata,
    # Preprocessing Workflow
    run_preprocessing,
    # Soil Water Balance
    soil_mass_balance,
    # Routing
    hillslope_routing,
    linear_channel_routing,
    # Groundwater
    groundwater_linear,
    # Energy Balance
    compute_energy_balance_1l,
    energy_balance_1l,
    diurnal_radiation_cycle,
    saturation_specific_humidity,
    solar_hours,
    solar_position,
    # Reservoirs
    process_reservoirs,
    Reservoir,
    Reservoirs,
    load_reservoirs,
    save_reservoirs,
    # Simulation
    Simulation,
    SimulationState,
    SimulationResults,
    # State I/O
    StateWriter,
    load_state,
    MeteoWriter,
    # Report I/O
    save_discharge_report,
    save_lateral_inflow_report,
    load_discharge_report,
    # Constants
    constants,
)

Development status

MOBIDICpy’s currently implemented features (v0.2):

• Configuration system
• GIS data I/O
• Grid operations
• River network processing
• Hillslope-reach mapping
• Meteorological preprocessing (station data, raster forcing, hyetograph generation)
• Data I/O and consolidation
• Complete preprocessing workflow
• Soil water balance (4 reservoirs: capillary, gravitational, plants, surface)
• Linear routing (hillslope + channel)
• Linear reservoir groundwater model (with multi-aquifer capability via the Mf raster)
• Reservoir module (preprocessing, routing, time-varying regulation)
• Energy balance, 1-layer (1L) scheme
• Simulation engine (basic)
• State I/O (NetCDF, including surface and deep-soil temperatures)
• Report I/O (CSV/Parquet discharge time series)
• Calibration and sensitivity analysis (PEST++ coupling via pyemu)

Not yet implemented features:

• Energy balance: 5-layer scheme and Snow module
• Advanced groundwater models (Dupuit, MODFLOW)
• Advanced routing (Muskingum-Cunge)
• Meteorological data gap filling and quality control
• CLI interface