neuroml / neuroml_api

C++ API for NeuroML 2

NeuroML API for C++

C++ API for NeuroML 2.

Using the API

For more info on the generated C++ structure, see the XSD user manual. The sample programs in the test folder will also give you a reasonable idea of how things work.

If you have a project built with CMake that depends on the API, you can include it (and its own dependencies) very easily in your project. Once the API has been installed (see below) simply add the following line to your CMakeLists.txt:

find_package(NeuroML_API REQUIRED)

and then link against the NeuroML::neuroml library, e.g. by

add_executable(example example.cxx)
target_link_libraries(example NeuroML::neuroml)

If you installed the NeuroML_API in a non-standard location, you may need to set the CMAKE_PREFIX_PATH CMake variable to that location in order to find the package.

Building the API

The NeuroML API is built using CMake (versions >= 3.14), and the process works best with 'out of source' builds, where you build the API in a folder separate from the source tree. Having cloned the repository, we therefore suggest you create a separate 'NeuroML_API_build' folder adjacent to the source, change into it, and then run the build configuration commands:

mkdir NeuroML_API_build
cd NeuroML_API_build
cmake ../NeuroML_API

You may then run

• make to build,
• make doc to build the HTML documentation using Doxygen (in a docs subfolder of your build folder; only available if Doxygen installed),
• ctest (or make test) to run tests,
• sudo make install to install on your system, or
• cpack to generate an installable package (see cpack documentation).

The default CMake options should be appropriate for most cases. The only essential external dependencies are Xerces C++ and CodeSynthesis XSD.

On Ubuntu based systems, you can install Xerces and xsd from the standard repositories using apt:

sudo apt-get install xsdcxx libxerces-c-dev

On Fedora and other RPM based distributions, you can install Xerces and xsd from the standard repositories using dnf or yum:

sudo dnf install xsd xerces-c-devel doxygen

If you install xsd in a non-standard location, please set the XSD_ROOT environment variable to the root folder for the software (i.e. the folder containing bin and libxsd folders).

You may wish to change the CMAKE_INSTALL_PREFIX to specify where the API will be installed. The generated library will be placed in a lib subfolder, and all necessary headers in an include/neuroml subfolder.

If you wish to regenerate the C++ bindings (because you have changed the XML Schema or xsdcxx options) you will need to pass REGENERATE_BINDINGS=ON to the CMake command:

cmake -DREGENERATE_BINDINGS=ON ...

You can also change the path to the schema file to use by setting the variable NeuroML_SCHEMA_PATH in CMake.

Once the bindings have been regenerated, you can run make copy_wrappers to copy the new versions back into the source tree, for committing to the repository.

neuroml_api's Issues

Add some higher level helper methods

For instance

• a function std::unique_ptr<neuroml2::NeuroMLDocument> neuroml::parseFile(const std::string& path_to_file) for one-liner validate & parse to object
• a method NeuroMLDocument::writeToFile(const std::string& path_to_file, ios_base::openmode mode = ios_base::out) for one-liner file output

Add automating testing with Travis

Schema is missing from installed package

Which means it only really works if the source tree is still present, at least for current examples, which hardcode the schema path for parse/serialise operations. And we don't want to rely on the schema specified in the .nml file for parsing since it often refers to an earlier alpha/beta version which we don't support.

HDF5 import/export

Similar to the Python API, although the HDF5 form of NML2 is still in flux, so not a priority.

Create executable to print summary information

There is a utility in pyNeuroML which can print the summary info in a NeuroML file, e.g. this file
https://github.com/NeuralEnsemble/libNeuroML/blob/development/neuroml/examples/test_files/simplenet.nml
with:

 pynml-summary simplenet.nml

prints:

*******************************************************
* NeuroMLDocument: simplenet
*
*   ExpTwoSynapse: ['syn0']
*   IafCell: ['iaf0']
*   PulseGenerator: ['input0', 'input1', 'input2', 'input3', 'input4']
*
*  Network: simplenet
*
*   10 cells in 2 populations 
*     Population: Pop0 with 5 components of type iaf0
*     Population: Pop1 with 5 components of type iaf0
*
*   16 connections in 1 projections 
*     Projection: Proj0 from Pop0 to Pop1, synapse: syn0
*       16 connections: [(Connection 0: 0 -> 0), ...]
*
*   5 inputs in 5 input lists 
*     Input list: il0 to Pop0, component input0
*       1 inputs: [(Input 0: 0:0(0.500000)), ...]
*     Input list: il1 to Pop0, component input1
*       1 inputs: [(Input 0: 1:0(0.500000)), ...]
*     Input list: il2 to Pop0, component input2
*       1 inputs: [(Input 0: 2:0(0.500000)), ...]
*     Input list: il3 to Pop0, component input3
*       1 inputs: [(Input 0: 3:0(0.500000)), ...]
*     Input list: il4 to Pop0, component input4
*       1 inputs: [(Input 0: 4:0(0.500000)), ...]
*
*******************************************************

It would be useful if there was a similar executable cnml-summary which gets created when the NeuroML_API is installed (with sudo make install).

Ideally this will be faster than the Python version for large files... An initial parsing of the XML file can be seen here: https://github.com/NeuroML/NeuroML_API/blob/master/test/example.cxx#L21

Update to use NMLv2.2 schema

Release under MIT licence

Allow loading of complete NeuroML models containing <include>

NeuroML files can include external files to avoid repetition of elements, e.g. <include href="hhneuron.cell.nml"/> in https://github.com/openworm/hodgkin_huxley_tutorial/blob/master/Tutorial2/NeuroML2/HHTutorial.net.nml

The C++ API should have a helper function to support the loading of the full model, e.g. as in the Python case: https://github.com/NeuralEnsemble/libNeuroML/blob/development/neuroml/loaders.py#L230

Then a summary can be printed for the full model, using this #8

@tuigimdochas