Metadata-Version: 2.4
Name: itzi-core
Version: 0.6.0
Summary: A flexible, API-first dynamic flood model.
Author-email: Laurent Courty <lrntct@gmail.com>
License-Expression: LGPL-2.1-or-later
Project-URL: Homepage, https://www.itzi.org
Project-URL: Repository, https://github.com/ItziModel/itzi-core
Project-URL: Issues, https://github.com/ItziModel/itzi-core/issues/
Keywords: science,engineering,hydrology,flood,inundation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.5
Requires-Dist: pyswmm>=2.1.0
Requires-Dist: bmipy>=2.0.1
Requires-Dist: pydantic>=2.13.4
Provides-Extra: xarray
Requires-Dist: xarray>=2026.4.0; extra == "xarray"
Dynamic: license-file

# itzi-core

`itzi-core` is the computational part of the [Itzi flood model](https://www.itzi.org). It provides the numerical simulation engine for distributed, dynamic flood modelling, including surface flow, hydrology and infiltration, and optional coupling to SWMM drainage networks.
Its architecture separates the simulation engine from data access through provider interfaces, so applications can plug in their own raster input, raster output, and vector output providers. This makes it possible to run the same computational model with local files, in-memory data, or cloud object storage without coupling the solver to a particular storage format or platform.

## Included Providers

The package already includes:

- An xarray raster input provider for static and time-varying gridded data.
- In-memory input and output providers for programmatic use and testing.

The xarray provider is available through the optional `xarray` dependency group.

## Installation

Itzi Core requires Python 3.12 or above.

Install the base package with `pip`:

```bash
pip install itzi-core
```

Or add it to a uv-managed project:

```bash
uv add itzi-core
```

Install the xarray provider:

```bash
pip install "itzi-core[xarray]"
```

With uv:

```bash
uv add "itzi-core[xarray]"
```

For development from a source checkout, use [uv](https://docs.astral.sh/uv/):

```bash
uv sync
uv pip install -e .
```

## Architecture

Simulations are configured with `SimulationBuilder`.
A run combines the numerical core with providers that implement the following interfaces:

- `RasterInputProvider` supplies static or time-varying raster inputs and domain metadata.
- `RasterOutputProvider` records gridded results at simulation timesteps and finalizes derived outputs.
- `VectorOutputProvider` records coupled drainage-network results.
- `MassBalanceOutputProvider` for storing mass balance and other simulation statistics.

Custom providers can implement these interfaces to integrate another data catalog, file format, service, or object store.

## Development

Run an individual test:

```bash
uv run pytest tests/test_xarray_input.py
```

Format the project:

```bash
uvx ruff format .
```

The numerical kernels include Cython extensions.
Rebuild the editable installation after changing a `.pyx` file:

```bash
uv pip install -e .
```

## License

Itzi Core is licensed under the [GNU Lesser General Public License v2.1 or later](LICENSE).

## Links

- [Itzi website](https://www.itzi.org)
- [Source repository](https://github.com/ItziModel/itzi-core)
- [Issue tracker](https://github.com/ItziModel/itzi-core/issues/)
