Skip to content

Commit 7e12c70

Browse files
EthanJamesLewEthanJamesLew
authored
Merge pull request #57 from EthanJamesLew/develop
Version 0.30
2 parents f70a5d3 + a36a1a5 commit 7e12c70

28 files changed

+1365
-95
lines changed

‎.gitattributes

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
autokoopman/_version.py export-subst

‎.github/workflows/documentation.yml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Sphinx Build
2+
on: [push, pull_request, workflow_dispatch]
3+
jobs:
4+
docs:
5+
runs-on: ubuntu-latest
6+
steps:
7+
- uses: actions/checkout@v2
8+
- uses: actions/setup-python@v2
9+
- name: Install dependencies
10+
run: |
11+
pip install sphinx sphinx_rtd_theme sphinx_mdinclude pip install pydata-sphinx-theme
12+
pip install pydmd
13+
pip install .
14+
- name: Sphinx build
15+
run: |
16+
sphinx-build documentation/sphinx/source _build
17+
- name: Deploy
18+
uses: peaceiris/actions-gh-pages@v3
19+
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/develop' }}
20+
with:
21+
publish_branch: gh-pages
22+
github_token: ${{ secrets.GITHUB_TOKEN }}
23+
publish_dir: _build/
24+
force_orphan: true

‎.github/workflows/notebook.yml

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Jupyter Notebooks
2+
3+
on: [push]
4+
5+
jobs:
6+
build-linux:
7+
runs-on: ubuntu-latest
8+
strategy:
9+
max-parallel: 5
10+
11+
steps:
12+
- uses: actions/checkout@v2
13+
- name: Set up Python 3.9
14+
uses: actions/setup-python@v2
15+
with:
16+
python-version: 3.9
17+
- name: Add conda to system path
18+
run: |
19+
# $CONDA is an environment variable pointing to the root of the miniconda directory
20+
echo $CONDA/bin >> $GITHUB_PATH
21+
- name: Install dependencies
22+
run: |
23+
conda env update --file environment.yml --name base
24+
- name: Test with pytest
25+
run: |
26+
pip install .
27+
conda install pytest
28+
pip install nbmake==0.5
29+
pytest --nbmake "./notebooks/"
30+
pytest
31+

‎.github/workflows/publish.yml

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Publish AutoKoopman
2+
3+
on: [push]
4+
5+
jobs:
6+
publish-whl:
7+
runs-on: ubuntu-latest
8+
strategy:
9+
max-parallel: 5
10+
11+
steps:
12+
- uses: actions/checkout@v2
13+
- name: Set up Python 3.9
14+
uses: actions/setup-python@v2
15+
with:
16+
python-version: 3.9
17+
- name: Add conda to system path
18+
run: |
19+
# $CONDA is an environment variable pointing to the root of the miniconda directory
20+
echo $CONDA/bin >> $GITHUB_PATH
21+
- name: Prepare build requirements
22+
run: >-
23+
python -m
24+
pip install
25+
build
26+
--user
27+
- name: Build a binary wheel and a source tarball
28+
run: >-
29+
python -m
30+
build
31+
--sdist
32+
--wheel
33+
--outdir dist/
34+
.
35+
- name: Publish distribution 📦 to Test PyPI
36+
if: startsWith(github.ref, 'refs/tags')
37+
uses: pypa/gh-action-pypi-publish@release/v1
38+
with:
39+
password: ${{ secrets.TEST_PYPI_API_TOKEN }}
40+
repository_url: https://test.pypi.org/legacy/
41+
- name: Publish distribution 📦 to PyPI
42+
if: startsWith(github.ref, 'refs/tags')
43+
uses: pypa/gh-action-pypi-publish@release/v1
44+
with:
45+
password: ${{ secrets.PYPI_API_TOKEN }}

‎.lift/config.toml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
ignoreFiles = '''
2+
autokoopman/_version.py
3+
'''

‎README.md

Lines changed: 60 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,47 @@
1-
# AutoKoopman
1+
[![PyPI version](https://badge.fury.io/py/AutoKoopman.svg)](https://pypi.org/project/autokoopman/)
2+
[![license](https://img.shields.io/github/license/EthanJamesLew/AutoKoopman)](LICENSE)
3+
[![Conda CI Workflow](https://github.com/EthanJamesLew/AutoKoopman/actions/workflows/python-package-conda.yml/badge.svg)](https://github.com/EthanJamesLew/AutoKoopman/actions/workflows/python-package-conda.yml)
4+
[![Sphinx Workflow](https://github.com/EthanJamesLew/AutoKoopman/actions/workflows/documentation.yml/badge.svg)](https://github.com/EthanJamesLew/AutoKoopman/actions/workflows/documentation.yml)
5+
[![Jupyter Workflow](https://github.com/EthanJamesLew/AutoKoopman/actions/workflows/notebook.yml/badge.svg)](https://github.com/EthanJamesLew/AutoKoopman/actions/workflows/notebook.yml)
6+
7+
![](https://raw.githubusercontent.com/EthanJamesLew/AutoKoopman/enhancement/v-0.30-tweaks/documentation/img/brand/logo-full.svg)
28

3-
![Conda CI Workflow](https://github.com/EthanJamesLew/AutoKoopman/actions/workflows/python-package-conda.yml/badge.svg)
9+
# AutoKoopman
410

511
## Overview
6-
AutoKoopman is a python library for the use of Koopman operator methods for data-driven dynamical systems analysis and control. The library
7-
has convenient functions to learn systems using a few lines of code. It has a variety of linearization methods under
8-
shared class interfaces. These methods are pluggable into hyperparameter optimizers which can automate the process of model
9-
optimization.
12+
13+
AutoKoopman is a high-level system identification tool that automatically optimizes all hyper-parameters to estimate accurate system models with globally linearized representations. Implemented as a python library under shared class interfaces, AutoKoopman uses a collection of Koopman-based algorithms centered on conventional dynamic mode decomposition and deep learning. Koopman theory relies on embedding system states to *observables*; AutoKoopman provides major types of static observables.
14+
15+
The library supports
16+
* Discrete-Time and Continuous-Time System Identification
17+
* Extended Dynamic Mode Decomposition (EDMD) [[Williams et al.]](#1)
18+
* Deep Koopman [[Li et al.]](#2)
19+
* SINDy [[Brunton et al.]](#3)
20+
* Static Observables
21+
* Random Fourier Features [[Bak et al.]](#4)
22+
* Polynomial
23+
* Neural Network [[Li et al.]](#2)
24+
* System Identification with Input and Control
25+
* Koopman with Input and Control (KIC) [[Proctor et al.]](#5)
26+
* Online (Streaming) System Identification
27+
* Online DMD [[Zhang et al.]](#6)
28+
* Hyperparameter Optimization
29+
* Random Search
30+
* Grid Search
31+
* Bayesian Optimization
1032

1133
## Use Cases
12-
A systems engineer / researcher who wishes to leverage data-driven dynamical systems techniques. The user may
13-
have measurements of their system with no prior model.
14-
* System Prediction - the user can simulate a model learned from their measurements. They use popular techniques like DMD and SINDy out of the box, and implement their own methods to plug into the provided analysis infrastructure (e.g. hyperparameter optimization, visualization).
15-
* System Linearization - the user can get a linear representation of their system in its original states or koopman observables. They can use this linear form to perform tasks like controller synthesis and system reachability.
34+
The library is intended for a systems engineer / researcher who wishes to leverage data-driven dynamical systems techniques. The user may have measurements of their system with no prior model.
35+
36+
* **Prediction:** Predict the evolution of a system over long time horizons
37+
* **Control:** Synthesize control signals that achieve desired closed-loop behaviors and are optimal with respect to some objective.
38+
* **Verification:** Prove or falsify the safety requirements of a system.
1639

1740
## Installation
1841

19-
The module requires python 3.8 or higher. With pip installed, run
42+
The module is published on [PyPI](https://pypi.org/project/autokoopman/). It requires python 3.8 or higher. With pip installed, run
2043
```shell
21-
pip install .
44+
pip install autokoopman
2245
```
2346
at the repo root. Run
2447
```shell
@@ -28,7 +51,7 @@ to ensure that the module can be imported.
2851

2952
## Examples
3053

31-
### Complete Example
54+
### A Complete Example
3255
AutoKoopman has a convenience function `auto_koopman` that can learn dynamical systems from data in one call, given
3356
training data of trajectories (list of arrays),
3457
```python
@@ -38,6 +61,8 @@ import numpy as np
3861
# this is the convenience function
3962
from autokoopman import auto_koopman
4063

64+
np.random.seed(20)
65+
4166
# for a complete example, let's create an example dataset using an included benchmark system
4267
import autokoopman.benchmark.fhn as fhn
4368
fhn = fhn.FitzHughNagumo()
@@ -83,7 +108,28 @@ plt.plot(*trajectory.states.T)
83108
plt.plot(*true_trajectory.states.T)
84109
```
85110

111+
## Architecture
112+
113+
The library architecture has a modular design, allowing users to implement custom modules and plug them into the learning pipeline with ease.
114+
115+
![Library Architecture](https://github.com/EthanJamesLew/AutoKoopman/raw/enhancement/v-0.30-tweaks/documentation/img/autokoopman_objects.png)
116+
*AutoKoopman Class Structure in the Training Pipeline*. A user can implement any of the classes to extend AutoKoopman (e.g., custom observables, a custom tuner, a new system id estimator).
86117

87118
## Documentation
88119

89-
[AutoKoopman Documentation](https://ethanjameslew.github.io/AutoKoopman/)
120+
See the
121+
[AutoKoopman Documentation](https://ethanjameslew.github.io/AutoKoopman/).
122+
123+
## References
124+
125+
<a id="1">[1]</a> Williams, M. O., Kevrekidis, I. G., & Rowley, C. W. (2015). A data–driven approximation of the koopman operator: Extending dynamic mode decomposition. Journal of Nonlinear Science, 25, 1307-1346.
126+
127+
<a id="2">[2]</a> Li, Y., He, H., Wu, J., Katabi, D., & Torralba, A. (2019). Learning compositional koopman operators for model-based control. arXiv preprint arXiv:1910.08264.
128+
129+
<a id="3">[3]</a> Brunton, S. L., Proctor, J. L., & Kutz, J. N. (2016). Discovering governing equations from data by sparse identification of nonlinear dynamical systems. Proceedings of the national academy of sciences, 113(15), 3932-3937.
130+
131+
<a id="4">[4]</a> Bak, S., Bogomolov, S., Hencey, B., Kochdumper, N., Lew, E., & Potomkin, K. (2022, August). Reachability of Koopman linearized systems using random fourier feature observables and polynomial zonotope refinement. In Computer Aided Verification: 34th International Conference, CAV 2022, Haifa, Israel, August 7–10, 2022, Proceedings, Part I (pp. 490-510). Cham: Springer International Publishing.
132+
133+
<a id="5">[5]</a> Proctor, J. L., Brunton, S. L., & Kutz, J. N. (2018). Generalizing Koopman theory to allow for inputs and control. SIAM Journal on Applied Dynamical Systems, 17(1), 909-930.
134+
135+
<a id="6">[6]</a> Zhang, H., Rowley, C. W., Deem, E. A., & Cattafesta, L. N. (2019). Online dynamic mode decomposition for time-varying systems. SIAM Journal on Applied Dynamical Systems, 18(3), 1586-1609.

‎autokoopman/__init__.py

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,26 @@
11
# TODO: update this
22
__author__ = "Ethan Lew"
33
__copyright__ = "Copyright 2023"
4-
__credits__ = ["Ethan Lew", "Abdelrahman Hekal", "Kostiantyn Potomkin", "Niklas Kochdumper", "Brandon Hencey", "Stanley Bak", "Sergiy Bogomolov"]
4+
__credits__ = [
5+
"Ethan Lew",
6+
"Abdelrahman Hekal",
7+
"Kostiantyn Potomkin",
8+
"Niklas Kochdumper",
9+
"Brandon Hencey",
10+
"Stanley Bak",
11+
"Sergiy Bogomolov",
12+
]
513
__license__ = "GPLv3"
6-
__version__ = "0.21"
714
__maintainer__ = "Ethan Lew"
815
__email__ = "ethanlew16@gmail.com"
916
__status__ = "Prototype"
1017

18+
# we auto-manage versions
19+
from ._version import get_versions
20+
21+
__version__ = get_versions()["version"]
22+
del get_versions
23+
1124
from autokoopman.autokoopman import auto_koopman
1225

1326
from autokoopman.core.system import (
@@ -22,3 +35,7 @@
2235
UniformTimeTrajectoriesData,
2336
UniformTimeTrajectory,
2437
)
38+
39+
from . import _version
40+
41+
__version__ = _version.get_versions()["version"]

0 commit comments

Comments
 (0)