Hippocampal-CA1-LAM v2.0

🧠 Literature-grounded mechanistic model of the CA1 hippocampal laminar circuit

A reproducible, research-grade computational model of CA1: a two-compartment conductance-based pyramidal neuron, a four-sublayer laminar structure, theta↔SWR state switching, and calcium-based plasticity. Every structural and dynamical parameter is taken from peer-reviewed sources (see Bibliography).

Scope and honesty. This is a mechanistic research model, not a validated digital twin. Parameters are literature-sourced; the model has not been fit to or validated against the authors' own electrophysiology. Treat outputs as hypotheses about circuit dynamics, not measurements.

• Two-compartment pyramidal neuron (soma–dendrite) with HCN gradient, NMDA, GABA conductances — parameters from Magee 1998, Jahr & Stevens 1990.
• Four-sublayer laminar structure. Layer proportions are derived from the 58,065-cell smFISH atlas of Pachicano et al. (Nat. Commun. 2025). The atlas is the empirical source for the proportions — not the simulated network size. The simulated network size is configurable (n_neurons, default 100).
• Theta ↔ SWR state switching with an explicit state machine, gated inhibition (OLM/PV) and replay detection.
• Calcium-based plasticity (Graupner & Brunel, PNAS 2012) with Tsodyks–Markram short-term plasticity.
• AI-memory integration: a HippoRAG-inspired retrieval module.
• Deterministic: seed=42 reproduces an identical 6-test golden signal.

bash quick_start.sh      # venv + deps + golden suite (expected: 6/6 PASSED)

pip install -r requirements.txt

python test_golden_standalone.py     # expected: 6/6 PASSED
python examples/demo_basic_usage.py  # minimal CA1Network walkthrough

python examples/demo_ca_plasticity.py   # calcium LTP/LTD demo
python examples/demo_theta_swr.py       # theta↔SWR switching demo
make test                               # full pytest suite
make lint                               # flake8 + format check
python scripts/benchmark.py             # performance profile

The same checks the CI runs, in order:

python -m pytest -q                          # unit + golden tests (204)
bandit -r core plasticity ai_integration data validation --severity-level medium
gitleaks detect --config .gitleaks.toml      # secret scan
python scripts/unicode_scan.py               # homoglyph / RTL scan
python scripts/validate_configs.py .         # JSON/YAML validity
python scripts/ci_policy_check.py            # workflow policy
pip-audit -r requirements.txt                # dependency CVEs

• Installation Guide
• Usage Examples
• API Reference
• Architecture
• Testing
• CI/CD
• Bibliography
• Contributing

All parameters from peer-reviewed sources — full DOIs in the Bibliography:

• Laminar proportions — Pachicano et al., Nat. Commun. 2025 (58,065-cell smFISH atlas)
• Calcium plasticity — θ_d = 1.0 μM, θ_p = 2.0 μM (Graupner & Brunel, PNAS 2012)
• HCN gradient / NMDA — Magee 1998; Jahr & Stevens 1990
• Theta dynamics — O'Keefe & Recce 1993

• ✅ Two-compartment neuron, laminar structure, theta/SWR switching, Ca²⁺ plasticity — implemented
• ✅ 204 unit tests + 6 deterministic golden tests (seed=42)
• ✅ Type hints, CI gates (tests, bandit, gitleaks, unicode, config, dependency audit)
• ⚠️ Not validated against in-house electrophysiology — see scope note above

@software{hippocampal_ca1_lam_2025,
  title  = {Hippocampal-CA1-LAM: a literature-grounded mechanistic CA1 model},
  author = {neuron7xLab},
  year   = {2025},
  url    = {https://github.com/neuron7xLab/Hippocampal-CA1-LAM}
}

MIT License — see LICENSE.