{"id":21716448,"url":"https://github.com/decargroup/pykoop","last_synced_at":"2025-04-05T20:03:42.800Z","repository":{"id":37956246,"uuid":"392435742","full_name":"decargroup/pykoop","owner":"decargroup","description":"Koopman operator identification library in Python, compatible with `scikit-learn`","archived":false,"fork":false,"pushed_at":"2024-11-20T20:21:53.000Z","size":55878,"stargazers_count":70,"open_issues_count":7,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T19:01:41.835Z","etag":null,"topics":["control","dynamical-systems","koopman","machine-learning","scikit-learn"],"latest_commit_sha":null,"homepage":"https://pykoop.readthedocs.io/en/stable/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/decargroup.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-03T19:42:38.000Z","updated_at":"2025-03-23T21:12:26.000Z","dependencies_parsed_at":"2025-01-07T02:44:17.210Z","dependency_job_id":"a0509df3-1806-48fa-b63f-7ac66ceb60aa","html_url":"https://github.com/decargroup/pykoop","commit_stats":{"total_commits":604,"total_committers":2,"mean_commits":302.0,"dds":0.008278145695364225,"last_synced_commit":"25c42a8dc8652d993398e2e099cedda14129f365"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decargroup%2Fpykoop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decargroup%2Fpykoop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decargroup%2Fpykoop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decargroup%2Fpykoop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/decargroup","download_url":"https://codeload.github.com/decargroup/pykoop/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247393552,"owners_count":20931811,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["control","dynamical-systems","koopman","machine-learning","scikit-learn"],"created_at":"2024-11-26T01:11:10.810Z","updated_at":"2025-04-05T20:03:42.764Z","avatar_url":"https://github.com/decargroup.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. role:: class(code)\n\npykoop\n======\n\n.. image:: https://github.com/decargroup/pykoop/actions/workflows/test-package.yml/badge.svg\n    :target: https://github.com/decargroup/pykoop/actions/workflows/test-package.yml\n    :alt: Test package\n.. image:: https://readthedocs.org/projects/pykoop/badge/?version=stable\n    :target: https://pykoop.readthedocs.io/en/stable/?badge=stable\n    :alt: Documentation status\n.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.5576490.svg\n    :target: https://doi.org/10.5281/zenodo.5576490\n    :alt: DOI\n.. image:: https://mybinder.org/badge_logo.svg\n    :target: https://mybinder.org/v2/gh/decargroup/pykoop/main?labpath=notebooks%2F1_example_pipeline_simple.ipynb\n    :alt: Examples on binder\n\n``pykoop`` is a Koopman operator identification library written in Python. It\nallows the user to specify Koopman lifting functions and regressors in order to\nlearn a linear model of a given system in the lifted space.\n\n.. image:: https://raw.githubusercontent.com/decargroup/pykoop/main/doc/_static/pykoop_diagram.png\n   :alt: Koopman pipeline diagram\n\nTo learn more about Koopman operator theory, check out\n`this talk \u003chttps://www.youtube.com/watch?v=Lidd_M7gzvA\u003e`_\nor\n`this review article \u003chttps://arxiv.org/abs/2102.12086\u003e`_.\n\n\n``pykoop`` places heavy emphasis on modular lifting function construction and\n``scikit-learn`` compatibility. The library aims to make it easy to\nautomatically find good lifting functions and regressor hyperparameters by\nleveraging ``scikit-learn``'s existing cross-validation infrastructure.\n``pykoop`` also gracefully handles control inputs and multi-episode datasets\nat every stage of the pipeline.\n\n``pykoop`` also includes several experimental regressors that use linear matrix\ninequalities to constraint the asymptotic stability of the Koopman system, or\nregularize the regression using its H-infinity norm. Check out\n`arXiv:2110.09658 [eess.SY] \u003chttps://arxiv.org/abs/2110.09658\u003e`_ and\n`arXiv:2102.03613 [eess.SY] \u003chttps://arxiv.org/abs/2102.03613\u003e`_ for details.\n\n\nExample\n=======\n\nConsider Tikhonov-regularized EDMD with polynomial lifting functions applied to\nmass-spring-damper data. Using ``pykoop``, this can be implemented as:\n\n.. code-block:: python\n\n    import pykoop\n    from sklearn.preprocessing import MaxAbsScaler, StandardScaler\n\n    # Get example mass-spring-damper data\n    eg = pykoop.example_data_msd()\n\n    # Create pipeline\n    kp = pykoop.KoopmanPipeline(\n        lifting_functions=[\n            ('ma', pykoop.SkLearnLiftingFn(MaxAbsScaler())),\n            ('pl', pykoop.PolynomialLiftingFn(order=2)),\n            ('ss', pykoop.SkLearnLiftingFn(StandardScaler())),\n        ],\n        regressor=pykoop.Edmd(alpha=1),\n    )\n\n    # Fit the pipeline\n    kp.fit(\n        eg['X_train'],\n        n_inputs=eg['n_inputs'],\n        episode_feature=eg['episode_feature'],\n    )\n\n    # Predict using the pipeline\n    X_pred = kp.predict_trajectory(eg['x0_valid'], eg['u_valid'])\n\n    # Score using the pipeline\n    score = kp.score(eg['X_valid'])\n\n    # Plot results\n    kp.plot_predicted_trajectory(eg['X_valid'], plot_input=True)\n\nMore examples are available in ``examples/``, in ``notebooks/``, or on\n`binder \u003chttps://mybinder.org/v2/gh/decargroup/pykoop/main?labpath=notebooks%2F1_example_pipeline_simple.ipynb\u003e`_.\n\n\nLibrary layout\n==============\n\nMost of the required classes and functions have been imported into the\n``pykoop`` namespace. The most important object is the\n:class:`pykoop.KoopmanPipeline`, which requires a list of lifting functions and\na regressor.\n\nSome example lifting functions are\n\n- :class:`pykoop.PolynomialLiftingFn`,\n- :class:`pykoop.RbfLiftingFn`,\n- :class:`pykoop.DelayLiftingFn`, and\n- :class:`pykoop.BilinearInputLiftingFn`.\n\n``scikit-learn`` preprocessors can be wrapped into lifting functions using\n:class:`pykoop.SkLearnLiftingFn`. States and inputs can be lifted independently\nusing :class:`pykoop.SplitPipeline`. This is useful to avoid lifting inputs.\n\nSome basic regressors included are\n\n- :class:`pykoop.Edmd` (includes Tikhonov regularization),\n- :class:`pykoop.Dmdc`, and\n- :class:`pykoop.Dmd`.\n\nMore advanced (and experimental) LMI-based regressors are included in the\n``pykoop.lmi_regressors`` namespace. They allow for different kinds of\nregularization as well as hard constraints on the Koopman operator.\n\nYou can roll your own lifting functions and regressors by inheriting from\n:class:`pykoop.KoopmanLiftingFn`, :class:`pykoop.EpisodeIndependentLiftingFn`,\n:class:`pykoop.EpisodeDependentLiftingFn`, and\n:class:`pykoop.KoopmanRegressor`.\n\nSome sample dynamic models are also included in the ``pykoop.dynamic_models``\nnamespace.\n\n\nInstallation and testing\n========================\n\n``pykoop`` can be installed from PyPI using\n\n.. code-block:: sh\n\n    $ pip install pykoop\n\nAdditional LMI solvers can be installed using\n\n.. code-block:: sh\n\n    $ pip install mosek\n    $ pip install cvxopt\n    $ pip install smcp\n\nMosek is recommended, but is nonfree and requires a license.\n\nThe library can be tested using\n\n.. code-block:: sh\n\n    $ pip install -r requirements-dev.txt\n    $ pytest\n\nNote that ``pytest`` must be run from the repository's root directory.\n\nTo skip unit tests that require a MOSEK license, including all doctests and\nexamples, run\n\n.. code-block:: sh\n\n    $ pytest ./tests -k \"not mosek\"\n\nThe documentation can be compiled using\n\n.. code-block:: sh\n\n    $ cd doc\n    $ make html\n\nIf you want a hook to check source code formatting before allowing a commit,\nyou can use\n\n.. code-block:: sh\n\n   $ cd .git/hooks/\n   $ ln -s ../../.githooks/pre-commit .\n   $ chmod +x ./pre-commit\n\nYou will need ``yapf`` installed for this.\n\n\nRelated packages\n================\n\nOther excellent Python packages for learning dynamical systems exist,\nsummarized in the table below:\n\n============ ==================================================================\nLibrary      Unique features\n============ ==================================================================\n`pykoop`_    - Modular lifting functions\n             - Full ``scikit-learn`` compatibility\n             - Built-in regularization\n             - Multi-episode datasets\n`pykoopman`_ - Continuous-time Koopman operator identification\n             - Built-in numerical differentiation\n             - Detailed DMD outputs\n             - DMDc with known control matrix\n`PyDMD`_     - Extensive library containing pretty much every variant of DMD\n`PySINDy`_   - Python implementation of the famous SINDy method\n             - Related to, but not the same as, Koopman operator approximation\n============ ==================================================================\n\n.. _pykoop: https://github.com/decargroup/pykoop\n.. _pykoopman: https://github.com/dynamicslab/pykoopman\n.. _PyDMD: https://github.com/mathLab/PyDMD\n.. _PySINDy: https://github.com/dynamicslab/pysindy\n\n\nCitation\n========\n\nIf you use this software in your research, please cite it as below or see\n``CITATION.cff``.\n\n.. code-block:: bibtex\n\n    @software{dahdah_pykoop_2024,\n        title={{decargroup/pykoop}},\n        doi={10.5281/zenodo.5576490},\n        url={https://github.com/decargroup/pykoop},\n        publisher={Zenodo},\n        author={Steven Dahdah and James Richard Forbes},\n        version = {{v2.0.2}},\n        year={2024},\n    }\n\n\nLicense\n=======\n\nThis project is distributed under the MIT License, except the contents of\n``pykoop/_sklearn_metaestimators/``, which are from the `scikit-learn`_\nproject, and are distributed under the BSD-3-Clause License.\n\n.. _scikit-learn: https://github.com/scikit-learn/scikit-learn\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecargroup%2Fpykoop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdecargroup%2Fpykoop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecargroup%2Fpykoop/lists"}