sbiosteadystate
Find steady state of SimBiology model
Syntax
Description
[
attempts to find a steady state of a SimBiology^{®} model, success
, variant_out
]
= sbiosteadystate(model
)model
. The function returns
success
, which is true
if a steady state
was found, and a SimBiology
Variant object
,
variant_out
, with all nonconstant species, compartments,
and parameters of the model having the steadystate values. If a steady state was
not found, then the success
is false
and
variant_out
contains the last values found by the
algorithm.
[
applies the alternate quantity values stored in a variant object or vector of
objects, success
, variant_out
]
= sbiosteadystate(model
, variant_in
)variant_in
, to the model before trying to find the
steadystate values.
[
also applies a success
, variant_out
]
= sbiosteadystate(model
, variant_in
, scheduleDose
)ScheduleDose
object or vector of schedule doses
scheduleDose
to the corresponding model quantities before
trying to find the steady state values. Only doses at time = 0 are allowed, that is,
the dose time of each dose object must be 0. To specify a dose without specifying a
variant, set variant_in
to an empty array,
[]
.
[
also returns a SimBiology model, success
, variant_out
, model_out
]
= sbiosteadystate(model
,___)model_out
that is a copy of the input
model
with the states set to the steadystate solution that
was found. Also, model_out
has all initial assignment rules
disabled.
[
also returns the exit information about the steady state computation.success
, variant_out
, model_out
, exitInfo
]
= sbiosteadystate(model
,___)
[___] = sbiosteadystate(___,
uses
additional options specified by one or more Name,Value
)Name,Value
pair
arguments.
Examples
Find a Steady State of a Simple Gene Regulation Model
This example shows how to find a steady state of a simple gene regulation model, where the protein product from translation controls transcription.
Load the sample SimBiology project containing the model, m1. The model has five reactions and four species.
sbioloadproject('gene_reg.sbproj','m1')
Display the model reactions.
m1.Reactions
ans = SimBiology Reaction Array Index: Reaction: 1 DNA > DNA + mRNA 2 mRNA > mRNA + protein 3 DNA + protein <> DNA_protein 4 mRNA > null 5 protein > null
A steady state calculation attempts to find the steady state values of nonconstant quantities. To find out which model quantities are nonconstant in this model, use sbioselect
.
sbioselect(m1,'Where','Constant*','==',false)
ans = SimBiology Species Array Index: Compartment: Name: Value: Units: 1 unnamed DNA 50 molecule 2 unnamed DNA_protein 0 molecule 3 unnamed mRNA 0 molecule 4 unnamed protein 0 molecule
There are four species that are not constant, and the initial amounts of three of them are set to zero.
Use sbiosteadystate
to find the steady state values for those nonconstant species.
[success,variantOut] = sbiosteadystate(m1)
success = logical
1
variantOut = SimBiology Variant  SteadyState (inactive) ContentIndex: Type: Name: Property: Value: 1 compartment unnamed Capacity 1.0 2 species DNA InitialAmount 8.7902390... 3 species DNA_protein InitialAmount 41.209760... 4 species mRNA InitialAmount 1.1720318... 5 species protein InitialAmount 23.440637... 6 parameter Transcription.k1 Value .2 7 parameter Translation.k2 Value 20.0 8 parameter [Binding/Unbin... Value .2 9 parameter [Binding/Unbin... Value 1.0 10 parameter [mRNA Degradat... Value 1.5 11 parameter [Protein Degra... Value 1.0
The initial amounts of all species of the model have been set to the steadystate values. DNA
is a conserved species since the total of DNA
and DNA_protein
is equal to 50.
You can also use a variant to store alternate initial amounts and use them during the steady state calculation. For instance, you could set the initial amount of DNA to 100 molecules instead of 50.
variantIn = sbiovariant('v1'); addcontent(variantIn,{'species','DNA','InitialAmount',100}); [success2,variantOut2,m2] = sbiosteadystate(m1,variantIn)
success2 = logical
1
variantOut2 = SimBiology Variant  SteadyState (inactive) ContentIndex: Type: Name: Property: Value: 1 compartment unnamed Capacity 1.0 2 species DNA InitialAmount 12.787619... 3 species DNA_protein InitialAmount 87.212380... 4 species mRNA InitialAmount 1.7050159... 5 species protein InitialAmount 34.100318... 6 parameter Transcription.k1 Value .2 7 parameter Translation.k2 Value 20.0 8 parameter [Binding/Unbin... Value .2 9 parameter [Binding/Unbin... Value 1.0 10 parameter [mRNA Degradat... Value 1.5 11 parameter [Protein Degra... Value 1.0
m2 = SimBiology Model  cell Model Components: Compartments: 1 Events: 0 Parameters: 6 Reactions: 5 Rules: 0 Species: 4 Observables: 0
Since the algorithm has found a steady state, the third output m2
is the steady state model, where the values of nonconstant quantities have been set to steady state values. In this example, the initial amounts of all four species have been updated to steady state values.
m2.Species
ans = SimBiology Species Array Index: Compartment: Name: Value: Units: 1 unnamed DNA 12.7876 molecule 2 unnamed DNA_protein 87.2124 molecule 3 unnamed mRNA 1.70502 molecule 4 unnamed protein 34.1003 molecule
Input Arguments
model
— SimBiology model
SimBiology model object
SimBiology model, specified as a SimBiology Model object
.
variant_in
— SimBiology variant
[]
 variant object  vector of variant objects
SimBiology variant, specified as an empty array []
, a
Variant object
or vector of
variant objects. The alternate quantity values stored in the variants are
applied to the model before finding the steady state. If there are
duplicate specifications for a property value, the last occurrence for the
property value in the array of variants is used.
scheduleDose
— Dosing information
[]

ScheduleDose
object  vector of ScheduleDose
objects
Dosing information, specified as an empty array []
, a ScheduleDose
object or vector of
ScheduleDose
objects. The dose must be bolus, that is,
there must be no time lag or administration time for the dose. In other
words, its LagParameterName
and
DurationParameterName
properties must be empty, and
the dose time (the Time
property) must be 0. For details
on how to create a bolus dose, see Creating Doses Programmatically.
NameValue Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: 'AbsTol',1e6
specifies to use the absolute tolerance
value of 10^{–6}
.
Method
— Method to compute steady state
'auto'
(default)  'simulation'
 'algebraic'
Method to compute the steady state of model
,
specified as the commaseparated pair consisting of
'Method'
and a character vector
'auto'
, 'simulation'
, or
'algebraic'
. The default
('auto'
) behavior is to use the
'algebraic'
method first. If that method is
unsuccessful, the function uses the 'simulation'
method.
For the simulation method, the function simulates the model and uses finite differencing to detect a steady state. For details, see Simulation Method.
For the algebraic method, the function computes a steady state by finding a root of the flux function algebraically. For nonlinear models, this method requires Optimization Toolbox™. For details, see Algebraic Method.
Note
The steady state returned by the algebraic method is not guaranteed to be the same as the one found by the simulation method. The algebraic method is faster since it involves no simulation, but the simulation method might be able to find a steady state when the algebraic method could not.
Example: 'Method','algebraic'
AbsTol
— Absolute tolerance to detect convergence
1e8
(default)  positive, real scalar
Absolute tolerance to detect convergence, specified as the
commaseparated pair consisting of 'AbsTol'
and a
positive, real scalar.
When you use the algebraic method, the absolute tolerance is used to specify optimization settings and detect convergence. For details, see Algebraic Method.
When you use the simulation method, the absolute tolerance is used to determine convergence when finding a steady state solution by forward integration as follows: $$\left(\Vert \frac{d\overrightarrow{S}}{dt}\Vert <AbsTol\right)or\left(\Vert \frac{d\overrightarrow{S}}{dt}\Vert <RelTol\ast \Vert \overrightarrow{S}\Vert \right)$$, where $$\overrightarrow{S}$$ is a vector of nonconstant species, parameters, and compartments.
RelTol
— Relative tolerance to detect convergence
1e6
(default)  positive, real scalar
Relative tolerance to detect convergence, specified as the
commaseparated pair consisting of 'RelTol'
and a
positive, real scalar. This namevalue pair argument is used for the
simulation
method only. The algorithm converges
and reports a steady state if the algorithm finds model states by
forward integration, such that $$\left(\Vert \frac{d\overrightarrow{S}}{dt}\Vert <AbsTol\right)or\left(\Vert \frac{d\overrightarrow{S}}{dt}\Vert <RelTol\ast \Vert \overrightarrow{S}\Vert \right)$$, where $$\overrightarrow{S}$$ is a vector of nonconstant species, parameters, and
compartments.
MaxStopTime
— Maximum amount of simulation time to take before terminating without a steady state
100000
(default)  positive integer
Maximum amount of simulation time to take before terminating without a
steady state, specified as the commaseparated pair consisting of
'MaxStopTime'
and a positive integer. This
namevalue pair argument is used for the simulation
method only.
MinStopTime
— Minimum amount of simulation time to take before searching for a steady state
1
(default)  positive integer
Minimum amount of simulation time to take before searching for a
steady state, specified as the commaseparated pair consisting of
'MinStopTime'
and a positive integer. This
namevalue pair argument is used for the simulation
method only.
Output Arguments
success
— Flag to indicate if a steady state of the model is found
true
 false
Flag to indicate if a steady state of the model is found, returned
as true
or false
.
variant_out
— SimBiology variant
variant object
SimBiology variant, returned as a variant object. The variant includes all species, parameters, and compartments of the model with the nonconstant quantities having the steadystate values.
model_out
— SimBiology model at the steady state
model object
SimBiology model at the steady state, returned as a model
object. model_out
is a copy of the input model
,
with the nonconstant species, parameters, and compartments set to
the steadystate values. Also, model_out
has
all initial assignment rules disabled. Simulating the model at steady
state requires that initial assignment rules be inactive, since these
rules can modify the values in variant_out
.
Note
If you decide to commit the
variant_out
to the inputmodel
that has initial assignment rules, thenmodel
is not expected to be at the steady state because the rules perturb the system when you simulate themodel
.model_out
is at steady state only if simulated without any doses.
exitInfo
— Exit information about steady state computation
character vector
Exit information about the steady state computation, returned as a character vector. The information contains different messages for corresponding exit conditions.
Steady state found (simulation)
– A steady state is found using the simulation method.Steady state found (algebraic)
– A steady state is found using the algebraic method.Steady state found (unstable)
– An unstable steady state is found using the algebraic method.Steady state found (possibly underdetermined)
– A steady state that is, possibly, not asymptotically stable is found using the algebraic method.No Steady state found
– No steady state is found.Optimization Toolbox (TM) is missing
– The method is set to'algebraic'
for nonlinear models and Optimization Toolbox is missing.
More About
Simulation Method
sbiosteadystate
simulates the model until
MaxStopTime
. During the simulation, the function
approximates the gradient using finite differencing (forward difference) over time
to detect a steady state.
Algebraic Method
sbiosteadystate
tries to find a steady state
of the model algebraically by finding a root of the flux function
v. The flux function includes reaction equations, rate rules,
and algebraic equations, that is,
v(X,P) = 0
, where
X and P are nonconstant quantities and
parameters of the model. Thereby the mass conservation imposed by the reaction
equations is respected.
For nonlinear models, sbiosteadystate
uses fmincon
(Optimization Toolbox) to get an initial guess for the root. The solution found by
fmincon
is then improved by fsolve
(Optimization Toolbox). To detect convergence, sbiosteadystate
uses the absolute tolerance ('AbsTol'
). In other words,
OptimalityTolerance
, FunctionTolerance
,
and StepTolerance
options of the corresponding optimization
function are set to the 'AbsTol'
value.
For linear models, sbiosteadystate
finds the roots of the
flux function v by solving a linear system defined by the
reaction and conservation equations. For linear models, there are no rate or
algebraic equations.
Version History
Introduced in R2016a
See Also
sbiosimulate
 sbiovariant
 sbiomodel
 sbioaccelerate
 Model object
 ScheduleDose
object
 Variant object
 commit
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 Belgium (English)
 Denmark (English)
 Deutschland (Deutsch)
 España (Español)
 Finland (English)
 France (Français)
 Ireland (English)
 Italia (Italiano)
 Luxembourg (English)
 Netherlands (English)
 Norway (English)
 Österreich (Deutsch)
 Portugal (English)
 Sweden (English)
 Switzerland
 United Kingdom (English)