Metadata-Version: 2.4
Name: super-neuron-core
Version: 1.1.1
Summary: Reference-compatible and public-product scalar Super Neuron core
License-Expression: Apache-2.0
Keywords: neuron,phase2a,rk4,scientific-computing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: <4,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# super-neuron-core

`super-neuron-core` is a standalone, dependency-free Python distribution with
two explicitly labeled paths:

- a frozen, Phase 2A-compatible reference path; and
- a public-product path for explicit parameter configuration and deterministic
  scalar simulation helpers.

It is separate from both the research repository and the existing
`superNeuron` runtime.

## Install

```bash
pip install super-neuron-core==1.1.1
```

## Reference mode

```python
from super_neuron_core import SuperNeuron

neuron = SuperNeuron.reference()
state = neuron.initial_state()
state, output = neuron.step(
    state=state,
    input_current_mA_per_cm2=6.0,
    dt_ms=0.025,
)
print(state.v_mV, output.spike, output.threshold_crossing)
```

The functional API is equivalent:

```python
from super_neuron_core import neuron_step, neuron_step_batch

state, output = neuron_step(state, 6.0, dt_ms=0.025)
states, outputs = neuron_step_batch([state], [6.0], dt_ms=0.025)
```

`SuperNeuron.reference()` and `SuperNeuron.preset("phase2a-reference")` retain
the frozen Phase 2A parameters and `dt_ms=0.025`. The threshold is 0 mV and an
output is true only for an upward crossing from below 0 mV to at least 0 mV
during a step. There is no reset, refractory suppression, plasticity, routing,
network behavior, parameter fitting, or adapter layer.

## Product mode

Product mode makes configuration explicit. It does not modify reference mode
or its state/output serialization identity.

```python
from super_neuron_core import constant_current, custom_neuron, simulate

neuron = custom_neuron(resting_potential_mV=-65.0)
trace = simulate(neuron, constant_current(6.0, duration_ms=2.0))

print(trace.times_ms[-1], trace.voltages_mV[-1])
trace.write_json("trace.json")
trace.write_csv("trace.csv")
```

`SuperNeuron.preset("product-default")` and `product_default_neuron()` create
a `ProductNeuron` whose parameters intentionally equal the 1.0.1 reference
defaults. It remains product mode with product configuration serialization; it
is not the frozen reference object or its state/output serialization identity.
The available named presets are returned by `available_presets()`.

Product input programs use explicit units:

- `constant_current(amplitude_mA_per_cm2, duration_ms, dt_ms=...)`
- `pulse_train(amplitude_mA_per_cm2, start_ms=..., pulse_width_ms=...,
  interval_ms=..., count=..., duration_ms=..., dt_ms=...)`

`simulate()` creates an immutable trace with dependency-free JSON and CSV
export. `plot_voltage()` is optional and requires `matplotlib` only when it is
called.

### Exploratory timestep configuration

Product mode can use an explicit exploratory timestep. Users must validate
timestep sensitivity for their own protocol; this package makes no general
accuracy or performance claim for non-reference timesteps.

```python
from super_neuron_core import constant_current, custom_neuron, simulate

neuron = custom_neuron(dt_ms=0.2)
trace = simulate(
    neuron,
    constant_current(6.0, duration_ms=2.0, dt_ms=neuron.dt_ms),
)
```

### Known limitations

The frozen scalar dynamics are a deterministic phasic/excitability reference
model, not a tonic-spiking Hodgkin–Huxley replacement. Sustained-current
depolarization block is a known limitation in tested regimes. Product mode
supports explicit parameter exploration, but no bundled tonic-spiking preset
is validated or provided.

The batch API intentionally uses deterministic scalar-semantics iteration; it
does not claim vectorized performance.

The supported public-surface and identity rules are documented in
[`INTEROPERABILITY.md`](INTEROPERABILITY.md). The package includes a `py.typed`
marker for static type-checking consumers.

## Release boundary

Versions 1.0.x preserve the frozen/reference-compatible scalar line. Versions
1.1.0 and 1.1.1 add public-product configuration, simulation helpers, and
direct convenience imports while keeping an explicit, regression-tested
reference mode. Product features are not Phase 2A evidence claims, even where
product-default uses the same numerical values. Any future reference semantic
correction must be explicitly documented with regression evidence.

Phase 65 remains bound to the archived immutable
`super-neuron-core==1.0.0` wheel. Version 1.0.1 does not alter, supersede, or
reinterpret Phase 65 evidence.

## Package boundary

This package imports no `bio-neuron`, `superNeuron`, NumPy, Torch, JAX, Brian2,
or NEST code. Version 1.0.0 is the immutable public Phase 2A reference
release. The 1.1.x reference mode retains its model parameters, timestep,
state fields, and serialized scientific identity. Product configuration is
separate and only permits explicit overrides of existing parameter fields.
Runtime replacement, parameter fitting, framework adapters, and
biological-validity claims remain outside the core release boundary.

The package is licensed under Apache-2.0. Benchmark tooling and performance
probes live in the separate `super-neuron-core-benchmarks` project and are not
runtime dependencies of this distribution.

For a reproducible local dry-run after installing the build tool, use
`python tools/build_release.py --outdir <output-directory> --epoch 1760000000`.
The helper normalizes source-archive metadata; it does not upload or publish
anything.
