Running NESTML ############## Running NESTML causes several processing steps to occur: 1. The model is parsed from file and checked (syntax, consistent physical units, and so on). 2. Code is generated from the model by one of the "code generators" selected when NESTML was invoked. 3. If necessary, the code is compiled and built by the "builder" that belongs to the selected code generator. Supported target platforms -------------------------- Currently, the following target platforms are supported for code generation. Click on each for further information: .. grid:: 2 .. grid-item-card:: :text-align: center :class-title: sd-d-flex-row sd-align-minor-center :doc:`NEST Simulator ` |nest_logo| .. grid-item-card:: :text-align: center :class-title: sd-d-flex-row sd-align-minor-center :doc:`NEST Simulator (compartmental) ` |nest_logo| .. grid:: 2 .. grid-item-card:: :text-align: center :class-title: sd-d-flex-row sd-align-minor-center :doc:`Python-standalone ` |python_logo| .. grid-item-card:: :text-align: center :class-title: sd-d-flex-row sd-align-minor-center :doc:`SpiNNaker ` |spinnaker_logo| .. grid:: 2 .. grid-item-card:: :text-align: center :class-title: sd-d-flex-row sd-align-minor-center :doc:`NEST Desktop ` |nest_desktop_logo| .. grid-item-card:: :text-align: center :class-title: sd-d-flex-row sd-align-minor-center :doc:`"Pretty" render ` |pretty_render_logo| .. grid:: 2 .. grid-item-card:: :text-align: center :class-title: sd-d-flex-row sd-align-minor-center :doc:`GeNN ` |genn_logo| .. grid-item-card:: :text-align: center :class-title: sd-d-flex-row sd-align-minor-center :doc:`NEST GPU ` |nest_gpu_logo| .. |nest_logo| image:: ../fig/nest-simulator-logo.png :width: 95px :height: 40px :target: running_nest.html .. |python_logo| image:: ../fig/python-logo.png :width: 40px :height: 40px :target: running_python_standalone.html .. |spinnaker_logo| image:: ../fig/spinnaker_logo.svg :width: 40px :height: 40px :target: running_spinnaker.html .. |pretty_render_logo| image:: ../fig/nestml_code_render_thumbnail.png :width: 100px :height: 40px :target: running_pretty_render.html .. |genn_logo| image:: ../fig/genn-logo-thumbnail.png :width: 100px :height: 36px :target: running_genn.html .. |nest_desktop_logo| image:: ../fig/nest-desktop.svg :width: 40px :height: 40px :target: running_nest_desktop.html .. |nest_gpu_logo| image:: ../fig/nest-gpu.svg :width: 95 :height: 40px :target: running_nest_gpu.html .. warning:: To ensure correct and reproducible results, always inspect the generated code by hand. Run comprehensive numerical testing of the model(s). In case of doubt, please create a `GitHub Issue `_ or write in on the `NEST mailing list `_. 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: .. code-block:: python 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: .. code-block:: python 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: .. list-table:: :header-rows: 1 :widths: 10 10 10 * - 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. A list of available options can be found under the section "Code generation options" for your intended target platform on the page :ref:`Running NESTML`. For a detailed description of all the arguments of ``generate_target()``, see :func:`pynestml.frontend.pynestml_frontend.generate_target`. Running NESTML from the command line ------------------------------------ The toolchain can also be executed from the command line by running: .. code-block:: bash 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: .. list-table:: :header-rows: 1 :widths: 10 30 * - 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. The available targets are ``NEST``, ``PYTHON-STANDALONE``, ``SPINNAKER``, and ``NEST_DESKTOP``. 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. A list of available options can be found under the section "Code generation options" for your intended target platform on the page :ref:`Running NESTML`. Filesystem permissions ~~~~~~~~~~~~~~~~~~~~~~ If you are using NESTML on a shared server or high performance computing (HPC) system, it could be that NESTML was installed in a location in the filesystem to which you do not have write access. In this case, make sure to explicitly set the ``install_path`` when generating the target code to a directory to which you have write access, for example, inside your home directory. For example: .. code-block:: python from pynestml.frontend.pynestml_frontend import generate_nest_target nestml_file_path = "~/nestml-neurons" # this should be a path inside your home directory # or other directory to which you have write permission nestml_target_path = nestml_file_path + "/nestml_target/" nestml_install_path = nestml_file_path + "/nestml_install/" print(f"Generating NEST target code from {nestml_file_path} to {nestml_target_path}") generate_nest_target( input_path=str(nestml_file_path), target_path=str(nestml_target_path), install_path=str(nestml_install_path) ) Then, when running the Python simulation script which contains the ``nest.Install()``, make sure to first set the ``LD_LIBRARY_PATH``, such as: .. code-block:: bash export LD_LIBRARY_PATH="~/nestml-neurons/nestml_install":$LD_LIBRARY_PATH