romda 3.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- romda-3.0.0/LICENSE +21 -0
- romda-3.0.0/PKG-INFO +197 -0
- romda-3.0.0/README.md +155 -0
- romda-3.0.0/pyproject.toml +108 -0
- romda-3.0.0/romda.egg-info/PKG-INFO +197 -0
- romda-3.0.0/romda.egg-info/SOURCES.txt +48 -0
- romda-3.0.0/romda.egg-info/dependency_links.txt +1 -0
- romda-3.0.0/romda.egg-info/requires.txt +21 -0
- romda-3.0.0/romda.egg-info/top_level.txt +1 -0
- romda-3.0.0/setup.cfg +4 -0
- romda-3.0.0/src/__init__.py +28 -0
- romda-3.0.0/src/bias_estimators/__init__.py +12 -0
- romda-3.0.0/src/bias_estimators/aux.py +526 -0
- romda-3.0.0/src/bias_estimators/bias.py +526 -0
- romda-3.0.0/src/bias_estimators/constantbias.py +105 -0
- romda-3.0.0/src/bias_estimators/esn.py +420 -0
- romda-3.0.0/src/data_assimilation.py +68 -0
- romda-3.0.0/src/estimators/__init__.py +71 -0
- romda-3.0.0/src/estimators/base.py +431 -0
- romda-3.0.0/src/estimators/deterministic.py +288 -0
- romda-3.0.0/src/estimators/ensembles.py +984 -0
- romda-3.0.0/src/estimators/inflation.py +49 -0
- romda-3.0.0/src/models/__init__.py +51 -0
- romda-3.0.0/src/models/data_driven/__init__.py +20 -0
- romda-3.0.0/src/models/data_driven/autoencoders/__init__.py +320 -0
- romda-3.0.0/src/models/data_driven/autoencoders/pod.py +492 -0
- romda-3.0.0/src/models/data_driven/autoencoders/pod_utils.py +576 -0
- romda-3.0.0/src/models/data_driven/esn.py +1212 -0
- romda-3.0.0/src/models/data_driven/esn_config.py +652 -0
- romda-3.0.0/src/models/data_driven/linear_model.py +212 -0
- romda-3.0.0/src/models/data_driven/pod_esn.py +581 -0
- romda-3.0.0/src/observations.py +778 -0
- romda-3.0.0/src/plotting/__init__.py +4 -0
- romda-3.0.0/src/plotting/annular.py +557 -0
- romda-3.0.0/src/plotting/cylinder.py +664 -0
- romda-3.0.0/src/plotting/plot_results.py +272 -0
- romda-3.0.0/src/plotting/pod.py +318 -0
- romda-3.0.0/src/plotting/utils_plotting.py +145 -0
- romda-3.0.0/src/utils.py +1085 -0
- romda-3.0.0/tests/test_bias_estimators.py +99 -0
- romda-3.0.0/tests/test_deterministic.py +54 -0
- romda-3.0.0/tests/test_estimator_config.py +89 -0
- romda-3.0.0/tests/test_estimator_da.py +118 -0
- romda-3.0.0/tests/test_history_reset_last_states.py +36 -0
- romda-3.0.0/tests/test_inflation.py +34 -0
- romda-3.0.0/tests/test_linear_model_kf.py +65 -0
- romda-3.0.0/tests/test_models_shim.py +27 -0
- romda-3.0.0/tests/test_observations.py +75 -0
- romda-3.0.0/tests/test_pod_esn.py +104 -0
- romda-3.0.0/tests/test_pod_spod.py +176 -0
romda-3.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2022-2026 Andrea Nóvoa
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
romda-3.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: romda
|
|
3
|
+
Version: 3.0.0
|
|
4
|
+
Summary: Real-time reduced-order modelling and bias-aware data assimilation
|
|
5
|
+
Author-email: Andrea Nóvoa <a.novoa@imperial.ac.uk>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://andreanovoa.github.io/real-time-bias-aware-DA/
|
|
8
|
+
Project-URL: Repository, https://github.com/andreanovoa/real-time-bias-aware-DA
|
|
9
|
+
Project-URL: Issues, https://github.com/andreanovoa/real-time-bias-aware-DA/issues
|
|
10
|
+
Keywords: data-assimilation,bias-estimation,real-time,ensemble-kalman-filter
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: dynamodels<1.0,>=0.2
|
|
23
|
+
Requires-Dist: echostatenetwork[opt]<1.0,>=0.1
|
|
24
|
+
Requires-Dist: matplotlib<4.0,>=3.9
|
|
25
|
+
Requires-Dist: numpy<3.0,>=2.0
|
|
26
|
+
Requires-Dist: pillow
|
|
27
|
+
Requires-Dist: pyts>=0.13
|
|
28
|
+
Requires-Dist: pyyaml
|
|
29
|
+
Requires-Dist: requests>=2.32
|
|
30
|
+
Requires-Dist: scipy<2.0,>=1.13
|
|
31
|
+
Requires-Dist: tqdm>=4.67
|
|
32
|
+
Requires-Dist: typeguard
|
|
33
|
+
Provides-Extra: dev
|
|
34
|
+
Requires-Dist: pytest>=8.4; extra == "dev"
|
|
35
|
+
Requires-Dist: ruff; extra == "dev"
|
|
36
|
+
Provides-Extra: notebooks
|
|
37
|
+
Requires-Dist: ipykernel>=6.30; extra == "notebooks"
|
|
38
|
+
Requires-Dist: ipywidgets>=8.1; extra == "notebooks"
|
|
39
|
+
Requires-Dist: jupyter>=1.1; extra == "notebooks"
|
|
40
|
+
Requires-Dist: nbconvert>=7.0; extra == "notebooks"
|
|
41
|
+
Dynamic: license-file
|
|
42
|
+
|
|
43
|
+
# romda — real-time reduced-order modelling and bias-aware data assimilation
|
|
44
|
+
|
|
45
|
+
`romda` is an open-source Python package for real-time data assimilation with
|
|
46
|
+
reduced-order models: ensemble Kalman filters (including the regularized bias-aware
|
|
47
|
+
EnKF), physical and data-driven forecast models (ESN, POD-ESN), bias estimators, and
|
|
48
|
+
POD/SPOD decompositions — with applications to thermoacoustics and fluid flows.
|
|
49
|
+
|
|
50
|
+
📖 **Documentation:** https://andreanovoa.github.io/real-time-bias-aware-DA/
|
|
51
|
+
|
|
52
|
+
> This repository was formerly the `real-time-DA` package. The code used in the papers listed
|
|
53
|
+
> 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).
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## 🚀 Getting started
|
|
59
|
+
|
|
60
|
+
1. **Install from PyPI**
|
|
61
|
+
```
|
|
62
|
+
pip install romda
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
or, to work on the source, clone and install in editable mode:
|
|
66
|
+
```
|
|
67
|
+
git clone https://github.com/andreanovoa/real-time-bias-aware-DA
|
|
68
|
+
cd real-time-bias-aware-DA
|
|
69
|
+
conda create -n romda python=3.12 && conda activate romda
|
|
70
|
+
pip install -e ".[dev,notebooks]" --use-pep517 # dev = pytest, notebooks = jupyter
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
2. (Optional) **Run the test suite**
|
|
74
|
+
```
|
|
75
|
+
python -m pytest tests/ # unit and integration tests
|
|
76
|
+
python -m pytest scripts/tutorials/test_tutorials.py # execute the tutorial notebooks
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Quick example — bias-aware state and parameter estimation on a Van der Pol twin experiment:
|
|
80
|
+
```python
|
|
81
|
+
import numpy as np
|
|
82
|
+
from romda.bias_estimators import ConstantBias
|
|
83
|
+
from romda.estimators import rBA_EnKF
|
|
84
|
+
from romda.models.physical import VdP
|
|
85
|
+
from romda.observations import Observations
|
|
86
|
+
|
|
87
|
+
truth = Observations(model=VdP, t_start=0.6, t_stop=0.8, Nt_obs=30,
|
|
88
|
+
add_noise=True, manual_bias='linear')
|
|
89
|
+
Cdd = np.diag((0.05 * np.max(abs(truth.y_obs), axis=0)) ** 2)
|
|
90
|
+
|
|
91
|
+
ensemble = rBA_EnKF(parent_model=VdP(dt=truth.dt), parent_bias=ConstantBias,
|
|
92
|
+
m=10, std_phi=0.1, std_alpha=dict(zeta=(40., 60.)))
|
|
93
|
+
|
|
94
|
+
for d, t_d in zip(truth.y_obs, truth.t_obs):
|
|
95
|
+
ensemble.forecast_step(t_end=t_d) # advance model (and bias) to the observation time
|
|
96
|
+
ensemble.analysis_step(d=d, Cdd=Cdd) # Bayesian update
|
|
97
|
+
```
|
|
98
|
+
(The ensemble forecast runs in a multiprocessing pool, so in a script keep this under `if __name__ == "__main__":`.)
|
|
99
|
+
|
|
100
|
+
Check out the [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.
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
## 🌟 What is available?
|
|
107
|
+
Data assimilation methods [`romda.estimators`](src/estimators/)
|
|
108
|
+
* EnKF — ensemble Kalman filter
|
|
109
|
+
* EnSRKF — ensemble square-root Kalman filter
|
|
110
|
+
* rBA-EnKF — regularized bias-aware EnKF
|
|
111
|
+
* KalmanFilter — the classical (linear) Kalman filter
|
|
112
|
+
|
|
113
|
+
Physical models [`romda.models.physical`](https://github.com/andreanovoa/dynamodels) (from the `dynamodels` package)
|
|
114
|
+
* Rijke tube model (dimensional with Galerkin projection)
|
|
115
|
+
* Van der Pol oscillator
|
|
116
|
+
* Lorenz 63
|
|
117
|
+
* Lorenz 96
|
|
118
|
+
* Azimuthal thermoacoustics model
|
|
119
|
+
* Kuramoto-Sivashinsky equation
|
|
120
|
+
|
|
121
|
+
Data-driven models [`romda.models.data_driven`](src/models/data_driven/)
|
|
122
|
+
* `ESN_model` — Echo State Network as a forecasting model
|
|
123
|
+
* `POD_ESN` — POD dimensionality reduction + ESN forecaster
|
|
124
|
+
* `LinearModel` — linear map with process noise (Kalman-filter tutorials)
|
|
125
|
+
* Projectors ([`autoencoders/`](src/models/data_driven/autoencoders/)): `POD`, `SPOD` — (Spectral) Proper Orthogonal Decomposition (Sieber 2016, Towne 2018)
|
|
126
|
+
|
|
127
|
+
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
|
|
128
|
+
|
|
129
|
+
Bias estimators [`romda.bias_estimators`](src/bias_estimators/)
|
|
130
|
+
* Echo State Network
|
|
131
|
+
* Constant bias
|
|
132
|
+
* No bias (unbiased limit)
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
## 📂 Structure
|
|
137
|
+
```
|
|
138
|
+
.
|
|
139
|
+
├── data/ # Dataset files
|
|
140
|
+
├── docs/ # Documentation site sources + media used in the notebooks
|
|
141
|
+
├── results/ # Generated results
|
|
142
|
+
├── scripts/
|
|
143
|
+
│ └── tutorials/ # Teaching notebooks + notebook execution tests
|
|
144
|
+
├── src/ # Source code (the romda package: `from romda... import ...`)
|
|
145
|
+
│ ├── observations.py # Truth / observation generation
|
|
146
|
+
│ ├── data_assimilation.py # run_da_loop: the shared sequential DA driver
|
|
147
|
+
│ ├── utils.py
|
|
148
|
+
│ ├── estimators/ # Estimator hierarchy (the DA layer)
|
|
149
|
+
│ │ ├── base.py # Estimator base class (forecast_step, bias wiring)
|
|
150
|
+
│ │ ├── ensembles.py # EnsembleEstimator: EnKF, EnSRKF, rBA_EnKF
|
|
151
|
+
│ │ ├── deterministic.py # DeterministicEstimator: KalmanFilter
|
|
152
|
+
│ │ └── inflation.py # Covariance inflation
|
|
153
|
+
│ ├── bias_estimators/ # Bias model classes
|
|
154
|
+
│ │ ├── bias.py # Bias base class
|
|
155
|
+
│ │ ├── esn.py # ESN_bias
|
|
156
|
+
│ │ └── constantbias.py # ConstantBias, NoBias
|
|
157
|
+
│ ├── models/ # Model layer
|
|
158
|
+
│ │ ├── __init__.py # re-exports the dynamodels package (Model base,
|
|
159
|
+
│ │ │ # integrators, physical models) + pickle aliases
|
|
160
|
+
│ │ └── data_driven/ # ESN_model, POD_ESN, LinearModel, esn_config
|
|
161
|
+
│ │ └── autoencoders/ # Projector hierarchy: POD, SPOD (+ pod_utils)
|
|
162
|
+
│ └── plotting/ # Visualization helpers
|
|
163
|
+
├── tests/ # Unit and integration test suite
|
|
164
|
+
├── mkdocs.yml # Documentation site configuration
|
|
165
|
+
├── pyproject.toml # Package setup
|
|
166
|
+
└── README.md # This file
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## 📚 Main publications from this repository
|
|
173
|
+
|
|
174
|
+
##### Journal papers
|
|
175
|
+
|
|
176
|
+
- [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).
|
|
177
|
+
- [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).
|
|
178
|
+
- [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).
|
|
179
|
+
|
|
180
|
+
##### Conference papers and proceedings
|
|
181
|
+
- [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).
|
|
182
|
+
- [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).
|
|
183
|
+
- [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).
|
|
184
|
+
|
|
185
|
+
##### PhD thesis
|
|
186
|
+
- [x] Nóvoa (2024). Real-time data assimilation in nonlinear dynamcal systems. University of Cambridge. [Thesis](https://doi.org/10.17863/CAM.113001).
|
|
187
|
+
|
|
188
|
+
<!-- ##### Conference presentations _(incomplete list)_
|
|
189
|
+
- **APS-DFD 2024, Salt Lake City:** [Abstract](https://meetings.aps.org/Meeting/DFD24/Session/C02.14) | [Poster](https://github.com/user-attachments/files/17966063/APS-poster-final-version.pdf).
|
|
190
|
+
- **APS-DFD 2023, Washington DC:** [Abstract](https://meetings.aps.org/Meeting/DFD23/Session/L30.8).
|
|
191
|
+
- **EFMC14 2022, Athens:** [Abstract](https://euromech.org/conferences/proceedings.htm).
|
|
192
|
+
- **APS-DFD 2022, Phoenix:** [Abstract](https://meetings.aps.org/Meeting/DFD22/Session/G12.4). -->
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
## 🤝 Contributing
|
|
196
|
+
|
|
197
|
+
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/).
|
romda-3.0.0/README.md
ADDED
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# romda — real-time reduced-order modelling and bias-aware data assimilation
|
|
2
|
+
|
|
3
|
+
`romda` is an open-source Python package for real-time data assimilation with
|
|
4
|
+
reduced-order models: ensemble Kalman filters (including the regularized bias-aware
|
|
5
|
+
EnKF), physical and data-driven forecast models (ESN, POD-ESN), bias estimators, and
|
|
6
|
+
POD/SPOD decompositions — with applications to thermoacoustics and fluid flows.
|
|
7
|
+
|
|
8
|
+
📖 **Documentation:** https://andreanovoa.github.io/real-time-bias-aware-DA/
|
|
9
|
+
|
|
10
|
+
> This repository was formerly the `real-time-DA` package. The code used in the papers listed
|
|
11
|
+
> 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).
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 🚀 Getting started
|
|
17
|
+
|
|
18
|
+
1. **Install from PyPI**
|
|
19
|
+
```
|
|
20
|
+
pip install romda
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
or, to work on the source, clone and install in editable mode:
|
|
24
|
+
```
|
|
25
|
+
git clone https://github.com/andreanovoa/real-time-bias-aware-DA
|
|
26
|
+
cd real-time-bias-aware-DA
|
|
27
|
+
conda create -n romda python=3.12 && conda activate romda
|
|
28
|
+
pip install -e ".[dev,notebooks]" --use-pep517 # dev = pytest, notebooks = jupyter
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
2. (Optional) **Run the test suite**
|
|
32
|
+
```
|
|
33
|
+
python -m pytest tests/ # unit and integration tests
|
|
34
|
+
python -m pytest scripts/tutorials/test_tutorials.py # execute the tutorial notebooks
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Quick example — bias-aware state and parameter estimation on a Van der Pol twin experiment:
|
|
38
|
+
```python
|
|
39
|
+
import numpy as np
|
|
40
|
+
from romda.bias_estimators import ConstantBias
|
|
41
|
+
from romda.estimators import rBA_EnKF
|
|
42
|
+
from romda.models.physical import VdP
|
|
43
|
+
from romda.observations import Observations
|
|
44
|
+
|
|
45
|
+
truth = Observations(model=VdP, t_start=0.6, t_stop=0.8, Nt_obs=30,
|
|
46
|
+
add_noise=True, manual_bias='linear')
|
|
47
|
+
Cdd = np.diag((0.05 * np.max(abs(truth.y_obs), axis=0)) ** 2)
|
|
48
|
+
|
|
49
|
+
ensemble = rBA_EnKF(parent_model=VdP(dt=truth.dt), parent_bias=ConstantBias,
|
|
50
|
+
m=10, std_phi=0.1, std_alpha=dict(zeta=(40., 60.)))
|
|
51
|
+
|
|
52
|
+
for d, t_d in zip(truth.y_obs, truth.t_obs):
|
|
53
|
+
ensemble.forecast_step(t_end=t_d) # advance model (and bias) to the observation time
|
|
54
|
+
ensemble.analysis_step(d=d, Cdd=Cdd) # Bayesian update
|
|
55
|
+
```
|
|
56
|
+
(The ensemble forecast runs in a multiprocessing pool, so in a script keep this under `if __name__ == "__main__":`.)
|
|
57
|
+
|
|
58
|
+
Check out the [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.
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
## 🌟 What is available?
|
|
65
|
+
Data assimilation methods [`romda.estimators`](src/estimators/)
|
|
66
|
+
* EnKF — ensemble Kalman filter
|
|
67
|
+
* EnSRKF — ensemble square-root Kalman filter
|
|
68
|
+
* rBA-EnKF — regularized bias-aware EnKF
|
|
69
|
+
* KalmanFilter — the classical (linear) Kalman filter
|
|
70
|
+
|
|
71
|
+
Physical models [`romda.models.physical`](https://github.com/andreanovoa/dynamodels) (from the `dynamodels` package)
|
|
72
|
+
* Rijke tube model (dimensional with Galerkin projection)
|
|
73
|
+
* Van der Pol oscillator
|
|
74
|
+
* Lorenz 63
|
|
75
|
+
* Lorenz 96
|
|
76
|
+
* Azimuthal thermoacoustics model
|
|
77
|
+
* Kuramoto-Sivashinsky equation
|
|
78
|
+
|
|
79
|
+
Data-driven models [`romda.models.data_driven`](src/models/data_driven/)
|
|
80
|
+
* `ESN_model` — Echo State Network as a forecasting model
|
|
81
|
+
* `POD_ESN` — POD dimensionality reduction + ESN forecaster
|
|
82
|
+
* `LinearModel` — linear map with process noise (Kalman-filter tutorials)
|
|
83
|
+
* Projectors ([`autoencoders/`](src/models/data_driven/autoencoders/)): `POD`, `SPOD` — (Spectral) Proper Orthogonal Decomposition (Sieber 2016, Towne 2018)
|
|
84
|
+
|
|
85
|
+
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
|
|
86
|
+
|
|
87
|
+
Bias estimators [`romda.bias_estimators`](src/bias_estimators/)
|
|
88
|
+
* Echo State Network
|
|
89
|
+
* Constant bias
|
|
90
|
+
* No bias (unbiased limit)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
## 📂 Structure
|
|
95
|
+
```
|
|
96
|
+
.
|
|
97
|
+
├── data/ # Dataset files
|
|
98
|
+
├── docs/ # Documentation site sources + media used in the notebooks
|
|
99
|
+
├── results/ # Generated results
|
|
100
|
+
├── scripts/
|
|
101
|
+
│ └── tutorials/ # Teaching notebooks + notebook execution tests
|
|
102
|
+
├── src/ # Source code (the romda package: `from romda... import ...`)
|
|
103
|
+
│ ├── observations.py # Truth / observation generation
|
|
104
|
+
│ ├── data_assimilation.py # run_da_loop: the shared sequential DA driver
|
|
105
|
+
│ ├── utils.py
|
|
106
|
+
│ ├── estimators/ # Estimator hierarchy (the DA layer)
|
|
107
|
+
│ │ ├── base.py # Estimator base class (forecast_step, bias wiring)
|
|
108
|
+
│ │ ├── ensembles.py # EnsembleEstimator: EnKF, EnSRKF, rBA_EnKF
|
|
109
|
+
│ │ ├── deterministic.py # DeterministicEstimator: KalmanFilter
|
|
110
|
+
│ │ └── inflation.py # Covariance inflation
|
|
111
|
+
│ ├── bias_estimators/ # Bias model classes
|
|
112
|
+
│ │ ├── bias.py # Bias base class
|
|
113
|
+
│ │ ├── esn.py # ESN_bias
|
|
114
|
+
│ │ └── constantbias.py # ConstantBias, NoBias
|
|
115
|
+
│ ├── models/ # Model layer
|
|
116
|
+
│ │ ├── __init__.py # re-exports the dynamodels package (Model base,
|
|
117
|
+
│ │ │ # integrators, physical models) + pickle aliases
|
|
118
|
+
│ │ └── data_driven/ # ESN_model, POD_ESN, LinearModel, esn_config
|
|
119
|
+
│ │ └── autoencoders/ # Projector hierarchy: POD, SPOD (+ pod_utils)
|
|
120
|
+
│ └── plotting/ # Visualization helpers
|
|
121
|
+
├── tests/ # Unit and integration test suite
|
|
122
|
+
├── mkdocs.yml # Documentation site configuration
|
|
123
|
+
├── pyproject.toml # Package setup
|
|
124
|
+
└── README.md # This file
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## 📚 Main publications from this repository
|
|
131
|
+
|
|
132
|
+
##### Journal papers
|
|
133
|
+
|
|
134
|
+
- [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).
|
|
135
|
+
- [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).
|
|
136
|
+
- [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).
|
|
137
|
+
|
|
138
|
+
##### Conference papers and proceedings
|
|
139
|
+
- [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).
|
|
140
|
+
- [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).
|
|
141
|
+
- [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).
|
|
142
|
+
|
|
143
|
+
##### PhD thesis
|
|
144
|
+
- [x] Nóvoa (2024). Real-time data assimilation in nonlinear dynamcal systems. University of Cambridge. [Thesis](https://doi.org/10.17863/CAM.113001).
|
|
145
|
+
|
|
146
|
+
<!-- ##### Conference presentations _(incomplete list)_
|
|
147
|
+
- **APS-DFD 2024, Salt Lake City:** [Abstract](https://meetings.aps.org/Meeting/DFD24/Session/C02.14) | [Poster](https://github.com/user-attachments/files/17966063/APS-poster-final-version.pdf).
|
|
148
|
+
- **APS-DFD 2023, Washington DC:** [Abstract](https://meetings.aps.org/Meeting/DFD23/Session/L30.8).
|
|
149
|
+
- **EFMC14 2022, Athens:** [Abstract](https://euromech.org/conferences/proceedings.htm).
|
|
150
|
+
- **APS-DFD 2022, Phoenix:** [Abstract](https://meetings.aps.org/Meeting/DFD22/Session/G12.4). -->
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
## 🤝 Contributing
|
|
154
|
+
|
|
155
|
+
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/).
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=64", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "romda"
|
|
7
|
+
version = "3.0.0"
|
|
8
|
+
description = "Real-time reduced-order modelling and bias-aware data assimilation"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = {text = "MIT"}
|
|
12
|
+
authors = [
|
|
13
|
+
{name = "Andrea Nóvoa", email = "a.novoa@imperial.ac.uk"}
|
|
14
|
+
]
|
|
15
|
+
keywords = ["data-assimilation", "bias-estimation", "real-time", "ensemble-kalman-filter"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 4 - Beta",
|
|
18
|
+
"Intended Audience :: Science/Research",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.10",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Programming Language :: Python :: 3.14",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
dependencies = [
|
|
28
|
+
"dynamodels>=0.2,<1.0",
|
|
29
|
+
"echostatenetwork[opt]>=0.1,<1.0", # [opt] = scikit-optimize for ESN hyperparameter search
|
|
30
|
+
"matplotlib>=3.9,<4.0",
|
|
31
|
+
"numpy>=2.0,<3.0",
|
|
32
|
+
"pillow",
|
|
33
|
+
"pyts>=0.13",
|
|
34
|
+
"pyyaml",
|
|
35
|
+
"requests>=2.32",
|
|
36
|
+
"scipy>=1.13,<2.0",
|
|
37
|
+
"tqdm>=4.67",
|
|
38
|
+
"typeguard",
|
|
39
|
+
]
|
|
40
|
+
|
|
41
|
+
[project.optional-dependencies]
|
|
42
|
+
dev = [
|
|
43
|
+
"pytest>=8.4",
|
|
44
|
+
"ruff",
|
|
45
|
+
]
|
|
46
|
+
notebooks = [
|
|
47
|
+
"ipykernel>=6.30",
|
|
48
|
+
"ipywidgets>=8.1",
|
|
49
|
+
"jupyter>=1.1",
|
|
50
|
+
"nbconvert>=7.0",
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
[project.urls]
|
|
54
|
+
Homepage = "https://andreanovoa.github.io/real-time-bias-aware-DA/"
|
|
55
|
+
Repository = "https://github.com/andreanovoa/real-time-bias-aware-DA"
|
|
56
|
+
Issues = "https://github.com/andreanovoa/real-time-bias-aware-DA/issues"
|
|
57
|
+
|
|
58
|
+
[tool.setuptools]
|
|
59
|
+
# The src directory IS the romda package (src/__init__.py is romda/__init__.py)
|
|
60
|
+
package-dir = {"romda" = "src"}
|
|
61
|
+
packages = [
|
|
62
|
+
"romda",
|
|
63
|
+
"romda.bias_estimators",
|
|
64
|
+
"romda.estimators",
|
|
65
|
+
"romda.models",
|
|
66
|
+
"romda.models.data_driven",
|
|
67
|
+
"romda.models.data_driven.autoencoders",
|
|
68
|
+
"romda.plotting",
|
|
69
|
+
]
|
|
70
|
+
|
|
71
|
+
[tool.pytest.ini_options]
|
|
72
|
+
testpaths = ["tests"]
|
|
73
|
+
python_files = ["test_*.py", "*_test.py"]
|
|
74
|
+
python_classes = ["Test*"]
|
|
75
|
+
python_functions = ["test_*"]
|
|
76
|
+
addopts = [
|
|
77
|
+
"-v",
|
|
78
|
+
"--strict-markers",
|
|
79
|
+
]
|
|
80
|
+
|
|
81
|
+
[tool.mypy]
|
|
82
|
+
python_version = "3.14.3"
|
|
83
|
+
warn_return_any = true
|
|
84
|
+
warn_unused_configs = true
|
|
85
|
+
disallow_untyped_defs = false
|
|
86
|
+
disallow_incomplete_defs = false
|
|
87
|
+
check_untyped_defs = true
|
|
88
|
+
no_implicit_optional = true
|
|
89
|
+
warn_redundant_casts = true
|
|
90
|
+
warn_unused_ignores = true
|
|
91
|
+
|
|
92
|
+
[tool.ruff]
|
|
93
|
+
line-length = 120
|
|
94
|
+
target-version = "py39"
|
|
95
|
+
|
|
96
|
+
[tool.ruff.lint]
|
|
97
|
+
select = [
|
|
98
|
+
"E", # pycodestyle errors
|
|
99
|
+
"W", # pycodestyle warnings
|
|
100
|
+
"F", # pyflakes
|
|
101
|
+
"I", # isort
|
|
102
|
+
"N", # pep8-naming
|
|
103
|
+
"UP", # pyupgrade
|
|
104
|
+
]
|
|
105
|
+
ignore = [
|
|
106
|
+
"E501", # line too long (handled by formatter)
|
|
107
|
+
"N802", "N803", "N806", "N815", # DA notation: M, Af, Cdd, Nq, ... (see Notation in CLAUDE.md)
|
|
108
|
+
]
|