{"id":50030737,"url":"https://github.com/hnxj/jaxfne","last_synced_at":"2026-05-23T21:01:51.637Z","repository":{"id":358296556,"uuid":"1240775255","full_name":"HNXJ/jaxfne","owner":"HNXJ","description":"JAX Tensor-Field Neural Equations (TFNE)","archived":false,"fork":false,"pushed_at":"2026-05-20T21:53:24.000Z","size":451,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T23:52:43.483Z","etag":null,"topics":["differential-equations","electromagnetic-simulation","electrophysiology","jax","neurobiology","neurophysiology","neuroscience"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HNXJ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-16T14:56:00.000Z","updated_at":"2026-05-20T18:58:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/HNXJ/jaxfne","commit_stats":null,"previous_names":["hnxj/jaxfne"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/HNXJ/jaxfne","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HNXJ%2Fjaxfne","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HNXJ%2Fjaxfne/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HNXJ%2Fjaxfne/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HNXJ%2Fjaxfne/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HNXJ","download_url":"https://codeload.github.com/HNXJ/jaxfne/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HNXJ%2Fjaxfne/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33412082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["differential-equations","electromagnetic-simulation","electrophysiology","jax","neurobiology","neurophysiology","neuroscience"],"created_at":"2026-05-20T20:13:05.009Z","updated_at":"2026-05-23T21:01:51.631Z","avatar_url":"https://github.com/HNXJ.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jaxfne\n\n**JAX-native TFNE (Tensor-Field Neural Emitter) workflows for reproducible computational neurophysiology.**\n\n[![PyPI](https://img.shields.io/pypi/v/jaxfne.svg)](https://pypi.org/project/jaxfne/) ·\n[![Docs](https://readthedocs.org/projects/jaxfne/badge/?version=latest)](https://jaxfne.readthedocs.io/en/latest/) ·\n[![GitHub](https://img.shields.io/badge/github-HNXJ%2Fjaxfne-blue)](https://github.com/HNXJ/jaxfne) ·\n[![Issues](https://img.shields.io/github/issues/HNXJ/jaxfne)](https://github.com/HNXJ/jaxfne/issues)\n\n---\n\n## What is jaxfne?\n\njaxfne is a compact JAX-native framework for composing neural simulations from modular operators:\n\n```\nEmitter (neuron state) → Source (membrane current) → Field (proxy/solved) → Probe (readout) → Objective\n```\n\n**Primary use:** Build reproducible laminar-field proxy simulations with deterministic PRNG, JSON-safe outputs, and clear claim boundaries.\n\n**Not a biological simulator.** jaxfne is a computational-scaffold framework for teaching, prototyping, and experimenting with neural-field source models. All outputs are proxies unless explicitly validated against empirical data.\n\n---\n\n## Quick Start\n\n### Install\n\n```bash\npip install jaxfne\n```\n\nOptional JAX acceleration:\n```bash\npip install -e '.[jax]'\n```\n\nOptional development/visualization:\n```bash\npip install -e '.[dev,viz]'\n```\n\n### Minimal Example\n\n```python\nimport jaxfne as jtfne\n\ncfg = (\n    jtfne.configuration()\n    .network(name=\"V1\", kind=\"cortical_column\", n=100)\n    .emitter(family=\"izhikevich\", preset=\"cortical_eig\")\n    .field(domain=\"laminar_column\", conductivity=\"proxy\", boundary=\"mean_zero_neumann\")\n    .probe(name=\"laminar_16ch\", modes=[\"spikes\", \"V_m\", \"source\", \"CSD\"], n_contacts=16)\n)\n\nmodel = jtfne.construct(cfg)\nsignals = model.simulate(jtfne.simulation(duration_ms=100.0, dt_ms=0.1, seed=0))\nreadouts = model.compute_readout(signals, [\n    jtfne.readout_spec(\"rate\", \"spike_rate_hz\"),\n    jtfne.readout_spec(\"csd\", \"csd_abs_mean\"),\n])\n\nmanifest = model.manifest(signals, readouts)\nprint(f\"Simulation complete: {signals.V_m.shape[0]} timesteps, {signals.V_m.shape[1]} neurons\")\nprint(f\"Source status: {manifest['source_calibration_status']}\")\nprint(f\"Field status: {manifest['field_solver_status']}\")\n```\n\n---\n\n## The Pipeline\n\n### 1. Emitter: Neural Dynamics\n\nDeclare neuron model (Izhikevich or custom) and recurrent connectivity:\n\n```python\n.emitter(family=\"izhikevich\", preset=\"cortical_eig\")\n```\n\n**Output:** State vector $z(t)$ and native membrane current $I(t)$ [time, neurons]\n\n**Status:** Izhikevich presets are provided; no biological calibration claimed (computational scaffold)\n\n### 2. Source: Spatial Projection\n\nProject neural current into space (laminar probe contacts or voxels):\n\n```python\n.field(domain=\"laminar_column\", conductivity=\"proxy\", ...)\n```\n\n**Output:** Source density $q(x,t)$ [time, contacts]\n\n**Status:** Proxy projection using anatomical position and Izhikevich native current; no empirical validation\n\n### 3. Field: Field Approximation\n\nCurrent default: **proxy CSD** (no PDE solve).\n\n```\nfield_solver_status = \"laminar_proxy_no_pde\"\n```\n\nCSD and LFP are computed from source without solving the Poisson equation. Conductivity is metadata-only.\n\n**Available (v0.2.27+):** Conservation-inspired proxy diagnostics. Physical conductivity remains gated future work (v0.3.x).\n\n### 4. Probe: Multimodal Readouts\n\nExtract metrics from emitter state and field:\n\n| Operator | Output | Meaning |\n|----------|--------|---------|\n| **Spikes (SPK)** | Binary spike raster [T, N] | Action potentials (thresholded state) |\n| **Voltage (V_m)** | Membrane voltage [T, N] | Membrane potential state |\n| **Source** | Transmembrane current [T, X] | Spatial source density |\n| **LFP-proxy** | Local field potential [T, X] | Proxy; not physical units |\n| **CSD-proxy** | Current-source density [T, X] | Proxy; spatial divergence of source |\n| **EEG-proxy** | Electroencephalogram [T, N_channels] | Proxy; not physical units |\n| **MEG-proxy** | Magnetoencephalogram [T, N_channels] | Proxy; not physical units |\n| **EMM-proxy** | Metabolic-like cost [T] | Relative activity intensity (NOT biological metabolism) |\n\nAll readouts are proxies unless explicitly solved and validated.\n\n### 5. Objective \u0026 Optimization\n\nDeclare optimization targets and run GSDR/AGSDR (custom optimizers; Optax optional):\n\n```python\nobjectives = [\n    jtfne.objective(name=\"spike_rate\", target=10.0, metric=\"spike_rate_hz\"),\n    jtfne.objective(name=\"mean_voltage\", target=-50.0, metric=\"mean_V_m\"),\n]\n```\n\n---\n\n## Validation\n\n### Fast validation (every commit, ~1 minute)\n\n```bash\npython -m compileall -q jaxfne tests examples scripts\nPYTEST_DISABLE_PLUGIN_AUTOLOAD=1 PYTHONPATH=. python -m pytest -q --tb=line\n```\n\n**Results:** 806 tests passed, 5 skipped. Examples 00–06 run. Build validation passes.\n\n### Extended validation (release, ~5–10 minutes)\n\n```bash\npython scripts/run_all_tutorials.py --smoke --write-figures\npython scripts/validate_tutorial_outputs.py outputs/\n```\n\nRuns large tutorials (examples 02–07) with deterministic figures and asset hashing. See [CI policy](docs/ci_policy.md).\n\n---\n\n## Documentation Map\n\n| Topic | Document | Purpose |\n|-------|----------|---------|\n| **Equations \u0026 Math** | [Mathematical Glossary Flow](docs/mathematical_glossary_flow.md) | TFNE equations (emitter, source, field, probe) with term glossaries and claim boundaries |\n| **Source Detail** | [Source/Field Equations](docs/source_field_equations.md) | Source modes, forbidden double-counting pattern, field metadata, code examples |\n| **Architecture** | [Computation Basis](docs/computation_basis.md) | TFNE as collapsible tensor-field scaffold; extensibility doctrine |\n| **Probe Operators** | [Probe Operators](docs/probe_operators.md) | Eight multimodal operators, claim boundaries per operator |\n| **I/O \u0026 Manifests** | [Output Bundles](docs/output_bundles.md) | Signals, Manifest, ReadoutResult schema and JSON-safe contracts |\n| **Bridges \u0026 Interop** | [Jaxley Interop](docs/jaxley_interop.md) | Convert Jaxley voltage traces to jaxfne Signals |\n| **Scope \u0026 Limits** | [Scope and Limitations](docs/scope_and_limitations.md) | What jaxfne claims and does not claim |\n| **Full Docs** | [jaxfne.readthedocs.io](https://jaxfne.readthedocs.io/) | API reference, tutorials, changelog |\n\n---\n\n## Roadmap\n\n| Version | Phase | Content | Status |\n|---------|-------|---------|--------|\n| **v0.2.24** | Foundation Audit | Audited contracts, verified solver status, updated language | ✓ Released |\n| **v0.2.25** | Docs-First | Mathematical glossary, source/field doctrine, computation basis | ✓ Released |\n| **v0.2.26** | Extensibility | Documented future bases, multi-area scaffolds, BasisSpec | ✓ Released |\n| **v0.2.27** | Diagnostics | Conservation-inspired proxy diagnostics, source norms, field-gradient proxy | ✓ Released |\n| **v0.2.28** | Tutorial Figures | Canonical tutorial figure manifest, static PNGs, Jaxley bridge hardening | ✓ Released |\n| **v0.2.29** | Tensor-Network Ancestry | Pellionisz/Llinás context, basis-transform doctrine | ✓ Released |\n| **v0.2.30** | Performance Hardening | Benchmark receipts, JSON safety validation, CI policy | ✓ Released |\n| **v0.3.x** | Tutorial-Scenario Line | 32-phase tutorial spine on stable v0.2.30 toolbox; no automatic package bumps | 🔄 In Progress |\n\n**Current phase:** v0.3 tutorial-scenario line (built on `jaxfne==0.2.30`). The v0.3 line is primarily docs, notebooks, equations, and figures. The v0.3 line uses `import jaxfne as jtfne` on the stable v0.2.30 toolbox unless a package bug requires a patch release.\n\n---\n\n## Claim Status\n\n**truth_mode:** `truth_safe_unverified`  \n**claim_level:** `computational_scaffold`  \n**physical_amplitude_claim_allowed:** `False`  \n\njaxfne is **not a biological simulator.** All outputs are computational proxies:\n\n- **Izhikevich native current** is a mathematical dynamics model, not empirically calibrated membrane current\n- **Source projection** uses declared anatomy but is not validated against measured sources\n- **Field (proxy)** is NOT a solved Poisson equation; CSD/LFP are kernel-based approximations\n- **Readout proxies** (LFP, CSD, EEG, MEG, EMM) are relative metrics, not physical units\n- **Optimization** is mathematical fitness; success ≠ biological plausibility\n\n**When to use jaxfne:**\n- Teaching neural-field concepts\n- Prototyping source-field models\n- Benchmarking optimization strategies\n- Validating model consistency (future: conservation diagnostics)\n\n**When NOT to use jaxfne:**\n- Making biological claims without separate empirical validation\n- Publishing simulation results as if they are real neural data\n- Claiming physical conductivity without calibration\n- Interpreting metabolic cost (EMM-proxy) as biological metabolism\n\n---\n\n## License\n\nMIT License.\n\n---\n\n## Contributing\n\nIssues, feature requests, and pull requests welcome. See [CONTRIBUTING](docs/contributing.md).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhnxj%2Fjaxfne","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhnxj%2Fjaxfne","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhnxj%2Fjaxfne/lists"}