Metadata-Version: 2.4
Name: jaxfne
Version: 0.4.20
Summary: JAX Field Neural Equations: a source-to-field neurophysiology engine for TFNE models.
Project-URL: Homepage, https://github.com/HNXJ/jaxfne
Project-URL: Repository, https://github.com/HNXJ/jaxfne
Project-URL: Documentation, https://jaxfne.readthedocs.io/en/latest/
Project-URL: Issues, https://github.com/HNXJ/jaxfne/issues
Project-URL: Changelog, https://github.com/HNXJ/jaxfne/blob/main/docs/changelog.md
Project-URL: Citation, https://github.com/HNXJ/jaxfne/blob/main/CITATION.cff
Project-URL: Source Code, https://github.com/HNXJ/jaxfne
Author: Hamed Nejat
License: MIT
License-File: LICENSE
Keywords: Izhikevich,JAX,LFP,computational neuroscience,laminar cortex,neural simulation,neuroscience,spectrolaminar
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: jax<0.11,>=0.4.25
Requires-Dist: jaxlib<0.11,>=0.4.25
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: all
Requires-Dist: build; extra == 'all'
Requires-Dist: h5py; extra == 'all'
Requires-Dist: ipykernel; extra == 'all'
Requires-Dist: ipywidgets; extra == 'all'
Requires-Dist: jaxley>=0.13.0; extra == 'all'
Requires-Dist: kaleido; extra == 'all'
Requires-Dist: matplotlib<3.11,>=3.10.9; extra == 'all'
Requires-Dist: nbclient; extra == 'all'
Requires-Dist: nbformat; extra == 'all'
Requires-Dist: optax>=0.2; extra == 'all'
Requires-Dist: pandas; extra == 'all'
Requires-Dist: pillow; extra == 'all'
Requires-Dist: plotly; extra == 'all'
Requires-Dist: pytest; extra == 'all'
Requires-Dist: pytest-cov; extra == 'all'
Requires-Dist: pytest-xdist; extra == 'all'
Requires-Dist: pyyaml; extra == 'all'
Requires-Dist: reportlab; extra == 'all'
Requires-Dist: ruff==0.16.2; extra == 'all'
Requires-Dist: scipy==1.17.1; extra == 'all'
Requires-Dist: zarr; extra == 'all'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: ipykernel; extra == 'dev'
Requires-Dist: ipywidgets; extra == 'dev'
Requires-Dist: kaleido; extra == 'dev'
Requires-Dist: matplotlib<3.11,>=3.10.9; extra == 'dev'
Requires-Dist: nbclient; extra == 'dev'
Requires-Dist: nbformat; extra == 'dev'
Requires-Dist: optax>=0.2; extra == 'dev'
Requires-Dist: pandas; extra == 'dev'
Requires-Dist: plotly; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-xdist; extra == 'dev'
Requires-Dist: ruff==0.16.2; extra == 'dev'
Requires-Dist: scipy==1.17.1; extra == 'dev'
Provides-Extra: io
Requires-Dist: h5py; extra == 'io'
Requires-Dist: pyyaml; extra == 'io'
Requires-Dist: zarr; extra == 'io'
Provides-Extra: jax-fem
Requires-Dist: jax-fem>=0.0.12; extra == 'jax-fem'
Provides-Extra: jaxley
Requires-Dist: jaxley>=0.13.0; extra == 'jaxley'
Provides-Extra: opt
Requires-Dist: optax>=0.2; extra == 'opt'
Provides-Extra: viz
Requires-Dist: ipywidgets; extra == 'viz'
Requires-Dist: kaleido; extra == 'viz'
Requires-Dist: matplotlib<3.11,>=3.10.9; extra == 'viz'
Requires-Dist: pandas; extra == 'viz'
Requires-Dist: pillow; extra == 'viz'
Requires-Dist: plotly; extra == 'viz'
Requires-Dist: reportlab; extra == 'viz'
Requires-Dist: scipy==1.17.1; extra == 'viz'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/HNXJ/jaxfne/main/docs/assets/jaxfne-itxt.png" alt="jaxfne" width="200">
</p>

<p align="center">
  <a href="https://pypi.org/project/jaxfne/"><img src="https://img.shields.io/pypi/v/jaxfne?color=brightgreen" alt="PyPI"></a>
  <a href="https://jaxfne.readthedocs.io/en/latest/"><img src="https://readthedocs.org/projects/jaxfne/badge/?version=latest" alt="Docs"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
</p>

# jaxfne

**Tensor-Field Neural Equations (TFNE)** expressed as a JAX simulation engine for
layer-resolved neural circuits, source operators, field proxies, probes, objectives,
and evidence receipts.

**Scientific grammar:** `Emitter → Source → Field → Probe → Objective → Optimizer → Manifest`

**Execution grammar:** `CircuitSpec → construct → Model → simulate → Signals`

`CircuitSpec` is a **conceptual category** (`Configuration | NeuronalTensor`),
not a concrete public production class — `construct` accepts either a
`Configuration` (original path) or a `NeuronalTensor` with a
`RuntimeConfiguration` (tensor-first path). It is unrelated to the
experimental `jaxfne.experimental_hpc.CircuitSpec` type, which is
not accepted by production `construct`.

**Adaptation** (optional HDP family): finite-dimensional hidden biophysical state
$H$ and adaptive parameter coordinates $\Theta$ (synaptic and intrinsic),
mediated by

$$
\dot X = F_X(X,H,\Theta,U),\quad
\dot H = F_H(H,X,\Theta,U),\quad
\dot\Theta = F_\Theta(H,X,\Theta).
$$

$H$-state is the latent representation; HDP is the adaptive dynamical formulation
that uses it. See [H-state / HDP guide](docs/guides/hdp.md).

## Install

```bash
pip install jaxfne
pip install "jaxfne[viz]"   # optional plotting
```

Development: `pip install -e ".[dev,viz]"` after cloning.

## Minimal example

```python
import jaxfne as jtfne

jtfne.enable_x64()
tensor  = jtfne.load_canonical_neuronal_tensor("canonical-v1-column-1000n")
model   = jtfne.construct(tensor, jtfne.RuntimeConfiguration(seed=0, duration_ms=1000.0, dt_ms=0.5))
signals = jtfne.simulate(model)
```

### Optional: generative development (JDNA)

Instead of loading a fixed tensor, generate one from a PseudoGenome:

```python
genome  = jtfne.load_canonical_pseudogenome("canonical-v1-column-1000n")
tensor  = jtfne.develop(genome, seed=0)   # K_D: development seed
model   = jtfne.construct(tensor, jtfne.RuntimeConfiguration(seed=1, duration_ms=1000.0, dt_ms=0.5))
signals = jtfne.simulate(model)
```

JDNA is an optional path; the direct `Configuration`/`NeuronalTensor` paths
remain first-class. See [JDNA guide](docs/guides/jdna.md).

JaxFNE composes established neural dynamical models, source/readout operators, and `JAX-native` execution under the TFNE typed state/map grammar. See [TFNE theory](docs/doctrine/tfne_containment_architecture.md) and [References](docs/reference/references.md).

Import convention: `import jaxfne as jtfne`. Builder paths, paradigms, and
optimization: [Quickstart](docs/quickstart.md).

## Relative and calibrated outputs

Simulated quantities are **relative** by default. **Calibrated** claims require an
explicit transformation with evidence. See [Scope & status](docs/scope_and_status.md).

## Documentation

| Resource | Link |
|----------|------|
| Quickstart | [docs/quickstart.md](docs/quickstart.md) |
| Site | [jaxfne.readthedocs.io](https://jaxfne.readthedocs.io/) |
| Tutorials | [docs/tutorials/](docs/tutorials/) |
| Études | [docs/etudes/](docs/etudes/) |
| Frozen compatibility contract (0.4.13) | [docs/public_surface_contract.md](docs/public_surface_contract.md) |
| Changelog | [docs/changelog.md](docs/changelog.md) |

## Citation

[`CITATION.cff`](CITATION.cff) · [citation guide](docs/citation.md)

## Visual examples

Real package outputs (simulated proxy scaffolds; calibration requires an
explicit transformation with evidence):
circuit geometry from `Model.neuron_table()`, a 10 s spike raster, a
laminar spectrolaminar readout, and long-timescale firing-rate dynamics
with homeostasis on/off. More: [showcases](docs/guides/showcases.md).

<table>
  <tr>
    <td align="center">
      <a href="docs/guides/showcases.md">
        <img src="https://raw.githubusercontent.com/HNXJ/jaxfne/main/docs/assets/showcases/circuit_geometry_column.png" alt="Circuit geometry" width="340">
      </a><br>
      <sub>Canonical laminar column — geometry from `neuron_table()`</sub>
    </td>
    <td align="center">
      <a href="docs/guides/showcases.md">
        <img src="https://raw.githubusercontent.com/HNXJ/jaxfne/main/docs/assets/showcases/homeostasis_full_raster_10s.png" alt="Spike raster" width="340">
      </a><br>
      <sub>10 s spike raster — homeostasis on (proxy)</sub>
    </td>
  </tr>
  <tr>
    <td align="center">
      <a href="docs/guides/showcases.md">
        <img src="https://raw.githubusercontent.com/HNXJ/jaxfne/main/docs/assets/showcases/spectrolaminar_slow_homeostasis_suite.png" alt="Spectrolaminar readout" width="340">
      </a><br>
      <sub>Spectrolaminar proxy readout — depth-graded homeostasis</sub>
    </td>
    <td align="center">
      <a href="docs/guides/showcases.md">
        <img src="https://raw.githubusercontent.com/HNXJ/jaxfne/main/docs/assets/showcases/homeostasis_rate_change_10s.png" alt="Long-timescale dynamics" width="340">
      </a><br>
      <sub>Population rate over 10 s — homeostasis off vs on (r*=10 Hz)</sub>
    </td>
  </tr>
</table>
