spikegen 0.1.0__tar.gz

spikegen-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: A wrong or non-reproducible spike train
+title: ""
+labels: bug
+---
+
+## Call
+
+The generator and parameters, including the seed, for example
+`homogeneous_poisson(rate=50, duration=2, seed=0)`.
+
+## Expected
+
+What you expected (a property, a count range, or reproducibility).
+
+## Actual
+
+What you observed.
+
+## Environment
+
+- spikegen version:
+- Python version:

spikegen-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest a process or capability for spikegen
+title: ""
+labels: enhancement
+---
+
+## What
+
+The process or capability you would like.
+
+## Why
+
+The workflow this would support.
+
+## References
+
+The definition or paper that pins down the expected behavior.

spikegen-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## Summary
+
+What this changes and why.
+
+## Checklist
+
+- [ ] Tests added or updated (a bug fix starts with a failing test)
+- [ ] Seeded reproducibility and range invariants covered for any new generator
+- [ ] `uv run ruff check .` passes
+- [ ] `uv run mypy src` passes
+- [ ] `uv run pytest` passes
+- [ ] No runtime dependencies added
+- [ ] No em dash characters in docs or commit messages

spikegen-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy src
+      - run: pytest -q

spikegen-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+uv.lock
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+.DS_Store

spikegen-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+- Multi-unit population generation.
+- An optional NumPy fast path.
+
+## [0.1.0]
+
+### Added
+- `regular`, `homogeneous_poisson`, `inhomogeneous_poisson` (thinning), and `gamma_renewal`
+  spike-train generators returning plain sorted lists of times, with explicit seeds.
+- `with_refractory` to enforce a minimum inter-spike interval.
+- Validation with clear errors, and a test suite with exact values, seeded reproducibility,
+  structural invariants, and Hypothesis property tests.

spikegen-0.1.0/CLAUDE.md

@@ -0,0 +1,48 @@
+# spikegen
+
+Pure-Python spike-train generators. Zero runtime dependencies. Complements spikedist.
+
+## Commands
+
+- Create env and install: `uv venv && uv pip install -e ".[dev]"`
+- Test: `uv run pytest -q`
+- Lint: `uv run ruff check .` (format with `uv run ruff format .`)
+- Types: `uv run mypy src`
+- Build: `uv build` (then `uv run --with twine twine check dist/*` before publishing)
+
+## Architecture
+
+`src/spikegen/`:
+- `_validate.py` shared validation (rate, duration, seed, positivity)
+- `processes.py` the generators (regular, homogeneous and inhomogeneous Poisson, gamma
+  renewal) plus with_refractory
+- `__init__.py` public surface
+
+See `docs/architecture.md` for the algorithms.
+
+## Conventions
+
+- Generators return plain sorted `list[float]` of spike times.
+- Stochastic generators take an explicit integer `seed` and are reproducible via
+  `random.Random(seed)`.
+- Parameters are keyword-only; no default values.
+- Use `1 - random()` inside the exponential-interval log to avoid log(0).
+- No runtime dependencies (standard library `random` and `math` only).
+
+## Testing rules
+
+- Exact values for the deterministic generators (regular, with_refractory).
+- Seeded reproducibility for the stochastic generators.
+- Structural invariants (sorted, within [0, duration)).
+- Hypothesis property tests; bug fixes start with a failing test.
+
+## Release
+
+- Semantic versioning; update `CHANGELOG.md` and `__version__`.
+- Gates: `uv run pytest && uv run ruff check . && uv run mypy src && uv build && uv run twine check dist/*`.
+- Publish to PyPI, tag `vX.Y.Z`, GitHub release.
+
+## Style
+
+- No em dash characters in docs, comments, or commit messages.
+- Comments explain non-obvious reasoning only.

spikegen-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,37 @@
+# Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and maintainers pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Showing empathy and kindness toward other people.
+- Being respectful of differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Focusing on what is best for the community.
+
+Examples of unacceptable behavior:
+
+- Harassment, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information without explicit permission.
+- Other conduct which could reasonably be considered inappropriate.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainer at amaar2cool@gmail.com. All complaints will be
+reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

spikegen-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to spikegen
+
+Thanks for your interest. This project values correctness, reproducibility, and zero
+runtime dependencies.
+
+## Development
+
+```sh
+uv venv
+uv pip install -e ".[dev]"
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+```
+
+A standard virtual environment with `pip install -e ".[dev]"` works the same way.
+
+## Guidelines
+
+- No runtime dependencies. The standard library `random` and `math` are enough.
+- Seeded generators must be reproducible: the same seed gives the same train. Tests assert
+  this.
+- Every generator needs structural tests (sorted, within range) and, where it is
+  deterministic, exact-value tests.
+- Parameters are keyword-only with no default values.
+- A bug fix starts with a failing test.
+- Run `uv run ruff format .` before committing.
+- Commit messages follow `type(scope): description`.
+
+## Reporting issues
+
+Open an issue with the call and its parameters, the seed, and what you expected versus what
+you observed.

spikegen-0.1.0/LICENSE

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

spikegen-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: spikegen
+Version: 0.1.0
+Summary: Generate spike trains (Poisson, gamma renewal, regular, inhomogeneous) in pure Python with zero dependencies.
+Project-URL: Homepage, https://github.com/amaar-mc/spikegen
+Project-URL: Repository, https://github.com/amaar-mc/spikegen
+Project-URL: Issues, https://github.com/amaar-mc/spikegen/issues
+Project-URL: Changelog, https://github.com/amaar-mc/spikegen/blob/main/CHANGELOG.md
+Author: Amaar Chughtai
+License: MIT License
+        
+        Copyright (c) 2026 Amaar Chughtai
+        
+        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.
+License-File: LICENSE
+Keywords: computational-neuroscience,neuromorphic,neuroscience,point-process,poisson-process,renewal-process,simulation,spike-train,spiking-neural-networks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# spikegen
+
+<p align="center">
+  <img src="assets/logo.png" alt="spikegen logo" width="160">
+</p>
+
+[![PyPI](https://img.shields.io/pypi/v/spikegen)](https://pypi.org/project/spikegen/)
+[![CI](https://github.com/amaar-mc/spikegen/actions/workflows/ci.yml/badge.svg)](https://github.com/amaar-mc/spikegen/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+Generate spike trains in pure Python with zero dependencies. Poisson, gamma renewal, regular, and inhomogeneous processes, returned as plain sorted lists of spike times, with explicit seeds for reproducibility.
+
+## Install
+
+```sh
+pip install spikegen
+```
+
+## 30-second example
+
+```python
+from spikegen import homogeneous_poisson, regular, gamma_renewal, with_refractory
+
+homogeneous_poisson(rate=50.0, duration=2.0, seed=0)   # Poisson spikes in [0, 2)
+regular(rate=10.0, duration=1.0)                        # [0.0, 0.1, 0.2, ...]
+gamma_renewal(rate=20.0, shape=2.0, duration=1.0, seed=0)  # more regular than Poisson
+
+spikes = homogeneous_poisson(rate=80.0, duration=1.0, seed=0)
+with_refractory(spikes, refractory=0.002)              # enforce a 2 ms refractory period
+```
+
+Times are in the same units as `1 / rate` (seconds if rate is in Hz). Seeded processes are
+reproducible: the same seed gives the same train.
+
+## Why this exists
+
+Generating synthetic spike trains is a daily need, but the generators live inside heavy
+frameworks: `elephant` requires neo and quantities, `pyspike` is NumPy-based, and other
+options are old or partial. `spikegen` is a small, dependency-free generator that returns
+plain lists of floats, so reproducible spike trains are one import away. It pairs with
+[spikedist](https://pypi.org/project/spikedist/): generate trains, then measure the
+distance between them.
+
+## Processes
+
+- `regular(rate, duration)`: evenly spaced spikes. Deterministic.
+- `homogeneous_poisson(rate, duration, seed)`: constant-rate Poisson process.
+- `inhomogeneous_poisson(rate_fn, max_rate, duration, seed)`: time-varying rate by thinning.
+- `gamma_renewal(rate, shape, duration, seed)`: gamma inter-spike intervals; shape 1 is
+  Poisson, larger shape is more regular.
+- `with_refractory(times, refractory)`: drop spikes within a minimum interval.
+
+All parameters are keyword-only and explicit.
+
+## Testing
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Tests cover exact values for the deterministic generators, seeded reproducibility, the
+rate-bound and ordering invariants, and the validation paths, with property tests via
+Hypothesis.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

spikegen-0.1.0/README.md

@@ -0,0 +1,72 @@
+# spikegen
+
+<p align="center">
+  <img src="assets/logo.png" alt="spikegen logo" width="160">
+</p>
+
+[![PyPI](https://img.shields.io/pypi/v/spikegen)](https://pypi.org/project/spikegen/)
+[![CI](https://github.com/amaar-mc/spikegen/actions/workflows/ci.yml/badge.svg)](https://github.com/amaar-mc/spikegen/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+Generate spike trains in pure Python with zero dependencies. Poisson, gamma renewal, regular, and inhomogeneous processes, returned as plain sorted lists of spike times, with explicit seeds for reproducibility.
+
+## Install
+
+```sh
+pip install spikegen
+```
+
+## 30-second example
+
+```python
+from spikegen import homogeneous_poisson, regular, gamma_renewal, with_refractory
+
+homogeneous_poisson(rate=50.0, duration=2.0, seed=0)   # Poisson spikes in [0, 2)
+regular(rate=10.0, duration=1.0)                        # [0.0, 0.1, 0.2, ...]
+gamma_renewal(rate=20.0, shape=2.0, duration=1.0, seed=0)  # more regular than Poisson
+
+spikes = homogeneous_poisson(rate=80.0, duration=1.0, seed=0)
+with_refractory(spikes, refractory=0.002)              # enforce a 2 ms refractory period
+```
+
+Times are in the same units as `1 / rate` (seconds if rate is in Hz). Seeded processes are
+reproducible: the same seed gives the same train.
+
+## Why this exists
+
+Generating synthetic spike trains is a daily need, but the generators live inside heavy
+frameworks: `elephant` requires neo and quantities, `pyspike` is NumPy-based, and other
+options are old or partial. `spikegen` is a small, dependency-free generator that returns
+plain lists of floats, so reproducible spike trains are one import away. It pairs with
+[spikedist](https://pypi.org/project/spikedist/): generate trains, then measure the
+distance between them.
+
+## Processes
+
+- `regular(rate, duration)`: evenly spaced spikes. Deterministic.
+- `homogeneous_poisson(rate, duration, seed)`: constant-rate Poisson process.
+- `inhomogeneous_poisson(rate_fn, max_rate, duration, seed)`: time-varying rate by thinning.
+- `gamma_renewal(rate, shape, duration, seed)`: gamma inter-spike intervals; shape 1 is
+  Poisson, larger shape is more regular.
+- `with_refractory(times, refractory)`: drop spikes within a minimum interval.
+
+All parameters are keyword-only and explicit.
+
+## Testing
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Tests cover exact values for the deterministic generators, seeded reproducibility, the
+rate-bound and ordering invariants, and the validation paths, with property tests via
+Hypothesis.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

spikegen-0.1.0/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Scope
+
+`spikegen` is a pure computation library with no runtime dependencies, no network access,
+and no file system access. The attack surface is limited to incorrect results from
+malformed input, which the library guards against with explicit validation.
+
+## Reporting a vulnerability
+
+If you find a security issue, please email amaar2cool@gmail.com with details and steps to
+reproduce. Please do not open a public issue for security reports. You can expect an
+initial response within a few days.
+
+## Supported versions
+
+The latest published minor version receives fixes. Pre-1.0 releases may introduce breaking
+changes in minor versions, as allowed by semantic versioning.

spikegen-0.1.0/docs/architecture.md

@@ -0,0 +1,45 @@
+# Architecture
+
+`spikegen` is a small set of pure functions over the standard library `random` and `math`.
+Each generator returns a sorted `list[float]` of spike times in `[0, duration)`.
+
+## Regular
+
+`regular` places spikes at `0, 1/rate, 2/rate, ...`. The index is multiplied by the step
+rather than accumulated, so floating-point error does not drift across a long train.
+
+## Homogeneous Poisson
+
+`homogeneous_poisson` draws exponential inter-spike intervals: the next interval is
+`-ln(1 - U) / rate` for a uniform U. Using `1 - U` keeps the argument of the log away from
+zero. Spikes accumulate until the time leaves `[0, duration)`.
+
+## Inhomogeneous Poisson
+
+`inhomogeneous_poisson` uses thinning: propose spikes from a homogeneous process at
+`max_rate`, then keep each proposed spike at time t with probability `rate_fn(t) / max_rate`.
+`rate_fn` must return a value in `[0, max_rate]`; a value outside that range raises, since
+it would make the thinning probability invalid.
+
+## Gamma renewal
+
+`gamma_renewal` draws inter-spike intervals from a gamma distribution with the given shape
+and a scale of `1 / (rate * shape)`, so the mean interval is `1 / rate`. Shape 1 reduces to
+the exponential intervals of a Poisson process; larger shapes give more regular spiking.
+
+## Refractory filter
+
+`with_refractory` sorts the input and keeps a spike only when it is at least `refractory`
+after the previously kept spike, which models an absolute refractory period.
+
+## Reproducibility
+
+Every stochastic generator takes an integer `seed` and uses `random.Random(seed)`, so the
+same arguments always produce the same train. The tests rely on this for exact assertions
+and confirm that different seeds give different trains.
+
+## Why pure Python
+
+The processes are short and standard, and the standard library provides uniform and gamma
+variates. Implementing them with no dependencies keeps installation trivial and the output
+(plain lists of floats) immediately usable, including by spikedist.

spikegen-0.1.0/docs/charter.md

@@ -0,0 +1,32 @@
+# Charter
+
+## Purpose
+
+Provide correct, reproducible, dependency-free spike-train generators that return plain
+lists of spike times, so synthetic spike data is one import away and drops straight into
+other lightweight tools.
+
+## Scope
+
+- The common point processes: regular, homogeneous Poisson, inhomogeneous Poisson (by
+  thinning), and gamma renewal.
+- A refractory-period filter.
+- Explicit seeding for reproducibility.
+
+## Non-goals
+
+- A simulation framework or neuron models. spikegen produces spike times, not dynamics.
+- A required NumPy dependency. NumPy may appear later only as an optional accelerator.
+- Analysis of spike trains. spikedist covers distances and similarities.
+
+## Principles
+
+- Correctness and reproducibility first. Seeded generators are deterministic and tested.
+- Zero runtime dependencies.
+- Small, stable, explicit API. Keyword-only parameters.
+- Plain data out (lists of floats), so it composes with anything.
+
+## Audience
+
+Computational neuroscience researchers and students, and neuromorphic engineers who need
+reproducible synthetic spike trains without a framework.

spikegen-0.1.0/docs/logo-prompt.md

@@ -0,0 +1,11 @@
+# Logo prompt
+
+The logo in `assets/logo.png` was generated with OpenAI `gpt-image-1` (1024x1024,
+medium quality) from this prompt:
+
+> Minimal geometric logo for a library that generates neural spike trains. A single
+> horizontal baseline with thin vertical tick marks at irregular intervals rising from it,
+> like a freshly generated Poisson spike train. Flat vector, premium research-lab
+> aesthetic. White background, black ticks and baseline, one pale blue accent tick. Subtle
+> thin grid. Centered, generous negative space, no text, no letters, no robots, no neon,
+> crisp and high-signal.

spikegen-0.1.0/examples/generate.py

@@ -0,0 +1,19 @@
+"""Generate a few spike trains and print their spike counts.
+
+Run with: python examples/generate.py
+"""
+
+from spikegen import gamma_renewal, homogeneous_poisson, regular, with_refractory
+
+duration = 1.0
+
+poisson = homogeneous_poisson(rate=50.0, duration=duration, seed=0)
+gamma = gamma_renewal(rate=50.0, shape=4.0, duration=duration, seed=0)
+clock = regular(rate=50.0, duration=duration)
+refractory = with_refractory(poisson, refractory=0.005)
+
+print(f"duration: {duration} s, target rate: 50 Hz")
+print(f"  regular            {len(clock)} spikes")
+print(f"  poisson            {len(poisson)} spikes")
+print(f"  gamma (shape 4)    {len(gamma)} spikes")
+print(f"  poisson + 5 ms ref {len(refractory)} spikes")

spikegen-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spikegen"
+version = "0.1.0"
+description = "Generate spike trains (Poisson, gamma renewal, regular, inhomogeneous) in pure Python with zero dependencies."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Amaar Chughtai" }]
+keywords = [
+  "spike-train",
+  "neuroscience",
+  "computational-neuroscience",
+  "neuromorphic",
+  "poisson-process",
+  "renewal-process",
+  "point-process",
+  "spiking-neural-networks",
+  "simulation",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11", "hypothesis>=6"]
+
+[project.urls]
+Homepage = "https://github.com/amaar-mc/spikegen"
+Repository = "https://github.com/amaar-mc/spikegen"
+Issues = "https://github.com/amaar-mc/spikegen/issues"
+Changelog = "https://github.com/amaar-mc/spikegen/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spikegen"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+files = ["src"]

spikegen-0.1.0/src/spikegen/__init__.py

@@ -0,0 +1,18 @@
+"""Generate spike trains in pure Python with zero dependencies."""
+
+from .processes import (
+    gamma_renewal,
+    homogeneous_poisson,
+    inhomogeneous_poisson,
+    regular,
+    with_refractory,
+)
+
+__all__ = [
+    "gamma_renewal",
+    "homogeneous_poisson",
+    "inhomogeneous_poisson",
+    "regular",
+    "with_refractory",
+]
+__version__ = "0.1.0"

spikegen-0.1.0/src/spikegen/_validate.py

@@ -0,0 +1,26 @@
+from math import isfinite
+
+
+def check_rate(rate: float) -> None:
+    if not isfinite(rate) or rate <= 0:
+        raise ValueError(f"rate must be a positive number, received {rate!r}")
+
+
+def check_duration(duration: float) -> None:
+    if not isfinite(duration) or duration < 0:
+        raise ValueError(f"duration must be a non-negative number, received {duration!r}")
+
+
+def check_positive(name: str, value: float) -> None:
+    if not isfinite(value) or value <= 0:
+        raise ValueError(f"{name} must be a positive number, received {value!r}")
+
+
+def check_non_negative(name: str, value: float) -> None:
+    if not isfinite(value) or value < 0:
+        raise ValueError(f"{name} must be a non-negative number, received {value!r}")
+
+
+def check_seed(seed: int) -> None:
+    if not isinstance(seed, int):
+        raise ValueError(f"seed must be an integer, received {seed!r}")

spikegen-0.1.0/src/spikegen/processes.py

@@ -0,0 +1,102 @@
+import math
+import random
+from collections.abc import Callable, Sequence
+
+from ._validate import (
+    check_duration,
+    check_non_negative,
+    check_positive,
+    check_rate,
+    check_seed,
+)
+
+
+def regular(*, rate: float, duration: float) -> list[float]:
+    """Evenly spaced spikes at 0, 1/rate, 2/rate, ... within [0, duration). Deterministic.
+    Indices are multiplied by the step rather than accumulated to avoid floating drift."""
+    check_rate(rate)
+    check_duration(duration)
+    step = 1.0 / rate
+    times: list[float] = []
+    i = 0
+    t = 0.0
+    while t < duration:
+        times.append(t)
+        i += 1
+        t = i * step
+    return times
+
+
+def homogeneous_poisson(*, rate: float, duration: float, seed: int) -> list[float]:
+    """Homogeneous Poisson process on [0, duration) with the given rate, drawing
+    exponential inter-spike intervals. Seeded for reproducibility."""
+    check_rate(rate)
+    check_duration(duration)
+    check_seed(seed)
+    rng = random.Random(seed)
+    times: list[float] = []
+    t = 0.0
+    while True:
+        # 1 - U avoids log(0) when U happens to be 0.
+        t += -math.log(1.0 - rng.random()) / rate
+        if t >= duration:
+            break
+        times.append(t)
+    return times
+
+
+def inhomogeneous_poisson(
+    *, rate_fn: Callable[[float], float], max_rate: float, duration: float, seed: int
+) -> list[float]:
+    """Inhomogeneous Poisson process by thinning: propose spikes at max_rate and keep each
+    at time t with probability rate_fn(t) / max_rate. rate_fn must return a value in
+    [0, max_rate] for every t in [0, duration). Seeded for reproducibility."""
+    check_positive("max_rate", max_rate)
+    check_duration(duration)
+    check_seed(seed)
+    rng = random.Random(seed)
+    times: list[float] = []
+    t = 0.0
+    while True:
+        t += -math.log(1.0 - rng.random()) / max_rate
+        if t >= duration:
+            break
+        rate = rate_fn(t)
+        if rate < 0.0 or rate > max_rate:
+            raise ValueError(f"rate_fn returned {rate!r} at t={t!r}, outside [0, max_rate]")
+        if rng.random() < rate / max_rate:
+            times.append(t)
+    return times
+
+
+def gamma_renewal(*, rate: float, shape: float, duration: float, seed: int) -> list[float]:
+    """Gamma renewal process: inter-spike intervals follow a gamma distribution with the
+    given shape and a mean of 1/rate. shape = 1 reduces to a Poisson process; larger shape
+    gives more regular spiking. Seeded for reproducibility."""
+    check_rate(rate)
+    check_positive("shape", shape)
+    check_duration(duration)
+    check_seed(seed)
+    rng = random.Random(seed)
+    scale = 1.0 / (rate * shape)  # mean interval = shape * scale = 1 / rate
+    times: list[float] = []
+    t = 0.0
+    while True:
+        t += rng.gammavariate(shape, scale)
+        if t >= duration:
+            break
+        times.append(t)
+    return times
+
+
+def with_refractory(times: Sequence[float], *, refractory: float) -> list[float]:
+    """Enforce a minimum inter-spike interval by dropping each spike that falls within
+    refractory of the previously kept spike. Inputs are sorted first."""
+    check_non_negative("refractory", refractory)
+    kept: list[float] = []
+    last: float | None = None
+    for t in sorted(times):
+        if last is None or t - last >= refractory:
+            kept.append(t)
+            last = t
+    return kept

spikegen-0.1.0/tests/test_processes.py

@@ -0,0 +1,65 @@
+import pytest
+
+from spikegen import (
+    gamma_renewal,
+    homogeneous_poisson,
+    inhomogeneous_poisson,
+    regular,
+    with_refractory,
+)
+
+
+def test_regular_exact() -> None:
+    assert regular(rate=2.0, duration=1.0) == [0.0, 0.5]
+    assert regular(rate=1.0, duration=3.0) == [0.0, 1.0, 2.0]
+    assert regular(rate=10.0, duration=0.0) == []
+
+
+def test_with_refractory_exact() -> None:
+    assert with_refractory([0.0, 0.1, 0.15, 0.3], refractory=0.12) == [0.0, 0.15, 0.3]
+    assert with_refractory([0.3, 0.0, 0.1], refractory=0.05) == [0.0, 0.1, 0.3]
+
+
+def test_homogeneous_reproducible_and_structural() -> None:
+    a = homogeneous_poisson(rate=50.0, duration=2.0, seed=7)
+    assert a == homogeneous_poisson(rate=50.0, duration=2.0, seed=7)
+    assert homogeneous_poisson(rate=50.0, duration=2.0, seed=8) != a
+    assert all(0.0 <= t < 2.0 for t in a)
+    assert a == sorted(a)
+    assert all(a[i] < a[i + 1] for i in range(len(a) - 1))
+
+
+def test_gamma_reproducible_and_in_range() -> None:
+    g = gamma_renewal(rate=20.0, shape=2.0, duration=5.0, seed=3)
+    assert g == gamma_renewal(rate=20.0, shape=2.0, duration=5.0, seed=3)
+    assert all(0.0 <= t < 5.0 for t in g)
+    assert g == sorted(g)
+
+
+def test_inhomogeneous_zero_rate_gives_no_spikes() -> None:
+    assert inhomogeneous_poisson(rate_fn=lambda t: 0.0, max_rate=100.0, duration=1.0, seed=1) == []
+
+
+def test_inhomogeneous_reproducible_and_in_range() -> None:
+    def rate_fn(t: float) -> float:
+        return 50.0 if t < 0.5 else 5.0
+
+    a = inhomogeneous_poisson(rate_fn=rate_fn, max_rate=50.0, duration=1.0, seed=2)
+    assert a == inhomogeneous_poisson(rate_fn=rate_fn, max_rate=50.0, duration=1.0, seed=2)
+    assert all(0.0 <= t < 1.0 for t in a)
+
+
+def test_inhomogeneous_rejects_out_of_range_rate() -> None:
+    with pytest.raises(ValueError):
+        inhomogeneous_poisson(rate_fn=lambda t: 200.0, max_rate=50.0, duration=1.0, seed=1)
+
+
+def test_validation() -> None:
+    with pytest.raises(ValueError):
+        regular(rate=0.0, duration=1.0)
+    with pytest.raises(ValueError):
+        homogeneous_poisson(rate=10.0, duration=-1.0, seed=1)
+    with pytest.raises(ValueError):
+        gamma_renewal(rate=10.0, shape=0.0, duration=1.0, seed=1)
+    with pytest.raises(ValueError):
+        with_refractory([0.0], refractory=-0.1)

spikegen-0.1.0/tests/test_properties.py

@@ -0,0 +1,25 @@
+from hypothesis import given
+from hypothesis import strategies as st
+
+from spikegen import gamma_renewal, homogeneous_poisson
+
+rates = st.floats(min_value=1.0, max_value=200.0, allow_nan=False, allow_infinity=False)
+durations = st.floats(min_value=0.0, max_value=3.0, allow_nan=False, allow_infinity=False)
+shapes = st.floats(min_value=0.5, max_value=5.0, allow_nan=False, allow_infinity=False)
+seeds = st.integers(min_value=0, max_value=100000)
+
+
+@given(rates, durations, seeds)
+def test_poisson_is_sorted_and_in_range(rate: float, duration: float, seed: int) -> None:
+    spikes = homogeneous_poisson(rate=rate, duration=duration, seed=seed)
+    assert spikes == sorted(spikes)
+    assert all(0.0 <= t < duration for t in spikes)
+
+
+@given(rates, shapes, durations, seeds)
+def test_gamma_is_sorted_and_in_range(
+    rate: float, shape: float, duration: float, seed: int
+) -> None:
+    spikes = gamma_renewal(rate=rate, shape=shape, duration=duration, seed=seed)
+    assert spikes == sorted(spikes)
+    assert all(0.0 <= t < duration for t in spikes)