Metadata-Version: 2.5
Name: grat
Version: 0.2.1
Summary: Groundwater Recharge Assessment Tool
Project-URL: Homepage, https://github.com/blueraster/earth-genome-grat
Project-URL: Repository, https://github.com/blueraster/earth-genome-grat
Project-URL: Issues, https://github.com/blueraster/earth-genome-grat/issues
Author-email: Andy Bell <abell@blueraster.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=2.2.6
Requires-Dist: pandas>=2.3.3
Description-Content-Type: text/markdown

# grat

[![CI](https://github.com/blueraster/grat/actions/workflows/ci.yml/badge.svg)](https://github.com/blueraster/grat/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/grat.svg)](https://pypi.org/project/grat/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

GRAT is a groundwater recharge assessment tool. It models how water available for
recharge is allocated, day by day across a span of water years, to canals, basins and
farm fields, and reports the resulting groundwater recharge.

## Installation

```bash
pip install grat
```

## Usage

Run the model and produce reports:

```python
from grat import read_report, run_grat

result = run_grat(sites, wafr, bottlenecks, crop_calendar, precip)

result["zip_path"]  # the results archive
result["reports"]  # the report names that were produced
result["series"]["unused_wafr"]  # the frontend visualisation data
```

`run_grat` returns a plain dict. To look at any report it produced, read it back by
name as a pandas dataframe:

```python
df = read_report(result["output_folder"], "annual_summary_recharge")
df = read_report(result["output_folder"], "daily_recharge_by_site", year=2001)
```

Reports are asked for by name, and a run only builds what those reports need:

```python
result = run_grat(..., reports=["annual_summary_recharge", "acres_available_and_used"])
```

`grat.reports.catalog.ALL_REPORTS` lists everything available.

To drive the year loop yourself and work with the dataframes directly, without writing
any csv files, pass `None` as the output folder:

```python
from grat.model.engine import process_year
from grat.reports import report_picker

year = process_year(sites, bottlenecks, wafr, crop_calendar, precip)
reports = report_picker(
    ["annual_summary_recharge"], None, 2001, year["sites"], raw_wafr, year["wafr"], year["bottlenecks"]
)
reports["annual_summary_recharge"]
```

## Documentation

- [docs/model.md](docs/model.md) — `grat.model`: sites, allocation order, bottlenecks,
  transfers, and running the year loop yourself.
- [docs/reports.md](docs/reports.md) — `grat.reports`: the report catalog, what each
  report contains, and how to read one back.

## Development

This project uses [uv](https://docs.astral.sh/uv/) for dependency management.

```bash
uv sync                  # install dependencies (incl. dev group) into .venv
uv run pytest            # run tests
uv run ruff check .      # lint
uv run ruff format .     # format
```

## License

MIT — see [LICENSE](LICENSE).
