mass.simulation.simulation
The Simulation module addresses the simulation of MassModel
s.
The Simulation
is designed to address all aspects related to the
simulation of one or more MassModel
s. These aspects include
initializing and compiling the model into a roadrunner.RoadRunner
instance (the ODE integrator), storing the numerical values necessary for the
simulations, and handling the simulation results by creating and storing
MassSolution
s.
A Simulation
is initialized by providing a simulatable
MassModel
that can be converted into an SBML compliant model.
Multiple models can be added to the Simualtion
in order to simulate
an ensemble of models. To add an additional model to the ensemble, the model
must meet three criteria:
The model must have equivalent ODEs to the
reference_model
The model must not have the same ID as the
reference_model
.The model must have all numerical values needed for simulation.
Perturbations can be implemented for a given simulation as long as they follow the following guidelines:
Perturbations are
dict
s where the{key: value}
pairs are the variables to be perturbed and the new numerical value or value change.To scale the current value of a variable, the value should be a
str
representing the formula for altering perturbation variable, where the variable in thestr
is identical to the perturbation key.If providing a formula
str
as the perturbation value, it must be possible to ‘sympify’ the string using thesympify()
function. It must only have one variable, identical to the perturbation key.Only boundary conditions can be changed to have functions of time that represent the external concentration at that point in time. If a perturbation value is to be a string representing a function, it must be a function, it may only contain the time variable
't'
and the boundary metabolite variable.
Some examples of perturbations following the guidelines for a model containing
the specie with ID 'MID_c'
, boundary metabolite with ID 'MID_b'
, and
reaction with ID 'RID'
:
Altering
initial_conditions
(ICs):
{'MID_c': 2}
Change the IC value to 2.
{'MID_c': 'MID_c * 1.5'}
Increase current IC value by 50%.Altering
parameters
:
{'kf_RID': 'kf_RID * 0.75'}
Decrease kf parameter value by 25%.
{'Keq_RID': 100}
Change Keq parameter value to 100.Altering
boundary_conditions
(BCs):
{'MID_b': 'sin(2 * pi * t)'}
Change BC to asin
function.
{'MID_b': 'MID_b + cos(t)'}
Addcos
function to current BC value.
Note that perturbations using functions of time may take longer to implement than other perturbations.
All simulation results are returned as MassSolution
s.
Each simulated model has a corresponding MassSolution
s stored
in the Simulation
. These solution objects are stored until being
replaced by a new MassSolution
upon resimulating the model. This
means that there can only be one concentration solution and one flux solution
per simulated model. A failed simulation of a model will return an empty
MassSolution
.
Though the Simulation
utilizes the roadrunner
package, the
standard logging
module will be used for mass
logging purposes in
the simulation
submodule. Therefore, the roadrunner logger is disabled
upon loading the simulation
submodule. However, because the
Simulation
utilizes the roadrunner
package for simulating
models, the roadrunner.Logger
can be accessed via the
RR_LOGGER
variable for those who wish to utilize it. See the
roadrunner
documentation for more information on how to configure the
roadrunner.Logger
.
Module Contents
Classes
Class for managing setup and result handling of simulations. |
Attributes
Logger for |
|
The logger for the |
- mass.simulation.simulation.LOGGER[source]
Logger for
simulation
submodule.- Type
- mass.simulation.simulation.RR_LOGGER[source]
The logger for the
roadrunner
.- Type
roadrunner.Logger
- class mass.simulation.simulation.Simulation(reference_model, id=None, name=None, verbose=False, **kwargs)[source]
Bases:
cobra.core.object.Object
Class for managing setup and result handling of simulations.
The
Simulation
class is designed to address all aspects related to the simulation ofMassModel
objects, including setting the solver and solver options, perturbation of concentrations and parameters, simulation of a single model or an ensemble of models, and handling of simulation results.- Parameters
reference_model (MassModel) – The model to load for simulation. The model will be set as the
Simulation.reference_model
.id (str or None) – An identifier to associate with the
Simulation
. IfNone
then one is automatically created based on the model identifier.name (str) – A human readable name for the
Simulation
.verbose (bool) – Whether to provide a QCQA report and more verbose messages when trying to load the model. Default is
False
.*kwargs –
- variable_step_size :
bool
indicating whether to initialize the integrator with a variable time step for simulations.Default is
True
.- allow_approx :
bool
indicating whether to allow the steady state solver to approximate the steady state solution in cases where NLEQ methods fail to converge to steady state due to a singular Jacobian matrix.Default is
True
.
- property reference_model[source]
Return the reference model of the
Simulation
.
- property models[source]
Return the IDs of models that exist in the
Simulation
.
- property concentration_solutions[source]
Get a copy of stored
MassSolution
s for concentrations.- Returns
Contains all
MassSolution
objects for concentrations.- Return type
- property flux_solutions[source]
Get a copy of the stored
MassSolution
s for fluxes.- Returns
Contains all
MassSolution
objects for fluxes.- Return type
- set_new_reference_model(model, verbose=False)[source]
Set a new reference model for the
Simulation
.To set a new reference model, the model must meet three criteria:
The model must have equivalent ODEs to the
reference_model
.The model must not have the same ID as the
reference_model
The model must have all numerical values needed for simulation.
If the criteria is not met, a warning is raised and the reference model will not change.
After changing the reference model, the previous reference model will remain included in the
Simulation
.- Parameters
model (MassModel or str) – Either a new or existing
MassModel
, or the string identifer of an existing model in theSimulation
to be set as the new reference model.verbose (bool) – Whether to output additional and more verbose messages. Default is
False
.
- get_model_simulation_values(model)[source]
Return two dictionaries containing initial and parameter values.
- Parameters
model (MassModel or str) – The model or its identifier whose values are to be returned.
- Returns
tuple (init_conds, parameters)
init_conds (
DictWithID
) – ADictWithID
containing initial conditions.parameters (
DictWithID
) – ADictWithID
containing model parameters.
- add_models(models, verbose=False, disable_safe_load=False)[source]
Add the model values to the
Simulation
.To add a model to the
Simulation
, three criteria must be met:The model must have equivalent ODEs to the
reference_model
The model must not have the same ID as the
reference_model
.The model must have all numerical values needed for simulation.
Notes
Only the model values are added to the
Simulation
.If a model already exists in the Simulation, it will be replaced.
To verify that the model has equivalent ODEs to the reference model, use
MassModel.has_equivalent_odes()
.
- Parameters
Warning
Use the
disable_safe_load
argument with caution, as setting the value asdisable_safe_load=True
will reduce the time it takes to add models, but models that do not adhere to the three criteria may create unexepcted downstream errors.
- remove_models(models, verbose=False)[source]
Remove the model values from the
Simulation
.Notes
The
reference_model
cannot be removed from theSimulation
. In order to remove the current reference model, the reference model must first be changed to a different model using theset_new_reference_model()
method.
- get_model_objects(models=None)[source]
Return the loaded models as
MassModel
s.Notes
With the exception of the
reference_model
, only the numerical values of a mdoel are stored in order to improve performance. Therefore, when using this method to retrieve theMassModel
s, all models are created anew, meaning that they will NOT be the sameMassModel
s that were loaded into the Simulation.- Parameters
models (iterable of model identifiers) – An iterable of strings containing the model identifiers of the desired
MassModel
s to return. IfNone
then all models in theSimulation
will be returned.- Returns
- Return type
- simulate(models=None, time=None, perturbations=None, **kwargs)[source]
Simulate models and return results as
MassSolution
s.A simulation is carried out by simultaneously integrating the ODEs of the
models
to compute their solutions over the time interval specified bytime
, while temporarily incorporating events and changes specified inperturbations
.- Parameters
models (iterable of models or their string identifiers, None) – The models to simulate. If
None
then all models loaded into the simulation object will be used. All models must already exist in theSimulation
.time (tuple) – Either a
tuple
containing the initial and final time points, or atuple
containing the initial time point, final time point, and the number of time points to use.perturbations (dict) – A
dict
of perturbations to incorporate into the simulation. Seesimulation
documentation for more information on valid perturbations.**kwargs –
- verbose :
bool
indicating the verbosity of the method.Default is
False
.- steps :
int
indicating number of steps at which the output is sampled where the samples are evenly spaced andsteps = (number of time points) - 1.
Steps and number of time points may not both be specified.Default is
None
.- interpolate :
bool
indicating whether simulation results should be returned to as interpolating functions.Default is
False
.- update_solutions :
bool
indicating whether to replace the stored solutions in the simulation with the new simulation results.Default is
True
.- decimal_precision :
bool
indicating whether to apply thedecimal_precision
attribute of theMassConfiguration
to the solution values.Default is
False
.
- Returns
tuple (conc_solutions, flux_solutions)
conc_solutions (MassSolution or DictList) – If only one model was simulated, the return type is a
MassSolution
containing the concentration solutions. If multiple models were simulated, the return type is aDictList
ofMassSolution
s containing the concentration solutions. If a simulation failed, the correspondingMassSolution
will be returned as empty.flux_solutions (MassSolution or DictList) – If only one model was simulated, the return type is a
MassSolution
containing the flux solutions. If multiple models were simulated, the return type is aDictList
ofMassSolution
s containing the flux solutions. If a simulation failed, the correspondingMassSolution
will be returned as empty.
See also
integrator
Access the integrator utilized in simulations.
- find_steady_state(models=None, strategy='nleq2', perturbations=None, update_values=False, **kwargs)[source]
Find steady states for models.
The steady state is found by carrying out the provided strategy.
The
'simulate'
strategy will simulate the model for a long time (default1e8
), and ensure the absolute difference between solutions at the final two time points is less than thesteady_state_threshold
in theMassConfiguration
.Other strategies involve using the
roadrunner.roadrunner.SteadyStateSolver
class to determine the steady state through global Newtonian methods. The steady state is found when the sum of squares of the rates of change is less than thesteady_state_threshold
in theMassConfiguration
.
- Parameters
models (iterable of models or their string identifiers, None) – The models to simulate. If
None
then all models loaded into the simulation object will be used. All models must already exist in theSimulation
.strategy (str) –
The strategy for finding the steady state. Must be one of the following:
'simulate'
'nleq1'
'nleq2'
perturbations (dict) – A
dict
of perturbations to incorporate into the simulation. Seesimulation
documentation for more information on valid perturbations.update_values (bool) – Whether to update the model with the steady state results. Default is
False
.**kwargs –
- verbose :
bool
indicating the verbosity of the method.Default is
False
.- steps :
int
indicating number of steps at which the output is sampled where the samples are evenly spaced andsteps = (number of time points) - 1.
Steps and number of time points may not both be specified. Only valid forstrategy='simulate'
.Default is
None
.- tfinal :
float
indicating the final time point to use in when simulating to long times to find a steady state. Only valid forstrategy='simulate'
.Default is
1e8
.- num_attempts :
int
indicating the number of attempts the steady state solver should make before determining that a steady state cannot be found. Only valid forstrategy='nleq1'
orstrategy='nleq2'
.Default is
2
.- decimal_precision :
bool
indicating whether to apply thedecimal_precision
attribute of theMassConfiguration
to the solution values.Default is
False
.
- Returns
tuple (conc_solutions, flux_solutions)
conc_solutions (MassSolution or DictList) – If only one model was simulated, the return type is a
MassSolution
containing the concentration solutions. If multiple models were simulated, the return type is aDictList
ofMassSolution
s containing the concentration solutions. If a simulation failed, the correspondingMassSolution
will be returned as empty.flux_solutions (MassSolution or DictList) – If only one model was simulated, the return type is a
MassSolution
containing the flux solutions. If multiple models were simulated, the return type is aDictList
ofMassSolution
s containing the flux solutions. If a simulation failed, the correspondingMassSolution
will be returned as empty.
See also
integrator
Access the integrator utilized in the
"simulate"
strategy.steady_state_solver
Access the steady state solver utilized in root finding strategies i.e.
"nleq1"
and"nleq2"
.
- _make_rr_selections(selections=None, include_time=True, verbose=False)[source]
Set the observable output of the simulation.
Warning
This method is intended for internal use only.
- _format_perturbations_input(perturbations, verbose=False)[source]
Check and format the perturbation input.
Perturbations are checked before simulations are carried out to limit fails during the simulation due to bad syntax or values.
Warning
This method is intended for internal use only.
- _set_simulation_values(model, perturbations, verbose=False)[source]
Set the simulation numerical values in the roadrunner instance.
Warning
This method is intended for internal use only.
- _set_values_in_roadrunner(model, reset, sim_values_to_set)[source]
Set the roadrunner values to reflect the given model.
Warning
This method is intended for internal use only.
- _make_mass_solutions(model, selections, results, update_values=False, **kwargs)[source]
Make the MassSolutions using the results of the Simulation.
Warning
This method is intended for internal use only.
- _update_stored_solutions(solution_type, solutions)[source]
Update stored MassSolutions with new MassSolution objects.
Warning
This method is intended for internal use only.
- _reset_roadrunner(reset)[source]
Reset the RoadRunner to its the original state.
Warning
This method is intended for internal use only.
- _find_steady_state_simulate(model, **kwargs)[source]
Find the steady state of a model through simulation of the model.
Warning
This method is intended for internal use only.
- _find_steady_state_solver(model, **kwargs)[source]
Find the steady state of the model using a RoadRunner solver method.
Warning
This method is intended for internal use only.
- update_model_simulation_values(model, initial_conditions=None, parameters=None, verbose=False)[source]
Update the simulation values for a given model.
- Parameters
model (MassModel or its string identifier.) – A previously loaded MassModel.
initial_conditions (dict or None) – A
dict
containing initial conditions to update.parameters (dict or None) – A
dict
containing parameters to update. IfNone
provided, will attempt to extract values from the given MassModel
- _update_mass_model_with_values(mass_model, value_dict=None)[source]
Update the MassModel object with the stored model values.
Warning
This method is intended for internal use only.