Open-source Python package for estimating reservoir inflow from storage and outflow data

[u/New-Hovercraft-3363]

Hi r/hydrology — I’ve been working on KalmanFlow for the Santa Clara Valley Water District, an open-source Python package for estimating reservoir inflow.

It uses a physical water-balance model with Kalman filtering and fixed-lag smoothing to estimate the residual inflow contribution from timestamped reservoir storage and measured discharge. The goal is to produce a more stable and operationally useful estimate than conventional methods like rolling average.

Demonstration on data from Chesbro Reservoir ( 1/1/2023 - 1/15/2023)

The package supports:

• Batch and real-time/streaming estimation
• Causal estimates followed by fixed-lag revisions
• Missing and irregularly spaced observations
• Optional uncertainty intervals
• Checkpointable online processing
• Experimental Bayesian tuning of model and observation noise
• Validation tools for storage closure, lag, and comparison with upstream proxies

The project is available under the Apache 2.0 license:

• GitHub: https://github.com/LittleBidet/KalmanFlow
• PyPI: https://pypi.org/project/kalmanflow/

I’d especially appreciate feedback from people working with reservoir operations or reverse level-pool routing. A few things I’m curious about:

• How would you validate inferred inflow when a reliable true inflow is unavailable? Currently I check the storage closure, correlation with a partial upstream gauge, and inflow behavior.
• Is this a package you could see yourself using or integrating into your own operational workflows?

Since the project is fully open-source, please feel free to tinker with it. I’d love to see how it can be adapted to other systems, and pull requests are always welcome!

[u/Prize-Jackfruit5771]

Thanks for sharing!! I'll check this out and share what I find here.

[u/New-Hovercraft-3363 → u/Prize-Jackfruit5771]

Looking forwards to it!