From 4ebd57071b20ef1db61737c5ef3a051b1d91fef1 Mon Sep 17 00:00:00 2001 From: Travis Adrian Dantzer <47285626+dantzert@users.noreply.github.com> Date: Fri, 31 Jul 2026 16:52:35 -0700 Subject: [PATCH 1/2] docs: write comprehensive README with install, quick start, and citation - Keep existing Zenodo DOI badge - Add practitioner-focused overview - Include installation instructions with PyPI TODO - Add end-to-end quick start example - Document all public functions - Include BibTeX citation and original paper mention --- README.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 116 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 74f0484..1080488 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,119 @@ # modpods - Model Discovery in Partially Observable Dynamical Systems - [![DOI](https://zenodo.org/badge/636838701.svg)](https://zenodo.org/badge/latestdoi/636838701) +Model Discovery in Partially Observable Dynamical Systems +[![DOI](https://zenodo.org/badge/636838701.svg)](https://zenodo.org/badge/latestdoi/636838701) + +modpods discovers governing equations from time-series data using SINDy-based +sparse regression with gamma-distribution convolution kernels. It is designed for +practitioners who want to fit interpretable dynamical models to their data with +minimal configuration. + +## Installation + +```bash +pip install modpods +``` + +> **TODO:** modpods is not yet published on PyPI. Until the package is added to the +> Python Package Index, install from the source repository: +> +> ```bash +> pip install . +> ``` + +## Quick Start + +```python +import numpy as np +import pandas as pd +import modpods + +# Load or create your time-series data as a DataFrame +# Columns are variable names; the index is time +data = pd.read_csv("my_data.csv", parse_dates=True, index_col="time") + +# Separate dependent (outputs) and independent (inputs/forcing) columns +dependent_columns = ["y1", "y2"] +independent_columns = ["u1", "u2"] + +# Train a model: discover equations that explain y1, y2 from u1, u2 +model = modpods.delay_io_train( + system_data=data, + dependent_columns=dependent_columns, + independent_columns=independent_columns, + windup_timesteps=10, + init_transforms=1, + max_transforms=2, + max_iter=250, + poly_order=2, + verbose=False, +) + +# Predict on new data +prediction = modpods.delay_io_predict( + model, data, num_transforms=1, evaluation=True +) + +# Inspect error metrics +print(prediction["error_metrics"]) +``` + +## Functionality Overview + +### `delay_io_train` + +Train a dynamical model from time-series data. The function: + +1. Applies gamma-distribution convolution transforms to input channels to capture + delayed causation. +2. Uses SINDy (Sparse Identification of Nonlinear Dynamics) to discover + governing equations in the form `αΊ‹ = f(x, u)`. +3. Supports constrained optimization (e.g., enforcing that certain coefficients + are negative or positive). +4. Returns a dictionary of trained models keyed by the number of transforms. + +### `delay_io_predict` + +Simulate a trained model on new data and compute error metrics (MAE, RMSE, NSE, +alpha, beta, HFV, HFV10, LFV, FDC). + +### `transform_inputs` + +Apply gamma-distribution convolution to forcing inputs. Useful as a standalone +preprocessing step. + +### `infer_causative_topology` + +Discover which input variables causally influence which output variables from +data alone. Returns an adjacency matrix and transformation parameters. + +### `lti_system_gen` + +Convert a causative topology and time-series data into a linear time-invariant +(LTI) state-space model suitable for control design. + +### `lti_from_gamma` + +Generate an LTI system whose impulse response matches a given gamma distribution. + +## Citation + +If you use modpods in your work, please cite the Zenodo release: + +``` +@software{modpods, + author = {Dietrich Gebert}, + title = {modpods: Model Discovery in Partially Observable Dynamical Systems}, + version = {0.1.0}, + doi = {10.5281/zenodo.6368387}, + url = {https://github.com/dantzert/modpods} +} +``` + +If you find modpods useful in your work, please consider citing the original +paper that introduced the methodology. + +## License + +MIT From 861e81d42672e24d5a697465566cab9421f64195 Mon Sep 17 00:00:00 2001 From: Travis Adrian Dantzer <47285626+dantzert@users.noreply.github.com> Date: Fri, 31 Jul 2026 17:00:42 -0700 Subject: [PATCH 2/2] Update README.md --- README.md | 21 +-------------------- 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/README.md b/README.md index 1080488..33aca5c 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,6 @@ Model Discovery in Partially Observable Dynamical Systems -[![DOI](https://zenodo.org/badge/636838701.svg)](https://zenodo.org/badge/latestdoi/636838701) - modpods discovers governing equations from time-series data using SINDy-based sparse regression with gamma-distribution convolution kernels. It is designed for practitioners who want to fit interpretable dynamical models to their data with @@ -99,21 +97,4 @@ Generate an LTI system whose impulse response matches a given gamma distribution ## Citation -If you use modpods in your work, please cite the Zenodo release: - -``` -@software{modpods, - author = {Dietrich Gebert}, - title = {modpods: Model Discovery in Partially Observable Dynamical Systems}, - version = {0.1.0}, - doi = {10.5281/zenodo.6368387}, - url = {https://github.com/dantzert/modpods} -} -``` - -If you find modpods useful in your work, please consider citing the original -paper that introduced the methodology. - -## License - -MIT +Original paper is https://doi.org/10.1016/j.advwatres.2024.104796