SBML.org — the global portal for all things SBML

Modularization

The following are issues identified by Sarah and Mike; with related thoughts resulting from discussion. Please add your own comments.

Contents

API Functionality

As people are starting to work on SBML Level 3 extensions, we aim to encourage them to simultaneously work on an implementation of the extension that can be utilized as a module of libSBML. Thus we need to provide an API that provides the "bridge" between the module code and core libSBML.

Our aim is to implement an API and use it to interface to the existing layout code in order to demonstrate it's application.

At present we forsee the need for the following functions:

register

  • a function that tells libSBML that a module is present
  • libSBML may need some sort of internal registry of modules that are present at compile time

initialize

  • a function that can be called to tell libSBML that a particular module is to be used
    • possible set the internal registry to "Active" for the given module
  • possible takes a namespace string as an argument
    • this would facilitate running the initialize function following the first parse read of a document i.e., automatically supplying the arguments based on the namespaces declared within the document
  • sets the default level and version (and namespaces) of SBML
    • this is actually a current issue and will be discussed further (see createSBML)

Image:New.gif Following discussions with Ben he suggested that we utilize the 'loadlibrary' functionality. Thus only libsbml core would have an initialize function. This function would take arguments specifying which extensions are to be used. It would check the 'internal registry' to see whether the appropriate modules were present and then call loadlibrary("XXX") for each.

addAttributes

  • a function that adds attributes to one of core components of SBML e.g., add attribute 'glyph' to SpeciesReference
    • the current read/writeAttributes functions in libSBML would need to
      • query the internal registry to find which modules are active
      • read/write any attributes that have been added

Image:New.gif Rather than have each module try to inform libsbml_core of any additional attributes/components, it would be simpler to add a function to every read/write function that passes control to other libraries. It is then the responsibility of the extension library to perform the appropriate action. e.g.

SpeciesReference::readAttributes(XMLAttributes& attributes)
{
  existing code 
  ....
  
  passControlToOtherLibraries(attributes);
}

Obviously the other libraries need to pass control back; but they may also need to pass control to other extensions before coming back to libsbml_core.

addNewComponent

  • a function to add a completely new component to SBML e.g., add the component 'BoundingBox'
    • the current readSBML function in libSBML would need to find and read these additional components

addListOfNewComponents

  • a function to add a ListOfNewComponents to one of the core components of SBML e.g., add a ListOfLayouts to a Model
    NOTE: the core component need not be a Model
    • the current readSBML function in libSBML would need to find and read these additional components

addValidator

  • modules will need to write their own validation code and will need some mechanism for telling libSBML about it
    NOTE: this may be complicated (see validateSBML)

Multiple Models

SBML Level 3 extensions will permit multiple models within a single SBML document. At present libSBML assumes that each document contains only a single model.

Considerations for handling multiple models

  • create a ListOfModels within the document object
  • need to consider what the default level/version/namespace of each model will be; particularly since users may combine existing models with mismatching namespaces into a single document
  • components within a model will need to point to a parent model rather than a parent document which is currently the case

libSBML functionality

This is an overview of things people do with libSBML and comments on the implications for modularization.

readSBML

  • this should be straight-forward to handle once additional attributes/components can be accessed

writeSBML

  • this should be straight-forward to handle once additional attributes/components can be accessed

validateSBML

Sarah thinks this will be problematic with the validation code in its current state (whilst freely admitting that she does not fully understand the mechanisms used Image:icon_smile.gif )

Potential issues:

  • constraints applied by existing validators may become inapplicable and additional constraints will be necessary
  • the error reporting code has a variety of enumerations to which additions will ned to be handled

Assuming code is to be purely C++ (see Development Language) it should be possible for the module code to create a new validator based on the existing Validator class. This would have an init() function that loads its own set of constraints. A libSBML call to checkConsistency would then need to establish which modules are "Active" and call the appropriate Validators.

Image:New.gif Using the approach that means any read/write function passes control to other libraries it would be possible for the validation to work in the same way.

Aside: A recent feature request for libSBML was the ability to apply validation constraints relating to an object to a single object. For example, an editor application may allow a user to create a Rule and then wish to validate that Rule before allowing it to be added to the Model. If there is any refactoring of the validation code necessary we should consider this at the same time.

Image:New.gif We might want to consider whether it would be possible to write a function that took the validator type, the constraint id and an object and produced an instance of the given validator type that contained only the given constraint id and then applied it only to the given object. For example:

validate(LIBSBML_CAT_IDENTIFIER_CONSISTENCY, 10301, (Rule*)r)
{
  Validator v;
  v.init(10301);
  v.validate(r);
}

This needs thought but may be a viable alternative to restructuring all the rules.

convertSBML

This will also be problematic. Currently "conversion" is performed as a by-product of changing the level/version of a document and calling writeSBML. The writeAttributes functions write out the attributes and values appropriate for the level/version. However, when the setLevelAndVersion function is used to change the level/version, an appropriate compatability validator is called to determine whether such conversion is possible.

Potential issues:

  • compatability validators would need to added by the module - with the same potential issues as for validation
  • the applicability of the setLevelAndVersion function (for more explanation see createSBML)
  • namespaces need to be considered

createSBML

The actual creation of SBML should be straight-forward to handle once additional attributes/components can be accessed.

However, there is an underlying issue which is already a problem with libSBML; namely the creation of objects before the creation of a document. Any object in libSBML obtains the SBML level and version from it's parent document. In the absence of a parent document the level and version default to the latest level and version of SBML. Consider the following code:


Model *model = new Model();

model->setName("foo");

Document *document = new SBMLDocument();

document->setLevelAndVersion(1, 2);

document->addModel(model);


It seems likely that the user is intending to create an SBML Level 1 Version 2 model. However, if the document were to written out the model name attribute would be empty! This is a consequence of the fact that at the point at which the model was created the default values for level and version were 2 and 3 respectively. The setName function on a Level 2 model acts on the internal id variable not on the name variable. To produce the required behaviour the code should read as follows:


Document *document = new SBMLDocument();

document->setLevelAndVersion(1, 2);

Model *model = document->createModel();

model->setName("foo");


This issue has arisen for several aspects of SBML; not just the name/id issue. With the additional of modules and therefore even more variations on level/version/namespaces combinations, it is likely to be an even bigger problem.

A possible solution may be to force all users to initialize libSBML with the namespaces to be used and thus set the default level and version. This would be similar to the initialize function suggested for the API.

Development Language

The core libSBML is written in C/C++ from which the other language bindings are generated. If we are to continue to provide the range of language bindings, then the code for both libSBML core and any modules needs to be in C/C++. So we would propose

  • libSBML-Module API is written in C++
  • module developers are asked to develop in C++
  • module developers are asked to contribute local.i files that can be used by SWIG to generate language bindings

Retrieved from "http://sbml.org/SBML_Projects/libSBML/Modularization"

This page was last modified 08:11, 14 July 2008.



Please use our issue tracking system for any questions or suggestions about this website. This page was last modified 08:11, 14 July 2008.