Making changes to the NeuroML standard

Making changes to the NeuroML standard#

The NeuroML standard is stored in two sets of files, each serving a specific purpose:

  • the NeuroML XML Schema Definition (XSD) file: this specifies the structure of a valid NeuroML XML file: what XML tags may be used and the how they are related

  • the NeuroML LEMS ComponentType definition XML files: these include the definitions of the NeuroML standard ComponentTypes in LEMS constructs, which include the mathematical details underlying these ComponentTypes

These files are housed in the NeuroML repository.

The XSD schema file is used to validate NeuroML XML files, as shown in the page on validating NeuroML files. Further, the NeuroML Python model in libNeuroML is also generated from the XSD file using the generateDS utility.

The LEMS ComponentType definition XML files are also used for a series of additional validation tests, and since they include the details of the underlying dynamics for all ComponentTypes, they are also used for the simulation of NeuroML models either using the reference LEMS interpreter, jLEMS, or through automated code generation for supported simulation platforms (via jNeuroML). Additionally, the LEMS definition files are also used the generate the human readable schema documentation included in this documentation resource.

The two sets of files are therefore, tightly coupled. Any changes to the XSD file must also be followed by corresponding changes to the LEMS definition files.

Procedure#

PR waiting

TODO: A pull request to include the transfer_docs_to_xsd.py script in the repository is in review here: NeuroML/NeuroML2#172

The suggested way of making changes to these files is via pull requests to the NeuroML repository which will undergo review by the NeuroML editorial board and the development team. As noted in the general contribution guidelines, the development branch tracks the next release of the NeuroML standard. So, all pull request must be made against the development branch.

  • New ComponentTypes, and their elements (parameters, variables etc.) that are added in the LEMS definition XML files should be properly documented.

  • After both sets of files have been modified, please run the transfer_docs_to_xsd.py script in the scripts folder to copy documentation over from the XML files to the XSD schema file. This script will also run basic sanity checks to ensure that all ComponentTypes in the LEMS XML definition files are represented in the XSD schema file and vice-versa.

  • Please run xmllint on the files to ensure they are formatted correctly.

  • Please make individual commits for changes to the XSD file, and the XML files. This ensures that their change history is clearly maintained.

Regenerating schema documentation#

Once the pull request has been merged in the NeuroML repository, the human readable schema documentation included in this documentation resource must be updated. This is done by running the generate-jupyter-ast.py script included in the documentation source repository. This will read the LEMS XML definition files and regenerate the corresponding documentation pages. A pull request can then be opened with the updated pages.

Updating the Java API: org.neuroml.model#

TODO: Document what needs to be done for NeuroML/org.neuroml.model

Updating the Python API: libNeuroML#

PR waiting

TODO: A pull request to include the regenerate-nml.sh script in the repository is in review here: NeuralEnsemble/libNeuroML#110

Any changes to the XSD schema file require regeneration of the Python object model in libNeuroML:

  • copy over the updated XSD schema file to the neuroml/nml/ directory in the development branch

  • commit the new XSD file

  • run the regenerate-nml.sh script to regenerate and reformat nml.py

  • build and install libNeuroML into a new virtual environment

  • run all tests using pytest

  • run all examples and ensure that they run correctly (please see the GitHub actions workflow for more information)

  • if all checks pass successfully, a pull request can be opened

Updating the C++ API#

TODO: Document what needs to be done for NeuroML/NeuroML_API