Metadata-Version: 2.5
Name: kipe
Version: 0.4.0
Summary: Parameter estimation with reduced-order unscented Kalman filtering, and identifiability analysis, for PDE models
Project-URL: Homepage, https://github.com/cardiomath/kipe
Project-URL: Issues, https://github.com/cardiomath/kipe/issues
Author-email: David Nolte <dajuno@users.noreply.github.com>
License-Expression: MIT
License-File: AUTHORS
License-File: LICENSE
Keywords: FEniCS,ROUKF,data-assimilation,fisher-information,identifiability,inverse-problems,parameter-estimation,unscented-kalman-filter
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.12
Requires-Dist: matplotlib>=3.8
Requires-Dist: mpi4py>=4
Requires-Dist: numpy>=1.26
Requires-Dist: plotext<7,>=6.1
Requires-Dist: pydantic>=2.7
Requires-Dist: ruamel-yaml>=0.18
Provides-Extra: dev
Requires-Dist: jsonschema>=4; extra == 'dev'
Requires-Dist: mypy==2.3.1; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff==0.16.9; extra == 'dev'
Requires-Dist: scipy>=1.12; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser<6,>=5; extra == 'docs'
Requires-Dist: sphinx-rtd-theme<4,>=3.1; extra == 'docs'
Requires-Dist: sphinx<10,>=9; extra == 'docs'
Requires-Dist: sphinxcontrib-mermaid<3,>=1; extra == 'docs'
Description-Content-Type: text/markdown

# kipe

[![CI](https://github.com/cardiomath/kipe/actions/workflows/ci.yml/badge.svg)](https://github.com/cardiomath/kipe/actions/workflows/ci.yml)
[![Documentation](https://img.shields.io/badge/docs-cardiomath.github.io%2Fkipe-blue)](https://cardiomath.github.io/kipe/)
![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

<!-- docs: start of the introduction (index.md) -->

***K**alman-based **i**dentifiability and **p**arameter **e**stimation*

kipe estimates the parameters of dynamical models, e.g., PDE models, from time series of
measurements, with the reduced-order unscented Kalman filter (ROUKF). The filter needs only
forward runs of your model, no derivatives, through a lean interface. Around the estimation,
kipe generates synthetic measurement data for twin experiments, from a run of the model or from
the checkpoints of an earlier run, and will analyze the identifiability of the parameters with
the Fisher information (planned).

## Key features

+ **Solver-agnostic**: Connect your model through a small forward-solver interface
+ **Derivative-free**: Optimizer is based on the reduced-order
unscented Kalman filter (ROUKF) and hence it needs only forward runs.
+ **Modular observation operators**: New observation operators can be implemented easily by
  extending the library.
+ **Twin experiments**: Generate synthetic measurements from a model run.
+ **Reproducible runs**: Keep results, logs, and run provenance together.

> **Status: early development.** The core works (ROUKF estimation, synthetic data, plotting, run
> provenance), as does a first FEniCSx backend for measurements on finite element meshes, but the
> study file format and the Python API may still change. Feedback is very welcome: please open an
> [issue](https://github.com/cardiomath/kipe/issues).

<!-- docs: end of the introduction -->

## Installation

`kipe` needs Python ≥ 3.12 and an MPI library (for `mpi4py`):

```bash
pip install kipe
pip install mpich  # only if there is no MPI library on your system
```

For FEniCSx models, install kipe into your FEniCSx (dolfinx 0.9) environment.

## Quick start

A twin experiment with the FitzHugh–Nagumo model: synthetic data from the true parameters, then
the estimation from a wrong initial guess.

```bash
git clone https://github.com/cardiomath/kipe
cd kipe/examples/fitzhugh_nagumo
kipe synthesis study.yaml
kipe estimation study.yaml
kipe plot study.yaml --truth  # --terminal without a display
```

## Documentation

**[cardiomath.github.io/kipe](https://cardiomath.github.io/kipe/)**: getting started, running a
study, measurements, the study file reference, the theory, and how to extend kipe.

## Development

```bash
git clone https://github.com/cardiomath/kipe
cd kipe
pip install -e ".[dev]"
pre-commit install --hook-type pre-commit --hook-type commit-msg
pytest
```

See [Development](https://cardiomath.github.io/kipe/development.html) in the documentation.

## License

MIT, see [LICENSE](https://github.com/cardiomath/kipe/blob/main/LICENSE). If you use kipe, please
cite it as described in
[CITATION.cff](https://github.com/cardiomath/kipe/blob/main/CITATION.cff).
