Create C++ API for NeuroML 2

[pgleeson]

C++ API for reading/editing/writing NeuroML2

Priorities will be:

• Ease of (re)generation from latest Schema
  • Ease of installation
  • Lack of external dependencies
  • Examples (based on https://github.com/NeuralEnsemble/libNeuroML/tree/master/neuroml/examples)

An initial version of this be worked on by @jonc125 under https://github.com/NeuroML/NeuroML_API

One option to be explored is a quick C++ API with Codesynthesis XSD...

[jonc125]

Note that with CodeSynthesis we can distribute the required bits of their code with the NeuroML API under an open source licence provided that our code "does something useful" rather than just being a wrapper around the auto-generated code. See http://www.codesynthesis.com/projects/xsd/FLOSSE for details. So we'd probably need some utility stuff similar to the Python libNeuroML before we could do this. But if we can then I think the only external dependency would be Xerces-C++ which is pretty standard.

(People wanting to regenerate the bindings would need to install CodeSynthesis XSD themselves.)

[jonc125]

Initial demo created in https://github.com/NeuroML/NeuroML_API/commit/7ce61dbb198d50deb963a6120e28c02c3ba31e14

Some questions:

• Do we want type and method names to match the Schema or Python API?

  Probably best to stick to the generated default method names for now. Python field names are pythonic by demand of python users, but if C++ variable names closely match XML form (and class types are capitalised) that should be fine for C++ users

• I'm guessing we're not worrying about HDF5 import/export for non-Python bindings (at least not yet)?

  Not yet, but we'll have to address that when the HDF5 form of NML2 is more stable. fine to ignore for now.

• Apart from that, I assume that the methods defined in neuroml/nml/helper_methods.py would be useful to have in the C++ classes too. (Using http://wiki.codesynthesis.com/Tree/Customization_guide)

  Yes, but helper_methods.py is not comprehensive just yet. Best work on geting the right place for adding some examples of helper methods and allow users to add their own. Looks like NeuroML_custom.cxx does exactly this.

• What other extra utility functionality would be wanted in this API?

  Perhaps some higher level helper methods for creating new NMLDocs, reading/writing/validating with one function call?

• What kind of installation experience is wanted? For instance, do we want to make it easy for people using CMake to pick this up as a library?

  CMake looks like the best bet

[jonc125]

Done some work on adding custom methods; latest in NeuroML/NeuroML_API@c170898. I haven't done everything from the Python library as some of them appear to be for classes that are now deprecated, and I couldn't see test files using them in the Python repo.

The next step would probably be to package this as a CMake project that can be installed as library + headers, with the hooks for other CMake projects to find it easily.

It could also do with some more thorough testing, including of creating models from scratch. We should agree on a naming convention to follow before doing much more coding around the APi though!

[pgleeson]

@jonc125 See above for answers... I have it successfully installed locally and have managed to write another example for creating nml files, but just saw some refactoring for cmake before I could commit.. Let me know when updated version is stable.

[jonc125]

@pgleeson Everything should be in the right place now and ready to use. Just some fine-tuning of options, but that shouldn't prevent you adding another example. Would be useful to see what you've done in creating something from scratch to see what kinds of helpers would be wanted there.

Another question - do you have a preference for licence to use? I think we discussed MIT last week? Then I can add the appropriate "Copyright UCL" notices.

[pgleeson]

Closing this issue and new ones can be create for refinements.

[jonc125]

Probably best to put any new issues in https://github.com/NeuroML/NeuroML_API/issues