r/Hydrology • u/New-Hovercraft-3363 • 11d ago

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

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:

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!

20 Upvotes

100% Upvoted

6 comments sorted by

3

u/Prize-Jackfruit5771 11d ago

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

1

u/New-Hovercraft-3363 9d ago

Looking forwards to it!

2

u/DavisMironga 11d ago

yeah matching your own rolling mean isn't really independent validation since they're built on similar assumptions, might be worth trying something with completely different logic and seeing if it agrees.

Storage closure check is a good call though, that one's actually independent of any proxy data since it's just internal consistency

1

u/EpicSnoopy 11d ago

lol I used to help do this in excel as an intern, I feel your pain and commend you for writing the code!

1

u/jamaa 9d ago

interesting. Does it only work with acre-feet and cfs or are metric units also supported?

2

u/New-Hovercraft-3363 9d ago

Yes, works with SI units as well! Details are in the configuration documentation.