NeuroML support¶

Arbor offers limited support for models described in NeuroML version 2. This is not built by default, but can be enabled by providing the -DARB_NEUROML=ON argument to CMake at configuration time (see NeuroML support). This will build the arbornml libray and defines the corresponding arbor::arbornml CMake target.

The arbornml library uses libxml2 for XML parsing. Applications using arbornml will need to link against libxml2 in addition, though this is performed implicitly within CMake projects that add arbor::arbornml as a link library.

All classes and functions provided by the arbornml library are provided in the arbnml namespace.

Libxml2 interface¶

Libxml2 offers threadsafe XML parsing, but not by default. If the application uses arbornml in an unthreaded context, or has already explicitly initialized libxml2, nothing more needs to be done. Otherwise, the libxml2 function xmlInitParser() must be called explicitly.

arbornml provides a helper guard object for this purpose, defined in arbornml/with_xml.hpp:

class with_xml¶: An RAII guard object that calls xmlInitParser() upon construction, and xmlCleanupParser() upon destruction. The constructor takes no parameters.

NeuroML 2 morphology support¶

NeuroML documents are represented by the arbnml::neuroml class, which in turn provides methods for the identification and translation of morphology data. neuroml objects are moveable and move-assignable, but not copyable.

An implementation limitation restrictes valid segment id values to those which can be represented by an unsigned long long value.

class neuroml¶

neuroml(std::string)¶

Build a NeuroML document representation from the supplied string.

std::vector<std::string> cell_ids() const¶

Return the id of each <cell> element defined in the NeuroML document.

std::vector<std::string> morphology_ids() const¶

Return the id of each top-level <morphology> element defined in the NeuroML document.

std::optional<morphology_data> morphology(const std::string&) const¶

Return a representation of the top-level morphology with the supplied identifier, or std::nullopt if no such morphology could be found. Parse errors or an inconsistent representation will raise an exception derived from neuroml_exception.

std::optional<morphology_data> cell_morphology(const std::string&) const¶

Return a representation of the morphology associated with the cell with the supplied identifier, or std::nullopt if the cell or its morphology could not be found. Parse errors or an inconsistent representation will raise an exception derived from neuroml_exception.

The morphology representation contains the corresponding Arbor arb::morphology object, label dictionaries for regions corresponding to its segments and segment groups by name and id, and a map providing the explicit list of segments contained within each defined segment group.

class morphology_data¶

std::optional<std::string> cell_id¶

The id attribute of the cell that was used to find the morphology in the NeuroML document, if any.

std::string id¶

The id attribute of the morphology.

arb::morphology morphology¶

The corresponding Arbor morphology.

arb::label_dict segments¶

A label dictionary with a region entry for each segment, keyed by the segment id (as a string).

arb::label_dict named_segments¶

A label dictionary with a region entry for each name attribute given to one or more segments. The region corresponds to the union of all segments sharing the same name attribute.

arb::label_dict groups¶

A label dictionary with a region entry for each defined segment group

std::unordered_map<std::string, std::vector<unsigned long long>> group_segments¶

A map from taking each segment group id to its corresponding collection of segments.

Exceptions¶

All NeuroML-specific exceptions are defined in arbornml/nmlexcept.hpp, and are derived from arbnml::neuroml_exception which in turn is derived from std::runtime_error. With the exception of the no_document exception, all contain an unsigned member line which is intended to identify the problematic construct within the document.

class xml_error : neuroml_exception¶: A generic XML error generated by the libxml2 library.

class no_document : neuroml_exception¶: A request was made on an neuroml document without any content.

class parse_error : neuroml_exception¶: Failure parsing an element or attribute in the NeuroML document. These can be generated if the document does not confirm to the NeuroML2 schema, for example.

class bad_segment : neuroml_exception¶: A <segment> element has an improper id attribue, refers to a non-existent parent, is missing a required parent or proximal element, or otherwise is missing a mandatory child element or has a malformed child element.

class bad_segment_group : neuroml_exception¶: A <segmentGroup> element has a malformed child element or references a non-existent segment group or segment.

class cyclic_dependency : neuroml_exception¶: A segment or segment group ultimately refers to itself via parent or include elements respectively.