Package: pykoop
pykooppykoopis 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.To learn more about Koopman operator theory, check outthis talkorthis review article.pykoopplaces heavy emphasis on modular lifting function construction andscikit-learncompatibility. The library aims to make it easy to
automatically find good lifting functions and regressor hyperparameters by
leveragingscikit-learn’s existing cross-validation infrastructure.pykoopalso gracefully handles control inputs and multi-episode datasets
at every stage of the pipeline.pykoopalso includes several experimental regressors that use linear matrix
inequalities to constraint the asymptotic stability of the Koopman system, or
regularize the regression using its H-infinity norm. Check outarXiv:2110.09658 [eess.SY]andarXiv:2102.03613 [eess.SY]for details.ExampleConsider Tikhonov-regularized EDMD with polynomial lifting functions applied to
mass-spring-damper data. Usingpykoop, this can be implemented as:importpykoopfromsklearn.preprocessingimportMaxAbsScaler,StandardScaler# Get example mass-spring-damper dataeg=pykoop.example_data_msd()# Create pipelinekp=pykoop.KoopmanPipeline(lifting_functions=[('ma',pykoop.SkLearnLiftingFn(MaxAbsScaler())),('pl',pykoop.PolynomialLiftingFn(order=2)),('ss',pykoop.SkLearnLiftingFn(StandardScaler())),],regressor=pykoop.Edmd(alpha=1),)# Fit the pipelinekp.fit(eg['X_train'],n_inputs=eg['n_inputs'],episode_feature=eg['episode_feature'],)# Predict using the pipelineX_pred=kp.predict_trajectory(eg['x0_valid'],eg['u_valid'])# Score using the pipelinescore=kp.score(eg['X_valid'])# Plot resultskp.plot_predicted_trajectory(eg['X_valid'],plot_input=True)More examples are available inexamples/, innotebooks/, or onbinder.Library layoutMost of the required classes and functions have been imported into thepykoopnamespace. The most important object is thepykoop.KoopmanPipeline, which requires a list of lifting functions and
a regressor.Some example lifting functions arepykoop.PolynomialLiftingFn,pykoop.RbfLiftingFn,pykoop.DelayLiftingFn, andpykoop.BilinearInputLiftingFn.scikit-learnpreprocessors can be wrapped into lifting functions usingpykoop.SkLearnLiftingFn. States and inputs can be lifted independently
usingpykoop.SplitPipeline. This is useful to avoid lifting inputs.Some basic regressors included arepykoop.Edmd(includes Tikhonov regularization),pykoop.Dmdc, andpykoop.Dmd.More advanced (and experimental) LMI-based regressors are included in thepykoop.lmi_regressorsnamespace. 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 frompykoop.KoopmanLiftingFn,pykoop.EpisodeIndependentLiftingFn,pykoop.EpisodeDependentLiftingFn, andpykoop.KoopmanRegressor.Some sample dynamic models are also included in thepykoop.dynamic_modelsnamespace.Installation and testingpykoopcan be installed from PyPI using$pipinstallpykoopAdditional LMI solvers can be installed using$pipinstallmosek$pipinstallcvxopt$pipinstallsmcpMosek is recommended, but is nonfree and requires a license.The library can be tested using$pipinstall-rrequirements-dev.txt$pytestNote thatpytestmust be run from the repository’s root directory.To skip unit tests that require a MOSEK license, including all doctests and
examples, run$pytest./tests-k"not mosek"The documentation can be compiled using$cddoc$makehtmlIf you want a hook to check source code formatting before allowing a commit,
you can use$cd.git/hooks/$ln-s../../.githooks/pre-commit.$chmod+x./pre-commitYou will needyapfinstalled for this.Related packagesOther excellent Python packages for learning dynamical systems exist,
summarized in the table below:LibraryUnique featurespykoopModular lifting functionsFullscikit-learncompatibilityBuilt-in regularizationMulti-episode datasetspykoopmanContinuous-time Koopman operator identificationBuilt-in numerical differentiationDetailed DMD outputsDMDc with known control matrixPyDMDExtensive library containing pretty much every variant of DMDPySINDyPython implementation of the famous SINDy methodRelated to, but not the same as, Koopman operator approximationCitationIf you use this software in your research, please cite it as below or seeCITATION.cff.@software{dahdah_pykoop_2022,title={{decargroup/pykoop}},doi={10.5281/zenodo.5576490},url={https://github.com/decargroup/pykoop},publisher={Zenodo},author={Steven Dahdah and James Richard Forbes},version={{v1.2.3}},year={2022},}LicenseThis project is distributed under the MIT License, except the contents ofpykoop/_sklearn_metaestimators/, which are from thescikit-learnproject, and are distributed under the BSD-3-Clause License.