Metadata-Version: 2.5
Name: spikecraft
Version: 0.1.0
Summary: Write spiking-neuron equations, get trainable PyTorch layers. Includes a model zoo (LIF, ALIF, Izhikevich, AdEx, Hodgkin-Huxley, ...).
Project-URL: Homepage, https://github.com/<your-username>/spikecraft
Author: Sanaullah
License-Expression: MIT
License-File: LICENSE
Keywords: neuromorphic,neuron models,pytorch,snn,spiking neural networks,surrogate gradient
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Requires-Dist: sympy>=1.12
Requires-Dist: torch>=2.0
Provides-Extra: bench
Requires-Dist: numpy; extra == 'bench'
Requires-Dist: snntorch>=0.9; extra == 'bench'
Requires-Dist: tonic>=1.4; extra == 'bench'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: numpy; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# spikecraft

Write a spiking neuron as equations, get a trainable PyTorch layer. Or pick one from the zoo — every zoo model is itself just an equation preset you can open and edit.

```bash
pip install spikecraft        # after publishing; for now: pip install -e .
```

## 1. Your own neuron from equations

```python
import spikecraft as sf

neuron = sf.Neuron(
    equations="""
        dv/dt = (-(v - v_rest) + R*I) / tau
        da/dt = -a / tau_a
    """,
    threshold="v > v_th + beta*a",
    reset="v = v_reset; a += 1",
    params=dict(tau=10.0, tau_a=100.0, beta=0.2, R=1.0, v_rest=0.0, v_reset=0.0, v_th=1.0),
    learnable=["tau", "beta"], per_neuron=True,   # trained by backprop, one value per neuron
    surrogate="atan",                             # fast_sigmoid | sigmoid | atan | triangle | gaussian
    solver="exp_euler",                           # exact exponential step where the ODE allows
)
layer = sf.SpikingLinear(neuron, in_features=128, out_features=64)
spikes = layer(x)          # x: [T, B, 128] -> [T, B, 64]
```

- `I` is the input current (rename with `input="..."`). `dt` and time constants share one unit (ms by convention).
- Functions: `exp, log, sqrt, tanh, sin, cos, abs, max, min, sigmoid, heaviside`.
- Reset supports `=`, `+=`, `-=`, `*=`. Leave `reset=None` and use `threshold_mode="rising"` for models without reset (e.g. Hodgkin–Huxley).
- Mistakes are caught early: unknown symbols, malformed equations, resets on missing states.

## 2. Model zoo

```python
from spikecraft import zoo
zoo.list_models()
# ['ALIF', 'AdEx', 'EIF', 'HodgkinHuxley', 'Izhikevich', 'LIF', 'QIF',
#  'ResonateAndFire', 'SynapticLIF', 'TwoCompartment']

lif  = zoo.LIF(tau=20.0, learnable=["tau"])
izh  = zoo.Izhikevich(firing="chattering")   # regular_spiking, intrinsically_bursting, fast_spiking, ...
hh   = zoo.HodgkinHuxley()
print(zoo.AdEx())                             # shows its equations and params
```

Edit a preset's equations directly:

```python
spec = zoo.spec("LIF")
spec["equations"] = "dv/dt = (-(v - v_rest) + R*I + bias) / tau"
spec["params"]["bias"] = 0.1
my_lif = sf.Neuron(**spec)
```

| Model | States | Notes |
|---|---|---|
| LIF | v | leaky integrate-and-fire |
| SynapticLIF | i, v | current-based synapse filter |
| ALIF | v, a | adaptive threshold |
| QIF / EIF | v | quadratic / exponential IF |
| Izhikevich | v, u | 6 named firing types |
| AdEx | v, w | Brette–Gerstner, pA / mV |
| HodgkinHuxley | v, m, h, n | gates integrated exactly (Rush–Larsen) |
| ResonateAndFire | x, y | damped oscillator |
| TwoCompartment | vd, vs | dendrite input, somatic spike |

## 3. Layers and utilities

- `SpikingLinear`, `SpikingConv2d`, and `Spiking(any_module, neuron)` for any synapse. `recurrent=True` adds recurrent weights.
- Neurons are plain `nn.Module`s: `neuron.step(I, state)` for custom loops, `neuron(I_seq, return_states=True)` for traces.
- `sf.encoding.rate`, `latency`, `repeat`, `spike_count`.
- `torch.save` / `state_dict` work as usual.

## How it works

Equations are parsed with SymPy and compiled to PyTorch. For each state `x` the solver computes `A = ∂f/∂x`; if `A` doesn't depend on `x`, the step is the exact exponential update `x ← x·e^{AΔt} + (e^{AΔt}−1)/A · (f − Ax)`, otherwise forward Euler. Spikes use a Heaviside forward pass with a surrogate gradient backward pass.

## Development

```bash
pip install -e ".[dev]"
pytest
python examples/train_custom_vs_zoo.py
python -m build && twine upload dist/*
```

## License

MIT
