Merge pull request #21 from ludgerpaehler/claude/plotting

Merge in miscellaneous improvements

Author: ludgerpaehler

.claude/CLAUDE.md

@@ -0,0 +1,28 @@
+name: Lint
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+jobs:
+  pre-commit:
+    name: pre-commit hooks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dev dependencies
+        run: uv sync --group dev
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Run pre-commit
+        run: uv run pre-commit run --all-files

.github/workflows/lint.yml

@@ -1,8 +1,13 @@
 # Ignore PyCaches
-src/koopmanrl/__pycache__/
-src/koopmanrl/environments/__pycache__/
+koopmanrl/__pycache__/
+koopmanrl/environments/__pycache__/
 tests/__pycache__/
+koopmanrl_utils/movies/__pycache__/
 
 # Ignore simulation results
 runs/
 saved_models/
+
+# Ignore visualization outputs
+figures/
+video_frames/

.gitignore

@@ -11,19 +11,19 @@ repos:
           - id: debug-statements
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.14.13
+      rev: v0.15.7
       hooks:
           - id: ruff
             args: [--fix]
           - id: ruff-format
 
     - repo: https://github.com/jendrikseipp/vulture
-      rev: v2.14
+      rev: v2.15
       hooks:
           - id: vulture
-            args: [--min-confidence, "80", src/koopmanrl]
+            args: [--min-confidence, "80", koopmanrl]
     - repo: https://github.com/pycqa/isort
-      rev: 7.0.0
+      rev: 8.0.1
       hooks:
           - id: isort
             name: isort (python)

.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+# KoopmanRL Agent Guide
+
+Use this note as the entry point before touching the repository. It points to the canonical module guides and highlights the conventions that apply everywhere.
+
+## Read First
+- `configurations/AGENTS.md` -
+- `scripts/AGENTS.md` -
+- `src/koopmanrl/AGENTS.md` -
+- `tests/AGENTS.md` -
+
+## Global Conventions
+- Reinforcement learning core logic has to stay script-addressable through `python -m ..`.
+- When operations are to be parallelized, strict priority should be given to [Ray](https://github.com/ray-project/ray) for parallelization.
+- Outside of hyperparameter optimization, prefer a CleanRL single file-style syntax
+
+## Repository Layout
+```
+configurations/          best hyperparameter configurations for the algorithms as JSON files
+scripts/                 utility scripts which reproduce the results from the paper
+src/koopmanrl/           core library including the two subfolders environments/, and koopman_tensor/
+tests/                   regression tests and unit tests for the library's core functionality
+```
+
+## Working Checklist
+1. Review the relevant AGENTS guide(s) and existing tests/examples for the feature you touch.
+2. Prototype changes in modules or helper scripts—avoid interactive REPL work.
+3. Add or update targeted tests (`tests/test_*.py`) alongside code changes.
+4. Run the scoped pytest command (`uv run test -m ...`) before submitting.
+5. Keep documentation edits minimal and aligned with the per-module format.

AGENTS.md

@@ -0,0 +1,66 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "KoopmanRL: Koopman-Assisted Reinforcement Learning"
+version: 1.0.0
+date-released: 2026-04-20
+authors:
+  - family-names: Paehler
+    given-names: Ludger
+    email: ludger.paehler@tum.de
+    affiliation: Technical University of Munich
+    orcid: "https://orcid.org/0000-0002-7200-7637"
+  - family-names: Rozwood
+    given-names: Preston
+    email: pwr@cornell.edu
+    affiliation: Cornell University
+    orcid: "https://orcid.org/0009-0007-3589-3514"
+  - family-names: Mehrez
+    given-names: Edward J.
+    email: ejm322@cornell.edu
+    affiliation: Cornell University
+  - family-names: Wen
+    given-names: Sun
+    email: ws455@cornell.edu
+    affiliation: Cornell University
+  - family-names: Brunton
+    given-names: Steven L.
+    email: sbrunton@uw.edu
+    affiliation: University of Washington
+    orcid: "https://orcid.org/0000-0002-6565-5118"
+repository-code: "https://github.com/dynamicslab/koopmanrl"
+url: "https://github.com/dynamicslabs/koopmanrl"
+abstract: >
+    KoopmanRL is a reinforcement learning framework which utilizes the
+    Koopman operator to enhance maximum entropy-based reinforcement
+    learning algorithms at the example of the discrete value iteration,
+    and the Soft actor-critic algorithm. This package accompanies the
+    paper "Koopman-Assisted Reinforcement Learning" providing the
+    CleanRL-style implementations of the algorithms, and the hyperparameter
+    tuning harnesses to tune the algorithms on new environments.
+keywords:
+  - reinforcement learning
+  - Koopman operator
+  - PyTorch
+  - machine learning
+license: MIT
+references:
+  - type: journal-paper
+    title: "Koopman-Assisted Reinforcement Learning"
+    journal:
+      name: "tbd"
+    year: 2026
+    authors:
+      - family-names: Rozwood
+        given-names: Preston
+        orcid: "https://orcid.org/0009-0007-3589-3514"
+      - family-names: Mehrez
+        given-names: Edward J.
+      - family-names: Paehler
+        given-names: Ludger
+        orcid: "https://orcid.org/0000-0002-7200-7637"
+      - family-names: Wen
+        given-names: Sun
+      - family-names: Brunton
+        given-names: Steven L.
+        orcid: "https://orcid.org/0000-0002-6565-5118"