Learn more about SimBiology

SimBiology Model Components

On this page…
Organization of SimBiology Objects Model Compartment Species Reaction Kinetic Law Parameters Rules Events Configuration Sets Variants Simulation Data

Organization of SimBiology Objects

If you plan to work mainly from the SimBiology desktop GUI, you can skip this section and go to Model. The GUI allows you to interactively work with SimBiology model components without having prior knowledge of object-oriented programming, or the object implementation thereof in the software product.

If you plan on using the product at the command line, it is useful understand the hierarchical organization of SimBiology objects.

SimBiology objects are organized as a hierarchical list of objects under one root object.

Models and each model component are represented as objects. Further, there are objects to store simulation settings (configset object) and data from simulation and analysis tasks (data object)

Models must contain at least one species object and one compartment object. The hierarchy of objects in models is as follows:

  Model
    Compartment
       Species
    Parameters
    Reaction
        Kinetic Law
            Parameters
    Rules
    Events
    Variant 
    Configset

SimData

Parameters can be scoped to a kinetic law or the model.

The recommended method to store your SimBiology models is to create and store project files.

Back to Top

Model

A SimBiology model is a collection of interrelated reactions, rules, and events that transform, transport, and bind species. The model components are compartments, species, reactions, parameters, rules, and events. After creating a model, add a compartment, then you can add reactions to the model, define a kinetic law for each reaction, and add the parameters for the reaction.

Properties define the characteristics of an object. For example, a reaction object includes properties for reactions, reaction rates, and links to associated species, parameters, and kinetic laws. You can interactively change object properties in the graphical user interface. Use the get and set commands to list object properties and change their values at the command line.

Back to Top

Compartment

A compartment allows you to associate pools of species to physically isolated regions.

Since compartments define physically isolated regions, species are assigned to compartments. Reactions, rules, events, and parameters are assigned to the model.

All models must have at least one compartment and all species in a model must be assigned to a compartment. You can create a compartment within another compartment, but compartment names must be unique within a model. For information on specifying names of compartments, see Name in the SimBiology Reference documentation.

Back to Top

Species

A species is a chemical or entity that participates in reactions, for example, DNA, ATP, Pi, creatine , G-Protein, or Mitogen-Activated Protein Kinase (MAPK). Species amounts can vary or remain constant during a simulation.

For information on specifying names of species, see Name in the SimBiology Reference documentation.

Back to Top

Reaction

A reaction describes a transformation, transport, or binding process that changes one or more species. Typically, the change is the amount of a species.

Examples:

Creatine + ATP <-> ADP + phophocreatine
glucose + 2 ADP + 2 Pi -> 2 lactic acid + 2 ATP + 2 H2O
cytoplasm.A -> nucleus.A
[compartment 1].[species A] -> [compartment 2].[species A]

Spaces are required before and after species names and stoichiometric values. Stoichiometry values must be greater than zero. If the stoichiometry value is not specified it is assumed to be 1. In a model with a single compartment, the species is specified using its name. In a model with multiple compartments, the species must be specified as compartmentName.speciesName. Enclose names with non-alphanumeric characters in brackets.

Back to Top

Kinetic Law

A kinetic law provides a mechanism for applying a specific rate law to multiple reactions. It acts as a template for the reaction rate. The kinetic law is defined by an expression, and the species and parameter variables used in the expression.

The ReactionRate is the result of defining the names of parameters and species variables in a rate law. To get ReactionRate, the species variables and parameter variables that participate in the reaction rate should be clearly assigned in the Project Settings-Reactions pane on the Kinetic Law tab.

For example, the kinetic law Henri-Michaelis-Menten is expressed in the software as

where Vm and Km are defined as parameters and S is defined as a species. (To see parameter and species definitions for a kinetic law, access the Kinetic Law Manager from the Desktop menu.)

By applying the kinetic law Henri-Michaelis-Menten to a reaction

  A -> B
  with Vm = Va and Km = Ka
  and S = A

the rate equation is

A, Va, and Ka are defined in the Kinetic Law tab.

Reaction Rate Equation

The reaction rate equation is a mathematical expression that describes the rate at which the reactants combine to form products.

For a reaction following Mass Action kinetics,

  Creatine + ATP <-> ADP + phophocreatine

the rate equation is written as

  K*Creatine*ATP - Krev*phosphocreatine*ADP

Back to Top

Parameters

A parameter is a quantity that can change or can be constant. Parameters are generally used to define rate constants. But, you could also use parameters as constants to modify model component values in rules and events.

For information on specifying names of parameters see Name in the SimBiology Reference documentation.

Scope refers to the definition of a parameter at the model (global) level or kinetic law (local) level.

If the scope of the parameter is global in the model, it can be used by any rule, event, or by any reaction rate in the model. If the scope of the parameter is at the kinetic law level, it can be used only by the kinetic law in the reaction for which it was defined.

 How to Use Scope

Back to Top

Rules

A rule is a mathematical expression that modifies a species amount, compartment capacity, or a parameter value. There are four types of SimBiology rules:

• algebraic — Algebraic rules are evaluated continuously during a simulation. An algebraic rule takes the form 0 = Expression and the rule is specified as the Expression. For example, you could write a mass conservation expression such as species_total = species1 + species2 where species_total is the independent variable, write the rule as

  species1 + species2 - species_total

• initialAssignment — initialAssignment rules are evaluated once at the beginning of a simulation. initialAssignment rules are expressed as Variable = Expression. For example, you could write an initialAssignment rule to set the amount of species1 to be proportional to species2.

  species1 = k/species2

• repeatedAssignment — repeatedAssignment rules are evaluated at every time-step during a simulation. repeatedAssignment rules are expressed as Variable = Expression. For example, you could use the rule to specify the amount of species1 to always be proportional to species2.

  species1 = k/species2

• Rate — Rate rules are evaluated continuously during a simulation. Rate rules are determined by dVariable/dt = Expression, which is expressed in the software as Variable = Expression. For example, to define the rate of change in the quantity of species3 (dspecies3/dt), write the rule in the software as:

  species3 = k * (species1 + species2)

  One example of a rate rule is when Species1 is at the boundary of the system, but the rate of input of species1 to the system can be determined by a rate rule.

  Tip   If you plan to use a parameter in a rule, remember to set the Scope of the parameter to model. Further, if you are using an algebraic or rate rule to vary the value of a parameter during the simulation, clear the ConstantValue check box for the parameter in the Parameters pane, Settings tab.

For more information, see Changing Model Component Values Using Rules in the SimBiology User's Guide.

Back to Top

Events

Events are used to describe sudden changes in model behavior. An event lets you specify discrete transitions in model component values that occur when a user-specified condition become true. You can specify that the event occurs at a particular time, or specify a time-independent condition. For example, you can use events to activate or deactivate certain species (activator or inhibitor species), change parameter values, change reaction rates in response to addition or removal of species. For more information about events, evaluation of events, and examples, see Changing Model Component Values Using Events in the SimBiology User's Guide.

Back to Top

Configuration Sets

Configuration sets contain the options that the solver uses during simulation of a model. To add, view or edit configuration sets associated with a model, in the Project Explorer expand Model Variable Settings and click Configuration Settings. The configuration set contains the following options for you to choose:

• Type of solver

• Data to record (Data Logging tab)

• Stop time for the simulation

• Solver error tolerances, and for ode solvers – the maximum time step the solver should take

• Whether to perform sensitivity analysis during simulation

• Whether to perform dimensional analysis and unit conversion during simulation

• Species and parameter input and output factors for sensitivity analysis

For more information see Performing Simulations in the SimBiology User's Guide.

Back to Top

Variants

Variants let you store the names and values of model components and allow you to use the values stored in the variant as the alternate value to be applied during a simulation. To add, view or edit variants associated with a model, in the Project Explorer expand Model Variable Settings and click Variants. You can store values for species InitialAmount, parameter Value, and compartment Capacity, in variants.

Using one or more variants associated with a model allows you to evaluate model behavior during simulation, with different values for the various model components without having to search and replace these values, or having to create additional models with these values. If you determine that the values in a variant accurately define your model, you can permanently replace the values in your model with the values stored in the variant object by clicking Commit.

For more information see Storing and Applying Alternate Model Values Using Variantsin the SimBiology User's Guide.

Back to Top

Simulation Data

The SimBiology SimData object contains simulation data. The SimData object holds time and state data as well as metadata, such as the types and names for the logged states, or the configuration set used during simulation. For more information see SimData object.

Back to Top

SimBiology Support and SBML

Building SimBiology Models

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS