Metadata-Version: 2.4
Name: super-neuron-core
Version: 1.1.0
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.0
```

## 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 SuperNeuron, constant_current, simulate

neuron = SuperNeuron.custom(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")` is a product-mode convenience preset
whose values intentionally equal the 1.0.1 reference defaults. It does not
silently introduce a non-reference parameter profile. 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.

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. Version
1.1.0 adds public-product configuration and simulation helpers 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.0 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.
