neurosush 0.3.1__tar.gz

neurosush-0.3.1/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: build
+    groups:
+      python:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci
+    groups:
+      actions:
+        patterns: ["*"]

neurosush-0.3.1/.github/workflows/bench.yml

@@ -0,0 +1,29 @@
+name: Benchmarks
+
+on:
+  schedule:
+    - cron: '0 3 * * 1'  # Mondays
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: pip install torch --index-url https://download.pytorch.org/whl/cpu
+      - run: pip install -e .
+      - run: python benchmarks/suite.py --out benchmark.json
+      - uses: actions/upload-artifact@v7
+        with:
+          name: benchmark
+          path: benchmark.json
+      - name: Compare with the baseline (fails when a case halves)
+        shell: bash  # -eo pipefail: the comparison's exit code survives the pipe to tee
+        run: python benchmarks/compare.py benchmarks/baseline.json benchmark.json | tee -a "$GITHUB_STEP_SUMMARY"

neurosush-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,93 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: pip install pre-commit
+      - run: pre-commit run --all-files --show-diff-on-failure
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: pip install torch --index-url https://download.pytorch.org/whl/cpu
+      - run: pip install "mypy>=1.10"
+      - run: mypy
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ['3.10', '3.11', '3.12', '3.13']
+        include:
+          - os: macos-latest
+            python: '3.12'
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - if: runner.os == 'Linux'
+        run: pip install torch --index-url https://download.pytorch.org/whl/cpu
+      - if: runner.os == 'macOS'
+        run: pip install torch
+      - run: pip install -e ".[dev]"
+      - if: matrix.os == 'ubuntu-latest' && matrix.python == '3.12'
+        run: pytest --cov --cov-report=xml --cov-fail-under=90
+      - if: matrix.os != 'ubuntu-latest' || matrix.python != '3.12'
+        run: pytest
+      - uses: actions/upload-artifact@v7
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.12'
+        with:
+          name: coverage
+          path: coverage.xml
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check --strict dist/*
+      - name: Smoke test the wheel in a fresh environment
+        run: |
+          python -m venv "${RUNNER_TEMP}/wheel-venv"
+          "${RUNNER_TEMP}/wheel-venv/bin/python" -m pip install torch --index-url https://download.pytorch.org/whl/cpu
+          "${RUNNER_TEMP}/wheel-venv/bin/python" -m pip install dist/*.whl
+          cd "${RUNNER_TEMP}"
+          "${RUNNER_TEMP}/wheel-venv/bin/python" -c "import neurosush; print(neurosush.__version__)"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/

neurosush-0.3.1/.github/workflows/release.yml

@@ -0,0 +1,95 @@
+name: Release
+
+# A commit on main whose __version__ is a release version (for example 0.2.0) that has no
+# GitHub release yet is released automatically: verify, full CI, GitHub release with the
+# wheel and sdist, then PyPI once publishing is switched on. Pushing a tag vX.Y.Z by hand
+# works too.
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  plan:
+    runs-on: ubuntu-latest
+    outputs:
+      release: ${{ steps.decide.outputs.release }}
+      tag: ${{ steps.decide.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v7
+      - id: decide
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version=$(python3 scripts/release_check.py --print-version)
+          tag="v${version}"
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+          if ! python3 scripts/release_check.py --is-release "$version"; then
+            echo "release=false" >> "$GITHUB_OUTPUT"; echo "${version} is a development version"
+          elif gh release view "$tag" --repo "$GITHUB_REPOSITORY" > /dev/null 2>&1; then
+            echo "release=false" >> "$GITHUB_OUTPUT"; echo "${tag} is already released"
+          else
+            echo "release=true" >> "$GITHUB_OUTPUT"; echo "releasing ${tag}"
+          fi
+
+  verify:
+    needs: plan
+    if: needs.plan.outputs.release == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - run: python3 scripts/release_check.py --tag "${{ needs.plan.outputs.tag }}" --notes-out notes.md
+      - uses: actions/upload-artifact@v7
+        with:
+          name: notes
+
+          path: notes.md
+
+  ci:
+    needs: verify
+    uses: ./.github/workflows/ci.yml
+
+  github-release:
+    needs: [plan, ci]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/download-artifact@v8
+        with:
+          name: notes
+      - env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.plan.outputs.tag }}
+        run: >
+          gh release create "$TAG" dist/* --repo "$GITHUB_REPOSITORY" --target "$GITHUB_SHA"
+          --title "$TAG" --notes-file notes.md
+
+  pypi:
+    needs: github-release
+    # Switch on after adding this repository as a PyPI trusted publisher:
+    # Settings > Secrets and variables > Actions > Variables > PYPI_PUBLISH = true
+    if: vars.PYPI_PUBLISH == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

neurosush-0.3.1/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+.mypy_cache/
+# local tooling, never committed
+.worker/
+.ref/
+graphify-out/
+.claude/
+CLAUDE.md
+AGENTS.md

neurosush-0.3.1/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+# Install once with `pre-commit install`; the hooks then run on every commit.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.8
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

neurosush-0.3.1/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to neuroSush are documented here, following the
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## [Unreleased]
+
+## [0.3.1] - 2026-09-24
+
+### Added
+- Package metadata for PyPI (summary, keywords, project links, classifiers) and
+  `CITATION.cff`.
+
+### Changed
+- The README introduces the whole project, links absolutely (so it also works on PyPI), shows
+  the spiking sequence memory learning, and lists the limitations.
+
+## [0.3.0] - 2026-09-24
+
+### Added
+- Spiking temporal memory: `ActiveSegments` (distal dendritic segments with NMDA-like
+  plateaus and a coincidence window) and `MinicolumnInhibition`; a layer built from them
+  activates exactly the cells `TemporalMemory` activates, checked by
+  `tests/validation/test_segment_math.py` and `test_sequence_math.py`.
+- `SegmentLearning`: the temporal memory's learning in spike time, and `sequence_memory`,
+  which builds a spiking sequence memory layer with derived and checked timing. It learns
+  the same curves as `TemporalMemory` (`tests/validation/test_sequence_learning.py`).
+- `experiments/sequence_learning.py`: the full learning curves, with parameters and seeds.
+- `SpatialPooler.state_dict()`/`load_state_dict()` and the same for `TemporalMemory`
+  (including its random generator), so both resume exactly.
+- More of `tests/validation`: conv2d, local2d, lateral and pooling currents and the conv and
+  local STDP rules against the dense synapse-by-synapse definition; reward-modulated STDP
+  against its closed form, and the distal reward problem (Izhikevich 2007).
+- `benchmarks/suite.py` and `compare.py`, run weekly by the Benchmarks workflow: throughput
+  normalized by a calibration workload, compared with a baseline recorded on a GitHub
+  runner (a case that halves fails).
+
+### Fixed
+- STDP computed in torch's default dtype instead of the traces' dtype, so a float64
+  network learned in float32 precision (and conv and local synapses got float32 updates).
+
+## [0.2.0] - 2026-09-24
+
+### Added
+- `neurosush.htm`: SDR operations with exact match probabilities, scalar, random
+  distributed and category encoders, `SDRClassifier`, `SpatialPooler`, `TemporalMemory`,
+  grid cell modules, `ActiveDendrites`, and voting columns for object recognition.
+- `neurosush.predictive_coding.PredictiveCodingNetwork`: hierarchical predictive coding with
+  learned weights, priors and variances.
+- `examples/sequence_prediction.py` and `examples/object_recognition.py`.
+- `Recorder`: records attributes of a network, neuron group or synapse group over time.
+- `neurosush.checkpoint`: save and load the complete state of a network and resume it
+  exactly, batched or not.
+- `Behavior.state_dict()`/`load_state_dict()`, and the same for delay buffers.
+- Strict mypy type checking of the package (in `scripts/check.sh` and CI).
+- `tests/validation`: the spiking core checked against the closed-form solutions of its
+  equations (LIF, exponential and adaptive LIF, traces, STDP, inhibitory STDP, homeostasis,
+  dopamine, Poisson encoders and delays).
+- Tests marked `gpu` that compare CUDA and CPU runs, pre-commit hooks (also run by the CI
+  lint job), and Dependabot updates for pip and GitHub Actions.
+
+### Changed
+- A synaptic input without `SpikeGather` is now an error; before, the synapse silently
+  delivered no current.
+- `SpikeGather` needs an `Axon` only on the source; `syn.post_spike` is gathered when the
+  destination has one too (traces and plasticity need it and say so).
+- `Axon` checks that the `dst_delay` of incoming synapses fits its history.
+- A group shape in a JSON spec that is neither an int nor three ints raises `ValueError`.
+
+## [0.1.0] - 2026-09-24
+
+### Added
+- Simulation core: `Network`, `NeuronGroup`, `SynapseGroup`, `Behavior` with an explicit
+  execution `Order`, delay buffers, and seeded randomness.
+- Neurons: `LIF`, `ELIF`, `AdaptiveELIF` with pure dynamics, `Fire`, `KWTA`, `InherentNoise`,
+  `Axon` delays, `DendriteStructure` and `DendriteIntegration` (proximal, distal, apical),
+  `ActivityHomeostasis`, `VoltageHomeostasis`, and `SpikeInput`.
+- Synapses: `WeightInit` (dense or sparse), `DelayInit`, dense, one-to-one, sparse, conv2d,
+  local2d, lateral and average-pooling inputs, `SpikeGather`, `Traces`, `STDP`, `RSTDP`,
+  `ISTDP`, `WeightClip`, `WeightNormalization`, `CurrentNormalization`.
+- `Payoff` and `Dopamine` reward modulation.
+- Poisson and latency encoders, DoG and Gabor kernels, grid masks, `LocationDataset` and
+  `spike_frames`.
+- Cortical structures: layers with ports, `connect`, `CorticalColumn`, and JSON specs built
+  through a class registry.
+- `examples/two_patterns.py`, which learns two input patterns with STDP.
+- Fast paths: ring-buffer delays validated once, and event-driven in-place STDP for dense
+  synapses (5-6x faster on CPU); `benchmarks/dense_stdp.py` measures it.
+- Batched simulation: `Network(batch_size=B)` and `spike_frames(..., batch_size=B)` run `B`
+  samples side by side with shared weights (about 23,000 sample-steps/s on a laptop GPU for
+  the 784 -> 400 benchmark).
+- CI (lint, tests on Python 3.10 to 3.13, coverage, build) and a tag-driven release workflow
+  with PyPI trusted publishing.

neurosush-0.3.1/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below, together with the papers of the models you use."
+title: "neuroSush: brain-inspired computing on PyTorch"
+type: software
+authors:
+  - alias: sush
+    email: soroushdeimi@gmail.com
+repository-code: "https://github.com/soroushdeimi/neuroSush"
+license: MIT
+abstract: >-
+  A PyTorch library that simulates spiking neural networks (integrate-and-fire neurons with
+  dendritic compartments and delays, STDP-family plasticity with dopamine modulation),
+  implements the Thousand Brains and hierarchical temporal memory models and hierarchical
+  predictive coding, and provides a spiking layer that computes the temporal memory. Every
+  model is validated against its mathematics.
+keywords:
+  - spiking neural networks
+  - hierarchical temporal memory
+  - thousand brains theory
+  - predictive coding
+  - computational neuroscience
+  - pytorch

neurosush-0.3.1/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing
+
+## Development setup
+
+Use Python 3.10 or newer. Create and activate a virtual environment, install CPU
+PyTorch, then install the package with development dependencies:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+pip install -e ".[dev]"
+```
+
+On macOS, use `pip install torch` instead of the CPU index command.
+Install the git hooks once; they fix whitespace and run ruff on every commit, as the CI
+lint job does:
+
+```bash
+pre-commit install
+```
+
+Run the full check before committing:
+
+```bash
+bash scripts/check.sh
+```
+
+Tests marked `gpu` compare CUDA runs with the CPU. They are skipped on machines without a
+CUDA device (including CI), so run them locally after changing tensor code:
+`pytest -m gpu`.
+
+## Code and commits
+
+Keep math in pure functions and behaviors thin. Test equations with hand-computed
+values, and never mutate inputs in place. Add type hints to public functions and
+use `from __future__ import annotations` in Python modules. Follow
+`docs/ARCHITECTURE.md` for the simulation model and conventions.
+
+Use Conventional Commits with a scope: `feat`, `fix`, `docs`, `test`, `build`,
+`ci`, or `refactor`, for example `fix(neurons): validate time constants`.
+
+## Benchmarks
+
+`python benchmarks/suite.py` times the main workloads (dense STDP, batched simulation,
+spatial pooler and temporal memory learning). Each rate is also divided by a calibration
+workload measured on the same machine, which removes most of the difference between
+machines, though not all of it: the same code measured up to 27% apart on two GitHub
+runners. The Benchmarks workflow runs the suite every Monday (or on demand) and compares it
+with `benchmarks/baseline.json`; a case that loses half its normalized throughput fails
+the run, and the table in the run summary shows every change.
+
+To record or move the baseline after an intended change, download the `benchmark`
+artifact of a Benchmarks run on GitHub and commit it as `benchmarks/baseline.json`; a
+baseline from another machine is not comparable.
+
+## Releasing
+
+Releases are automatic:
+
+1. Set `__version__` in `src/neurosush/__init__.py` to the release version.
+2. Move the Unreleased notes under `## [X.Y.Z] - YYYY-MM-DD`, keeping an
+   Unreleased section for future changes.
+3. Run `bash scripts/check.sh`, commit, and push to `main`.
+
+On that push the Release workflow sees a release version without a GitHub
+release, checks the version and changelog, runs the full CI, and creates the tag
+`vX.Y.Z` and a GitHub release with the wheel, the sdist and the changelog notes.
+Development versions (`X.Y.Z.devN`) are never released. Pushing a tag `vX.Y.Z`
+by hand does the same.
+
+PyPI publishing is a separate job that is off until it is set up once: add this
+repository as a trusted publisher on PyPI (workflow `release.yml`, environment
+`pypi`), create the `pypi` environment in the repository settings, and set the
+repository variable `PYPI_PUBLISH` to `true`. After that every release is also
+published to PyPI.

neurosush-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sush
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.