mass.simulation.simulation

The Simulation module addresses the simulation of MassModels.

The Simulation is designed to address all aspects related to the simulation of one or more MassModels. 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 MassSolutions.

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:

1. The model must have equivalent ODEs to the reference_model

2. The model must not have the same ID as the reference_model.

3. 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:

1. Perturbations are dicts where the {key: value} pairs are the variables to be perturbed and the new numerical value or value change.

2. 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 the str is identical to the perturbation key.

3. If providing a formula str as the perturbation value, it must be possible to ‘sympify’ the string using the sympify() function. It must only have one variable, identical to the perturbation key.

4. 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 a sin function.

  • {'MID_b': 'MID_b + cos(t)'} Add cos 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 MassSolutions. Each simulated model has a corresponding MassSolutions 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

Simulation

Class for managing setup and result handling of simulations.

Attributes

LOGGER	Logger for simulation submodule.
RR_LOGGER	The logger for the roadrunner.

mass.simulation.simulation.LOGGER

Logger for simulation submodule.

Type

logging.Logger

mass.simulation.simulation.RR_LOGGER

The logger for the roadrunner.

Type

roadrunner.Logger

class mass.simulation.simulation.Simulation(reference_model, id=None, name=None, verbose=False, **kwargs)

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 of MassModel 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. If None 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

Return the reference model of the Simulation.

property models

Return the IDs of models that exist in the Simulation.

property roadrunner

Return the RoadRunner instance.

property concentration_solutions

Get a copy of stored MassSolutions for concentrations.

Returns

Contains all MassSolution objects for concentrations.

Return type

DictList

property flux_solutions

Get a copy of the stored MassSolutions for fluxes.

Returns

Contains all MassSolution objects for fluxes.

Return type

DictList

property integrator

Return the roadrunner.roadrunner.Integrator.

property steady_state_solver

Return the roadrunner.roadrunner.SteadyStateSolver.

set_new_reference_model(model, verbose=False)

Set a new reference model for the Simulation.

To set a new reference model, the model must meet three criteria:

1. The model must have equivalent ODEs to the reference_model.

2. The model must not have the same ID as the reference_model

3. 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 the Simulation 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)

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) – A DictWithID containing initial conditions.

• parameters (DictWithID) – A DictWithID containing model parameters.

add_models(models, verbose=False, disable_safe_load=False)

Add the model values to the Simulation.

To add a model to the Simulation, three criteria must be met:

1. The model must have equivalent ODEs to the reference_model

2. The model must not have the same ID as the reference_model.

3. 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

• models (iterable of models) – An iterable containing the MassModels to add.

• verbose (bool) – Whether to print if loading of models succeeds or fails. Default is False.

• disable_safe_load (bool) – Whether to disable criteria checks. Default is False.

Warning

Use the disable_safe_load argument with caution, as setting the value as disable_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)

Remove the model values from the Simulation.

Notes

The reference_model cannot be removed from the Simulation. In order to remove the current reference model, the reference model must first be changed to a different model using the set_new_reference_model() method.

Parameters

• models (iterable of models or their identifiers) – An iterable of MassModels or their string identifiers to be removed.

• verbose (bool) – Whether to print if removal of models succeeds. Default is False.

get_model_objects(models=None)

Return the loaded models as MassModels.

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 the MassModels, all models are created anew, meaning that they will NOT be the same MassModels that were loaded into the Simulation.

Parameters

models (iterable of model identifiers) – An iterable of strings containing the model identifiers of the desired MassModels to return. If None then all models in the Simulation will be returned.

Returns

mass_models – A DictList containing all of the MassModels.

Return type

DictList

simulate(models=None, time=None, perturbations=None, **kwargs)

Simulate models and return results as MassSolutions.

A simulation is carried out by simultaneously integrating the ODEs of the models to compute their solutions over the time interval specified by time, while temporarily incorporating events and changes specified in perturbations.

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 the Simulation.

• time (tuple) – Either a tuple containing the initial and final time points, or a tuple 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. See simulation 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 and steps = (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 the decimal_precision attribute of the MassConfiguration 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 a DictList of MassSolutions containing the concentration solutions. If a simulation failed, the corresponding MassSolution 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 a DictList of MassSolutions containing the flux solutions. If a simulation failed, the corresponding MassSolution 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)

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 (default 1e8), and ensure the absolute difference between solutions at the final two time points is less than the steady_state_threshold in the MassConfiguration.

• 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 the steady_state_threshold in the MassConfiguration.

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 the Simulation.

• 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. See simulation 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 and steps = (number of time points) - 1. Steps and number of time points may not both be specified. Only valid for strategy='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 for strategy='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 for strategy='nleq1' or strategy='nleq2'.

  Default is 2.

  decimal_precision :

  bool indicating whether to apply the decimal_precision attribute of the MassConfiguration 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 a DictList of MassSolutions containing the concentration solutions. If a simulation failed, the corresponding MassSolution 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 a DictList of MassSolutions containing the flux solutions. If a simulation failed, the corresponding MassSolution 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)

Set the observable output of the simulation.

Warning

This method is intended for internal use only.

_format_perturbations_input(perturbations, verbose=False)

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)

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)

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)

Make the MassSolutions using the results of the Simulation.

Warning

This method is intended for internal use only.

_update_stored_solutions(solution_type, solutions)

Update stored MassSolutions with new MassSolution objects.

Warning

This method is intended for internal use only.

_reset_roadrunner(reset)

Reset the RoadRunner to its the original state.

Warning

This method is intended for internal use only.

_find_steady_state_simulate(model, **kwargs)

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)

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)

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. If None provided, will attempt to extract values from the given MassModel

_update_mass_model_with_values(mass_model, value_dict=None)

Update the MassModel object with the stored model values.

Warning

This method is intended for internal use only.

_get_all_values_for_sim(mass_model)

Get all model values as a single dict.

Warning

This method is intended for internal use only.

_add_model_values_to_simulation(model, verbose)

Add model values to the simulation.

Warning

This method is intended for internal use only.