How dynamicslab/pykoopman works
Project type and purpose
• PyKoopman is an open-source Python library (full-stack backend tool) for data-driven approximation of the Koopman operator.
• It provides a scikit-learn-style API (Koopman and KoopmanContinuous classes) that users instantiate, fit to data, and query for linearized models of nonlinear dynamical systems.
File structure
Top-level directories and files:
• src/pykoopman/… – core implementation
– analytics – post-fit analytics and metrics
– common – shared helper functions and example systems
– differentiation – methods for computing time derivatives
– observables – library of lifting functions (Identity, Polynomial, etc.)
– regression – regression algorithms (DMD, EDMD, KDMD, HAVOK, NNDMD)
– koopman.py, koopman_continuous.py – high-level API classes
• docs/… – documentation source and JOSS paper assets
• test/… – unit tests for each submodule
• .github/workflows/… – CI for tests, release, PDF generation
• setup.cfg, pyproject.toml, requirements*.txt – build, packaging, and dependency specs
README for additional insights
• Two primary components:
a. observables – span the lifted (feature) space
b. regressor – fit a finite-dimensional approximation of the Koopman operator
• Core API: instantiate a Koopman/KoopmanContinuous object, call .fit(), then analyze or predict.
Main components and their relationships
[User Code]
→ imports PyKoopman API
→ creates Koopman or KoopmanContinuous instance
[Koopman API]
• Configuration: references one or more Observables and a Regressor
• .fit(X, Y, U) calls into:
– Differentiation (optional) to compute ΔX or continuous derivatives
– Observables to lift state X → Z
– Regression to solve for operator K or Kc (lifting-space transition matrix)
– Analytics (optional) to compute metrics, mode decompositions, sparsity, etc.
[Outputs]
→ Transition matrices K, Koopman modes, predicted trajectories
External services & tooling:
• GitHub Actions – CI (run-tests.yml), release pipelines
• Read the Docs – documentation builds
• Codecov – test coverage reporting
• PyPI – package distribution
Architectural patterns and design principles
• Modular layering:
1. Core API layer (koopman.py)
2. Feature engineering layer (observables + differentiation)
3. Estimation layer (regression algorithms)
4. Analysis layer
• Strategy pattern: users can swap in different Observable or Regressor implementations at runtime.
• scikit-learn compatibility: fit/predict API, pipeline-style composition.