NeuroML/LEMS Examples

All 28 canonical NeuroML2 examples — represented, rendered, and validated in TVBO

Origin

The examples on this page are retrieved from the official NeuroML2 repository (LEMSexamples/ and examples/ directories). They constitute the canonical test suite that the NeuroML community uses to validate simulator implementations. Each example here has a 1-to-1 correspondence with an original LEMS_NML2_Ex*.xml file and its associated .nml component files.

TVBO can represent every one of these experiments in a single, unified YAML specification — no XML, no file scattering, no separate simulation harness.

---

What are .nml and LEMS .xml files?

NeuroML splits model descriptions across two complementary XML formats:

.nml files — Model Components

NeuroML files (.nml) define reusable biological components: ion channels, cells, synapses, morphologies, and networks. They use a domain-specific XML schema with elements like <ionChannelHH>, <cell>, <expOneSynapse>, and <network>. Each .nml file is a self-contained building block — for example, NML2_SingleCompHHCell.nml defines a Hodgkin-Huxley cell with Na, K, and leak channels, its morphology, and biophysical properties.

<!-- NML2_SingleCompHHCell.nml (excerpt) -->
<ionChannelHH id="naChan" conductance="10pS" species="na">
  <gateHHrates id="m" instances="3">
    <forwardRate type="HHExpLinearRate" rate="1per_ms" midpoint="-40mV" scale="10mV"/>
    <reverseRate type="HHExpRate" rate="4per_ms" midpoint="-65mV" scale="-18mV"/>
  </gateHHrates>
  ...
</ionChannelHH>

LEMS .xml files — Simulation Experiments

LEMS files (Low Entropy Model Specification) are the simulation harness. They <Include> the .nml component files, wire them into a network, define simulation parameters (duration, time step), and specify what to record. A single LEMS file stitches together all the pieces needed to run an experiment:

<!-- LEMS_NML2_Ex5_DetCell.xml (excerpt) -->
<Include file="Cells.xml"/>           <!-- core type definitions -->
<Include file="Networks.xml"/>        <!-- core type definitions -->
<Include file="Simulation.xml"/>      <!-- core type definitions -->
<Include file="../examples/NML2_SingleCompHHCell.nml"/>  <!-- the actual model -->

<network id="net1">
  <population id="hhpop" component="hhcell" size="1"/>
</network>

<Simulation id="sim1" length="300ms" step="0.01ms" target="net1">
  <OutputFile id="of0" fileName="results/ex5.dat">
    <OutputColumn id="v" quantity="hhpop[0]/v"/>
  </OutputFile>
</Simulation>

The fragmentation problem

A typical NeuroML experiment requires 4+ XML files: 3 core LEMS includes (Cells.xml, Networks.xml, Simulation.xml — which themselves include dozens more), the LEMS simulation file, and one or more .nml model files. More complex examples reference additional channel, synapse, or morphology files. The actual model equations are implicit — encoded in type attributes that reference component types buried deep in the LEMS type hierarchy.

---

One TVBO YAML instead

TVBO collapses this entire multi-file XML structure into a single YAML document that is simultaneously:

• Human-readable — equations, parameters, units, network, integrator, and outputs are all visible in one place
• Machine-actionable — the same YAML can render to LEMS XML, JAX, NumPy, Julia, or any supported backend
• Self-contained — no external includes, no implicit type hierarchies, no file path dependencies
• Schema-validated — every field is checked against the LinkML data model; typos and missing fields are caught before simulation

For example, the FitzHugh-Nagumo oscillator (Ex9) requires a LEMS XML file that references Cells.xml, Networks.xml, and Simulation.xml — themselves importing hundreds of component type definitions. In TVBO, the same experiment is:

name: FitzHughNagumo
state_variables:
  V: { equation: { rhs: "V - V**3/3 - W + I" } }
  W: { equation: { rhs: "0.08 * (V + 0.7 - 0.8 * W)" } }
parameters:
  I: { value: 0.8 }
integrator: { scheme: euler, dt: 0.01, duration: 200 }

From this single spec, TVBO can:

1. exp.render("lems") → produce the exact LEMS XML that jNeuroML runs
2. exp.run() → simulate directly via JAX/NumPy
3. exp.render("julia") → generate Julia code for NetworkDynamics.jl
4. exp.render("pyrates") → export to PyRates

---

Validation approach

Each example notebook below:

1. Defines the model as a TVBO SimulationExperiment
2. Renders to LEMS XML via exp.render("lems")
3. Runs the original NeuroML2 LEMS file via jNeuroML as reference
4. Runs the TVBO version via NeuroMLAdapter.run()
5. Compares time-series numerically (RMSE, correlation, max error)
6. Plots overlaid reference vs. TVBO traces

Example categories

Category	Examples	Description
Single-cell ODE	Ex0 (IaF), Ex2 (Izh), Ex8 (AdEx), Ex9 (FN)	Simple 1–2 variable models with event-driven spikes
Conductance-based	Ex1 (HH), Ex5 (DetCell)	Hodgkin-Huxley-style cells with gating variables
Channels & Kinetics	Ex4 (KS), Ex10 (Q10), Ex15 (Ca), Ex18 (GHK), Ex24 (Frac)	Ion channel biophysics
Synapses	Ex3 (Net), Ex6 (NMDA), Ex7 (STP), Ex20/21 (Analog/Current), Ex27 (Multi)	Synaptic dynamics and plasticity
Networks	Ex12 (Net2), Ex13 (Instances), Ex19 (GapJ), Ex25 (MultiComp), Ex26 (Weights)	Multi-cell networks and connectivity
Other	Ex14 (PyNN), Ex16 (Inputs), Ex17 (Tissue), Ex22 (PinskyRinzel), Ex23 (Spiketimes)	Specialized examples

Prerequisites

pip install pyneuroml matplotlib scipy

jNeuroML (Java-based) is required for running the reference examples. It is bundled with pyNeuroML.

---