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
• capillary_rise() - Calculate capillary rise from groundwater

Routing

Hillslope and channel routing algorithms for water propagation.

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

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
• nse(), kge(), pbias(), rmse() - Hydrological performance metrics
• 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,
    capillary_rise,
    # Routing
    hillslope_routing,
    linear_channel_routing,
    # 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.1):

• 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)
• Reservoir module (preprocessing, routing, time-varying regulation)
• Simulation engine (basic)
• State I/O (NetCDF)
• Report I/O (CSV/Parquet discharge time series)
• Calibration and sensitivity analysis (PEST++ coupling via pyemu)

Coming soon:

• Energy balance module (1L, 5L schemes, Snow)
• Groundwater models (Linear, Linear_mult, Dupuit, MODFLOW)
• Advanced routing (Muskingum-Cunge)
• Meteorological data gap filling and quality control
• CLI interface