Running Python and HOC scripts
This section describes the various ways that you can run Python and HOC scripts. You may also want to refer to the Python and HOC reference sections for documentation of how to write scripts using the two languages.
HOC scripts are always run using one of the NEURON executables, such as
Python scripts can also be run using these executables, but may additionally be
run using the standard
Files passed to the NEURON executables are identified based on their file extensions, so:
nrniv script.hoc nrniv script.py nrniv -python script.hoc nrniv -python script.py python script.py
Will all work as expected. It is also possible to execute code from the commandline, for example:
nrniv -c "hoc_statement" nrniv -python -c "python_statement" python -c "python_statement"
In this case, it is necessary to tell NEURON whether or not the code being
-c is HOC or Python code, using the
When using Python, it is recommended that you organise your scripts so that
there is no need to pass more than one
.py file or
-c argument to
This is consistent with the
python command, which only accepts a single
script file or
-c option, and respecting this rule minimises the number of
possible differences between
python script.py and
This section describes some of the caveats and differences between different ways of running HOC and Python scripts. In most cases, these details will not be important.
- Use of custom MOD files:
If you use custom MOD files to extend NEURON, then some additional details may apply.
In this case, you will have run the nrnivmodl command, which will have produced a new executable called
specialin a subdirectory named according to your computer architecture (e.g.
specialaccepts the same commandline arguments as
nrniv, and it can be convenient or necessary (e.g. when using GPU support) to launch scripts using it.
- Multiple script files and commands:
In Python mode (
-python) the NEURON executables will only process one input file or
-ccommand, whereas in HOC mode it will execute several.
This means that
nrniv a.py b.pywill execute both scripts, but
nrniv -python a.py b.pywill only execute
b.pyas an argument in
nrniv -c "hoc_code_1" -c "hoc_code_2"will execute both fragments of HOC code, but
nrniv -python -c "pycode1" -c "pycode2"will only execute the first expression,
It is best to organise your Python scripts to have a single entry point and to not rely on executing multiple files. This is consistent with the regular
NEURON aims to provide the same Python environment with
nrniv -pythonas you would obtain with
pythondirectly. This includes the behaviour for the first entry in
sys.path, which is an empty string when
-cas used, and the script directory after resolving symlinks if a script is passed. See also: the corresponding section of the Python documentation. If you try and execute multiple Python scripts, the
sys.pathbehaviour may be surprising.
One intentional difference is that if the path to the
neuronmodule does not exist in
nrniv -pythonwill automatically append it, while if you were to run
pythonthen an attempt to
import neuronwould simply fail.
The NEURON executables also accept a
-pyexeargument, which governs which Python interpreter NEURON will try and launch. The
NRN_PYTHONEXEenvironment variable has the same effect, but if both are used then
This is typically only relevant in a build of NEURON that uses dynamic Python support (NRN_ENABLE_PYTHON_DYNAMIC), which typically means the macOS and Windows binary installers.
In this situation,
nrniv -pythonsearches for a Python installation in the following order:
The argument to
$PATH, where the set of
pythonX.Ynames corresponds to all the Python versions supported by the NEURON installation. The search order matches the NRN_PYTHON_DYNAMIC setting that was used at build time.
On Windows, some other heuristics are applied as a last resort.
NEURON will exit with an error if you try to force it to use an unsupported Python version using
NRN_PYTHONEXE. If these are not passed, it will accept the first Python that is supported by the installation.
On a system with multiple Python versions, this can lead to differences between
python -c "import neuron" # fails, NEURON not installed python3.10 -c "import neuron" # succeeds, NEURON installed for 3.10 nrniv -python -c "import neuron" # succeeds, search ignores `python` # and continues to find `python3.10`
Installations using Python wheels (
pip install neuron) explicitly set the
NRN_PYTHONEXEvariable, so this section is unlikely to be relevant for those installations.