Metadata-Version: 2.4
Name: romda
Version: 3.1.0
Summary: Real-time reduced-order modelling and bias-aware data assimilation
Author-email: Andrea Nóvoa <a.novoa@imperial.ac.uk>
License: MIT
Project-URL: Homepage, https://andreanovoa.github.io/real-time-bias-aware-DA/
Project-URL: Repository, https://github.com/andreanovoa/real-time-bias-aware-DA
Project-URL: Issues, https://github.com/andreanovoa/real-time-bias-aware-DA/issues
Keywords: data-assimilation,bias-estimation,real-time,ensemble-kalman-filter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
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: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dynamodels<1.0,>=0.2
Requires-Dist: echostatenetwork[opt]<1.0,>=0.1
Requires-Dist: matplotlib<4.0,>=3.9
Requires-Dist: numpy<3.0,>=2.0
Requires-Dist: pillow>=12.3.0
Requires-Dist: pyts>=0.13
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.32.4
Requires-Dist: scipy<2.0,>=1.13
Requires-Dist: tqdm>=4.67
Requires-Dist: typeguard
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: ruff>=0.11.5; extra == "dev"
Provides-Extra: notebooks
Requires-Dist: ipykernel>=6.30; extra == "notebooks"
Requires-Dist: ipywidgets>=8.1; extra == "notebooks"
Requires-Dist: jupyter>=1.1; extra == "notebooks"
Requires-Dist: nbconvert>=7.17.0; extra == "notebooks"
Dynamic: license-file

# romda — real-time reduced-order modelling and bias-aware data assimilation

[![PyPI](https://img.shields.io/pypi/v/romda)](https://pypi.org/project/romda/)
[![docs](https://github.com/andreanovoa/real-time-bias-aware-DA/actions/workflows/docs.yml/badge.svg)](https://andreanovoa.github.io/real-time-bias-aware-DA/)

`romda` is an open-source Python package for real-time data assimilation with
reduced-order models: ensemble Kalman filters (including the regularized bias-aware
EnKF), physical and data-driven forecast models (ESN, POD-ESN), bias estimators, and
POD/SPOD decompositions — with applications to thermoacoustics and fluid flows.

> This repository was formerly the `real-time-DA` package. The code used in the papers listed
> below is preserved at the release tags [v1.0](https://github.com/andreanovoa/real-time-bias-aware-DA/releases/tag/v1.0), [v1.1](https://github.com/andreanovoa/real-time-bias-aware-DA/releases/tag/v1.1) and [v2.1](https://github.com/andreanovoa/real-time-bias-aware-DA/releases/tag/v2.1).


---

## 🚀 Getting started

1. **Install from PyPI**
```
pip install romda
```

or, to work on the source, clone and install in editable mode:
```
git clone https://github.com/andreanovoa/real-time-bias-aware-DA
cd real-time-bias-aware-DA
conda create -n romda python=3.12 && conda activate romda
pip install -e ".[dev,notebooks]" --use-pep517   # dev = pytest, notebooks = jupyter
```

2. (Optional) **Run the test suite**
```
python -m pytest tests/                 # unit and integration tests
python -m pytest scripts/tutorials/test_tutorials.py    # execute the tutorial notebooks
```

Quick example — bias-aware state and parameter estimation on a Van der Pol twin experiment:
```python
import numpy as np
from romda.bias_estimators import ConstantBias
from romda.estimators import rBA_EnKF
from romda.models.physical import VdP
from romda.observations import Observations

truth = Observations(model=VdP, t_start=0.6, t_stop=0.8, Nt_obs=30,
                     add_noise=True, manual_bias='linear')
Cdd = np.diag((0.05 * np.max(abs(truth.y_obs), axis=0)) ** 2)

ensemble = rBA_EnKF(parent_model=VdP(dt=truth.dt), parent_bias=ConstantBias,
                    m=10, std_phi=0.1, std_alpha=dict(zeta=(40., 60.)))

for d, t_d in zip(truth.y_obs, truth.t_obs):
    ensemble.forecast_step(t_end=t_d)     # advance model (and bias) to the observation time
    ensemble.analysis_step(d=d, Cdd=Cdd)  # Bayesian update
```
(The ensemble forecast runs in a multiprocessing pool, so in a script keep this under `if __name__ == "__main__":`.)

Check out th    e [Tutorials folder](https://github.com/andreanovoa/real-time-bias-aware-DA/tree/main/scripts/tutorials), which includes several jupyter notebooks aiming to ease the understanding of the repository.


## Running a physical experiment

Install the package in editable mode and run experiments from the repository root:

```bash
pip install -e ".[dev,notebooks]" --use-pep517
python -m romda.experiments configs/tai_da/rijke.yml --seed 1
```

For example:

```bash
python -m romda.experiments configs/twin_da/lorenz63.yml --seed 3
```

See [Running physical experiments](docs/experiments.md) for the available cases and Python API.


---


## 🌟 What is available?
   Data assimilation methods [`romda.estimators`](src/estimators/)
   * EnKF — ensemble Kalman filter
   * EnSRKF — ensemble square-root Kalman filter
   * rBA-EnKF — regularized bias-aware EnKF
   * KalmanFilter — the classical (linear) Kalman filter

   Physical models `romda.models.physical` (from the [`dynamodels`](https://andreanovoa.github.io/dynamodels/) package)
   * Rijke tube model (dimensional with Galerkin projection)
   * Van der Pol oscillator
   * Lorenz 63
   * Lorenz 96
   * Azimuthal thermoacoustics model
   * Kuramoto-Sivashinsky equation

   Data-driven models [`romda.models.data_driven`](src/models/data_driven/)
   * `ESN_model` — Echo State Network as a forecasting model
   * `POD_ESN` — POD dimensionality reduction + ESN forecaster
   * `LinearModel` — linear map with process noise (Kalman-filter tutorials)
   * Projectors ([`autoencoders/`](src/models/data_driven/autoencoders/)): `POD`, `SPOD` — (Spectral) Proper Orthogonal Decomposition (Sieber 2016, Towne 2018)

   Reservoir core: `EchoStateNetwork` — from the external [`echostatenetwork`](https://github.com/andreanovoa/EchoStateNetwork) package, re-exported by `romda.models.data_driven`; `pod_utils` (in `autoencoders/`) — standalone POD/SPOD algorithms

   Bias estimators [`romda.bias_estimators`](src/bias_estimators/)
   * Echo State Network
   * Constant bias
   * No bias (unbiased limit)


---
## 📂 Structure
```
.
├── data/                        # Dataset files
├── docs/                        # Documentation site sources + media used in the notebooks
├── results/                     # Generated results
├── scripts/
│   └── tutorials/               # Teaching notebooks + notebook execution tests
├── src/                         # Source code (the romda package: `from romda... import ...`)
│   ├── observations.py          # Truth / observation generation
│   ├── data_assimilation.py     # run_da_loop: the shared sequential DA driver
│   ├── utils.py
│   ├── estimators/              # Estimator hierarchy (the DA layer)
│   │   ├── base.py              # Estimator base class (forecast_step, bias wiring)
│   │   ├── ensembles.py         # EnsembleEstimator: EnKF, EnSRKF, rBA_EnKF
│   │   ├── deterministic.py     # DeterministicEstimator: KalmanFilter
│   │   └── inflation.py         # Covariance inflation
│   ├── bias_estimators/         # Bias model classes
│   │   ├── bias.py              # Bias base class
│   │   ├── esn.py               # ESN_bias
│   │   └── constantbias.py      # ConstantBias, NoBias
│   ├── models/                  # Model layer
│   │   ├── __init__.py          # re-exports the dynamodels package (Model base,
│   │   │                        #   integrators, physical models) + pickle aliases
│   │   └── data_driven/         # ESN_model, POD_ESN, LinearModel, esn_config
│   │       └── autoencoders/    # Projector hierarchy: POD, SPOD (+ pod_utils)
│   └── plotting/                # Visualization helpers
├── tests/                       # Unit and integration test suite
├── mkdocs.yml                   # Documentation site configuration
├── pyproject.toml               # Package setup
└── README.md                    # This file
```


---

## 📚 Main publications from this repository

##### Journal papers

- [x] Nóvoa, Noiray, Dawson & Magri (2024). A real-time digital twin of azimuthal thermoacoustic instabilities. Journal of Fluid Mechanics. [Published paper](https://doi.org/10.1017/jfm.2024.1052) |  🏷️ [v1.0](https://github.com/andreanovoa/real-time-bias-aware-DA/releases/tag/v1.0). 
- [x] Nóvoa, Racca & Magri (2023). Inferring unknown unknowns. Computer Methods in Applied Mechanics and Engineering. [Published paper](https://doi.org/10.1016/j.cma.2023.116502) | [_Legacy_ repository](https://github.com/MagriLab/rBA-EnKF).
- [x] Nóvoa & Magri (2022). Real-time thermoacoustic data assimilation. Journal of Fluid Mechanics. [Published paper](https://doi.org/10.1017/jfm.2022.653) | [_Legacy_ repository](https://github.com/MagriLab/Real-time-TA-DA).

##### Conference papers and proceedings
- [x] Nóvoa & Magri (2025). Online model learning with data-assimilated reservoir computers. [Preprint](https://doi.org/10.48550/arXiv.2504.16767) | 🏷️ [v1.1](https://github.com/andreanovoa/real-time-bias-aware-DA/releases/tag/v1.1).
- [x] Nóvoa & Magri (2024). Real-time digital twins of multiphysics and turbulent flows. [Paper](https://web.stanford.edu/group/ctr/ctrsp24/ii11_NOVOA.pdf).
- [x] Nóvoa & Magri (2022). Bias-aware thermoacoustic data assimilation. In_ 51st International Congress and Exposition on Noise Control Engineering. [Paper](https://az659834.vo.msecnd.net/eventsairwesteuprod/production-inconference-public/808b4f8c38f944d188db8a326a98c65c). | [_Legacy_ repository](https://github.com/MagriLab/IN22-Bias-aware-TADA).

##### PhD thesis
- [x] Nóvoa (2024). Real-time data assimilation in nonlinear dynamcal systems. University of Cambridge. [Thesis](https://doi.org/10.17863/CAM.113001). 

--- 
## 🤝 Contributing

Contributions, bug reports, and feature requests are welcome! Please open an issue or submit a pull request. For questions or collaborations, please reach out to [A. Nóvoa](https://andreanovoa.github.io/).
