Current layout implementation
Details here are given to outline a suggested approach for the preliminary development of libSBML code to support SBML extensions, until we have a working implementation of the a more robust API. In a nutshell, we suggest that people wishing to start coding mimic the way the current layout extension is implemented in libSBML.
The main layout information appears within the annotation element on the model component of an SBML file, as shown:
<?xml version="1.0" encoding="UTF-8"?> <sbml xmlns="http://www.sbml.org/sbml/level2" level="2" version="1"> <model id="TestModel"> <annotation> <listOfLayouts xmlns="http://projects.eml.org/bcb/sbml/level2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <layout id="Layout_1"> <dimensions width="400" height="220"/> <listOfCompartmentGlyphs> <compartmentGlyph id="CompartmentGlyph_1" compartment="Compartment_1"> <boundingBox id="bb1"> <position x="5" y="5"/> <dimensions width="390" height="210"/> </boundingBox> </compartmentGlyph> </listOfCompartmentGlyphs> <listOfSpeciesGlyphs> ... </listOfSpeciesGlyphs> <listOfReactionGlyphs> <reactionGlyph id="ReactionGlyph_1" reaction="Reaction_1"> <curve> <listOfCurveSegments> <curveSegment xsi:type="LineSegment"> <start x="165" y="105"/> <end x="165" y="115"/> </curveSegment> </listOfCurveSegments> </curve> <listOfSpeciesReferenceGlyphs> ... </listOfSpeciesReferenceGlyphs> </reactionGlyph> </listOfReactionGlyphs> <listOfTextGlyphs> <textGlyph id="TextGlyph_01" graphicalObject="SpeciesGlyph_1" originOfText="SpeciesGlyph_1"> <boundingBox id="bbA"> <position x="92" y="26"/> <dimensions width="228" height="24"/> </boundingBox> </textGlyph> </listOfTextGlyphs> </layout> </listOfLayouts> </annotation>
Additionally the layout extension adds information within the annotation element of a speciesReference component.
<reaction id="Reaction_1" reversible="false"> <listOfReactants> <speciesReference species="Species_1"> <annotation> <layoutId xmlns="http://projects.eml.org/bcb/sbml/level2" id="SpeciesReference_1"/> </annotation> </speciesReference> </listOfReactants>
Storing extension information as annotations means that reading and writing of the information is easily achieved within libSBML, without too much code that will eventually become redundant as the modularization API is established. (Honestly it's minimal .)
Core libSBML is written in C++ and thus code for any extensions will have to be written in C++.
Any classes introduced by layout are added to the SBMLTypeCode_t enumeration in the SBMLTypeCodes.h file. The class/structure variants of each are included in sbmlfwd.h via a separate layoutfwd.h file. The extension adds a ListOfLayouts to the model which is used to store the attributes and values of the layout specific classes after they have been either read or created.
The class definition and functions for the layout extension are contained within the layout directory of the libSBML source tree. For historical reasons this directory is a subdirectory of the src/sbml directory. It is not strictly speaking necessary that any other extensions are located as subdirectories of sbml, however doing so makes adding extensions to the build process much easier so it is recommended. There are additional files, LayoutAnnotation.cpp and LayoutAnnotation.h in the src/annotation directory, that contain the functions that parse the annotation into the appropriate classes or the ListOfLayouts into an annotation.
The layout extension uses the preprocessor definition USE_LAYOUT which is defined when --enable-layout is specified using the configure script. The source code files use #ifdef USE_LAYOUT to introduce layout specific code within the core libSBML code and the 'Makefile's use the flag to add the appropriate files to the build process.
Specific layout code
Since only the model and speciesReference components contain layout information, the use of #ifdef USE_LAYOUT occurs only within the Model and SpeciesReference files. The code included within the core libSBML relates only to reading and writing layout information and general housekeeping functions such as copy, clone etc.
The src/bindings directory contains subdirectories for each of the language bindings. In the case of those bindings generated by SWIG, the local.i file in the relevant language directory uses the USE_LAYOUT flag to add appropriate information for the layout extension to the file.