# galoisinc/dlkoopman architecture

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

- Interactive diagram: https://gitdiagram.com/galoisinc/dlkoopman
- Repository: https://github.com/galoisinc/dlkoopman

## Overview

##### Project type and purpose
- This is an **open-source Python library** (“dlkoopman”) implementing deep-learning-based Koopman theory for state and trajectory prediction of nonlinear dynamical systems.
- It provides training pipelines (autoencoder + Koopman‐matrix learning), prediction modules, hyperparameter search, metrics, and user documentation/examples.

##### File structure
Top-level directories/files:
- .github/workflows – CI pipelines for formatting (isort) and testing (pytest)
- Dockerfile – container image build
- pyproject.toml – packaging and deps (e.g. PyTorch)
- dlkoopman/ – core library modules
– config.py: load/validate training and prediction parameters
– nets.py: encoder/decoder and Koopman matrix learner network definitions
– hyp_search.py: hyperparameter search orchestration
– metrics.py: error metrics (ANAE, etc.)
– state_pred.py: state‐prediction interface (via eigendecomposition)
– traj_pred.py: trajectory‐prediction interface (via linear layer evolution)
– utils.py: shared helpers (data loaders, tensor transforms)
- docs/ – generated API documentation (HTML)
- examples/ – Jupyter notebooks demonstrating state and trajectory prediction pipelines on sample data
- tests/ – unit tests for each module, reference data files

##### README for additional insights
- Core training flow: raw state sequence → encoder → encoded states → decoder & Koopman matrix learner → linear evolution → decoder → losses (reconstruction, linearity, prediction).
- Prediction flow splits into (a) **StatePred** (use eigendecomposition for arbitrary index extrapolation) and (b) **TrajPred** (use learned linear layer to step trajectories).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    User["User (CLI / Jupyter / API)"]:::external

    %% Configuration
    subgraph "Configuration Layer"
        Config["Configuration Manager"]:::core
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        DataInput[(Raw State Sequences)]:::data
        Encoder["Encoder Network"]:::core
        KoopLearner["Koopman Matrix Learner"]:::core
        Decoder["Decoder Network"]:::core
        Loss["Loss Computation"]:::core
        HP["Hyperparameter Search Engine"]:::core
        Checkpoint[(Model Checkpoints)]:::data
    end

    %% Prediction Pipeline
    subgraph "Prediction Pipeline"
        StatePred["StatePred Module"]:::core
        TrajPred["TrajPred Module"]:::core
    end

    %% Utilities
    Utils["Utilities (Data Loaders, Transforms)"]:::core

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        GHIsort["GitHub Actions: isort"]:::external
        GHPytest["GitHub Actions: pytest"]:::external
        Docker["Docker Image Build"]:::external
        PyProj["pyproject.toml"]:::external
    end

    %% Documentation & Examples
    subgraph "Docs & Examples"
        Docs["API Documentation"]:::docs
        Examples["Example Notebooks"]:::docs
    end

    %% Testing
    subgraph "Testing Suite"
        Tests["Unit Tests"]:::test
    end

    %% Data & Control Flows
    User --> Config
    Config --> DataInput
    Config --> StatePred
    Config --> TrajPred

    DataInput --> Encoder
    Encoder --> KoopLearner
    KoopLearner --> Decoder
    Decoder --> Loss
    Loss --> Checkpoint

    Config --> HP
    HP -.-> Encoder
    HP -.-> KoopLearner
    HP -.-> Decoder
    HP --> Checkpoint

    Utils --> DataInput
    Utils --> StatePred
    Utils --> TrajPred

    StatePred --> Checkpoint
    StatePred -->|"Generate State Predictions"|User
    TrajPred --> Checkpoint
    TrajPred -->|"Generate Trajectory Predictions"|User

    %% CI/CD & Packaging flows
    GHIsort --> Tests
    GHPytest --> Tests
    Tests -->|"Validate Modules"| Config
    Tests --> Encoder
    Tests --> KoopLearner
    Tests --> Decoder
    Tests --> Loss
    Tests --> StatePred
    Tests --> TrajPred
    Tests --> Utils

    Docker -->|"Package Library"| PyProj

    %% Documentation & Examples integration
    Docs --> Config
    Docs --> Encoder
    Docs --> KoopLearner
    Docs --> Decoder
    Docs --> Loss
    Docs --> StatePred
    Docs --> TrajPred
    Examples -->|"Demonstrate Usage"|StatePred
    Examples -->|"Demonstrate Usage"|TrajPred

    %% Styling
    classDef core fill:#ADD8E6,stroke:#333;
    classDef data fill:#90EE90,stroke:#333;
    classDef external fill:#FFA500,stroke:#333;
    classDef docs fill:#D3D3D3,stroke:#333;
    classDef test fill:#FFD700,stroke:#333;

    %% Click Events
    click Config "https://github.com/galoisinc/dlkoopman/blob/main/dlkoopman/config.py"
    click Encoder "https://github.com/galoisinc/dlkoopman/blob/main/dlkoopman/nets.py"
    click KoopLearner "https://github.com/galoisinc/dlkoopman/blob/main/dlkoopman/nets.py"
    click Decoder "https://github.com/galoisinc/dlkoopman/blob/main/dlkoopman/nets.py"
    click Loss "https://github.com/galoisinc/dlkoopman/blob/main/dlkoopman/metrics.py"
    click HP "https://github.com/galoisinc/dlkoopman/blob/main/dlkoopman/hyp_search.py"
    click StatePred "https://github.com/galoisinc/dlkoopman/blob/main/dlkoopman/state_pred.py"
    click TrajPred "https://github.com/galoisinc/dlkoopman/blob/main/dlkoopman/traj_pred.py"
    click Utils "https://github.com/galoisinc/dlkoopman/blob/main/dlkoopman/utils.py"
    click GHIsort "https://github.com/galoisinc/dlkoopman/blob/main/.github/workflows/isort.yml"
    click GHPytest "https://github.com/galoisinc/dlkoopman/blob/main/.github/workflows/pytest.yml"
    click Docker "https://github.com/galoisinc/dlkoopman/tree/main/Dockerfile"
    click PyProj "https://github.com/galoisinc/dlkoopman/blob/main/pyproject.toml"
    click Docs "https://github.com/galoisinc/dlkoopman/tree/main/docs/"
    click Examples "https://github.com/galoisinc/dlkoopman/tree/main/examples/"
    click Tests "https://github.com/galoisinc/dlkoopman/tree/main/tests/"
```
