Metadata-Version: 2.4
Name: cnkit
Version: 1.1.0
Summary: Curve number hydrology with Earth Observation: NRCS runoff relations, NLCD/HSG lookup, event separation, asymptotic CN, and antecedent moisture.
Project-URL: Homepage, https://github.com/skp703/cnkit
Project-URL: Repository, https://github.com/skp703/cnkit
Project-URL: Issues, https://github.com/skp703/cnkit/issues
Project-URL: Changelog, https://github.com/skp703/cnkit/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/skp703/cnkit#api-overview
Author-email: Saurav Kumar <kumar.saurav@gmail.com>
Maintainer-email: Saurav Kumar <kumar.saurav@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: NRCS,SCS,TR-55,curve number,hydrology,remote sensing,runoff
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.9
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Requires-Dist: scipy>=1.7
Provides-Extra: all
Requires-Dist: earthengine-api>=1.0; extra == 'all'
Requires-Dist: requests>=2.25; extra == 'all'
Provides-Extra: data
Requires-Dist: requests>=2.25; extra == 'data'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: earthengine-api>=1.0; extra == 'dev'
Requires-Dist: flake8>=7.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: requests>=2.25; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: pdoc>=14.0; extra == 'docs'
Provides-Extra: gee
Requires-Dist: earthengine-api>=1.0; extra == 'gee'
Requires-Dist: requests>=2.25; extra == 'gee'
Provides-Extra: test
Requires-Dist: earthengine-api>=1.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: requests>=2.25; extra == 'test'
Description-Content-Type: text/markdown

# cnkit

[![CI](https://github.com/skp703/cnkit/actions/workflows/ci.yml/badge.svg)](https://github.com/skp703/cnkit/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/cnkit.svg)](https://pypi.org/project/cnkit/)
[![Python](https://img.shields.io/pypi/pyversions/cnkit.svg)](https://pypi.org/project/cnkit/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/skp703/cnkit/blob/main/LICENSE)

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

```bash
pip install cnkit
```

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

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

Python 3.9 or newer is supported.

## Quick start

```python
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

```python
%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](https://github.com/skp703/cnkit)
- [Issue tracker](https://github.com/skp703/cnkit/issues)
- [Changelog](https://github.com/skp703/cnkit/blob/main/CHANGELOG.md)
- [License](https://github.com/skp703/cnkit/blob/main/LICENSE)

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