/RAPID_py

This is the python version river routing simulation based on RAPID model (Parallel computatIon of Discharge)

Primary LanguagePython

Kalman Filtering for River Network Modeling

This repository implements Kalman Filter (KF) algorithms for river network simulation, as described in the paper: Underlying Fundamentals of Kalman Filtering for River Network Modeling. The implementations are designed to facilitate simulation and analysis of river dynamics based on different state representations and assumptions.

Getting Started

Prerequisites

Ensure you have Conda installed on your system to manage the environment and dependencies.

Installation

  1. Create a Conda environment:

    conda create --name <env_name> python=3.x
conda activate <env_name>

  2. Install the required libraries:

    Navigate to the repository's root directory and run:

    pip install -r requirements.txt

Usage

This repository contains three versions of the Kalman Filter implementation tailored for different modeling approaches:

  1. Original Kalman Filter Implementation:

    • Description: Directly follows the methodology outlined in the referenced paper, with the state variable representing lateral inflows.
    • Execution: Run python rapid_python.py to perform the simulation.

  2. Another Kalman Filter Implementation:

    • Description: Similar to the first implementation but uses discharge of each reach as the state variable. This version integrates the discharge calculation process into the prediction step, contrasting with the basic implementation which requires separate discharge updates (refer to .update_discharge() function).
    • Execution: Run python rapid_python_kf2.py for simulation.

  3. Decentralized Estimation:

    • Status: Currently under development.

Data Preparation

Before executing the scripts, standard routing data must be prepared. The dataset includes:

  • Official Dataset Location: Zenodo Link
  • Quick Access Data[Recommended!!!]: A compressed file named 'rapid_data' is available for download from Google Drive. Download and place this file in the root directory of the repository for immediate use (remember name it as rapid_data)

Above dataset includes the following required Files:

  • Reaches ID File: riv_bas_id_San_Guad_hydroseq.csv, sorted from upstream to downstream.
  • Muskingum Parameters: k_San_Guad_2004_1.csv for each reach.
  • Connectivity File: rapid_connect_San_Guad.csv.
  • Lateral Inflow Data: Hourly/daily files, e.g., m3_riv_San_Guad_20100101_20131231_VIC0125_3H_utc_err_R286_D_scl.nc.
  • Gauge Observations: obs_tot_id_San_Guad_2010_2013_full.csv, Qobs_San_Guad_2010_2013_full.csv.
  • Land Surface Models: For uncertainty estimation, e.g., m3_riv_San_Guad_20100101_20131231_ENS0125_M_utc.nc.

Optional:

  • Shape Files: For visualizing river networks, e.g., StreamGageEvent_San_Guad_comid_withdir_full_2010_2013.zip.

Visualizing River Networks

To plot the geographical river network and gauge positions, use the following command:

python visual_shp_file.py

To plot the animation of the changes of river flow, use this command to read and visilize the estimation in file model_saved:

python visualize_estimation.py

remember change the 'kf_path' to the path of your estimation. Specificly, discharge_est.csv is original KF, discharge_est_kf2.csv is the new KF, dkf_discharge_est.csv is the decentralized version.

Contributing

We welcome contributions and suggestions to improve the implementations and documentation. Please refer to the issues section for pending enhancements or bug reports.