# dynamicslab/pykoopman architecture

> Architecture diagram of the GitHub repository dynamicslab/pykoopman, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dynamicslab/pykoopman
- Repository: https://github.com/dynamicslab/pykoopman

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and Components
    User["User Application"]:::external

    subgraph "Core API Layer"
        Koopman["Koopman Class"]:::coreapi
        KoopmanCont["KoopmanContinuous Class"]:::coreapi
    end

    subgraph "Feature Engineering Layer"
        Differentiation["Differentiation Module"]:::feature
        Observables["Observables Module"]:::feature
    end

    subgraph "Estimation Layer"
        Regression["Regression Module"]:::estimation
    end

    subgraph "Analysis Layer"
        Analytics["Analytics Module (optional)"]:::analysis
    end

    subgraph "Support Modules"
        Common["Common Helpers Module"]:::feature
        Tests["Testing Suite"]:::tooling
    end

    Output["Output Artifacts"]:::external

    subgraph "External Tooling & CI/CD"
        CI["GitHub Actions CI/CD"]:::tooling
        Docs["Documentation (ReadTheDocs)"]:::tooling
        PyPI["PyPI Distribution"]:::tooling
    end

    %% Data and Control Flow
    User -->|"instantiate & fit"| Koopman
    User -->|"instantiate & fit"| KoopmanCont
    Koopman -->|"compute derivatives"| Differentiation
    KoopmanCont -->|"compute derivatives"| Differentiation
    Koopman -->|"lift data"| Observables
    KoopmanCont -->|"lift data"| Observables
    Koopman -->|"estimate operator"| Regression
    KoopmanCont -->|"estimate operator"| Regression
    Koopman -.->|"compute diagnostics"| Analytics
    KoopmanCont -.->|"compute diagnostics"| Analytics
    Koopman -->|"return models & predictions"| Output
    KoopmanCont -->|"return models & predictions"| Output

    Common -->|used by| Differentiation
    Common -->|used by| Observables
    Common -->|used by| Regression
    Common -->|used by| Analytics

    Differentiation -->|tested by| Tests
    Observables -->|tested by| Tests
    Regression -->|tested by| Tests
    Analytics -->|tested by| Tests
    Koopman -->|tested by| Tests
    KoopmanCont -->|tested by| Tests

    CI -->|"runs tests"| Tests
    CI -->|"builds docs"| Docs
    CI -->|"publishes package"| PyPI

    %% Click Events
    click Koopman "https://github.com/dynamicslab/pykoopman/blob/master/src/pykoopman/koopman.py"
    click KoopmanCont "https://github.com/dynamicslab/pykoopman/blob/master/src/pykoopman/koopman_continuous.py"
    click Differentiation "https://github.com/dynamicslab/pykoopman/tree/master/src/pykoopman/differentiation/"
    click Observables "https://github.com/dynamicslab/pykoopman/tree/master/src/pykoopman/observables/"
    click Regression "https://github.com/dynamicslab/pykoopman/tree/master/src/pykoopman/regression/"
    click Analytics "https://github.com/dynamicslab/pykoopman/tree/master/src/pykoopman/analytics/"
    click Common "https://github.com/dynamicslab/pykoopman/tree/master/src/pykoopman/common/"
    click Tests "https://github.com/dynamicslab/pykoopman/tree/master/test/"
    click Docs "https://github.com/dynamicslab/pykoopman/tree/master/docs/"
    click CI "https://github.com/dynamicslab/pykoopman/blob/master/.github/workflows/run-tests.yml"

    %% Styles
    classDef coreapi fill:#cfe2f3,stroke:#0366d6,color:#000
    classDef feature fill:#d9ead3,stroke:#6aa84f,color:#000
    classDef estimation fill:#fce5cd,stroke:#e69138,color:#000
    classDef analysis fill:#d9d2e9,stroke:#8e7cc3,color:#000
    classDef tooling fill:#eeeeee,stroke:#999999,color:#000
    classDef external fill:#f0f0f0,stroke:#666666,color:#000
```
