Running NESTML

Running NESTML from Python

NESTML can be imported as a Python package, and can therefore be used from within other Python tools and scripts. After PyNESTML has been installed, the following function has to be imported:

from pynestml.frontend.pynestml_frontend import generate_target

Subsequently, it is possible to call PyNESTML from other Python tools and scripts via calls to generate_target(), which generates, builds and installs code for the target platform. generate_target() can be called as follows:

generate_target(input_path, target_platform, target_path, install_path, logging_level, module_name, store_log, suffix, dev, codegen_opts)

The following default values are used, corresponding to the command line defaults. Possible values for logging_level are the same as before (“DEBUG”, “INFO”, “WARNING”, “ERROR”, “NO”). Note that only the input_path argument is mandatory:

Argument	Type	Default
input_path	str or Sequence[str]	no default
target_platform	str	“NEST”
target_path	str	None
install_path	str	None
logging_level	str	“ERROR”
module_name	str	“nestmlmodule”
suffix	str	“”
store_log	bool	False
dev	bool	False
codegen_opts	Optional[Mapping[str, Any]]	(Optional) A JSON equivalent Python dictionary containing additional options for the target platform code generator. These options are specific to a given target platform, see for example Running NESTML with custom templates.

A typical script for the NEST Simulator target could look like the following. First, import the function:

from pynestml.frontend.pynestml_frontend import generate_target

generate_target(input_path="/home/nest/work/pynestml/models",
                target_platform="NEST",
                target_path="/tmp/nestml_target")

We can also use a shorthand function for each supported target platform (here, NEST):

from pynestml.frontend.pynestml_frontend import generate_nest_target

generate_nest_target(input_path="/home/nest/work/pynestml/models",
                     target_path="/tmp/nestml_target")

To dynamically load a module with module_name equal to nestmlmodule (the default) in PyNEST can be done as follows:

nest.Install("nestmlmodule")

The NESTML models are then available for instantiation, for example as:

pre, post = nest.Create("neuron_nestml", 2)
nest.Connect(pre, post, "one_to_one", syn_spec={"synapse_model": "synapse_nestml"})

Running NESTML from the command line

The toolchain can also be executed from the command line by running:

nestml ARGUMENTS

This will generate, compile, build, and install the code for a set of specified NESTML models. The following arguments can be given, corresponding to the arguments in the command line invocation:

Command	Description
-h or --help	Print help message.
--input_path	One or more input path(s). Each path is a NESTML file, or a directory containing NESTML files. Directories will be searched recursively for files matching “*.nestml”.
--target_path	(Optional) Path to target directory where generated code will be written into. Default is target, which will be created in the current working directory if it does not yet exist.
--target_platform	(Optional) The name of the target platform to generate code for. Default is NEST.
--logging_level	(Optional) Sets the logging level, i.e., which level of messages should be printed. Default is ERROR, available are [DEBUG, INFO, WARNING, ERROR, NO]
--module_name	(Optional) Sets the name of the module which shall be generated. Default is the name of the directory containing the models. The name has to end in “module”. Default is nestmlmodule.
--store_log	(Optional) Stores a log.txt containing all messages in JSON notation. Default is OFF.
--suffix	(Optional) A suffix string that will be appended to the name of all generated models.
--install_path	(Optional) Path to the directory where the generated code will be installed.
--dev	(Optional) Enable development mode: code generation is attempted even for models that contain errors, and extra information is rendered in the generated code. Default is OFF.
--codegen_opts	(Optional) Path to a JSON file containing additional options for the target platform code generator.

NEST Simulator target

After NESTML completes, the NEST extension module (by default called "nestmlmodule") can either be statically linked into NEST (see Writing an extension module), or loaded dynamically using the Install API call in Python.

Manually building the extension module

Sometimes it can be convenient to directly edit the generated code. To manually build and install the NEST extension module, go into the target directory and run:

cmake -Dwith-nest=<nest_install_dir>/bin/nest-config .
make all
make install

where <nest_install_dir> is the installation directory of NEST (e.g. /home/nest/work/nest-install).

Custom templates

See Running NESTML with custom templates.

NEST 2.* compatibility mode

To generate code that is compatible with NEST Simulator major version 2 (in particular, 2.20.*), use the following for the code generator dictionary (this is extracted from tests/nest_tests/nest2_compat_test.py):

codegen_opts = {
    "templates": {
        "path": os.path.join(os.path.dirname(__file__), os.pardir, os.pardir, "pynestml", "codegeneration",
                             "resources_nest", "point_neuron_nest2"),
        "model_templates": ["@NEURON_NAME@.cpp.jinja2", "@NEURON_NAME@.h.jinja2"],
        "module_templates": ["setup/CMakeLists.txt.jinja2", "setup/SLI_Init.sli.jinja2",
                             "setup/@MODULE_NAME@.h.jinja2", "setup/@MODULE_NAME@.cpp.jinja2"]
}}

The templates are in the directory pynestml/codegeneration/resources_nest/point_neuron_nest2.