Running a simulation

This section describes how to use CoreNEURON to simulate a NEURON model.

Building MOD files

As in a typical NEURON workflow, you can now use nrnivmodl to translate MOD files. In order to enable CoreNEURON support, you must set the -coreneuron flag. Make sure any necessary modules (compilers, CUDA, MPI etc.) are loaded before you run nrnivmodl:

nrnivmodl -coreneuron <directory containing .mod files>

Even if you don’t have additional MOD files (i.e. you are relying on builtin NEURON MOD files) you still need to use nrnivmodl -coreneuron to generate a CoreNEURON library. For example, you can run:

nrnivmodl -coreneuron .

With the command above, NEURON will create a x86_64/special binary that is linked to CoreNEURON (here x86_64 is the architecture name of your system).

If you see any compilation error then one of the MOD files might be incompatible with CoreNEURON. In this case, you should first consult the CoreNEURON Compatibility section, and if that does not provide a clear explanation then you should open an issue with an example of your MOD file.

Enabling CoreNEURON

With CoreNEURON, existing NEURON models can be run with minimal changes. For a given NEURON model, the following steps are usually required:

First, enable cache efficiency:

from neuron import h
h.CVode().cache_efficient(1)

Second, enable CoreNEURON:

from neuron import coreneuron
coreneuron.enable = True

If your build supports GPU execution then you may also enable this at runtime:

coreneuron.gpu = True

Warning

If you enable GPU execution you must launch your simulation using the special binary! This is explained in more detail below.

Finally, use psolve to run the simulation after initialization:

h.stdinit()
pc.psolve(h.tstop)

With the above steps, NEURON will build the model in memory and transfer it to CoreNEURON for simulation. At the end of the simulation CoreNEURON will, by default, transfer spikes, voltages, state variables, NetCon weights, all Vector.record, and most GUI trajectories to NEURON. These variables can be recorded using the regular NEURON API (e.g. Vector.record() or ParallelContext.spike_record()).

If you are primarily using HOC then before calling psolve you can enable CoreNEURON as:

// make sure NEURON is compiled with Python
if (!nrnpython("from neuron import coreneuron")) {
  printf("NEURON not compiled with Python support\n")
  return
}

// access coreneuron module via Python object
py_obj = new PythonObject()
py_obj.coreneuron.enable = 1

Once you have adapted your model by making the changes described above then you can execute your model like a normal NEURON simulation. For example:

mpiexec -n <num_process> nrniv -mpi -python your_script.py # python
mpiexec -n <num_process> nrniv -mpi your_script.hoc        # hoc

Alternatively, instead of nrniv you can use the special binary generated by nrnivmodl command. Note that for GPU execution you must use the special binary to launch your simulation:

mpiexec -n <num_process> x86_64/special -mpi -python your_script.py # python
mpiexec -n <num_process> x86_64/special -mpi your_script.hoc        # hoc

This is because the GPU-enabled build is statically linked to avoid issues with OpenACC, so python and nrniv cannot dynamically load CoreNEURON.

As CoreNEURON is used as a library under NEURON, it will use the same number of MPI ranks as NEURON. Also, if you enable threads using ParallelContext.nthread() then CoreNEURON will internally use the same number of OpenMP threads.

Note

You may need to replace mpiexec with an MPI launcher supported on your system, e.g. srun or mpirun.