NeuroML/LEMS conformance gallery

Every canonical NeuroML2 example, expressed as one TVB-O specification and checked against jNeuroML

The full NeuroML2 example suite in TVB-O: what a LEMS experiment costs in XML, what it costs in YAML, and how closely the two traces agree.

Interoperability·NeuroML / LEMS

The NeuroML2 repository ships a canonical example suite: the tests the NeuroML community uses to decide whether a simulator implements the standard. TVB-O expresses every one of them as a single specification and checks the result against jNeuroML. This page is the scoreboard; each row links to the worked example behind it.

What a LEMS experiment costs in XML

NeuroML splits a model across two file kinds. A .nml file defines reusable biological components (ion channels, cells, synapses, morphologies, networks) in a domain-specific schema:

<!-- 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>

A LEMS .xml file is the simulation harness: it includes the component files, wires them into a network, sets duration and step, and names what to record.

<!-- LEMS_NML2_Ex5_DetCell.xml (excerpt) -->
<Include file="Cells.xml"/>
<Include file="Networks.xml"/>
<Include file="Simulation.xml"/>
<Include file="../examples/NML2_SingleCompHHCell.nml"/>

<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>

A typical experiment therefore needs at least four files: three core includes that themselves import dozens more, the LEMS file, and one or more .nml models. The equations are nowhere in them; they live in type attributes pointing into the LEMS component-type hierarchy.

What it costs in TVB-O

One document, with the equations in it. The FitzHugh-Nagumo oscillator of Ex9:

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 that one spec, exp.render("lems") emits LEMS XML that jNeuroML runs, exp.run() simulates directly, and exp.render("julia") or exp.render("pyrates") targets another ecosystem entirely. See LEMS export for the emitter and IRI versus YAML for how a component is referenced rather than copied.

The conformance table

Each example is defined as a TVB-O SimulationExperiment, rendered to LEMS, run through jNeuroML as the reference, run again through NeuroMLAdapter, and compared trace by trace. The table below is read from the run record, so it reports what the last suite execution actually measured.

27 of 27 examples reproduce the jNeuroML reference; 0 of 27 render XML that is byte-identical to the canonical file.

Family	Example	Traces	Worst \(r\)	Worst NRMSE	Verdict
Single-cell ODE	Ex0 — IaF	1	1.000000	0	PASS
	Ex2 — Izh	4	1.000000	1.95e-18	PASS
	Ex8 — AdEx	4	1.000000	0	PASS
	Ex9 — FN	1	1.000000	6.83e-21	PASS
Conductance-based	Ex1 — HH	1	1.000000	4.37e-20	PASS
	Ex5 — DetCell	1	1.000000	4.07e-07	PASS
	Ex22 — PinskyRinzel	2	1.000000	787	PASS
Channels & kinetics	Ex4 — KS	1	1.000000	1.42e-20	PASS
	Ex10 — Q10	1	1.000000	1.64e-07	PASS
	Ex15 — CaDynamics	1	1.000000	1.43e-14	PASS
	Ex18 — GHK	1	1.000000	1.51e-21	PASS
	Ex24 — FractionalConductance	1	1.000000	4.56e-20	PASS
Synapses	Ex3 — Net	3	1.000000	0	PASS
	Ex6 — NMDA	1	1.000000	9.9e-06	PASS
	Ex7 — STP	3	0.999999	0.000242	PASS
	Ex20 — AnalogSynapses	3	1.000000	0	PASS
	Ex21 — CurrentBasedSynapses	1	1.000000	1.98e-19	PASS
	Ex27 — MultiSynapses	5	1.000000	0	PASS
Networks	Ex12 — Net2	9	1.000000	0.000237	PASS
	Ex13 — Instances	3	1.000000	0	PASS
	Ex19 — GapJunctions	2	1.000000	0	PASS
	Ex25 — MultiComp	12	1.000000	4.75e-20	PASS
	Ex26 — Weights	12	1.000000	1.75e-20	PASS
Interchange	Ex14 — PyNN	8	1.000000	1.73e-19	PASS
	Ex16 — Inputs	10	1.000000	5.42e-19	PASS
	Ex17 — Tissue	1	1.000000	1.72e-20	PASS
	Ex23 — Spiketimes	6	1.000000	4.21e-19	PASS

Read the two columns together

The verdict is correlation-based: an example passes when its trace tracks the reference in shape. Two consequences are visible in the table above and neither is hidden.

A scale error still passes. Ex22 (Pinsky-Rinzel) reaches \(r \approx 1\) with a worst NRMSE near 787. The waveform is right and the amplitude is not. Where the NRMSE column is not small, the example demonstrates structural agreement only.

The XML is equivalent, not identical. No example renders a byte-for-byte copy of the canonical file. TVB-O emits standard NeuroML2 component types that jNeuroML runs to the same result, which is the property that matters for interchange and the one the numerical columns measure.

Component examples

Alongside the LEMS simulation suite, the NeuroML2 repository ships component files that define models without running them. Each is expressed as a TVB-O object and re-emitted:

Cells	Abstract cells · Single-compartment HH · Full cell · Morphology
Channels	Simple ion channel
Synapses	Synapse types · Analog synapses · Gap junctions
Networks	Inputs · Instance-based network · Full NeuroML

Running the suite yourself

pip install pyneuroml matplotlib scipy
python Interoperability/NeuroML/examples/_run_all_examples.py

jNeuroML runs the reference side and ships with pyNeuroML, so a working Java is the only extra requirement. The script rewrites _run_all_examples_results.json, and the table above follows.