cnkit

Curve number hydrology with Earth Observation. cnkit implements NRCS runoff relations, initial-abstraction conversions, NLCD and hydrologic-soil-group lookups, storm-event and baseflow separation, asymptotic curve-number estimation, antecedent-moisture conventions, watershed delineation and optional Google Earth Engine reductions.

The library returns disagreements rather than hiding them. Where a quantity has more than one defensible definition, cnkit computes each one and exposes the spread for the analyst to evaluate.

Install

pip install cnkit

The core science needs only NumPy, pandas and SciPy. Install optional network or Earth Engine features as needed:

pip install "cnkit[data]"
pip install "cnkit[gee]"
pip install "cnkit[all]"

Python 3.9 or newer is supported.

Quick start

from cnkit import composite_runoff, runoff

round(float(runoff(3.0, 75)), 4)
# 0.9608

# 60% impervious at CN 98, 40% woods at CN 55, 1-inch storm.
distributed, weighted_cn, weighted_storage = composite_runoff(
    1.0, [98, 55], [0.6, 0.4]
)
[round(x, 4) for x in (distributed, weighted_cn, weighted_storage)]
# [0.4745, 0.0949, 0.0277]

The three answers use distributed runoff, a weighted curve number and weighted retention respectively. Their spread is a real modeling decision, not a rounding error.

Main modules

• cnkit.core: retention, runoff, curve-number conversion and composite runoff.
• cnkit.lookup: NLCD crossed with hydrologic soil group.
• cnkit.events: storm-event and baseflow separation.
• cnkit.asymptotic: asymptotic and competing curve-number estimators.
• cnkit.antecedent: rainfall and satellite-soil-moisture conventions.
• cnkit.data: USGS NWIS, USDA Soil Data Access and EPA StreamCat fetchers.
• cnkit.delineate: USGS NLDI, SS-Delineate and opt-in mghydro watersheds.
• cnkit.gee: optional Earth Engine basin reductions and time series.
• cnkit.workflows: end-to-end curve-number trajectories with provenance.

Earth Engine in Jupyter or Colab

%pip install -q "cnkit[gee]"

import os
from getpass import getpass
from cnkit.gee import initialise

project = os.environ.get("CNKIT_EE_PROJECT") or getpass("Earth Engine project id: ")
initialise(project=project)

The project id is supplied at runtime. cnkit does not bundle credentials, write to Earth Engine assets or record the project id. Use soils="sda" for CONUS work; soils="hihydrosoil" is experimental. The CSRL community raster passed its live Virginia coverage and complete-reduction tests but remains disabled for 1.1 by owner decision because of its 800 m resolution, missing embedded class metadata and community-asset risk.

Runnable notebooks work in JupyterLab and Colab without cloning the repository.

Scope and units

Rainfall, runoff and storage depths are in inches unless a function documents otherwise. Curve numbers are dimensionless. cnkit computes runoff volume; it does not compute peak discharge, time of concentration, hydrographs or routing.

The NRCS tables are not defined below CN 30, and computed runoff below roughly 0.5 inches carries large relative uncertainty. The code does not enforce those engineering judgment limits.

Links

• Source, examples and full documentation
• Issue tracker
• Changelog
• License

cnkit is released under the MIT License. Verify results before using them in design work.