# pykoop

`pykoop`

is a Koopman operator identification library written in Python. It
allows the user to specify Koopman lifting functions and regressors in order to
learn a linear model of a given system in the lifted space.

`pykoop`

places heavy emphasis on modular lifting function construction and
`scikit-learn`

compatibility. The library aims to make it easy to
automatically find good lifting functions and regressor hyperparameters by
leveraging `scikit-learn`

’s existing cross-validation infrastructure.
`pykoop`

also gracefully handles control inputs and multi-episode datasets
at every stage of the pipeline.

`pykoop`

also includes several experimental regressors that use linear matrix
inequalities to regularize or constrain the Koopman matrix from [lmikoop]
and [sysnorm].

# Example

Consider Tikhonov-regularized EDMD with polynomial lifting functions applied to
mass-spring-damper data. Using `pykoop`

, this can be implemented as:

```
import pykoop
from sklearn.preprocessing import MaxAbsScaler, StandardScaler
# Get sample mass-spring-damper data
X_msd = pykoop.example_data_msd()
# Create pipeline
kp = pykoop.KoopmanPipeline(
lifting_functions=[
('ma', pykoop.SkLearnLiftingFn(MaxAbsScaler())),
('pl', pykoop.PolynomialLiftingFn(order=2)),
('ss', pykoop.SkLearnLiftingFn(StandardScaler())),
],
regressor=pykoop.Edmd(alpha=0.1),
)
# Fit the pipeline
kp.fit(X_msd, n_inputs=1, episode_feature=True)
# Predict using the pipeline
X_pred = kp.predict_multistep(X_msd)
# Score using the pipeline
score = kp.score(X_msd)
```

# Library layout

Most of the required classes and functions have been imported into the
`pykoop`

namespace. The most important object is the
`KoopmanPipeline`

, which requires a list of lifting functions and
a regressor.

Some example lifting functions are

`PolynomialLiftingFn`

,`DelayLiftingFn`

, and`BilinearInputLiftingFn`

.

`scikit-learn`

preprocessors can be wrapped into lifting functions using
`SkLearnLiftingFn`

. States and inputs can be lifted independently using
`SplitPipeline`

. This is useful to avoid lifting inputs.

Some basic regressors included are

`Edmd`

(includes Tikhonov regularization),`Dmdc`

, and`Dmd`

.

More advanced (and experimental) LMI-based regressors are included in the
`pykoop.lmi_regressors`

namespace. They allow for different kinds of
regularization as well as hard constraints on the Koopman operator.

You can roll your own lifting functions and regressors by inheriting from
`KoopmanLiftingFn`

, `EpisodeIndependentLiftingFn`

,
`EpisodeDependentLiftingFn`

, and `KoopmanRegressor`

.

Some sample dynamic models are also included in the `pykoop.dynamic_models`

namespace.

# Installation and testing

`pykoop`

can be installed from PyPI using

```
$ pip install pykoop
```

Additional LMI solvers can be installed using

```
$ pip install mosek
$ pip install smcp
```

Mosek is recommended, but is nonfree and requires a license.

The library can be tested using

```
$ pip install -r requirements.txt
$ pytest
```

Note that `pytest`

must be run from the repository’s root directory.

To skip slow unit tests, including all doctests and examples, run

```
$ pytest ./tests -k "not slow"
```

The documentation can be compiled using

```
$ cd doc
$ make html
```

# References

- optht
Matan Gavish and David L. Donoho. “The optimal hard threshold for singular values is 4/sqrt(3).” IEEE Transactions on Information Theory 60.8 (2014): 5040-5053. http://arxiv.org/abs/1305.5870

- dissip
Keita Hara, Masaki Inoue, and Noboru Sebe. “Learning Koopman operator under dissipativity constraints.” arXiv:1911.03884v1 [eess.SY] (2019). https://arxiv.org/abs/1911.03884v1

- lmikoop
Steven Dahdah and James Richard Forbes. “Linear matrix inequality approaches to Koopman operator approximation.” arXiv:2102.03613 [eess.SY] (2021). https://arxiv.org/abs/2102.03613

- sysnorm
Steven Dahdah and James Richard Forbes. “System norm regularization methods for Koopman operator approximation.” arXiv:2110.09658 [eess.SY] (2021). https://arxiv.org/abs/2110.09658

- bilinear
Daniel Bruder, Xun Fu, and Ram Vasudevan. “Advantages of bilinear Koopman realizations for the modeling and control of systems with unknown dynamics.” arXiv:2010.09961v3 [cs.RO] (2020). https://arxiv.org/abs/2010.09961v3

# Citation

If you use this software in your research, please cite it as below or see
`CITATION.cff`

.

```
@software{dahdah_pykoop_2021,
title={{decarsg/pykoop}},
doi={10.5281/zenodo.5576490},
url={https://github.com/decarsg/pykoop},
publisher={Zenodo},
author={Steven Dahdah and James Richard Forbes},
year={2021},
}
```

# License

This project is distributed under the MIT License, except the contents of
`./pykoop/_sklearn_metaestimators/`

, which are from the scikit-learn
project, and are distributed under the BSD-3-Clause License.