Current NMODL Best Practices

NMODL and the Channel Builder.
Post Reply
ajpc6d
Posts: 23
Joined: Mon Oct 24, 2022 6:33 pm

Current NMODL Best Practices

Post by ajpc6d »

The available information on NMODL best practices seems to be contradictory at points, and I wonder if the best current practices could be summarized in one place?

As an example, the xtra.mod file states:
Prior to NEURON 5.5, the SOLVE statement in the BREAKPOINT block used METHOD cvode_t so that the adaptive integrators wouldn't miss the stimulus. Otherwise, the BREAKPOINT block would have been called _after_ the integration step... With NEURON 5.5 and later, this mechanism abandons the BREAKPOINT block and uses the two new blocks BEFORE BREAKPOINT and AFTER SOLVE
But I can't find corroboration of, or elaboration on, this point anywhere. Most of the information appears not to have been updated in years. Chapters 9/10 of The NEURON Book (as far as I've found) don't even mention the existence of BEFORE BREAKPOINT and AFTER SOLVE. From this quote, it seems that the code for the section.insert('hh') mechanism itself appears to be out of date.

So - in the interest of constructing a Hodgkin-Huxley-style density mechanism, what best practices should one follow today? Are there defunct/redundant blocks that should not be used, or not be used in combination?
ted
Site Admin
Posts: 6286
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

Re: Current NMODL Best Practices

Post by ted »

Most of the information appears not to have been updated in years.
That's because most of what needed to be documented hasn't changed in decades. Many changes are expected in NEURON version 9, especially metadata features that will be particularly useful for code introspection; this will doubtless be accompanied by new documentation.

WRT BEFORE BREAKPOINT and AFTER SOLVE, these keywords are actually documented, and that documentation is in the most appropriate location: at the start of the file that uses them: xtra.mod, which implements the xtra mechanism that is used for extracellular stimulation and recording. That documentation, quoted here, seems fairly explicit:
Prior to NEURON 5.5, the SOLVE statement in the BREAKPOINT block
used METHOD cvode_t so that the adaptive integrators wouldn't miss
the stimulus. Otherwise, the BREAKPOINT block would have been called
_after_ the integration step, rather than from within cvodes/ida,
causing this mechanism to fail to deliver a stimulus current
when the adaptive integrator is used.

With NEURON 5.5 and later, this mechanism abandons the BREAKPOINT
block and uses the two new blocks BEFORE BREAKPOINT and
AFTER SOLVE, like this--

BEFORE BREAKPOINT { : before each cy' = f(y,t) setup
ex = is*rx*(1e6)
}
AFTER SOLVE { : after each solution step
er = (10)*rx*im*area
}

This ensures that the stimulus potential is computed prior to the
solution step, and that the recorded potential is computed after.
The reference to cy' = f(y,t) is a bit obscure because of its conciseness; the curious are referred to section 4.2.4.1 Implementational considerations in the NEURON Book, especially the discussion of Equations 4.29a et seq.. If you don't have the book, get this preprint https://www.neuron.yale.edu/ftp/ted/boo ... xedref.pdf and look for the section with the header Adaptive integration: fast or accurate, occasionally both

AFAIK these keywords appear only in xtra.mod and files derived from it (e.g. xrec.mod, which is used only for extracelluar recording). They certainly aren't useful for any of the NMODL descriptions of ligand- and/or voltage-gated channels, or ion accumulation mechanism (buffers, pumps, exchangers, smooth endoplasmic reticulum, mitochondria, Frankenhaeuser-Hodgkin space or other zones of restricted diffusion), or synaptic mechanisms with or without synaptic plasticity (hebbian or non-hebbian), or artificial spiking cells. Fairly extensive documentation with examples pertinent to most of these applications is in the enhanced preprint of

Hines, M.L. and Carnevale, N.T. Expanding NEURON's Repertoire of Mechanisms with NMODL. Neural Computation 12:995-1007, 2000

which is available as https://neuron.yale.edu/neuron/static/p ... odl400.pdf

An introduction to using NMODL to implement of models of artificial spiking cells is presented in

Carnevale, NT and Hines, ML. 312.10 Efficient discrete event simulation of spiking neurons in NEURON.
Annual Meeting of the Society for Neuroscience, 2002, vol. 32.

which is available at https://www.neuron.yale.edu/neuron/stat ... poster.pdf

Some additional information about event-driven simulation is presented in

Hines, ML and Carnevale, NT. Discrete event simulation in the NEURON simulation environment.
Neurocomputing 2004, 58-60:1117-1122. DOI 10.1016/j.neucom.2004.01.175
ramcdougal
Posts: 267
Joined: Fri Nov 28, 2008 3:38 pm
Location: Yale School of Public Health

Re: Current NMODL Best Practices

Post by ramcdougal »

Another way of putting it: the description specified in nmodl400.pdf is still pretty accurate. The text you found refers to something very specific to xtra.mod... most models will still use BREAKPOINT instead. See hh.mod for how NEURON implemented Hodgkin-Huxley itself.

A few suggestions for modern best-practices:
  • Avoid GLOBALS. They're not THREADSAFE.
  • Avoid POINTERS, if you can. If you're trying to do gap junctions, you can do that (slower, but more accurately) with a LinearMechanism.
  • Avoid Euler. It's not very numerically stable.
  • Avoid VERBATIM. Putting in explicit C sometimes leads to inconsistencies across platforms and in any case is not very automatically parseable.
  • As shown in hh.mod, you can specify ontology identifiers with the REPRESENTS keyword. Omit them if you don't know what they should be.
  • section.insert('hh') is equivalent to section.insert(h.hh), but the h.hh object also provides other introspection capabilities, so I'd recommend using that instead of the string name
ted
Site Admin
Posts: 6286
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

Re: Current NMODL Best Practices

Post by ted »

Avoid Euler
For clear guidance on what integration method to specify in NMODL code, see Integration methods for SOLVE statements in the NEURON Forum's Hot tips area.
Post Reply