Model¶

The container of everything a model is made of.

The model holds the lists of every element: the function definitions, the unit definitions, the compartments, the species, the parameters, the initial assignments, the rules, the constraints, the reactions and the events. It also sets the units which the elements inherit when they do not declare their own, in particular the unit of time, which exists nowhere else.

The report shows the model as the root of the report, its lists as the sections of the report, and its units in the attributes of the inspector.

Attributes¶

Every element of a model also carries the common attributes of SBase.

substanceUnits

A species which does not set its substance units inherits this unit of the model. If neither is set, the amounts of that species have no declared unit, which is valid but makes the model harder to check.

The report shows the units of the model in the attributes of the inspector and renders them as a formula.

Default: a species which declares none has no declared substance units.

• 20233 (warning): The value of the attribute substanceUnits on a Model object should be either the units 'mole', 'item', 'avogadro', 'dimensionless', 'kilogram', 'gram', or the identifier of a UnitDefinition object based on these units.

timeUnits

This is the only place where the unit of time of a model is declared. It applies everywhere, in particular to the rate of every reaction and of every rate rule, which are per time.

The report shows the time units in the attributes of the model.

Default: time has no declared unit anywhere in the model.

• 20217 (warning): The value of the attribute 'timeUnits' on a Model object should be either the units 'second', 'dimensionless', or the identifier of a UnitDefinition object based on these units.

volumeUnits

A compartment which does not declare its own units inherits its units from the model, and which of the three attributes applies depends on the spatial dimensions of the compartment: volume for three, area for two, length for one.

The report shows the volume units in the attributes of the model.

Default: a three dimensional compartment which declares none has no declared units.

• 20218 (warning): The value of the attribute 'volumeUnits' on a Model object should be either the units 'litre', 'dimensionless', or the identifier of a UnitDefinition object based on these units or a unit derived from 'metre'.
• 20513 (warning): If the attribute 'units' on a Compartment object having a 'spatialDimensions' attribute value of '3' has not been set, then the unit of measurement associated with the compartment's size is determined by the value of the enclosing Model object's 'volumeUnits' attribute. If neither the Compartment object's 'units' nor the enclosing Model object's 'volumeUnits' attributes are set, the unit of compartment size is undefined.

areaUnits

A two dimensional compartment, a membrane for example, which does not declare its own units inherits them from this attribute of the model.

The report shows the area units in the attributes of the model.

Default: a two dimensional compartment which declares none has no declared units.

• 20219 (warning): The value of the attribute 'areaUnits' on a Model object should be either 'dimensionless' or the identifier of a UnitDefinition object based on 'dimensionless' or a unit derived from 'metre'.
• 20512 (warning): If the attribute 'units' on a Compartment object having a 'spatialDimensions' attribute value of '2' has not been set, then the unit of measurement associated with the compartment's size is determined by the value of the enclosing Model object's 'areaUnits' attribute. If neither the Compartment object's 'units' nor the enclosing Model object's 'areaUnits' attributes are set, the unit of compartment size is undefined.

lengthUnits

A one dimensional compartment which does not declare its own units inherits them from this attribute of the model.

The report shows the length units in the attributes of the model.

Default: a one dimensional compartment which declares none has no declared units.

• 20220 (warning): The value of the attribute 'lengthUnits' on a Model object should be either the units 'metre', 'dimensionless', or the identifier of a UnitDefinition object based on these units.
• 20511 (warning): If the attribute 'units' on a Compartment object having a 'spatialDimensions' attribute value of '1' has not been set, then the unit of measurement associated with the compartment's size is determined by the value of the enclosing Model object's 'lengthUnits' attribute. If neither the Compartment object's 'units' nor the enclosing Model object's 'lengthUnits' attributes are set, the unit of compartment size is undefined.

extentUnits

The extent of a reaction counts how often it has occurred, and its rate of change is what a kinetic law computes. The units of every kinetic law of the model are therefore the extent units divided by the time units, which also means that every reaction of a model has the same units.

The report shows the extent units in the attributes of the model and uses them when it derives the units of a kinetic law.

Default: the units of the kinetic laws of the model stay undefined.

• 20221 (warning): The value of the attribute extentUnits on a Model object should be either the units 'mole', 'item', 'avogadro', 'dimensionless', 'kilogram', 'gram', or the identifier of a UnitDefinition object based on these units.

conversionFactor

A species whose amount is not measured in the extent units of the reactions needs a factor to convert between the two, and SBML makes that conversion explicit instead of guessing it. The model can name a constant parameter which every species inherits when it does not name its own.

The report shows the referenced parameter with its value and its units in the attributes of the model.

Default: a species which names none has no conversion factor.

• 20216 (error): The value of the attribute 'conversionFactor' on a Model object must be the identifier of an existing Parameter object defined in the Model object's ListOfParameters.
• 20705 (error): A Parameter object referenced by the attribute 'conversionFactor' on a Species or Model object must have a value of 'true' for its attribute 'constant'.

listOfFunctionDefinitions

The lists of the model group its elements by type. This one holds the function definitions.

The report shows the list as the section "Function definitions" of the report and counts its entries in the type bar.

• 20206 (error): Apart from the general Notes and Annotation subobjects permitted on all SBML components, a ListOfFunctionDefinitions container object may only contain FunctionDefinition objects.

listOfUnitDefinitions

This list holds the unit definitions which the elements of the model reference by their identifier.

The report shows the list as the section "Unit definitions" of the report.

• 20207 (error): Apart from the general Notes and Annotation subobjects permitted on all SBML components, a ListOfUnitDefinitions container object may only contain UnitDefinition objects.

listOfCompartments

This list holds the compartments the species of the model live in.

The report shows the list as the section "Compartments" of the report.

• 20208 (error): Apart from the general Notes and Annotation subobjects permitted on all SBML components, a ListOfCompartments container object may only contain Compartment objects.

listOfSpecies

This list holds the species, the pools whose quantities the model computes.

The report shows the list as the section "Species" of the report.

• 20209 (error): Apart from the general Notes and Annotation subobjects permitted on all SBML components, a ListOfSpecies container object may only contain Species objects.

listOfParameters

This list holds the parameters which every mathematical expression of the model may use.

The report shows the list as the section "Parameters" of the report.

• 20210 (error): Apart from the general Notes and Annotation subobjects permitted on all SBML components, a ListOfParameters container object may only contain Parameter objects.

listOfInitialAssignments

This list holds the initial assignments which compute values at the start of a simulation.

The report shows the list as the section "Initial assignments" of the report.

• 20211 (error): Apart from the general Notes and Annotation subobjects permitted on all SBML components, a ListOfInitialAssignments container object may only contain InitialAssignment objects.

listOfRules

This list holds the three kinds of rule together: assignment rules, rate rules and algebraic rules.

The report separates them into three sections, because the three say very different things about a model.

• 20212 (error): Apart from the general Notes and Annotation subobjects permitted on all SBML components, a ListOfRules container object may only contain Rule objects.

listOfConstraints

This list holds the constraints, the conditions a simulation of the model has to satisfy.

The report shows the list as the section "Constraints" of the report.

• 20213 (error): Apart from the general Notes and Annotation subobjects permitted on all SBML components, a ListOfConstraints container object may only contain Constraint objects.

listOfReactions

This list holds the reactions, the processes which change the quantities of the species.

The report shows the list as the section "Reactions" of the report.

• 20214 (error): Apart from the general Notes and Annotation subobjects permitted on all SBML components, a ListOfReactions container object may only contain Reaction objects.

listOfEvents

This list holds the events, the discontinuous changes of the state of the model.

The report shows the list as the section "Events" of the report.

• 20215 (error): Apart from the general Notes and Annotation subobjects permitted on all SBML components, a ListOfEvents container object may only contain Event objects.

comp:listOfSubmodels

Every submodel instantiates a model definition of the document or a model of another file. A model without submodels is a model in the usual sense; a model with submodels stands for everything its submodels contain, after the deletions and the replacements have been applied.

The report shows the submodels of a model as a section of the report.

• 1020501 (error): There may be at most one instance of each of the following kinds of objects within a <model> or <modelDefinition> object using Hierarchical Model Composition: <listOfSubmodels> and <listOfPorts>.
• 1020502 (error): The various ListOf subobjects with a <model> object are optional, but if present, these container object must not be empty. Specifically, if any of the following classes of objects are present on the <model>, it must not be empty: <listOfSubmodels> and <listOfPorts>.
• 1020503 (error): Apart from the general notes and annotation subobjects permitted on all SBML objects, a <listOfSubmodels> container object may only contain <submodel> objects.

comp:listOfPorts

A port declares one element of the model as an intended point of interaction, the way a socket declares the interface of a device. Ports are advisory: nothing prevents a containing model from reaching into the model directly, but a modeller is asked to respect the interface.

The report shows the ports of a model as a section of the report.

Default: nothing of the model is declared as an interface.

• 1020501 (error): There may be at most one instance of each of the following kinds of objects within a <model> or <modelDefinition> object using Hierarchical Model Composition: <listOfSubmodels> and <listOfPorts>.
• 1020502 (error): The various ListOf subobjects with a <model> object are optional, but if present, these container object must not be empty. Specifically, if any of the following classes of objects are present on the <model>, it must not be empty: <listOfSubmodels> and <listOfPorts>.
• 1020504 (error): Apart from the general notes and annotation subobjects permitted on all SBML objects, a <listOfPorts> container object may only contain <port> objects.

fbc:listOfGeneProducts

Every gene product stands for one gene or one of its products and carries the label under which the reconstruction knows it. The reactions name them in their gene product association.

The report shows the gene products of a model as a section of the report.

• 2020201 (error): There may be at most one instance of each of the following kinds of objects within a <model> object using Flux Balance Constraints: <listOfFluxBounds> (V1 only), <listOfObjectives> <listOfGeneProducts> (V2 onwards) and <listOfUserDefinedConstraints> (V3).
• 2020202 (error): The various ListOf subobjects with a <model> object are optional, but if present, these container object must not be empty. Specifically, if any of the following classes of objects are present on the <model>, it must not be empty: <listOfFluxBounds> (V1 only), <listOfObjectives> and <listOfGeneProducts> (V2).
• 2020211 (error): Apart from the general notes and annotation subobjects permitted on all SBML objects, a <listOfGeneProducts> container object may only contain <geneProduct> objects.

fbc

The block holds the two attributes which belong to the model as a whole: whether it keeps to the restrictions of a strict problem, and which of its objectives is the active one.

The report shows both in the inspector of a model of a document which uses fbc.

fbc:strict

A strict model can be handed to a solver which does not read arbitrary mathematics: every reaction has both flux bounds, every bound is a constant parameter with a value which is not missing and not infinite in the direction which would remove the bound, every stoichiometry is a constant number, every coefficient of a flux objective is finite, and no initial assignment touches a bound or a stoichiometry.

A model which is not strict may compute a bound during a simulation, with an initial assignment, a rule or an event, which is how a hybrid model changes the capacity of a reaction over time. The attribute therefore says how every other number of the report has to be read, and it is required from Version 2 of the package on; a Version 1 document has none.

The report shows it in the inspector of the model.

• 2020209 (error): A <model> object must have the required attributes 'strict'. No other attributes from the Flux Balance Constraints namespace are permitted on a <model> object.
• 2020210 (error): The attribute 'fbc:strict' on the <model> object must have a value of datatype Boolean.
• 2020608 (error): When the value of the <model> 'fbc:strict' attribute is true, the value of the attribute 'fbc:coefficient' of a <fluxObjective> object must not be set to 'NaN', 'INF' or '-INF'.
• 2020707 (error): When the value of the <Model>s 'fbc:strict' attribute is 'true', a <Reaction> must define the attributes 'fbc:lowerFluxBound' and 'fbc:upperFluxBound'.
• 2020708 (error): When the value of the <Model>s 'fbc:strict' attribute is 'true', the <Parameter> objects referred to by the attributes 'fbc:lowerFluxBound' and 'fbc:upperFluxBound' must have their 'constant' attribute set to 'true'.
• 2020709 (error): When the value of the <Model>s 'fbc:strict' attribute is 'true', the <Parameter> objects referred to by the attributes 'fbc:lowerFluxBound' and 'fbc:upperFluxBound' must have a defined value for their 'value' attribute, which may not be 'NaN'.
• 2020710 (error): When the value of the <Model>s 'fbc:strict' attribute is 'true', the <Parameter> objects referred to by the attributes 'fbc:lowerFluxBound' and 'fbc:upperFluxBound' may not be targeted by an <InitialAssignment>.
• 2020711 (error): When the value of the <Model>s 'fbc:strict' attribute is 'true', the <Parameter> objects referred to by the attribute 'fbc:lowerFluxBound' may not have the value 'INF'.
• 2020712 (error): When the value of the <Model>s 'fbc:strict' attribute is 'true', the <Parameter> object referred to by the attribute 'fbc:upperFluxBound' may not have the value '-INF'.
• 2020713 (error): When the value of the <Model>s 'fbc:strict' attribute is 'true', the <Parameter> object referred to by the attribute 'fbc:lowerFluxBound' must be less than or equal to the value of the <Parameter> object referred to by the attribute 'fbc:upperFluxBound' .
• 2020714 (error): When the value of the <Model>s 'fbc:strict' attribute is 'true', the 'constant' attribute of <SpeciesReference> elements of a <Reaction> must be set to 'true'.
• 2020715 (error): When the value of the <Model>s 'fbc:strict' attribute is 'true', the value of a <SpeciesReference>'s 'stoichiometry> attribute must not be set to 'NaN', '-INF' or 'INF'.
• 2020716 (error): When the value of the <Model>s 'fbc:strict' attribute is 'true', the <SpeciesReference> elements of a <Reaction> may not be targeted by an <InitialAssignment>.

fbc:activeObjective

A model may carry several objectives, for example the growth it was published with next to the alternatives it was studied with, and this attribute names the one which describes the published simulation. It is an attribute of the list of objectives, which the report does not carry as an object of its own, so it sits next to strict in the fbc block of the model.

The report links the objective in the inspector of the model, and the inspector of that objective shows the model under "referenced by".

• 2020206 (error): A <listOfObjectives> object may have the optional attributes 'metaid' and 'sboTerm' defined by SBML Level 3 Core. Additionally the <listOfObjectives> must contain the attribute 'activeObjective'. No other attributes from the SBML Level 3 Core namespace or the Flux Balance Constraints namespace are permitted on a <listOfFluxBounds> object.
• 2020207 (error): The value of attribute 'fbc:activeObjective' on the <listOfObjectives> object must be of the data type SIdRef.
• 2020208 (error): The value of attribute 'fbc:activeObjective' on the <listOfObjectives> object must be the identifier of an existing <objective>.

fbc:listOfFluxBounds

A flux bound is how the first version of the package constrained a reaction. Version 2 removed the construct and replaced it by the two attributes of a reaction which name a parameter, so the list is empty for every document of a later version.

The report shows the flux bounds of a Version 1 model as a section of the report.

Default: the bounds of a reaction may be inferred from its reversibility.

• 2020201 (error): There may be at most one instance of each of the following kinds of objects within a <model> object using Flux Balance Constraints: <listOfFluxBounds> (V1 only), <listOfObjectives> <listOfGeneProducts> (V2 onwards) and <listOfUserDefinedConstraints> (V3).
• 2020202 (error): The various ListOf subobjects with a <model> object are optional, but if present, these container object must not be empty. Specifically, if any of the following classes of objects are present on the <model>, it must not be empty: <listOfFluxBounds> (V1 only), <listOfObjectives> and <listOfGeneProducts> (V2).
• 2020203 (error): Apart from the general notes and annotation subobjects permitted on all SBML objects, a <listOfFluxBounds> container object may only contain <fluxBound> objects.

fbc:listOfUserDefinedConstraints

A user defined constraint bounds a combination of fluxes and parameters which the stoichiometry of the network leaves free, for example the ratio of two reactions or a shared budget. The list exists from Version 3 of the package on and is empty in every earlier document.

The report shows the user defined constraints of a model as a section of the report.

Default: only the reaction network and the flux bounds constrain the fluxes.

• 2020201 (error): There may be at most one instance of each of the following kinds of objects within a <model> object using Flux Balance Constraints: <listOfFluxBounds> (V1 only), <listOfObjectives> <listOfGeneProducts> (V2 onwards) and <listOfUserDefinedConstraints> (V3).
• 2020213 (error): Apart from the general notes and annotation subobjects permitted on all SBML objects, a <ListOfUserDefinedConstraints> container object may only contain <userDefinedConstraint> objects.

fbc:listOfObjectives

A model may define several objectives and declares one of them as the active objective, the function which an analysis optimises unless it is told otherwise. The others are kept so that a model can carry the alternatives it was studied with.

The report shows the objectives of a model as a section of the report.

Default: the model poses no optimisation problem and cannot be formulated as a linear program.

• 2020201 (error): There may be at most one instance of each of the following kinds of objects within a <model> object using Flux Balance Constraints: <listOfFluxBounds> (V1 only), <listOfObjectives> <listOfGeneProducts> (V2 onwards) and <listOfUserDefinedConstraints> (V3).
• 2020202 (error): The various ListOf subobjects with a <model> object are optional, but if present, these container object must not be empty. Specifically, if any of the following classes of objects are present on the <model>, it must not be empty: <listOfFluxBounds> (V1 only), <listOfObjectives> and <listOfGeneProducts> (V2).
• 2020204 (error): Apart from the general notes and annotation subobjects permitted on all SBML objects, a <listOfObjectives> container object may only contain <objective> objects.

qual:listOfQualitativeSpecies

A model which uses the qual package holds its qualitative species in a list of their own, next to the species of the core. The two are not the same thing and a model does not mix them: an entity of a qualitative model has no amount and no concentration, it has a level.

The report shows them as a section of their own.

• 3020201 (error): There may be at most one instance of each of the following kinds of objects within a <model> object using Qualitative Models: <listOfTransitions> and <listOfQualitativeSpecies>.
• 3020202 (error): The various ListOf subobjects with a <model> object are optional, but if present, these container object must not be empty. Specifically, if any of the following classes of objects are present on the <model>, it must not be empty: <listOfQualitativeSpecies> and <listOfTransitions>.
• 3020204 (error): Apart from the general notes and annotation subobjects permitted on all SBML objects, a <listOfQualitativeSpecies> container object may only contain <qualitativeSpecies> objects.

qual:listOfTransitions

The transitions are the dynamics of a qualitative model, what the reactions with their kinetic laws are to a kinetic one. Every one of them reads some qualitative species and changes others.

The report shows them as a section of their own.

Default: nothing changes the levels of the qualitative species.

• 3020201 (error): There may be at most one instance of each of the following kinds of objects within a <model> object using Qualitative Models: <listOfTransitions> and <listOfQualitativeSpecies>.
• 3020202 (error): The various ListOf subobjects with a <model> object are optional, but if present, these container object must not be empty. Specifically, if any of the following classes of objects are present on the <model>, it must not be empty: <listOfQualitativeSpecies> and <listOfTransitions>.
• 3020203 (error): Apart from the general notes and annotation subobjects permitted on all SBML objects, a <listOfTransitions> container object may only contain <transition> objects.

In the report¶

kind

A document contains at most one model, but the comp package adds model definitions, which are models that exist to be instantiated by a submodel. The report treats both the same way and marks which of the two an element is.

The kind is shown in the attributes of the inspector of a model, it is model or modelDefinition.

annotation

The annotation of the model is where a tool writes what it knows about the model in its own vocabulary, next to the RDF the report reads as annotations and as history. The report does not carry the XML of the model, which is the whole model, so it carries the annotation element alone.

The "XML" button in the header of the inspector shows it.

• 10401 (error): Every top-level element within an annotation element must have a namespace declared.
• 10402 (error): There cannot be more than one top-level element using a given namespace inside a given annotation element.
• 10403 (error): Top-level elements within an annotation element cannot use any SBML namespace, whether explicitly (by declaring the namespace to be one of the URIs "http://www.sbml.org/sbml/level1", "http://www.sbml.org/sbml/level2", "http://www.sbml.org/sbml/level2/version2", or "http://www.sbml.org/sbml/level2/version3", or "http://www.sbml.org/sbml/level2/version4", or "http://www.sbml.org/sbml/level2/version5" or "http://www.sbml.org/sbml/level3/version1/core"), or implicitly (by failing to declare any namespace).
• 10404 (error): A given SBML object may contain at most one <annotation> element.

rendered substance units

The report resolves the unit definition which the model declares for the amounts of its species and renders it as a formula, so that mmol is shown as the unit itself instead of as an identifier.

It is shown next to the substance units in the attributes of the model.

rendered time units

The report resolves the unit definition which the model declares for time and renders it as a formula. Since the unit of time is declared nowhere else, this is where a reader sees whether a simulation runs in seconds, in minutes or in hours.

It is shown next to the time units in the attributes of the model.

rendered volume units

The report resolves the unit definition which the model declares for the size of its compartments with three dimensions and renders it as a formula.

It is shown next to the volume units in the attributes of the model.

rendered area units

The report resolves the unit definition which the model declares for the size of its compartments with two dimensions and renders it as a formula.

It is shown next to the area units in the attributes of the model.

rendered length units

The report resolves the unit definition which the model declares for the size of its compartments with one dimension and renders it as a formula.

It is shown next to the length units in the attributes of the model.

rendered extent units

The report resolves the unit definition which the model declares for the extent of its reactions and renders it as a formula. Together with the time units it says what the rate of every kinetic law is measured in.

It is shown next to the extent units in the attributes of the model.

Validation rules¶

• 10701 (warning): The value of the 'sboTerm' attribute on a <model> is expected to be an SBO identifier (http://www.biomodels.net/SBO/). In SBML Level 2 prior to Version 4 the value is expected to be a term derived from SBO:0000004, "modeling framework"; in Version 4 and above it is expected to be a term derived from SBO:0000231 "occurring entity representation"
• 20202 (error): The order of subelements within a <model> element must be the following (where any one may be optional, but the ordering must be maintained): <listOfFunctionDefinitions>, <listOfUnitDefinitions>, <listOfCompartmentTypes>, <listOfSpeciesTypes>, <listOfCompartments>, <listOfSpecies>, <listOfParameters>, <listOfInitialAssignments>, <listOfRules>, <listOfConstraints>, <listOfReactions> and <listOfEvents>.
• 20203 (error): The <listOf___> containers in a <model> are optional, but if present, the lists cannot be empty. Specifically, if any of the following are present in a <model>, they must not be empty: <listOfFunctionDefinitions>, <listOfUnitDefinitions>, <listOfCompartmentTypes>, <listOfSpeciesTypes>, <listOfCompartments>, <listOfSpecies>, <listOfParameters>, <listOfInitialAssignments>, <listOfRules>, <listOfConstraints>, <listOfReactions> and <listOfEvents>.
• 20205 (error): There may be at most one instance of each of the following kind of element in a <model> object: ListOfFunctionDefinitions, ListOfUnitDefinitions, ListOfCompartments, ListOfSpecies, ListOfParameters, ListOfInitialAssignments, ListOfRules, ListOfConstraints, ListOfReactions and ListOfEvents.
• 20222 (error): A Model object may only have the following attributes, all of which are optional: 'metaid', 'sboTerm', 'id', 'name', 'substanceUnits', 'timeUnits', 'volumeUnits', 'areaUnits', 'lengthUnits', 'extentUnits' and 'conversionFactor'. No other attributes from the SBML Level 3 Core namespace are permitted on a Model object.

Related elements¶

• SBMLDocument: the container of an SBML file, with its level, version and packages
• Compartment: a bounded space in which species are located
• Species: a pool of a chemical entity in a compartment
• Parameter: a named value which the mathematics of the model can use
• Reaction: a process which changes the quantities of species

Specification¶

SBML Level 3 Version 2 Core, Section 4.2 (Hucka et al. 2019, J Integr Bioinform 16(2):20190021).