# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# SimFunction object

Function-like interface to execute SimBiology models

## Description

The `SimFunction` object provides an interface that allows you to execute a SimBiology® model like a function and a workflow to perform parameter scans (in parallel if Parallel Computing Toolbox™ is available), Monte Carlo simulations, and scans with multiple or vectorized doses. Since a `SimFunction` object can be executed like a function handle, you can customize it to integrate SimBiology models with other MATLAB® products and other custom analyses (such as visual predictive checks).

Use the `createSimFunction` method to construct the SimFunction object. SimFunction objects are immutable once created and automatically accelerated at the first function execution.

## Syntax

If you specified any dosing information when you called `createSimFunction` to construct the `SimFunction` object `F`, then `F` has these syntaxes.

`simdata = F(phi,t_stop,u,t_output)` returns a `SimData object` `simdata` after simulating a SimBiology model using `phi`, a matrix of parameter values, `t_stop`, simulation stop time, `u`, dosing information, and `t_output`, output time.

`simdata = F(phi,t_stop,u)` uses the input arguments `phi`, `t_stop`, and `u`.

If you did not specify any dosing information when you called `createSimFunction`, then `F` has these signatures:

`simdata = F(phi,t_stop)` returns a `SimData object` `simdata` using `phi` and `t_stop`.

`simdata = F(phi,t_stop,[],t_output)` uses the input arguments `phi`, `t_stop`, empty dosed argument `[]`, and `t_output`. You must specify `u`, the dosing information, as an empty array`[]` for this signature.

 Note:   When `t_output` is empty and `t_stop` is specified, the simulations report the solver time points until `t_stop`. When `t_output` is specified and `t_stop` is empty, only the time points in `t_output` are reported. When both are specified, the reported time points are the union of solver time points and the time points in `t_output`. If the last `t_output` is greater than the corresponding `t_stop`, then simulation proceeds until the last time point in `t_output`.
````simdata = F(phi,tbl)` uses the input arguments `phi` and `tbl`. Using this signature only lets you specify output times as one of the variables of `tbl`. Any data row in `tbl` where all dependent variable columns having `NaN` values is ignored.```[T,Y] = F(_)``` returns `T`, a cell array of numeric vector, and `Y`, a cell array of 2-D numeric matrices, using any of the input arguments in the preceding syntaxes.```

## Input Arguments

`phi`

Matrix of size S-by-P, where S is the number of simulations to perform and P is the number of parameters specified in the `params` argument when you called `createSimFunction` to construct `F`. Each simulation is performed with the parameters specified in the corresponding row of `phi`.

When `phi` is specified as a 1-by-P matrix, then all simulations use the same parameters, and the number of simulations is determined from the `t_stop`, `u`, or `t_output` argument in that order.

For example, if `phi` and `t_stop` have a single row and `u` is a matrix of size N-by-DoseTargets, the number of simulations is determined as N.

`t_stop`

• Scalar specifying the same stop time for all simulations

• Vector of size N specifying a stop time for each simulation for all N simulations

`u`

• `table` of dosing information with two or three variables representing dose time, dose amount, and dose rate (optional). You must name the table variables as follows.

`u.Properties.VariableNames = {'Time','Amount','Rate'};`

If `UnitConversion` is on, specify units for each variable. For instance, you can specify units as follows.

`u.Properties.VariableUnits = {'second','molecule','molecule/second'};`

This table can have multiple rows, where each row represents a dose applied to the dose target at a specified dose time with a specified amount and rate if available.

 Note:   If you already have a ```ScheduleDose object```, you can get this table by using the `getTable` method of the object.
• `table` with one row and five variables containing `RepeatDose` data. Dose rate variable is optional. Name the variables as follows.

`u.Properties.VariableNames = {'StartTime','Amount','Rate','Interval','RepeatCount'};`

If `UnitConversion` is on, specify units for each variable. Units for `'RepeatCount'` variable can be empty `''` or `'dimensionless'`. The unit of the `'Amount'` variable must be dimensionally consistent with that of the target species. For example, if the unit of target species is in an amount unit (such as mole or molecule), then the `'Amount'` variable unit must have the same dimension, i.e., its unit must be an amount unit and cannot be a mass unit (such as gram or kilogram). The unit for the `'Rate'` variable must be dimensionally consistent as well.

`u.Properties.VariableUnits = {'second','molecule','molecule/second','second','dimensionless'};`
 Note:   If you already have a ```RepeatDose object```, you can get this table by using the `getTable` method of the object.
• Cell array of tables of size 1-by-N, where N is the number of dose targets. Each cell represents a table as described previously.

• Cell array of tables of size S-by-N, where S is the number of simulations and N is the number of dose targets. Each cell represents a table. S is equal to the number of rows in `phi`.

`t_output`

• Vector of monotonically increasing output times that is applied to all simulations

• Cell array containing a single time vector that is applied to all simulations

• Cell array of vectors representing output times. The ith cell element provides the output times for the ith simulation. The number of elements in the cell array must match the number of rows (simulations) in `phi`.

`tbl`

`table` or `dataset` that has time and dosing information such as group labels, independent variable, dependent variable(s), amount(s), and rate(s). You must name the variables of the table or data set as `'GROUP','TIME','DEPENDENTVAR1','DEPENDENTVAR2',...,'AMOUNT1','RATE1','AMOUNT2','RATE2',...`. The rate variable is optional for each dose.

If the `dosed` argument was empty when creating `F`, then amount- and rate-related variables are not required. If it is not empty, the number of amount and rate variables must match the number of dosed targets or species in `dosed`. The number of dependent variables must match the number of columns in `phi`.

If `UnitConversion` is on, specify a unit for each variable. The unit of `'Amount'` variable must be dimensionally consistent with that of the target species. See the description of the input argument `u` for details.

## Output Arguments

 `simdata` Array of SimData objects that contains results from executing the SimFunction `F`. The number of elements in the `simdata` array is the same as the number of rows in `phi`. The number of columns in each element of the `simdata` array, that is, `simdata(i).Data`, is equal to the number of elements in the `observed` cell array which was specified when creating `F`. `T` Cell array containing a numeric vector of size ```S x 1```. `S` is the number of simulations. The ith element of T contains the time point from the ith simulation. `Y` Cell array of 2-D numeric matrices. The ith element of `Y` contains data from the ith simulation. The number of rows in `T{i}` is equal to the number of rows in `Y{i}`.

## Constructor Summary

 createSimFunction (model) Create SimFunction object

## Method Summary

 accelerate(SimFunction) Prepare SimFunction object for accelerated simulations isaccelerated(SimFunction) Determine if SimFunction object is accelerated

## Property Summary

 `Parameters` `table` with variables named: `'Name'``'Value'``'Type'``'Units'` (only if `UnitConversion` is turned on)The table contains information about model quantities (species, compartments, or parameters) that define the inputs of a ```SimFunction object```. For instance, this table can contain parameters or species whose values are being scanned by the ```SimFunction object```. This property is read only. `Observables` `table` with variables named: `'Name'``'Type'``'Units'` (only if `UnitConversion` is turned on)This table contains information about model quantities (species, compartments, or parameters) that define the output of a ```SimFunction object```. This property is read only. `Dosed` `table` containing dosing information with variables named:`'TargetName'``'TargetDimension'` (only if `UnitConversion` is turned on)`'DurationParameterName'``'DurationParameterValue'``'DurationParameterUnits'` (only if `UnitConversion` is turned on)`'LagParameterName'``'LagParameterValue'` `'LagParameterUnits'` (only if `UnitConversion` is turned on)Variables related to the lag and duration parameters are included only when `'LagParameterName'` and `'DurationParameterName'` are not empty. This property is read only. `UseParallel` Logical. If `true` and Parallel Computing Toolbox is available, SimFunction is executed in parallel. This property is read-only. `UnitConversion` Logical. If true: During the execution of the `SimFunction` object, `phi` is assumed to be in the same units as units for corresponding model quantities specified in the `params` argument when the object was created using the `createSimFunction` method.Time (`t_output` or `t_stop`) is assumed to be in the same unit as the `TimeUnits` property of the active `configset object` of the SimBiology model from which `F` was created.Variables of dose tables (`u`) must have units specified by setting `u.Properties.VariableUnits` to a cell array of appropriate units. The dimension of the dose target such as an amount (molecule, mole, etc.) or mass (gram, kilogram, etc.), is stored on the `Dosed` property of `F`.The simulation result is in the same units as those specified on the corresponding quantities in the SimBiology model from which `F` was created.This property is read only. `DependentFiles` Cell array of character vectors containing the names of files that the model depends on. This property is used for deployment. This property is read only.

## Examples

collapse all

This example shows how to execute different signatures of the `SimFunction` object to simulate and scan parameters of the Lotka-Volterra (predator-prey) model described by Gillespie [1].

Load the sample project containing the model `m1`.

`sbioloadproject lotka;`

Create a `SimFunction` object `f` with `c1` and `c2` as input parameters to be scanned, and `y1` and `y2` as the output of the function with no dose.

`f = createSimFunction(m1,{'Reaction1.c1', 'Reaction2.c2'},{'y1', 'y2'}, [])`
```f = SimFunction Parameters: Name Value Type ______________ _____ ___________ 'Reaction1.c1' 10 'parameter' 'Reaction2.c2' 0.01 'parameter' Observables: Name Type ____ _________ 'y1' 'species' 'y2' 'species' Dosed: None```

Define an input matrix that contains values for each parameter (`c1` and `c2`) for each simulation. The number of rows indicates the total number of simulations, and each simulation uses the parameter values specified in each row.

`phi = [10 0.01; 10 0.02];`

Run simulations until the stop time is 5 and plot the simulation results.

`sbioplot(f(phi, 5));`

You can also specify a vector of different stop times for each simulation.

```t_stop = [3;6]; sbioplot(f(phi, t_stop));```

Next, specify the output times as a vector.

```t_output = 0:0.1:5; sbioplot(f(phi,[],[],t_output));```

Specify output times as a cell array of vectors.

```t_output = {0:0.01:3, 0:0.2:6}; sbioplot(f(phi, [], [], t_output));```

This example shows how to scan initial amounts of a species from a radioactive decay model with the first-order reaction: $\frac{dz}{dt}=c·x$, where `x` and `z` are species and `c` is the forward rate constant.

Load the sample project containing the radiodecay model `m1`.

`sbioloadproject radiodecay;`

Create a `SimFunction` object `f` to scan initial amounts of species `x`.

`f = createSimFunction(m1,{'x'},{'x','z'},[])`
```f = SimFunction Parameters: Name Value Type Units ____ _____ _________ __________ 'x' 1000 'species' 'molecule' Observables: Name Type Units ____ _________ __________ 'x' 'species' 'molecule' 'z' 'species' 'molecule' Dosed: None```

Define four different initial amounts of species x for scanning. The number of rows indicates the total number of simulations, and each simulation uses the parameter value specified in each row of the vector.

`phi = [200; 400; 600; 800];`

Run simulations until the stop time is 20 and plot the simulation results.

`sbioplot(f(phi, 20))`

This example shows how to simulate and scan a parameter of a radiodecay model while a species is being dosed.

Load the sample project containing the radiodecay model `m1`.

`sbioloadproject radiodecay;`

Create a `SimFunction` object `f` specifying parameter `Reaction1.c` to be scanned and species `x` as a dosed target.

`f = createSimFunction(m1,{'Reaction1.c'},{'x','z'},{'x'});`

Define a scalar dose of amount 200 molecules given at three time points (5, 10, and 15 seconds).

```dosetime = [5 10 15]; dose = [200 200 200]; u = table(dosetime', dose'); u.Properties.VariableNames = {'Time','Amount'}; u.Properties.VariableUnits = {'second','molecule'};```

Define the parameter values for `Reaction1.c` to scan.

`phi = [0.1 0.2 0.5]';`

Simulate the model for 20 seconds and plot the results.

`sbioplot(f(phi,20,u));`

You can also specify different dose amounts at different times.

```d1 = table(5,100); d1.Properties.VariableNames = {'Time','Amount'}; d1.Properties.VariableUnits = {'second','molecule'}; d2 = table(10,300); d2.Properties.VariableNames = {'Time','Amount'}; d2.Properties.VariableUnits = {'second','molecule'}; d3 = table(15,600); d3.Properties.VariableNames = {'Time','Amount'}; d3.Properties.VariableUnits = {'second','molecule'};```

Simulate the model using these doses and plot the results.

`sbioplot(f(phi,20,{d1;d2;d3}));`

You can also define a cell array of dose tables.

```u = cell(3,1); dosetime = [5 10 15]; dose = [200 200 200]; u{1} = table(dosetime',dose'); u{1}.Properties.VariableNames = {'Time','Amount'}; u{1}.Properties.VariableUnits = {'second','molecule'}; dosetime2 = [2 6 12]; dose2 = [500 500 500]; u{2} = table(dosetime2', dose2'); u{2}.Properties.VariableNames = {'Time','Amount'}; u{2}.Properties.VariableUnits = {'second','molecule'}; dosetime3 = [3 8 18]; dose3 = [100 100 100]; u{3} = table(dosetime3', dose3'); u{3}.Properties.VariableNames = {'Time','Amount'}; u{3}.Properties.VariableUnits = {'second','molecule'};```

Simulate the model using the dose tables and plot results.

`sbioplot(f(phi,20,u));`

## References

[1] Gillespie, D.T. (1977). Exact Stochastic Simulation of Coupled Chemical Reactions. The Journal of Physical Chemistry. 81(25), 2340–2361.