spikedist 0.2.0__tar.gz

spikedist-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: A wrong distance or unexpected behavior
+title: ""
+labels: bug
+---
+
+## Input
+
+The two spike trains and the parameters, for example
+`victor_purpura([0.0, 1.0], [0.5], cost=1.0)`.
+
+## Expected
+
+The value you expected, with a source if it is a published reference.
+
+## Actual
+
+The value you observed.
+
+## Environment
+
+- spikedist version:
+- Python version:

spikedist-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

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

spikedist-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Summary
+
+What this changes and why.
+
+## Checklist
+
+- [ ] Tests added or updated (a bug fix starts with a failing test)
+- [ ] Exact reference-value test for any new metric
+- [ ] Property tests for the relevant metric axioms
+- [ ] `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

spikedist-0.2.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

spikedist-0.2.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

spikedist-0.2.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# 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 van Rossum.
+- Fast O(n) van Rossum via the Houghton-Kreuz markage recursion.
+- An optional NumPy fast path for large pairwise computations.
+
+## [0.2.0]
+
+### Added
+- `schreiber(a, b, *, sigma)`: Gaussian correlation similarity in [0, 1].
+- `hunter_milton(a, b, *, tau)`: nearest-neighbor similarity in (0, 1].
+- `pairwise(trains, metric)`: full matrix of any metric over a list of trains.
+
+## [0.1.0]
+
+### Added
+- `victor_purpura(a, b, *, cost)`: Victor-Purpura distance via an O(n*m) dynamic program.
+- `van_rossum(a, b, *, tau)`: van Rossum distance via the closed form of the exponential-kernel inner products.
+- Input validation with clear errors; spikes treated as an unordered set and sorted internally.
+- Test suite with exact closed-form reference values and Hypothesis property tests for the metric axioms.

spikedist-0.2.0/CLAUDE.md

@@ -0,0 +1,45 @@
+# spikedist
+
+Pure-Python spike-train distance metrics. Zero runtime dependencies.
+
+## 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 twine check dist/*` before publishing)
+
+## Architecture
+
+`src/spikedist/` with one module per metric:
+- `_validate.py` shared input validation; returns sorted finite spike times
+- `victor_purpura.py` edit distance via an O(n*m) dynamic program
+- `van_rossum.py` kernel distance via the closed form of exponential-kernel inner products
+- `__init__.py` public surface
+
+See `docs/architecture.md` for the algorithms and the van Rossum normalization.
+
+## Conventions
+
+- Pure functions, strict typing, zero runtime dependencies.
+- Metric parameters (`cost`, `tau`) are required keyword-only arguments; no default values.
+- Spikes are an unordered set of times, sorted internally.
+- Validate inputs and raise clear ValueError messages on bad data.
+
+## Testing rules
+
+- Exact closed-form reference values for each metric (see README definitions).
+- Property tests (Hypothesis) for metric axioms: identity, symmetry, non-negativity, triangle inequality.
+- 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/*`.
+- Prefer TestPyPI first, then PyPI. Tag `vX.Y.Z` and a GitHub release.
+
+## Style
+
+- No em dash characters in docs, comments, or commit messages.
+- Comments explain non-obvious reasoning only.

spikedist-0.2.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.

spikedist-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to spikedist
+
+Thanks for your interest. This project values correctness, a small surface area,
+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
+```
+
+If you do not use uv, a standard virtual environment with `pip install -e ".[dev]"`
+works the same way.
+
+## Guidelines
+
+- No runtime dependencies. NumPy and friends may be optional accelerators only.
+- Every metric needs exact reference-value tests and property tests for the
+  metric axioms it satisfies (identity, symmetry, non-negativity, and the
+  triangle inequality where it holds).
+- Metric parameters are required keyword-only arguments. No default values.
+- Keep functions pure and fully typed; `mypy --strict` must pass.
+- A bug fix starts with a failing test.
+- Commit messages follow `type(scope): description`.
+
+## Adding a metric
+
+State the definition and its normalization in the docstring and the README, give
+at least one exact closed-form test case, and add the relevant property tests.
+
+## Reporting issues
+
+Open an issue with the two spike trains, the parameters, the expected value with
+a source, and the value you observed.

spikedist-0.2.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.

spikedist-0.2.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: spikedist
+Version: 0.2.0
+Summary: Spike-train distance and similarity metrics (Victor-Purpura, van Rossum, Schreiber, Hunter-Milton) in pure Python with zero dependencies.
+Project-URL: Homepage, https://github.com/amaar-mc/spikedist
+Project-URL: Repository, https://github.com/amaar-mc/spikedist
+Project-URL: Issues, https://github.com/amaar-mc/spikedist/issues
+Project-URL: Changelog, https://github.com/amaar-mc/spikedist/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,spike-distance,spike-metric,spike-train,spiking-neural-networks,van-rossum,victor-purpura
+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
+
+# spikedist
+
+[![CI](https://github.com/amaar-mc/spikedist/actions/workflows/ci.yml/badge.svg)](https://github.com/amaar-mc/spikedist/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+Spike-train distance and similarity metrics in pure Python with zero dependencies. Implements the Victor-Purpura and van Rossum distances and the Schreiber and Hunter-Milton similarities on plain sequences of spike times.
+
+## Install
+
+```sh
+pip install spikedist
+```
+
+## 30-second example
+
+```python
+from spikedist import victor_purpura, van_rossum, schreiber, hunter_milton
+
+a = [0.010, 0.025, 0.090]   # spike times in seconds
+b = [0.012, 0.030, 0.095]
+
+victor_purpura(a, b, cost=100.0)  # edit distance, cost is the q parameter
+van_rossum(a, b, tau=0.012)       # kernel distance, tau is the time constant
+schreiber(a, b, sigma=0.010)      # Gaussian correlation similarity in [0, 1]
+hunter_milton(a, b, tau=0.012)    # nearest-neighbor similarity in (0, 1]
+```
+
+Spike times can be Python lists, tuples, or any sequence of numbers, including
+NumPy arrays. They are treated as an unordered set of event times and sorted
+internally. There is no NumPy requirement.
+
+## Why this exists
+
+The Victor-Purpura and van Rossum distances are two of the most cited spike-train
+metrics, but every Python implementation lives inside a heavy framework or a
+compiled extension:
+
+- `elephant` implements both, but requires `neo` and `quantities` and works on
+  `neo.SpikeTrain` objects with units.
+- `pymuvr` is a fast multi-unit van Rossum implementation, but is a C++ extension
+  and requires NumPy.
+- `pyspike` is excellent for ISI-distance, SPIKE-distance, and SPIKE-synchrony,
+  but does not implement Victor-Purpura or van Rossum.
+
+`spikedist` is a small, typed, dependency-free package for when you just want the
+distance between two spike trains.
+
+## Definitions
+
+### Victor-Purpura
+
+`victor_purpura(a, b, *, cost)` is the minimum total cost to turn train `a` into
+train `b` using three operations: insert a spike (cost 1), delete a spike
+(cost 1), and shift a spike by `dt` (cost `cost * abs(dt)`). `cost` is the
+parameter usually written `q`. It is computed with an O(n*m) dynamic program.
+
+- `cost = 0` counts only the difference in spike count.
+- As `cost` grows, shifting becomes expensive and each unmatched spike approaches
+  a cost of 2.
+
+### van Rossum
+
+`van_rossum(a, b, *, tau)` convolves each train with a causal exponential kernel
+`exp(-t / tau)` and returns the Euclidean distance between the filtered signals.
+Using the closed form of the kernel inner products,
+
+```
+D^2 = 0.5 * (Saa + Sbb - 2 * Sab),  Sxy = sum over spike pairs exp(-|xi - yj| / tau)
+```
+
+With this normalization the distance between an empty train and a single spike is
+`sqrt(0.5)`, and as `tau` grows large the distance approaches
+`abs(len(a) - len(b)) / sqrt(2)`.
+
+Both distances are true metrics: non-negative, symmetric, zero only between equal
+trains, and they satisfy the triangle inequality. These properties are tested.
+
+### Schreiber similarity
+
+`schreiber(a, b, *, sigma)` convolves each train with a Gaussian of width `sigma`
+and returns the cosine similarity of the filtered signals, in `[0, 1]`. It is 1
+for identical trains.
+
+### Hunter-Milton similarity
+
+`hunter_milton(a, b, *, tau)` scores each spike by `exp(-dt / tau)` to its nearest
+neighbor in the other train and averages over both trains, giving a value in
+`(0, 1]`. It is 1 for identical trains.
+
+By convention both similarities treat two empty trains as identical (1.0) and a
+non-empty train against an empty one as fully dissimilar (0.0).
+
+### Pairwise matrices
+
+`pairwise(trains, metric)` builds the full matrix of any metric over a list of
+trains. Parameterize the metric with `functools.partial`:
+
+```python
+from functools import partial
+from spikedist import pairwise, van_rossum
+
+pairwise(trains, partial(van_rossum, tau=0.01))
+```
+
+## Roadmap
+
+- Multi-unit van Rossum.
+- Fast O(n) van Rossum via the Houghton-Kreuz markage recursion.
+- An optional NumPy fast path for large pairwise computations.
+
+## Testing
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Tests cover exact closed-form reference values and metric-property invariants
+(identity, symmetry, non-negativity, triangle inequality) via Hypothesis.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

spikedist-0.2.0/README.md

@@ -0,0 +1,127 @@
+# spikedist
+
+[![CI](https://github.com/amaar-mc/spikedist/actions/workflows/ci.yml/badge.svg)](https://github.com/amaar-mc/spikedist/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+Spike-train distance and similarity metrics in pure Python with zero dependencies. Implements the Victor-Purpura and van Rossum distances and the Schreiber and Hunter-Milton similarities on plain sequences of spike times.
+
+## Install
+
+```sh
+pip install spikedist
+```
+
+## 30-second example
+
+```python
+from spikedist import victor_purpura, van_rossum, schreiber, hunter_milton
+
+a = [0.010, 0.025, 0.090]   # spike times in seconds
+b = [0.012, 0.030, 0.095]
+
+victor_purpura(a, b, cost=100.0)  # edit distance, cost is the q parameter
+van_rossum(a, b, tau=0.012)       # kernel distance, tau is the time constant
+schreiber(a, b, sigma=0.010)      # Gaussian correlation similarity in [0, 1]
+hunter_milton(a, b, tau=0.012)    # nearest-neighbor similarity in (0, 1]
+```
+
+Spike times can be Python lists, tuples, or any sequence of numbers, including
+NumPy arrays. They are treated as an unordered set of event times and sorted
+internally. There is no NumPy requirement.
+
+## Why this exists
+
+The Victor-Purpura and van Rossum distances are two of the most cited spike-train
+metrics, but every Python implementation lives inside a heavy framework or a
+compiled extension:
+
+- `elephant` implements both, but requires `neo` and `quantities` and works on
+  `neo.SpikeTrain` objects with units.
+- `pymuvr` is a fast multi-unit van Rossum implementation, but is a C++ extension
+  and requires NumPy.
+- `pyspike` is excellent for ISI-distance, SPIKE-distance, and SPIKE-synchrony,
+  but does not implement Victor-Purpura or van Rossum.
+
+`spikedist` is a small, typed, dependency-free package for when you just want the
+distance between two spike trains.
+
+## Definitions
+
+### Victor-Purpura
+
+`victor_purpura(a, b, *, cost)` is the minimum total cost to turn train `a` into
+train `b` using three operations: insert a spike (cost 1), delete a spike
+(cost 1), and shift a spike by `dt` (cost `cost * abs(dt)`). `cost` is the
+parameter usually written `q`. It is computed with an O(n*m) dynamic program.
+
+- `cost = 0` counts only the difference in spike count.
+- As `cost` grows, shifting becomes expensive and each unmatched spike approaches
+  a cost of 2.
+
+### van Rossum
+
+`van_rossum(a, b, *, tau)` convolves each train with a causal exponential kernel
+`exp(-t / tau)` and returns the Euclidean distance between the filtered signals.
+Using the closed form of the kernel inner products,
+
+```
+D^2 = 0.5 * (Saa + Sbb - 2 * Sab),  Sxy = sum over spike pairs exp(-|xi - yj| / tau)
+```
+
+With this normalization the distance between an empty train and a single spike is
+`sqrt(0.5)`, and as `tau` grows large the distance approaches
+`abs(len(a) - len(b)) / sqrt(2)`.
+
+Both distances are true metrics: non-negative, symmetric, zero only between equal
+trains, and they satisfy the triangle inequality. These properties are tested.
+
+### Schreiber similarity
+
+`schreiber(a, b, *, sigma)` convolves each train with a Gaussian of width `sigma`
+and returns the cosine similarity of the filtered signals, in `[0, 1]`. It is 1
+for identical trains.
+
+### Hunter-Milton similarity
+
+`hunter_milton(a, b, *, tau)` scores each spike by `exp(-dt / tau)` to its nearest
+neighbor in the other train and averages over both trains, giving a value in
+`(0, 1]`. It is 1 for identical trains.
+
+By convention both similarities treat two empty trains as identical (1.0) and a
+non-empty train against an empty one as fully dissimilar (0.0).
+
+### Pairwise matrices
+
+`pairwise(trains, metric)` builds the full matrix of any metric over a list of
+trains. Parameterize the metric with `functools.partial`:
+
+```python
+from functools import partial
+from spikedist import pairwise, van_rossum
+
+pairwise(trains, partial(van_rossum, tau=0.01))
+```
+
+## Roadmap
+
+- Multi-unit van Rossum.
+- Fast O(n) van Rossum via the Houghton-Kreuz markage recursion.
+- An optional NumPy fast path for large pairwise computations.
+
+## Testing
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Tests cover exact closed-form reference values and metric-property invariants
+(identity, symmetry, non-negativity, triangle inequality) via Hypothesis.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

spikedist-0.2.0/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Scope
+
+`spikedist` 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.

spikedist-0.2.0/docs/architecture.md

@@ -0,0 +1,91 @@
+# Architecture
+
+`spikedist` is a small set of pure functions, one module per metric, sharing a
+single input-validation helper. There is no shared state and no I/O.
+
+## Input handling
+
+`_validate.check_train` converts any sequence of numbers to a list of floats,
+rejects non-finite values with a clear error, and sorts ascending. Spikes are
+treated as an unordered set of event times, so callers do not need to pre-sort.
+
+## Victor-Purpura distance
+
+`victor_purpura(a, b, *, cost)` is computed with the standard dynamic program.
+Let `g[i][j]` be the minimum cost to align the first `i` spikes of `a` with the
+first `j` spikes of `b`. Then
+
+```
+g[0][j] = j
+g[i][0] = i
+g[i][j] = min(
+    g[i-1][j] + 1,                      # delete a_i
+    g[i][j-1] + 1,                      # insert b_j
+    g[i-1][j-1] + cost * |a_i - b_j|,   # shift a_i onto b_j
+)
+```
+
+The implementation keeps only the previous row, so it runs in O(n*m) time and
+O(m) memory.
+
+## van Rossum distance
+
+`van_rossum(a, b, *, tau)` uses the closed form of the distance between the two
+trains after convolution with a causal exponential kernel `exp(-t / tau)`. The
+inner product of two filtered trains is, up to the shared factor `tau / 2`,
+
+```
+S(x, y) = sum over spike pairs exp(-|xi - yj| / tau)
+```
+
+so the squared distance is
+
+```
+D^2 = 0.5 * (S(a, a) + S(b, b) - 2 * S(a, b))
+```
+
+This avoids numerical integration. A tiny negative value from floating-point
+cancellation is clamped to zero before the square root.
+
+### Normalization
+
+With this definition the distance between an empty train and a single spike is
+`sqrt(0.5)`, and as `tau` grows large the distance approaches
+`|len(a) - len(b)| / sqrt(2)`. The choice is stated so results are reproducible
+and comparable. Libraries that normalize the empty-versus-single distance to 1
+differ from this by a constant factor.
+
+## Schreiber similarity
+
+`schreiber(a, b, *, sigma)` is the cosine similarity of the two trains after
+convolution with a Gaussian of standard deviation `sigma`. The Gaussian inner
+product reduces to a closed form, so with `K(d) = exp(-d^2 / (4 * sigma^2))` and
+`S(x, y) = sum over spike pairs K(xi - yj)` the similarity is
+
+```
+S(a, b) / sqrt(S(a, a) * S(b, b))
+```
+
+Cauchy-Schwarz bounds this by 1; a tiny floating-point overshoot is clamped. Two
+empty trains are defined as similarity 1.0 and a single empty train as 0.0.
+
+## Hunter-Milton similarity
+
+`hunter_milton(a, b, *, tau)` scores each spike by `exp(-dt / tau)` where `dt` is
+the distance to its nearest neighbor in the other train, averages that over one
+train, and then averages the two directions. Nearest neighbors are found by
+binary search on the sorted target train, so the cost is O((n + m) log m). The
+empty-train conventions match the Schreiber measure.
+
+## Pairwise matrices
+
+`pairwise(trains, metric)` evaluates a caller-supplied metric over every ordered
+pair of trains and returns a list of rows. It assumes nothing about the metric,
+so it makes no symmetry shortcut; the cost is O(n^2) metric calls.
+
+## Why pure Python
+
+The two metrics are short, well-specified algorithms. Implementing them without
+NumPy keeps installation trivial and the package usable anywhere. A NumPy fast
+path for large pairwise computations is planned as an optional extra, never a
+hard requirement.