snnlab 0.1.1__tar.gz

snnlab-0.1.1/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+dist/
+artifacts/
+temp/
+src/snnlab/lang/examples/generated/
+examples/generated/

snnlab-0.1.1/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+Changes to the combined snnlab Python distribution are recorded here. Package
+versions follow the policy in [VERSIONING.md](VERSIONING.md). Component and
+serialized-schema versions identify separate compatibility contracts.
+
+## [Unreleased]
+
+## [0.1.1] - 2026-10-04
+
+### Added
+
+1. Static Fumadocs documentation with KaTeX, search, GitHub Pages and Cloudflare hosting.
+2. Complete source-derived API references for `lang`, `sim` and `viz`, with automated drift checks.
+3. Six runnable general examples for bundles, simulation, input replay, training, checkpoint resume and retained-signal plotting.
+4. A changelog, single-source package version and release preparation/check helper.
+5. Automatic PyPI publishing on version-source changes to `main`, using Trusted Publishing and release tags after package checks pass.
+
+### Changed
+
+1. The documentation opens at the site root; previous `/docs/` paths redirect there.
+2. Documentation builds use Astro static output with Fumadocs React islands in place of Next.js.
+3. Package builds read the runtime version directly, and source archives exclude local documentation dependencies, caches and generated output.
+
+## [0.1.0] - 2026-10-03
+
+### Added
+
+1. Initial combined Python distribution extracted from Pinglab, exposing `snnlab.lang`, `snnlab.sim` and `snnlab.viz`.
+2. Portable graph authoring and validated bundles, graph-native and legacy execution, surrogate-gradient training, retained artifacts and visualization utilities.
+3. Portable tests and package checks, retaining existing numerical defaults, schemas and backend identifiers.
+
+The historical baseline is Git tag `v0.1.0`. Changes above it remain unreleased
+until a subsequent version is prepared and tagged.

snnlab-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eoin Murray
+
+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.

snnlab-0.1.1/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: snnlab
+Version: 0.1.1
+Summary: Author, simulate and visualise conductance-based spiking neural networks.
+Project-URL: Repository, https://github.com/eoinmurray/snnlab
+Author: Eoin Murray
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: h5py>=3.16.0
+Requires-Dist: matplotlib>=3.10.8
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: scipy>=1.15.3
+Requires-Dist: torch>=2.10.0
+Requires-Dist: torchvision>=0.25.0
+Description-Content-Type: text/markdown
+
+# snnlab
+
+A Python library for authoring, simulating and visualising conductance-based spiking neural networks.
+
+```sh
+uv add git+https://github.com/eoinmurray/snnlab
+```
+
+```python
+from snnlab import lang, sim, viz
+```
+
+1. `snnlab.lang` authors and validates deterministic graph bundles.
+2. `snnlab.sim` executes graphs and supports surrogate-gradient training.
+3. `snnlab.viz` renders recordings, diagrams, figures and animations.
+
+The simulator currently supports COBA-LIF and leaky-integrator graph populations, AMPA/GABA projections, recurrent/feedback connections and integer-timestep delays. It is not an arbitrary-equation simulator.
+
+## Simulator commands
+
+```sh
+uv run snnsim --help
+uv run python -m snnlab.sim sim --help
+uv run python -m snnlab.lang.examples.build_examples
+```
+
+Graphviz (`dot`) is required for diagram exports. FFmpeg is required for video exports. Install these separately through your operating system package manager. Core authoring and simulation do not require either executable.
+
+## Development
+
+```sh
+uv sync --dev
+uv run pytest -m "not slow"
+```
+
+For development in Pinglab, use `uv add --editable ../snnlab`. For reproducible runs, use a Git tag or commit and commit the consumer lockfile.
+
+## Documentation
+
+The Fumadocs site lives in [`docs/`](docs/README.md), with guides for authoring, simulation, training, visualisation, and scientific contracts.
+
+```sh
+cd docs
+npm ci
+npm run dev
+```
+
+## Compatibility
+
+Release history is recorded in [CHANGELOG.md](CHANGELOG.md). See
+[VERSIONING.md](VERSIONING.md) for the version policy, release preparation and
+tagging workflow. Check release metadata with `uv run python scripts/version.py check`.
+
+This initial extraction retains the existing bundle schemas, backend target `tools/snnsim`, component format versions and numerical defaults. Those strings identify persisted scientific contracts; they are not Python import paths. Package version 0.1.0 identifies the combined distribution.
+
+The retained-data regression against historical Pinglab runs remains in Pinglab. The portable tests live here. No scientific runs or generated example bundles are shipped.
+
+MIT licensed.

snnlab-0.1.1/README.md

@@ -0,0 +1,58 @@
+# snnlab
+
+A Python library for authoring, simulating and visualising conductance-based spiking neural networks.
+
+```sh
+uv add git+https://github.com/eoinmurray/snnlab
+```
+
+```python
+from snnlab import lang, sim, viz
+```
+
+1. `snnlab.lang` authors and validates deterministic graph bundles.
+2. `snnlab.sim` executes graphs and supports surrogate-gradient training.
+3. `snnlab.viz` renders recordings, diagrams, figures and animations.
+
+The simulator currently supports COBA-LIF and leaky-integrator graph populations, AMPA/GABA projections, recurrent/feedback connections and integer-timestep delays. It is not an arbitrary-equation simulator.
+
+## Simulator commands
+
+```sh
+uv run snnsim --help
+uv run python -m snnlab.sim sim --help
+uv run python -m snnlab.lang.examples.build_examples
+```
+
+Graphviz (`dot`) is required for diagram exports. FFmpeg is required for video exports. Install these separately through your operating system package manager. Core authoring and simulation do not require either executable.
+
+## Development
+
+```sh
+uv sync --dev
+uv run pytest -m "not slow"
+```
+
+For development in Pinglab, use `uv add --editable ../snnlab`. For reproducible runs, use a Git tag or commit and commit the consumer lockfile.
+
+## Documentation
+
+The Fumadocs site lives in [`docs/`](docs/README.md), with guides for authoring, simulation, training, visualisation, and scientific contracts.
+
+```sh
+cd docs
+npm ci
+npm run dev
+```
+
+## Compatibility
+
+Release history is recorded in [CHANGELOG.md](CHANGELOG.md). See
+[VERSIONING.md](VERSIONING.md) for the version policy, release preparation and
+tagging workflow. Check release metadata with `uv run python scripts/version.py check`.
+
+This initial extraction retains the existing bundle schemas, backend target `tools/snnsim`, component format versions and numerical defaults. Those strings identify persisted scientific contracts; they are not Python import paths. Package version 0.1.0 identifies the combined distribution.
+
+The retained-data regression against historical Pinglab runs remains in Pinglab. The portable tests live here. No scientific runs or generated example bundles are shipped.
+
+MIT licensed.

snnlab-0.1.1/VERSIONING.md

@@ -0,0 +1,86 @@
+# Versioning and releases
+
+The combined Python package uses `MAJOR.MINOR.PATCH` versions, following
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). The current version
+has one source: `__version__` in `src/snnlab/__init__.py`.
+[Hatchling reads that file](https://hatch.pypa.io/latest/version/) to build package
+metadata; do not add a second version literal to `pyproject.toml`.
+
+## Choosing a version
+
+1. Patch: backward-compatible corrections, including documentation and packaging fixes.
+2. Minor: new public functionality. Before 1.0, incompatible API or numerical-contract changes also require a minor bump and explicit migration notes.
+3. Major: after 1.0, incompatible public API, persisted-data or numerical-contract changes. Release 1.0 when the supported public contract is ready to be stable.
+
+Scientific compatibility includes units, timing, initialization, numerical
+defaults, checkpoint authentication and retained-data interpretation. Describe
+changes to these contracts explicitly in the changelog; a version bump alone
+does not explain their effect or establish numerical equivalence.
+
+## Package, component and schema identities
+
+1. `snnlab.__version__` identifies the installable distribution and matches Git tags such as `v0.1.0`.
+2. `snnlab.lang.__version__`, `snnlab.sim.__version__` and `snnlab.viz.__version__` are retained component compatibility identities. Change them deliberately when their owning contract changes; a package bump does not automatically bump them.
+3. Serialized schema strings and `tools/snnsim` identify persisted scientific contracts. Change their versions only with a corresponding schema migration or explicit compatibility policy.
+4. The docs npm package is tooling for the website. Its version does not identify a Python or scientific release.
+
+## Prepare a release
+
+Use Python 3.12 for the repository tools. Add user-facing changes beneath
+`## [Unreleased]` in `CHANGELOG.md` while developing. Existing released sections
+should remain a historical record.
+
+```sh
+uv run python scripts/version.py check
+uv run python scripts/version.py bump patch --dry-run
+uv run python scripts/version.py bump patch
+uv lock --check
+uv run python scripts/version.py check
+uv run ruff check .
+uv run pytest -q -m "not slow"
+uv run python docs/scripts/check_examples.py
+uv build
+```
+
+The bump helper accepts `patch`, `minor` or `major`. It updates the package
+version, moves the current Unreleased notes
+into a dated section, and creates an empty Unreleased section for subsequent
+work. It refuses an empty release or inconsistent starting metadata. It does
+not commit, tag, push or publish. The editable package record in `uv.lock` has
+no version literal because its version is dynamic; version bumps do not
+change dependency pins. Use `--date YYYY-MM-DD` to supply the release
+date explicitly; otherwise it uses the local calendar date.
+
+Review the generated diff before committing. For example, after preparing
+version `0.1.1`:
+
+```sh
+git add src/snnlab/__init__.py CHANGELOG.md
+git commit -m "Release 0.1.1"
+git push origin main
+```
+
+Replace the example version with the actual prepared version. A push to `main`
+that changes `src/snnlab/__init__.py` triggers `.github/workflows/publish.yml`,
+following Demolab's version-triggered release pattern. It runs package checks,
+builds the wheel and source archive, publishes to PyPI using Trusted Publishing,
+then creates `v<VERSION>`. Forks and manual runs on other branches cannot publish.
+The Actions **Run workflow** button can retry or backfill the current version;
+existing PyPI files and release tags are skipped on reruns. Never move or reuse
+a release tag for a different version. Git tags also support pinned installations:
+
+```sh
+uv add git+https://github.com/eoinmurray/snnlab@v0.1.0
+```
+
+## One-time publishing setup
+
+1. Create the GitHub environment `pypi` in `eoinmurray/snnlab`.
+2. In PyPI, register a Trusted Publisher for project `snnlab`: owner
+   `eoinmurray`, repository `snnlab`, workflow `publish.yml`, environment `pypi`.
+   If the project does not yet exist, use a pending publisher under account
+   **Publishing**. If it already exists and you maintain it, use the project's
+   **Publishing** settings. See the [PyPI Trusted Publishing documentation](https://docs.pypi.org/trusted-publishers/).
+3. Once registered, future version changes on `main` publish automatically.
+   No stored PyPI API token is required. This workflow creates a Git tag, but
+   does not create a GitHub Release.

snnlab-0.1.1/docs/.gitignore

@@ -0,0 +1,26 @@
+# deps
+/node_modules
+
+# generated content
+
+# test & build
+/coverage
+/.astro/
+/out/
+/build
+*.tsbuildinfo
+
+# misc
+.DS_Store
+*.pem
+/.pnp
+.pnp.js
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# others
+.env*.local
+.vercel
+next-env.d.ts
+.wrangler/

snnlab-0.1.1/docs/AGENTS.md

@@ -0,0 +1,3 @@
+# Documentation site
+
+This site uses Astro static output with Fumadocs React islands. Keep `output: static`, preserve the root documentation routes, and verify both root and GitHub Pages base-path builds. Content and metadata live in `content/docs`; API and example generators remain the source of generated pages. Run `npm run types:check` and `npm run build` after site changes.

snnlab-0.1.1/docs/README.md

@@ -0,0 +1,59 @@
+# snnlab documentation
+
+Fumadocs + Astro static documentation with KaTeX and browser-side search. Requires Node.js 22.12 or newer.
+
+```sh
+npm ci
+npm run dev
+```
+
+The documentation overview opens at `/`; guides use paths such as `/quickstart/`. Cloudflare redirects previous `/docs/` links to the new paths.
+
+Author pages in `content/docs/` and order them in `content/docs/meta.json`.
+
+```sh
+npm run types:check
+npm run build
+npm run preview
+```
+
+The build exports plain HTML, CSS, JavaScript, search data, and KaTeX fonts into `out/`. Astro uses `output: static`; no application server is needed. Markdown downloads use explicit `/llms.mdx/docs/.../content.md` routes; runtime content-negotiation rewrites are unavailable on static hosts.
+
+## GitHub Pages
+
+`.github/workflows/docs.yml` checks and builds docs on pull requests and deploys `main` through GitHub Pages Actions. The GitHub build sets `SITE_BASE_PATH=/snnlab` and `SITE_URL=https://eoinmurray.github.io/snnlab/`.
+
+## Cloudflare
+
+`wrangler.jsonc` deploys the root-path static export as Workers Static Assets at `ssnlab.eoinmurray.info`. An authenticated Wrangler installation is required.
+
+```sh
+SITE_URL=https://ssnlab.eoinmurray.info npm run deploy:cloudflare
+```
+
+Cloudflare deployments are manual through Wrangler. GitHub Pages updates automatically from `main`. Never deploy a build made with `/snnlab` as its base path to the custom-domain root.
+
+`astro.config.mjs` configures remark-math and rehype-katex. Commit `package-lock.json`; `.astro/`, `out/`, and `node_modules/` are generated and ignored.
+
+## API references
+
+Reference pages under `content/docs/api/` are generated from all non-private Python modules in `lang`, `sim`, and `viz`. They cover package exports, module-owned functions/classes/constants, public class members, constructor fields, return expressions, explicit exceptions and full implementation panels. Third-party inherited APIs and private helpers are excluded.
+
+```sh
+python3.12 docs/scripts/generate_api.py
+python3.12 docs/scripts/generate_api.py --check
+```
+
+Run these commands from the repository root with Python 3.12 (the CI-pinned generator version). Edit explanatory contracts in `docs/scripts/api_notes.json`, then regenerate. The generator uses the Python AST without importing simulators, invoking training, or downloading datasets. `api-coverage.json` records the covered inventory. CI checks drift and rebuilds docs when source changes.
+
+## General examples
+
+Standalone Python scripts live in the repository's `examples/` directory. Their complete-code pages and downloadable copies are generated by `scripts/generate_examples.py`. Edit the scripts and `scripts/example_notes.json`, then run these commands from the repository root:
+
+```sh
+python3 docs/scripts/generate_examples.py
+python3 docs/scripts/generate_examples.py --check
+uv run python docs/scripts/check_examples.py
+```
+
+The last command executes every example in a temporary directory. Package CI runs it, and docs CI checks that pages and downloads match the scripts. The retained-signal preview is produced by `examples/plot_recording.py`; after intentional plotting changes, rerun the example, inspect `artifacts/examples/plot_recording/recording.png`, and copy it to `docs/public/examples/recording.png`.