OpenReservoirComputing 0.3.3__tar.gz → 0.4.0__tar.gz

{openreservoircomputing-0.3.3 → openreservoircomputing-0.4.0}/.gitignore

@@ -97,10 +97,8 @@ ipython_config.py
 #Pipfile.lock
 
 # UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#uv.lock
+#   uv.lock IS COMMITTED to this repository on purpose: it gives contributors reproducible
+#   environments and CI runs `uv sync --locked` against it. Do not add it here.
 
 # poetry
 #   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.

{openreservoircomputing-0.3.3/src/OpenReservoirComputing.egg-info → openreservoircomputing-0.4.0}/PKG-INFO

@@ -1,63 +1,29 @@
 Metadata-Version: 2.4
 Name: OpenReservoirComputing
-Version: 0.3.3
+Version: 0.4.0
 Summary: GPU accelerated implementations of common RC architectures
+Project-URL: Repository, https://github.com/Jan-Williams/OpenReservoirComputing
 Author-email: "Jan P. Williams" <jmpw1@uw.edu>, Dima Tretiak <dtretiak@uw.edu>
 Maintainer-email: "Jan P. Williams" <jmpw1@uw.edu>
-Project-URL: Repository, https://github.com/Jan-Williams/OpenReservoirComputing
+License-File: LICENSE
 Keywords: reservoir computing
-Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: <3.14,>=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: jax
+Requires-Dist: diffrax
 Requires-Dist: equinox
+Requires-Dist: jax
 Requires-Dist: matplotlib
-Requires-Dist: setuptools_scm>=8.1
-Requires-Dist: diffrax
-Provides-Extra: all
-Requires-Dist: jax[cuda12]; extra == "all"
-Requires-Dist: ruff; extra == "all"
-Requires-Dist: ty; extra == "all"
-Requires-Dist: pytest; extra == "all"
-Requires-Dist: coverage; extra == "all"
-Requires-Dist: pytest-cov; extra == "all"
-Requires-Dist: notebook; extra == "all"
-Requires-Dist: ipykernel; extra == "all"
-Requires-Dist: pytest-env; extra == "all"
-Requires-Dist: mkdocs; extra == "all"
-Requires-Dist: mkdocs-material; extra == "all"
-Requires-Dist: mkdocs-autorefs; extra == "all"
-Requires-Dist: mkdocstrings[python]; extra == "all"
-Requires-Dist: mkdocs-jupyter; extra == "all"
-Provides-Extra: dev
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: ty; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: coverage; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: pytest-env; extra == "dev"
-Requires-Dist: mkdocs; extra == "dev"
-Requires-Dist: mkdocs-material; extra == "dev"
-Requires-Dist: mkdocs-autorefs; extra == "dev"
-Requires-Dist: mkdocstrings[python]; extra == "dev"
-Provides-Extra: notebooks
-Requires-Dist: notebook; extra == "notebooks"
-Requires-Dist: ipykernel; extra == "notebooks"
 Provides-Extra: gpu
-Requires-Dist: jax[cuda12]; extra == "gpu"
-Provides-Extra: docs
-Requires-Dist: mkdocs; extra == "docs"
-Requires-Dist: mkdocs-material; extra == "docs"
-Requires-Dist: mkdocs-autorefs; extra == "docs"
-Requires-Dist: mkdocstrings[python]; extra == "docs"
-Requires-Dist: mkdocs-jupyter; extra == "docs"
-Dynamic: license-file
+Requires-Dist: jax[cuda12]; (sys_platform == 'linux') and extra == 'gpu'
+Provides-Extra: notebooks
+Requires-Dist: ipykernel; extra == 'notebooks'
+Requires-Dist: notebook; extra == 'notebooks'
+Description-Content-Type: text/markdown
 
 <div align="center">
   <img src="imgs/ORC_logo_cropped.png" alt="ORC Logo" width="200px" />
@@ -79,6 +45,11 @@ The easiest way to get started with ORC is to install from PyPI:
 pip install OpenReservoirComputing
 ```
 
+or, if you use [uv](https://docs.astral.sh/uv/):
+```bash
+uv add OpenReservoirComputing
+```
+
 If you're interested in the latest, unreleased version or in contributing, you can install from source. Please see the Contribution guidelines below for more details. 
 
 ## Quick start example
@@ -131,35 +102,41 @@ plt.show()
 ORC models are built on top of [Equinox](https://docs.kidger.site/equinox/), and as a result we strongly recommend the use of Equinox transforms `eqx.filter_{jit, vmap, grad}` over `jax.{jit, vmap, grad}`. For more details, please check out the [JAX JIT Compatibility](https://Jan-Williams.github.io/OpenReservoirComputing/examples/jit_compatibility/) example notebook.
 
 ## Contribution guidelines
-First off, thanks for helping out! We appreciate your willingness to contribute! To get started, clone the repo and install the developer dependencies of ORC.
+First off, thanks for helping out! We appreciate your willingness to contribute! ORC uses [uv](https://docs.astral.sh/uv/) to manage development environments, which keeps setup to a single command.
+
+First, [install uv](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it. Then clone the repo and sync:
 
 ```bash
 git clone https://github.com/Jan-Williams/OpenReservoirComputing.git
+cd OpenReservoirComputing
+uv sync
 ```
 
-From the root directory of the repository, create an editable install for your given hardware.
+`uv sync` creates a `.venv`, installs ORC in editable mode, and installs the development dependencies at the exact versions recorded in `uv.lock`. There is no need to activate the environment — just prefix commands with `uv run`.
 
-CPU:
+For NVIDIA GPU support (Linux only — see the [installation docs](https://Jan-Williams.github.io/OpenReservoirComputing/getting-started/installation/) for why):
 ```bash
-pip install -e ".[dev]"
+uv sync --extra gpu
 ```
 
-GPU:
+To also install the documentation toolchain:
 ```bash
-pip install -e ".[dev, gpu]"
+uv sync --all-groups
 ```
 
 The main branch is protected from direct changes. If you would like to make a change please create a new branch and work on your new feature. After you are satisfied with your changes, please run our testing suite to ensure all is working well. We also expect new tests to be written for all changes if additions are made. The tests can be simply run from the root directory of the repository with
 ```bash
-pytest
+uv run pytest
 ```
 Followed by a formatting check 
 ```bash
-ruff check
+uv run ruff check
 ```
 and a type annotation check
 ```bash
-ty check
+uv run ty check src/
 ```
 
-Finally, submit your changes as a pull request! When you submit the PR, please request reviews from both @dtretiak and @Jan-Williams, we will try to get back to you as soon as possible. When you submit the PR, the above tests will automatically be run on your proposed changes through Github Actions, so it is best to get everything tested first before submitting!
+If you add or change a dependency, use `uv add <package>` (or `uv add --group dev <package>` for a development tool) and **commit the updated `uv.lock`** — CI runs `uv sync --locked` and will fail if the lockfile is out of date.
+
+Finally, submit your changes as a pull request! When you submit the PR, please request reviews from both @dtretiak and @Jan-Williams, we will try to get back to you as soon as possible. When you submit the PR, the above tests will automatically be run on your proposed changes through Github Actions, so it is best to get everything tested first before submitting!

{openreservoircomputing-0.3.3 → openreservoircomputing-0.4.0}/README.md

@@ -18,6 +18,11 @@ The easiest way to get started with ORC is to install from PyPI:
 pip install OpenReservoirComputing
 ```
 
+or, if you use [uv](https://docs.astral.sh/uv/):
+```bash
+uv add OpenReservoirComputing
+```
+
 If you're interested in the latest, unreleased version or in contributing, you can install from source. Please see the Contribution guidelines below for more details. 
 
 ## Quick start example
@@ -70,35 +75,41 @@ plt.show()
 ORC models are built on top of [Equinox](https://docs.kidger.site/equinox/), and as a result we strongly recommend the use of Equinox transforms `eqx.filter_{jit, vmap, grad}` over `jax.{jit, vmap, grad}`. For more details, please check out the [JAX JIT Compatibility](https://Jan-Williams.github.io/OpenReservoirComputing/examples/jit_compatibility/) example notebook.
 
 ## Contribution guidelines
-First off, thanks for helping out! We appreciate your willingness to contribute! To get started, clone the repo and install the developer dependencies of ORC.
+First off, thanks for helping out! We appreciate your willingness to contribute! ORC uses [uv](https://docs.astral.sh/uv/) to manage development environments, which keeps setup to a single command.
+
+First, [install uv](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it. Then clone the repo and sync:
 
 ```bash
 git clone https://github.com/Jan-Williams/OpenReservoirComputing.git
+cd OpenReservoirComputing
+uv sync
 ```
 
-From the root directory of the repository, create an editable install for your given hardware.
+`uv sync` creates a `.venv`, installs ORC in editable mode, and installs the development dependencies at the exact versions recorded in `uv.lock`. There is no need to activate the environment — just prefix commands with `uv run`.
 
-CPU:
+For NVIDIA GPU support (Linux only — see the [installation docs](https://Jan-Williams.github.io/OpenReservoirComputing/getting-started/installation/) for why):
 ```bash
-pip install -e ".[dev]"
+uv sync --extra gpu
 ```
 
-GPU:
+To also install the documentation toolchain:
 ```bash
-pip install -e ".[dev, gpu]"
+uv sync --all-groups
 ```
 
 The main branch is protected from direct changes. If you would like to make a change please create a new branch and work on your new feature. After you are satisfied with your changes, please run our testing suite to ensure all is working well. We also expect new tests to be written for all changes if additions are made. The tests can be simply run from the root directory of the repository with
 ```bash
-pytest
+uv run pytest
 ```
 Followed by a formatting check 
 ```bash
-ruff check
+uv run ruff check
 ```
 and a type annotation check
 ```bash
-ty check
+uv run ty check src/
 ```
 
+If you add or change a dependency, use `uv add <package>` (or `uv add --group dev <package>` for a development tool) and **commit the updated `uv.lock`** — CI runs `uv sync --locked` and will fail if the lockfile is out of date.
+
 Finally, submit your changes as a pull request! When you submit the PR, please request reviews from both @dtretiak and @Jan-Williams, we will try to get back to you as soon as possible. When you submit the PR, the above tests will automatically be run on your proposed changes through Github Actions, so it is best to get everything tested first before submitting!

openreservoircomputing-0.4.0/pyproject.toml

@@ -0,0 +1,132 @@
+[build-system]
+requires = ["hatchling>=1.27", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "OpenReservoirComputing"
+authors = [
+    { name = "Jan P. Williams", email = "jmpw1@uw.edu" },
+    { name = "Dima Tretiak", email = "dtretiak@uw.edu" },
+]
+
+maintainers = [
+    { name = "Jan P. Williams", email = "jmpw1@uw.edu" },
+]
+
+description = "GPU accelerated implementations of common RC architectures"
+readme = "README.md"
+dynamic = ["version"]
+dependencies = [
+    "jax",
+    "equinox",
+    "matplotlib",
+    "diffrax",
+]
+
+requires-python = ">=3.10, <3.14"
+keywords = ["reservoir computing"]
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Repository = "https://github.com/Jan-Williams/OpenReservoirComputing"
+
+[project.optional-dependencies]
+# JAX publishes CUDA wheels for Linux only (see JAX's installation docs). The marker
+# keeps this extra a no-op on macOS and native Windows instead of an install error.
+# Windows users with an NVIDIA GPU should install under WSL2, which reports
+# sys_platform == "linux" and therefore does get the CUDA build.
+gpu = ["jax[cuda12]; sys_platform == 'linux'"]
+notebooks = ["notebook", "ipykernel"]
+
+# Development and documentation dependencies live in PEP 735 dependency groups rather
+# than extras: they are never published in the package metadata, and `uv sync` installs
+# them automatically. They are therefore NOT reachable via `pip install -e ".[dev]"`.
+[dependency-groups]
+dev = [
+    "ruff",
+    "ty",
+    "pytest",
+    "pytest-cov",
+    "pytest-env",
+    "coverage",
+]
+docs = [
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocs-autorefs",
+    "mkdocstrings[python]",
+    "mkdocs-jupyter",
+    # mkdocs.yml runs mkdocs-jupyter with execute: true / allow_errors: false, so the
+    # docs build executes every example notebook and needs a Jupyter kernel.
+    "notebook",
+    "ipykernel",
+]
+
+[tool.uv]
+default-groups = ["dev"]
+required-version = ">=0.9.0"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+# Required explicitly: hatchling's autodetection looks for the normalized project name
+# ("openreservoircomputing"), which does not match the import package ("orc").
+packages = ["src/orc"]
+
+[tool.hatch.build.targets.sdist]
+# only-include (not include): docs/examples is a symlink to ../examples, and hatchling's
+# tree walk follows symlinks while de-duplicating on (st_dev, st_ino) -- so whichever of
+# examples/ or docs/examples/ is visited first wins and the other is dropped, making the
+# sdist non-deterministic across machines. only-include bypasses the tree walk entirely.
+only-include = [
+    "src/orc",
+    "tests",
+    "examples",
+    "pyproject.toml",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = "tests"
+addopts = "--ignore=scripts --ignore=docs"
+env = ["MPLBACKEND=Agg"]
+
+[tool.coverage.run]
+source_pkgs = ["orc"]
+branch = true
+
+[tool.coverage.paths]
+# Canonicalize editable (src/orc) and non-editable (site-packages/orc) layouts so
+# reports are comparable regardless of how the project was installed.
+source = ["src/orc", "*/site-packages/orc"]
+
+[tool.ruff]
+exclude = ["examples"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "D", "UP", "B", "A", "C4", "N", "SIM", "I"]
+
+ignore = ["N806", "N802", "N803", "F722"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D", "E402"]
+"docs/*.py" = ["D", "A"]
+"*.ipynb" = ["E", "W", "F", "D", "UP", "B", "A", "C4", "N", "SIM", "I"]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 88
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ty.src]
+exclude = ["tests", "examples"]

{openreservoircomputing-0.3.3 → openreservoircomputing-0.4.0}/src/orc/control/base.py

@@ -179,9 +179,7 @@ class RCControllerBase(eqx.Module, ABC):
         return self.force(in_seq, control_seq, res_state)
 
     @eqx.filter_jit
-    def apply_control(
-        self, control_seq: Array, res_state: Array
-    ) -> tuple[Array, Array]:
+    def apply_control(self, control_seq: Array, res_state: Array) -> Array:
         """Apply a predefined control sequence in closed-loop.
 
         The readout feeds back as the next input: u(t+1) = readout(x(t)).

{openreservoircomputing-0.3.3 → openreservoircomputing-0.4.0}/src/orc/forecaster/train.py

@@ -115,7 +115,7 @@ def train_RCForecaster(
             ts = force_kwargs["ts"]
 
             def _force(seq, state, t):
-                return model.force(seq, state, ts=t)
+                return model.force(seq, state, ts=t)  # ty: ignore[unknown-argument]
 
             tot_res_seq = eqx.filter_vmap(_force)(tot_seq, initial_res_state, ts)
         else:

{openreservoircomputing-0.3.3 → openreservoircomputing-0.4.0}/tests/forecaster/test_forecast_models.py

@@ -839,7 +839,7 @@ def test_multi_seq_equiv_manual_concat(lorenz_segments):
         beta,
     )
 
-    assert jnp.allclose(esn_multi.readout.wout, cmat)
+    assert jnp.allclose(esn_multi.readout.wout, cmat, atol=1e-2)
 
 
 def test_multi_seq_tot_res_seq_shape(lorenz_segments):

openreservoircomputing-0.3.3/.github/CODEOWNERS

@@ -1 +0,0 @@
-* @Jan-Williams

openreservoircomputing-0.3.3/.github/workflows/docs.yml

@@ -1,26 +0,0 @@
-name: Deploy Docs
-
-on:
-  push:
-    branches: [main]
-
-permissions:
-  contents: write
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Install dependencies
-        run: pip install -e .[docs]
-
-      - name: Deploy to GitHub Pages
-        run: mkdocs gh-deploy --force

openreservoircomputing-0.3.3/.github/workflows/draft-pdf.yml

@@ -1,28 +0,0 @@
-name: Draft PDF
-on:
-  push:
-    paths:
-      - JOSS/**
-      - .github/workflows/draft-pdf.yml
-
-jobs:
-  paper:
-    runs-on: ubuntu-latest
-    name: Paper Draft
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Build draft PDF
-        uses: openjournals/openjournals-draft-action@master
-        with:
-          journal: joss
-          # This should be the path to the paper within your repo.
-          paper-path: JOSS/paper.md
-      - name: Upload
-        uses: actions/upload-artifact@v4
-        with:
-          name: paper
-          # This is the output path where Pandoc will write the compiled
-          # PDF. Note, this should be the same directory as the input
-          # paper.md
-          path: JOSS/paper.pdf

openreservoircomputing-0.3.3/.github/workflows/publish.yml

@@ -1,46 +0,0 @@
-name: Publish to PyPI
-
-on:
-  release:
-    types: [published]
-
-permissions:
-  id-token: write
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # needed for setuptools_scm
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Install build tools
-        run: pip install build
-
-      - name: Build package
-        run: python -m build
-
-      - uses: actions/upload-artifact@v4
-        with:
-          name: dist
-          path: dist/
-
-  publish:
-    needs: build
-    runs-on: ubuntu-latest
-    environment: pypi
-    permissions:
-      id-token: write
-    steps:
-      - uses: actions/download-artifact@v4
-        with:
-          name: dist
-          path: dist/
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1

openreservoircomputing-0.3.3/.github/workflows/tests.yml

@@ -1,63 +0,0 @@
-name: CI
-
-on:
-    push:
-      branches:
-        - main
-    pull_request:
-      branches:
-        - main
-        
-jobs:
-  run-tests:
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.11", "3.12","3.13"]
-        os: [ubuntu-latest]
-    runs-on: ${{ matrix.os }}
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
-        cache: 'pip'
-        cache-dependency-path: pyproject.toml
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install .[dev]
-
-    - name: Format check with ruff
-      run: |
-        ruff check --output-format=github
-
-    - name: Type check with ty
-      run: |
-        ty check src/
-
-    - name: Test with pytest
-      run: |
-        pytest --junitxml=junit/test-results-${{ matrix.os }}-py${{ matrix.python-version }}.xml --cov=orc
-
-    - name: Show coverage report
-      run: |
-        coverage report
-        coverage xml
-
-    - name: Upload coverage to Codecov
-      if: matrix.python-version == '3.12'
-      uses: codecov/codecov-action@v5
-      with:
-        token: ${{ secrets.CODECOV_TOKEN }}
-        files: coverage.xml
-        flags: unittests
-        name: codecov-umbrella
-        fail_ci_if_error: false
-
-    - name: Test Summary
-      uses: test-summary/action@v2
-      with:
-        paths: "junit/*.xml"
-      if: always()

openreservoircomputing-0.3.3/JOSS/CITATION.cff

@@ -1,39 +0,0 @@
-cff-version: 1.2.0
-message: "If you use this software, please cite it as below."
-title: "OpenReservoirComputing: GPU-Accelerated Reservoir Computing in JAX"
-type: software
-authors:
-  - given-names: Jan P.
-    family-names: Williams
-    email: jmpw1@uw.edu
-    affiliation: University of Washington
-    orcid: https://orcid.org/0009-0005-4955-0411
-  - given-names: Dima
-    family-names: Tretiak
-    email: dtretiak@uw.edu
-    affiliation: University of Washington
-    orcid: https://orcid.org/0009-0005-0419-7554
-  - given-names: Steven L.
-    family-names: Brunton
-    affiliation: University of Washington
-    orcid: https://orcid.org/0000-0002-6565-5118
-  - given-names: J. Nathan
-    family-names: Kutz
-    affiliation: University of Washington
-    orcid: https://orcid.org/0000-0002-6004-2275
-  - given-names: Krithika
-    family-names: Manohar
-    affiliation: University of Washington
-    orcid: https://orcid.org/0000-0002-1582-6767
-repository-code: https://github.com/Jan-Williams/OpenReservoirComputing
-url: https://Jan-Williams.github.io/OpenReservoirComputing/
-license: Apache-2.0
-keywords:
-  - reservoir computing
-  - echo state networks
-  - time series forecasting
-  - JAX
-  - GPU computing
-  - chaotic systems
-# doi: TODO - will be assigned by JOSS upon acceptance
-# version: TODO - set to release version at submission time