Frequently Asked Questions about NEURON

Also be sure to check The NEURON Users' Group Forum, especially NEURON installation and configuration, Hot tips, and Getting started.
Using NEURON--general questions
Now that I've installed NEURON, how do I run it?
Installation went smoothly, but every time I bring NEURON up, the interpreter prints this strange message :
   "jvmdll" not defined in nrn.def
   JNI_CreateJavaVM returned -1
What's the best way to learn how to use NEURON?
How do I create a NEURON model?
Help! I'm having a hard time implementing models!
Why can't NEURON read the text file (or hoc file) that I created?
How do I print a hard copy of a NEURON window?
How do I plot something other than membrane potential?
How do I save and edit figures?
I've used the NEURON Main Menu to construct and manage models. How can I save what I have done?
What is a ses (session) file? Can I edit it?
How do I use NEURON's tools for electrotonic analysis?
Why should I use an odd value for nseg?
What's a good strategy for specifying nseg?
How do I change the background color used in NEURON's shape plots and other graphs?
How do I change the color scale used in shape plots?
I see an error message that says ... procedure too big in ./foo.hoc ...
Where can I find examples of mod files?
How do I compile mod files?
I can't get mod files to compile.
I installed a new version of NEURON, and now I see error messages like this:
   mechanisms fooba needs to be re-translated.
Is there a list of the functions that are built into NMODL?
Is there a list of the functions that are built into hoc?
What units does NEURON use for current, concentration, etc.?
When I type a new value into a numeric field, it doesn't seem to have any effect.
What is the difference between SEClamp and VClamp, and which should I use?
SEClamp and IClamp just deliver rectangular step waveforms. How can I make them produce an arbitrary waveform, e.g. something that I calculated or recorded from a real cell?
I just want a current clamp that will deliver a sequence of current pulses at regular intervals. Vector play seems like overkill for this.
I want a current clamp that will generate a pulse when I send it an event, or that I can use to produce pulses at precalculated times.
I have a set of recorded or calculated spike times. How can I use these to drive a postsynaptic mechanism?
How can I read data from a binary PClamp file?
How do I exit NEURON? I'm not using the GUI, and when I enter ^D at the oc> prompt it doesn't do anything.

For Mac users
Under OS X, how do I compile mod files or start NEURON?
How do I compile mod files under MacOS?

For MSWindows users
I installed NEURON but chose a different directory from the default (c:\nrn). The installer ran smoothly and reported no errors, but NEURON doesn't seem to work.
The GUI tools are too big for the small (800x600) display on my laptop computer--the CellBuilder won't even fit on the screen!
How can I get MSWindows to launch NEURON when I double click on a hoc file?
How do I compile mod files? I've been putting them in c:\nrn\bin and then running mknrndll . Is there a better way to do this?
I've installed NEURON but I don't see any hoc or mod files on my computer.
NotePad won't let me create a .hoc or .mod file. It keeps sticking ".txt" onto the end of file names!
Can I cut and paste to and from NEURON's interpreter window?

For UNIX/Linux users
How do I compile mod files under UNIX/Linux?
My computer has a small display. How can I change the typeface size used by NEURON's GUI?
My program foo.hoc doesn't use graphics. How do I start it so that there is no GUI? That will allow me to log onto a computer via ssh, use nohup to start a process, log off, and the process continues.


Using NEURON--general questions

Q: Now that I've installed NEURON, how do I run it?
A: To start NEURON and bring up the NEURON Main Menu toolbar (which you can use to build new models and load existing ones) :
  • UNIX/Linux : type nrngui at the system prompt.
  • OS X : double click on the nrngui icon in the folder where you installed NEURON.
  • MSWin : double click on the nrngui icon in the NEURON Program Group (or in the desktop NEURON folder).
To make NEURON read a file called foo.hoc when it starts :
  • UNIX/Linux : type nrngui foo.hoc at the system prompt. This also works for ses files.
  • OS X : drag and drop foo.hoc onto the nrngui icon. This also works for ses files.
  • MSWin : use Windows Explorer (not Internet Explorer) to navigate to the directory where foo.hoc is located, and then double click on foo.hoc . This does not work for ses files.
OS X users will find additional information here.

To exit NEURON : type quit() or ^D ("control D") at the oc> prompt, or use File / Quit in the NEURON Main Menu toolbar.

Q: Installation went smoothly, but every time I bring NEURON up, the interpreter prints this strange message :
"jvmdll" not defined in nrn.def
JNI_CreateJavaVM returned -1
A: You must be running an old version of NEURON. Warnings about Java, such as "Can't create Java VM" or "Info: optional feature is not present" mean that NEURON can't find a Java run-time environment. This is of interest only to individuals who are using Java to develop new tools. NEURON's computational engine, standard GUI library, etc. don't use Java.

Q: What's the best way to learn how to use NEURON?
A: First be sure to join The NEURON Forum. Then read these suggestions.

Q: How do I create a NEURON model?
A: By specifying representations in the computer of the three basic physical components of an actual experiment.
Component Wet lab Computational modeling
Experimental preparation
What is the biology itself?
brain slice, tissue culture etc. specification of what anatomical and biophysical properties to represent in model
Instrumentation
How will you stimulate it and record results?
voltage/current clamp, electrodes, stimulator, recorder etc. --computational representations of clamps, electrodes etc.
--specification of which variables to monitor and record
Control
How do you automate the experimental protocol?
programmable pulse generators etc. time step, when to stop, integration method, optimization algorithms

The classical approach to using NEURON is to specify all three components by writing a program in hoc, NEURON's programming language. You can do this with any editor you prefer, as long as it can save your code to an ASCII text file. Make sure your hoc files end with the extension .hoc

A more recent approach is to use the NEURON Main Menu toolbar's dropdown menus, which allow you to quickly create a wide range of models without having to write any code at all. You can save the GUI's windows and panels to session files that you can use later to recreate what you built (see the FAQ "What is a ses (session) file?").

The most flexible and productive way to work with NEURON is to combine hoc and the GUI in ways that exploit their respective strengths. Don't be afraid of the GUI--noone will accuse you of being a "girly man" if you take advantange of its powerful tools for model specification, instrumentation, and control. In fact, many of the GUI's most useful tools would be extremely difficult and time consuming to try to duplicate by writing your own hoc code.

Be sure to read the FAQ "Help! I'm having a hard time implementing models!"

Q: Help! I'm having a hard time implementing models!
A: Here are some general tips about program development.
  • Before you write any code, write down an explicit outline of how it should work. Use a "top-down" approach to avoid being overwhelmed at the start by implementational details.
  • Successful programming demands an incremental cycle of revision and testing. Start small with something simple that works. Add things one at a time, testing at every step to make sure the new stuff works and didn't break the old stuff.
  • Comment your code.
  • Use a "modular" programming style. At the most concrete level, this means using lots of short, simple procs and funcs.
    Also, "don't throw all your code into one giant hoc (or ses) file." Regardless of whether you use hoc, the GUI, or both, it will be much easier to create and revise programs if you keep model specification (the "experimental preparation") separate from instrumentation and control (the "user interface"). You might even put them in separate files, e.g. "model.hoc" might contain the code that specifies the anatomy and biophysics of your model cell or network, and "rig.ses" might specify a RunControl panel and other graphical tools that you use to run simulations, apply stimuli, and display results. Then you create a third file, called "init.hoc", which contains the following statements :
       load_file("nrngui.hoc") // get NEURON's gui library
       load_file("model.hoc") // the model specification
       load_file("rig.ses") // the instrumentation, control, and user interface
    When NEURON executes init.hoc, up comes your model and user interface.
    This greatly simplifies program development, testing and maintentance. For example, complex models and experimental rigs can be constructed in an incremental manner, so that init.hoc grows to contain many load_file statements.
  • Mine other code (e.g. the Programmers' Reference) for reusable or customizable working examples. "Good programmers imitate great code, great programmers steal great code." But test all code.

Q: Why can't NEURON read the text file (or hoc file) that I created?
A: The Mac, MSWin, and UNIX/Linux versions of NEURON can read ASCII text files created under any of these operating systems. ASCII, which is sometimes called "plain text" or "ANSI text", encodes each character with only 7 bits of each byte. Some text editors offer alternative formats for saving text files, and if you choose one of these you may find that NEURON will not read the file. For example, Notepad under Win2k allows files to be saved as "Unicode text", which will gag NEURON.

Q: How do I print a hard copy of a NEURON window?
A: Use the Print & File Window Manager (PFWM). Download printing.pdf to learn how.

Q: How do I plot something other than membrane potential?
A: Use the Plot what? tool.

Q: How do I save and edit figures?
A: The quick and dirty way is to capture screen images as bitmaps. The results are suitable for posting on WWW sites but resolution is generally too low for publication or grant proposals, and editing is a pain. For highest quality, PostScript is best. Use the Print & File Window Manager PFWM) to save the graphs you want to an Idraw file. This is an encapsulated PostScript format that can be edited by idraw, which comes with the UNIX/Linux version of NEURON. It can also be imported by many draw programs, e.g. CorelDraw. To learn more, see this tutorial from the NEURON Summer Course.

Q: I've used the NEURON Main Menu to construct and manage models. How can I save what I have done?
A: Here's how to save the GUI tools you spawned to a session file.

Q: What is a ses (session) file? Can I edit it?
A: A session file is a plain text file that contains hoc statements that will recreate the windows that were saved to it. It is often quite informative to examine the contents of a ses file, and sometimes it is very useful to change the file's contents with a text editor. Read this for more information.

Q: How do I use NEURON's tools for electrotonic analysis?
A: See this sample lesson from the NEURON Summer Course

Q: Why should I use an odd value for nseg?
A: So there will always be a node at 0.5 (the middle of a section).
Read about this in "NEURON: a Tool for Neuroscientists" by Hines & Carnevale.

Q: What's a good strategy for specifying nseg?
A: Probably the easiest and most efficient way is to use what we call the d_lambda rule, which means "set nseg to a value that is a small fraction of the AC length constant at a high frequency."
Get a copy of "NEURON: a Tool for Neuroscientists", which explains how it works.
Read how to use the d_lambda rule with your own models.

Q: How do I change the background color used in NEURON's shape plots and other graphs?
A: Edit the nrn.defaults file.

Q: How do I change the color scale used in shape plots?
A: Create a file that specifies the desired RGB values.

Q: I see an error message that says ... procedure too big in ./foo.hoc ...
A: There is an upper limit on the size of a procedure that the hoc parser can handle. The workaround is simple. Instead of having a single giant procedure, break it into several smaller procedures, and then call these procedures one after another. For example, suppose your procedure is
   proc buildcell() {
   ... lots of hoc statements ...
   }
just chop it into smaller chunks like this
   proc buildcell_1() {
   ... some hoc statements ...
   }
   proc buildcell_2() {
   ... some more hoc statements ...
   }
   ... etc ...
and then execute them with
   buildcell_1()
   buildcell_2()
   ...
How big can a procedure be? I've never tried to find out. Try cutting your big procedure in half and see if that works. If it doesn't, cut the pieces in half and try again. Eventually you'll find a size that works.

Q: Where can I find examples of mod files?
A: See the NMODL tips on the "getting started" page.

Q: How do I compile mod files?
A: Depends on whether you're running NEURON under MSWindows, UNIX/Linux, OS X, or MacOS. Whichever you use, it's a good idea to keep related mod files in the same directory as the hoc files that need them.

Q: I can't get mod files to compile.
A: Go to The NEURON Forum and check out the "NEURON installation and configuration" discussions for your particular operating system (OS X, MSWin, UNIX/Linux). For OS X and UNIX/Linux this problem often means that the software development environment (compilers and associated libraries) is missing or incomplete.

Q: I installed a new version of NEURON, and now I see error messages like this:
mechanisms fooba needs to be re-translated.
its version 5.2 "c" code is incompatible with this neuron version.
A: Compiling NMODL files produces several "intermediate files" whose names end in .o and .c . This error message means that you have some old intermediate files that were produced under the earlier version of NEURON. So just delete all the .o and .c files, then run nrnivmodl (or mknrndll), and the problem should disappear.

Q: Is there a list of the functions that are built into NMODL?
A: Look here

Q: Is there a list of the functions that are built into hoc?
A: You'll find them in the Programmer's Reference. Also see chapter 11. Interpreter - General in the old "Reference Manual."

Q: What units does NEURON use for current, concentration, etc.?
A: If you're using the GUI, you've probably noticed that buttons next to numeric fields generally indicate the units, such as (mV), (nA), (ms) for millivolt, nanoamp, or millisecond.
Here's a chart of the units that NEURON uses by default.
If you're writing your own mod files, you can specify what units will be used. For example, you may prefer to work with micromolar or nanomolar concentrations when dealing with intracellular free calcium or other second messengers. You can also define new units. See this tutorial to get a better understanding of units in NMODL.
For the terminally curious, here is a copy of the units.dat file that accompanies one of the popular Linux distributions. Presumably mod file variables should be able to use any of its entries.

Q: When I type a new value into a numeric field, it doesn't seem to have any effect.
A: You seem to be using a very old version of NEURON. If you can't update to the most recent version, try this:
After entering a new value, be sure to click on the button next to the numeric field (or press the Return key) so that the bright yellow warning indicator on the button is turned off. While the yellow indicator is showing, the field editor is still in entry mode and its contents have not yet been assigned to the proper variable in memory.

Q: What is the difference between SEClamp and VClamp, and which should I use?
A: SEClamp is just an ideal voltage source in series with a resistance (Single Electrode Clamp), while VClamp is a model of a two electrode voltage clamp with this equivalent circuit:
                   tau2
                   gain
                  +-|\____rstim____>to cell
  -amp --'\/`-------|/
                  |
                  |----||---
                  |___    __|-----/|___from cell
                      `'`'        \|
                      tau1 
If the purpose of your model is to study the properties of a cell, use SEClamp. If the purpose is to study how instrumentation artefacts affect voltage clamp data, use VClamp. For more information about these and other built-in point process mechanisms, go to the Programmer's Reference and click on the term pointprocesses.

Q: SEClamp and IClamp just deliver rectangular step waveforms. How can I make them produce an arbitrary waveform, e.g. something that I calculated or recorded from a real cell?
A: The Vector class's play method can be used to drive any variable with a sequence of values stored in a Vector. For example, you can play a Vector into an IClamp's amp, an SEClamp's amp1, an SEClamp's series resistance rs (e.g. if you have an experimentally measured synaptic conductance time course). To learn how to do this, get vectorplay.zip, which contains an exercise from one of our 5-day hands-on NEURON courses. Unzip it in an empty directory. This creates a subdirectory called vectorplay, where you will find a file called arbforc.html
Open this file with your browser and start the exercise.

Q: I just want a current clamp that will deliver a sequence of current pulses at regular intervals. Vector play seems like overkill for this.
A: Right you are. Pick up pulsedistrib.zip, and unzip it into an empty directory. This creates a subdirectory called pulsedistrib, which contains Ipulse1.mod, Ipulse2.mod, readme.txt, and test_1_and_2.hoc. Read readme.txt, compile the mod files, and then use NEURON to load test_1_and_2.hoc, which is a simple demo of these two current pulse generators.
pulsedistrib also contains ipulse3.mod, ipulse3rig.ses, and test_3.hoc, which address the next question in this list.

Q: I want a current clamp that will generate a pulse when I send it an event, or that I can use to produce pulses at precalculated times.
A: Then get pulsedistrib.zip, and unzip it. Inside the pulsedistrib subdirectory you'll find ipulse3.mod, ipulse3rig.ses, and test_3.hoc (and some other files that pertain to the previous question). ipulse3.mod contains the NMODL code for a current clamp that produces a current pulse when it receives an input event. test_3.hoc is a simple demo of the Ipulse3 mechanism, and ipulse3rig.ses is used by test_3.hoc to create the GUI for a demo of Ipulse3. It uses a NetStim to generate the events that drive the Ipulse3. If you want to drive an Ipulse3 with recorded or precomputed event times, use the VecStim class as described under the topic Driving a synapse with recorded or precomputed spike events in the "Hot tips" area of the NEURON Forum.

Q: I have a set of recorded or calculated spike times. How can I use these to drive a postsynaptic mechanism?
A: Assuming that your synaptic mechanism has a NET_RECEIVE block, so that it is driven by events delivered by a NetCon, I can think of two ways this might be done. Which one to use depends on how many calculated spike times you are dealing with.
If you only have a "few" spikes (up to a few dozen), you could just dump them into the spike queue at the onset of the simulation. Here's how:
1. Create a Vector and load it with the times at which you want to activate the synaptic mechanism.
2. Then use an FIinitializeHandler that stuffs the spike times into the NetCon's event queue by calling the NetCon class's event() method during initialization.
For example, if the Vector that holds the event times is syntimes, and the NetCon that drives the synaptic point process is nc, this would work:
objref fih
fih = new FInitializeHandler("loadqueue()")
proc loadqueue() { local ii
  for ii=0,syntimes.size()-1 nc.event(syntimes.x[ii])
}
Don't forget that these are treated as delivery times, i.e. the NetCon's delay will have no effect on the times of synaptic activation. If additional conduction latency is needed, you will have to incorporate it by adding the extra time to the elements of syntimes before the FInitializeHandler is called.
If you have a lot of spikes then it's best to use an NMODL-defined artificial spiking cell that generates spike events at times that are stored in a Vector (which you fill with data before the simulation). For more information see Driving a synapse with recorded or precomputed spike events in the "Hot tips" area of the NEURON Forum.

Q: How can I read data from a binary PClamp file?
A: clampex.zip contains a mod file that defines an object class (ClampExData) whose methods can read PClamp binary files--or at least it could several years ago--plus a sample data file and a hoc file to illustrate usage. If ClampExData doesn't work with the most recent PClamp file formats, at least clampex.mod is a starting point that you can modify as needed.

Q: How do I exit NEURON? I'm not using the GUI, and when I enter ^D at the oc> prompt it doesn't do anything.
A: You seem to be using an older MSWin or MacOS version of NEURON (why not get the most recent version?). Typing the command
quit()
at the oc> prompt works for all versions, new or old, under all OSes. Don't forget the parentheses, because quit() is a function. Oh, and you need to press the Enter or Return key too.

Using NEURON on the Mac

Q: Under OS X, how do I compile mod files or start NEURON?
A: The typical file organization is to have the hoc and mod files together in a folder (directory). The gui way to launch is then to drag the folder onto the mknrndll icon and then drag the seed hoc file onto the nrngui icon.

If you want to do everything with a UNIX-like terminal window, then in the folder containing the hoc and mod files type

nrnivmodl
nrngui your_starting_file.hoc
This assumes you have /Applications/NEURON-X.X/nrn/i386/bin in your PATH (substitute the version number for the X.X).

Q: How do I compile mod files under MacOS?
A: Read this. A useful tip : keep related mod files in the same directory as the hoc files that need them.


Using NEURON under MSWindows

Q: I installed NEURON but chose a different directory from the default (c:\nrn). The installer ran smoothly and reported no errors, but NEURON doesn't seem to work.
A: NEURON won't run if the path to it includes a blank space. If this is what happened, you should uninstall and reinstall NEURON into a different location. If this isn't the problem, please contact us for additional help.

Q: The GUI tools are too big for the small (800x600) display on my laptop computer--the CellBuilder won't even fit on the screen!
A: In the file c:\nrn\lib\nrn.def change
   *mswin_scale: 1.2
to
   *mswin_scale: 1.5

Q: How can I get MSWindows to launch NEURON when I double click on a hoc file?
A: You must be using an ancient version of NEURON. Here's how to tell Windows 95/98/NT to open hoc files with NEURON

Q: How do I compile mod files? I've been putting them in c:\nrn\bin and then running mknrndll . Is there a better way to do this?
A: It's a bad idea to copy, delete, or rename files in ($NEURONHOME)/bin, because a careless error could break your installation of NEURON. Here's a preferable approach.

Q: I've installed NEURON but I don't see any hoc or mod files on my computer.
A: Windows Explorer is hiding things from you. This is fine if you only use prepackaged applications like Word or Excel. However, if you're going to develop models, then you're developing software (regardless of whether you do it with NEURON's GUI tools or by writing hoc code), and you'll need to know exactly what's on your PC. Among other things, you have to be able to recognize file types, which means you must see file extensions. Specifically, you need to configure Windows Explorer to show details and show all files. It's also a good idea to display the full path in the title bar and to have Windows Explorer use a two panel display, so that the directory structure of your drive ("folders") is shown in the left panel and the contents of the current directory (current "folder") are shown on the right. Finally, unless you have a giant monitor with lots of space to waste, get rid of "Web style" appearance and use "Classic style."

Q: NotePad won't let me create a .hoc or .mod file. It keeps sticking ".txt" onto the end of file names!
A: NotePad does this when you save to a new file, but you can prevent it from happening by enclosing the file name in quotes, e.g. "myfile.hoc" or "mymechanism.mod". You only have to do this the first time you save to a file.
If you're going to do serious program development, you might want to try a different text editing program, and I don't mean WordPad or Word. There are some excellent alternatives, including freeware.

Q: Can I cut and paste to and from NEURON's interpreter window?
A: Yes. Recent versions of NEURON use a cygwin terminal for direct messages to and from the interpreter, and this terminal is "cut and paste compatible" with ordinary MSWin applications. However, the usual MSWin keyboard shortcuts ^C and ^V don't work in NEURON's terminal, so you have to use the mouse there. Here's how:
  • To copy from NEURON's terminal, first use "click and drag" to select the text you want to copy. Then you can paste this into an MSWin program (e.g. a text editor) with that program's Edit/Paste (or the keyboard shortcut ^V).
  • To copy to NEURON's terminal, start in the MSWin program and select the text you want to copy using either the mouse or the keyboard. Then select NEURON's terminal, hit the return key once to make sure you're at an oc> prompt, and click on the middle button of your mouse (or on the scroll wheel, if that's the kind of mouse you have). This even works for multiple lines of hoc code.
    If you have a two button mouse and no scroll wheel, you may need to enable "middle button emulation" (AKA "chording") in the MSWin Control Panel.

Using NEURON under UNIX/Linux

Note: paths specified here assume that InterViews and NEURON are installed in /usr/local/iv and /usr/local/nrn, respectively.
Q: How do I compile mod files under UNIX/Linux?
A: Read this. A useful tip : keep related mod files in the same directory as the hoc files that need them.

Q: My computer has a small display. How can I change the typeface size used by NEURON's GUI?
A: In /usr/local/nrn/share/nrn/lib/nrn.defaults change
   *font: *helvetica-medium-r-normal*--14*
to
   // *font: *helvetica-medium-r-normal*--14*
   *font: *-helvetica-medium-r-*-*-*-100-*
and in /usr/local/iv/share/app-defaults/InterViews change
   *font: fixed
to
   // *font: fixed
   *font: *-helvetica-medium-r-*-*-*-100-*
   *MenuItem*font: *-helvetica-medium-r-*-*-*-100-*
   *MenuBar*font: *-helvetica-medium-r-*-*-*-100-*
These sizes work well on an 800x600 laptop LCD; other sizes may be better for your hardware. It may be necessary to install the 75 DPI XWindow fonts in order to have a sufficient selection of typefaces and sizes.

Q: My program foo.hoc doesn't use graphics. How do I start it so that there is no GUI? That will allow me to log onto a computer via ssh, use nohup to start a process, log off, and the process continues.
A: If foo.hoc needs only the mechanisms that are built into NEURON, then instead of typing
   nrngui foo.hoc
just type
   nrniv foo.hoc
If foo.hoc needs something you compiled from mod files, you'll need to type
   i686/special foo.hoc
The "special" shell script launches nrniv with an argument that causes dynamic loading of the shared object that nrnivmodl created from your mod files.
An aside : The nrngui shell script not only makes nrniv load the nrngui.hoc file (which loads the GUI library and starts the NEURONMainMenu) -- it also checks to see if there is a i686/special (under Linux), and if so, executes that shell script instead of nrniv.