SimBiology.Compartment

Object containing compartment information

Description

The SimBiology.Compartment object represents a container for species in a model. The compartment size can vary or remain constant during a simulation. All models must have at least one compartment and all species in a model must be assigned to a compartment. Compartment names must be unique within a model.

Compartments allow you to define the size (Capacity) of physically isolated regions that may affect simulation, and associate pools of species within those regions. You can specify or change Capacity using rules, events, and variants, similar to species amounts or parameter values.

The model object stores compartments as a flat list. Each compartment stores information on its own organization; in other words a compartment has information on which compartment it lives within (Owner) and who it contains (Compartments).

The flat list of compartments in the model object lets you vary the way compartments are organized in your model without invalidating any expressions.

To add species that participate in reactions, add the reaction to the model using the addreaction method. When you define a reaction with a new species:

• If no compartment objects exist in the model, the addreaction method creates a compartment object (called unnamed) in the model and adds the newly created species to that compartment.

• If only one compartment object exists in the model, the method creates a species object in that compartment.

• If there is more than one compartment object in the model, you must qualify the species name with the compartment name.

  For example, cell.glucose denotes that you want to put the species named glucose into a compartment named cell. Additionally, if the compartment named cell does not exist, the process of adding the reaction creates the compartment and names it cell.

Alternatively, create and add a species object to a compartment object, using the addspecies method at the command line.

When you use SimBiology Model Builder to create a new model, it adds an empty compartment (unnamed), to which you can add species.

You can specify reactions that cross compartments using the syntax compartment1Name.species1Name –> compartment2Name.species2Name. If you add a reaction that contains species from different compartments, and the reaction rate dimensions are concentration/time, all reactants should be from the same compartment.

In addition, if the reaction is reversible then there are two cases:

• If the kinetic law is MassAction, and the reaction rate reaction rate dimensions are concentration/time, then the products must be from the same compartment.

• If the kinetic law is not MassAction, then both reactants and products must be in the same compartment.

Use dot notation to query the object properties or change properties that are not read-only. You can also use the get and set commands.

The SimBiology Model Builder app also enables you to add compartments, reactions, and other model components to your model and edit them. For an example, see Incorporate SGLT2 Inhibition into Physiologically Based Glucose-Insulin Model Using SimBiology Model Builder.

Creation

Use addcompartment to create and add a compartment to a SimBiology model.

Properties

Capacity — Compartment size

1 (default) | positive scalar

Compartment size, specified as a positive scalar.

If the size of the compartment does not vary during simulation, set Constant to true.

You can vary compartment capacity using rules or events. Events cannot result in the capacity having a negative value. Rules could result in the capacity having a negative value.

Note

Remember to set Constant to false for varying capacity.

The Capacity property is identical to the Value property.

Data Types: double

CapacityUnits — Compartment capacity units

empty character array (default) | character vector | string scalar

Compartment capacity units, specified as a character vector or string scalar. CapacityUnits is identical to the Units property.

Data Types: char | string

Compartments — Subcompartments

empty SimBiology.Compartment array (default) | array of SimBiology.Compartment objects

This property is read-only.

Subcompartments that are in the parent compartment, specified as an array of SimBiology.Compartment objects.

Use addcompartment to add a compartment to the parent compartment.

Constant — Flag to set compartment size as constant

true or 1 (default) | false or 0

Flag to set the compartment size as constant, specified as a numeric or logical 1 (true) or 0 (false).

The Constant property indicates whether the capacity (size) of the compartment object can vary during the simulation. Constant can be either true (1) or false (0). If Constant is true, the quantity of the compartment cannot vary during the simulation. If Constant is false, the quantity of the compartment can be determined by rules and events.

Data Types: double | logical

ConstantCapacity — Flag to set compartment size as constant

true or 1 (default) | false or 0

Flag to set compartment size as constant, specified as a numeric or logical 1 (true) or 0 (false). ConstantCapacity is identical to Constant.

Data Types: double | logical

Name — SimBiology.Compartment object name

character vector | string

SimBiology.Compartment object name, specified as a character vector or string.

For details on requirements and recommendations for naming SimBiology^® components, see Guidelines for Naming Model Components.

Data Types: char | string

Notes — Additional information

empty character array (default) | character vector | string

Additional information that you can add for SimBiology.Compartment, specified as a character vector or string.

Data Types: char | string

Owner — Owning compartment

[] (default) | SimBiology Compartment

This property is read-only.

Owning compartment, specified as a SimBiology.Compartment object.

In the compartment object, the Owner property shows you whether the compartment resides within another compartment. The Compartments property indicates whether other compartments reside within the compartment. You can add a compartment object using addcompartment.

Parent — Parent object

SimBiology.Model object

This property is read-only.

Parent object, specified as a SimBiology.Model object.

Species — Species in compartment

empty SimBiology.Species array (default) | array of SimBiology.Species objects

This property is read-only.

Species in the compartment, specified as an array of SimBiology.Species objects.

Species are entities that take part in reactions. A species object is added to the Species property when a reaction is added to the model object with the method addreaction. A species object can also be added to the Species property with addspecies.

If you remove a reaction with delete, and a species is no longer being used by any of the remaining reactions, the species object is not removed from the Species property. You have to call delete on each species to remove it.

There are reserved characters that cannot be used in species object names. See the Name property for more information.

Tag — Object label

empty character array (default) | character vector | string

Object label, specified as a character vector or string.

Tip

Use this property to group objects and then use sbioselect to retrieve. For example, use the Tag property of reaction objects to group synthesis or degradation reactions. You can then retrieve all synthesis reactions using sbioselect. Similarly, for species objects you can enter and store classification information, for example, membrane protein, transcription factor, enzyme classifications, or whether a species is an independent variable. You can also enter the full form of the name of the species.

Data Types: char | string

Type — Object type

'compartment' (default)

This property is read-only.

Object type, specified as 'compartment'. When you create a SimBiology object, the value of Type is automatically defined.

Data Types: char

Units — Units for compartment capacity

empty character array (default) | character vector | string scalar

Units for the compartment capacity, specified as a character vector or string scalar.

The Units property indicates the unit definition of the Capacity property of a compartment object. Units is identical to CapacityUnits.

Units can be one of the built-in units or you can create your own units. To get a list of the built-in units, use sbioshowunits. To create a custom unit, use sbiounit. If Units changes from one unit definition to another, the Value property does not automatically convert to the new units. sbioconvertunits does this conversion.

Note

SimBiology uses units including empty units in association with DimensionalAnalysis and UnitConversion features.

• When DimensionalAnalysis and UnitConversion are both false, units are not used. However, SimBiology still performs a minimum level of dimensional analysis to decide whether a reaction rate is in dimensions of amount/time or concentration/time.

• When DimensionalAnalysis is true and UnitConversion is false, units (if not empty) must have consistent dimensions so that SimBiology can perform dimensional analysis. However, the units are not converted.

• When UnitConversion is set to true (which requires DimensionalAnalysis to be true), SimBiology performs a dimensional analysis and converts everything to consistent units. Hence, you must specify consistent units, and no units can be empty. If you have a dimensionless parameter, you must still set its unit to dimensionless.

Example: 'liter'

Data Types: char | string

UserData — Data to associate with object

scalar | vector | string | ...

Data to associate with the object, specified as a numeric scalar, vector, string, or any other MATLAB data type.

The object does not use this data directly, but you can access it using dot notation or get.

Value — Capacity value

1.0 (default) | positive scalar

Capacity value, specified as a positive scalar. Value is identical to the Capacity property.

Data Types: double

Object Functions

Examples

Construct a Simple Model

This example shows you how to construct a simple model with two species (A and B) and a reaction. The reaction is A -> B, which follows mass action kinetics with the forward rate parameter k. Hence the rate of change is $dA/dt=-k*A$.

Create a SimBiology model named simpleModel.

m1 = sbiomodel('simpleModel');

Add a reaction that involves two species A and B, where A is converted to B.

r1 = addreaction(m1,'A -> B');

SimBiology automatically add species A and B to the model.

m1.species

ans = 
   SimBiology Species Array

   Index:    Compartment:    Name:    Value:    Units:
   1         unnamed         A        0               
   2         unnamed         B        0               

Set the initial amount of the first species (A) to 10.

m1.species(1).InitialAmount = 10;

Define the kinetic law of the reaction to follow mass action kinetics. You can achieve this by adding a kinetic law object to the reaction r1.

kineticLaw = addkineticlaw(r1,'MassAction');

Add a rate constant parameter to the mass action kinetic law. You must set the ParameterVariableNames property of the kinetic law object to the name of the parameter 'k' so that the reaction rate can be determined.

p1 = addparameter(kineticLaw,'k',0.5);
kineticLaw.ParameterVariableNames = 'k';

Simulate the model.

sd = sbiosimulate(m1);

Plot the simulation results.

sbioplot(sd);

Create a Rate Rule for an Exponential Rate of Change

This example shows how to change the amount of a species similar to a first-order reaction using the first-order rate rule. For example, suppose the species x decays exponentially. The rate of change of species x is:

$dx/dt=-k*x$

The analytical solution is:

$C_t=C_0*e^{-kt}$

where $C_t$ is the amount of species at time t, and $C_0$ is the initial amount. Use the following commands to set up a SimBiology model accordingly and simulate it.

m = sbiomodel('m');
c = addcompartment(m,'comp');
s = addspecies(m,'x','InitialAmount',2);
p = addparameter(m,'k','Value',1);
r = addrule(m,'x = -k * x','RuleType','rate');
[t,sd,species] = sbiosimulate(m);
plot(t,sd);
legend(species);
xlabel('Time');
ylabel('Species Amount');

If the amount of a species x is determined by a rate rule and x is also in a reaction, x must have its BoundaryCodition property set to true. For example, with a reaction a -> x and a rate rule $$\frac{dx}{dt}=k*x$$, set the BoundaryCodition property of species x to true so that a differential rate term is not created from the reaction. The amount of x is determined solely by a differential rate term from the rate rule. If the BoundaryCodition property is set to false, you will get the following error message such as Invalid rule variable 'x' in rate rule or reaction.

Version History

Introduced in R2008a

R2024a: Having duplicate model component names is no longer allowed

• When you load a model that contains duplicate names, SimBiology automatically updates those names. SimBiology disambiguates the duplicate names by adding a suffix "_N", where N is the first positive integer that results in a unique name. If there is an existing suffix, N will be incremented from that suffix. For example, if there are two model components named x_3, the function updates one of the names to x_4. If the existing suffix has leading zeros, the function omits the zeros in the new name. For instance, if x_003 is a duplicate name, it gets renamed to x_4. However, the function assumes that names with leading zeros and without leading zeros are different. For instance, x_005 and x_5 are considered to be different names.

• SimBiology issues an error if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. Within a single model, these components are required to have unique names even when they are of different types with the following two exceptions:

  • Species in different compartments can have the same name.

  • Parameters can have the same name if they are scoped to different parents. Specifically, you can use the same name for a model-scoped parameter and reaction-scoped parameters, where each reaction-scoped parameter belongs to a different reaction.

  For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.

R2022b: Having duplicate model component names issues a warning

SimBiology issues a warning if multiple model components have the same name.

R2022a: Having duplicate model component names will not be allowed in a future release

SimBiology will not allow you to have duplicate names for model components within a model.