# simOptions

Option set for `sim`

## Description

## Examples

### Create Default Option Set for Model Simulation

opt = simOptions;

### Specify Options for Model Simulation

Create an option set for `sim`

specifying the following options.

Zero initial conditions

Input offset of 5 for the second input of a two-input model

opt = simOptions('InitialCondition','z','InputOffset',[0; 5]);

### Add Noise to Simulation Output

Create noise data for a simulation with `500`

input data samples and two outputs.

noiseData = randn(500,2);

Create a default option set.

opt = simOptions;

Modify the option set to add the noise data.

opt.AddNoise = true; opt.NoiseData = noiseData;

### Use Historical Data to Specify Initial Conditions for Model Simulation

Use historical input-output data as a proxy for initial conditions when simulating your model.

Load a two-input, one-output data set.

load iddata7 z7

Identify a fifth-order state-space model using the data.

sys = n4sid(z7, 5);

Split the data set into two parts.

zA = z7(1:15); zB = z7(16:end);

Simulate the model using the input signal in `zB`

.

uSim = zB;

Simulation requires initial conditions. The signal values in `zA`

are the historical data, that is, they are the input and output values for the time immediately preceding data in `zB`

. Use `zA`

as a proxy for the required initial conditions.

IO = struct('Input',zA.InputData,'Output',zA.OutputData); opt = simOptions('InitialCondition',IO);

Simulate the model.

ysim = sim(sys,uSim,opt);

To understand how the past data is mapped to the initial states of the model, see Understand Use of Historical Data for Model Simulation.

### Obtain and Apply Estimated Initial Conditions

Load and plot the data.

load iddata1ic z1i plot(z1i)

Examine the initial value of the output data `y(1)`

.

ystart = z1i.y(1)

ystart = -3.0491

The measured output does not start at 0.

Estimate a second-order transfer function `sys`

and return the estimated initial condition `ic`

.

[sys,ic] = tfest(z1i,2,1); ic

ic = initialCondition with properties: A: [2x2 double] X0: [2x1 double] C: [0.2957 5.2441] Ts: 0

`ic`

is an `initialCondition`

object that encapsulates the free response of `sys`

, in state-space form, to the initial state vector in `X0`

.

Simulate `sys`

using the estimation data but without incorporating the initial conditions. Plot the simulated output with the measured output.

y_no_ic = sim(sys,z1i); plot(y_no_ic,z1i) legend('Model Response','Output Data')

The measured and simulated outputs do not agree at the beginning of the simulation.

Incorporate the initial condition into the `simOptions`

option set.

opt = simOptions('InitialCondition',ic); y_ic = sim(sys,z1i,opt); plot(y_ic,z1i) legend('Model Response','Output Data')

The simulation combines the model response to the input signal with the free response to the initial condition. The measured and simulated outputs now have better agreement at the beginning of the simulation. This initial condition is valid only for the estimation data `z1i`

.

## Input Arguments

### Name-Value Arguments

Specify optional pairs of arguments as
`Name1=Value1,...,NameN=ValueN`

, where `Name`

is
the argument name and `Value`

is the corresponding value.
Name-value 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: **`'AddNoise',true','InputOffset',[5;0]`

adds
default Gaussian white noise to the response model and specifies an
input offset of `5`

for the first of two model inputs.

`InitialCondition`

— Simulation initial conditions

`[]`

(default) | column vector | matrix | `initialCondition`

object | object array | structure | structure array | `'model'`

Simulation initial conditions, specified as one of the following:

`'z'`

— Zero initial conditions.Numerical column vector of initial states with length equal to the model order.

For multiexperiment data, specify a matrix with

*Ne*columns, where*Ne*is the number of experiments, to configure the initial conditions separately for each experiment. Otherwise, use a column vector to specify the same initial conditions for all experiments.Use this option for state-space models (

`idss`

and`idgrey`

) only.`initialCondition`

object —`initialCondition`

object that represents a model of the free response of the system to initial conditions. For multiexperiment data, specify a 1-by-*N*array of objects, where_{e}*N*is the number of experiments._{e}Use this option for linear models only. For an example, see Obtain and Apply Estimated Initial Conditions.

Structure with the following fields, which contain the historical input and output values for a time interval immediately before the start time of the data used in the simulation:

Field Description `Input`

Input history, specified as a matrix with *Nu*columns, where*Nu*is the number of input channels. For time-series models, use`[]`

. The number of rows must be greater than or equal to the model order.`Output`

Output history, specified as a matrix with *Ny*columns, where*Ny*is the number of output channels. The number of rows must be greater than or equal to the model order.For an example, see Use Historical Data to Specify Initial Conditions for Model Simulation.

For multiexperiment data, configure the initial conditions separately for each experiment by specifying

`InitialCondition`

as a structure array with*Ne*elements. To specify the same initial conditions for all experiments, use a single structure.The software uses

`data2state`

to map the historical data to states. If your model is not`idss`

,`idgrey`

,`idnlgrey`

, or`idnlarx`

, the software first converts the model to its state-space representation and then maps the data to states. If conversion of your model to`idss`

is not possible, the estimated states are returned empty.`'model'`

— Use this option for`idnlgrey`

models only. The software sets the initial states to the values specified in the`sys.InitialStates`

property of the model`sys`

.`[]`

— Corresponds to zero initial conditions for all models except`idnlgrey`

. For`idnlgrey`

models, the software treats`[]`

as`'model'`

and specifies the initial states as`sys.InitialStates`

.

`X0Covariance`

— Covariance of initial states vector

`[]`

(default) | matrix

Covariance of initial states vector, specified as one of the following:

Positive definite matrix of size

*Nx*-by-*Nx*, where*Nx*is the model order.For multiexperiment data, specify as an

*Nx*-by-*Nx*-by-*Ne*matrix, where*Ne*is the number of experiments.`[]`

— No uncertainty in the initial states.

Use this option only for state-space models (`idss`

and `idgrey`

)
when `'InitialCondition'`

is specified as a column
vector. Use this option to account for initial condition uncertainty
when computing the standard deviation of the simulated response of
a model.

`InputInterSample`

— Input-channel intersample behavior

`'auto'`

| `'zoh'`

| `'foh'`

| `'bl'`

Input-channel intersample behavior for transformations between discrete time and continuous time, specified as `'auto'`

, `'zoh'`

,`'foh'`

, or `'bl'`

.

The definitions of the three behavior values are as follows:

`'zoh'`

— Zero-order hold maintains a piecewise-constant input signal between samples.`'foh'`

— First-order hold maintains a piecewise-linear input signal between samples.`'bl'`

— Band-limited behavior specifies that the continuous-time input signal has zero power above the Nyquist frequency.

`iddata`

objects have a similar property,
`data.InterSample`

, that contains the same behavior value options.
When the `InputInterSample`

value is `'auto'`

and
the estimation data is in an `iddata`

object `data`

, the
software uses the `data.InterSample`

value. When the estimation data
is instead contained in a timetable or a matrix pair, with the `'auto'`

option, the software uses `'zoh'`

.

The software applies the same option value to all channels and all experiments.

`InputOffset`

— Input signal offset

`[]`

(default) | column vector | matrix

Input signal offset, specified as a column vector of length *Nu*.
Use `[]`

if there are no input offsets. Each element
of `InputOffset`

is subtracted from the corresponding
input data before the input is used to simulate the model.

For multiexperiment data, specify `InputOffset`

as:

An

*Nu*-by-*Ne*matrix to set offsets separately for each experiment.A column vector of length

*Nu*to apply the same offset for all experiments.

`OutputOffset`

— Output signal offset

`[]`

(default) | column vector | matrix

Output signal offset, specified as a column vector of length *Ny*.
Use `[]`

if there are no output offsets. Each element
of `OutputOffset`

is added to the corresponding
simulated output response of the model.

For multiexperiment data, specify `OutputOffset`

as:

An

*Ny*-by-*Ne*matrix to set offsets separately for each experiment.A column vector of length

*Ny*to apply the same offset for all experiments.

`AddNoise`

— Noise addition toggle

`false`

(default) | `true`

Noise addition toggle, specified as a logical value indicating whether to add noise to the response model.

`NoiseData`

— Noise signal data

`[]`

(default) | matrix | cell array of matrices

Noise signal data specified as one of the following:

`[]`

— Default Gaussian white noise.Matrix with

*N*rows and_{s}*N*columns, where_{y}*N*is the number of input data samples, and_{s}*N*is the number of outputs. Each matrix entry is scaled according to_{y}`NoiseVariance`

property of the simulated model and added to the corresponding output data point. To set`NoiseData`

at a level that is consistent with the model, use white noise with zero mean and a unit covariance matrix.Cell array of

*N*matrices, where_{e}*N*is the number of experiments for multiexperiment data. Use a cell array to set the_{e}`NoiseData`

separately for each experiment, otherwise set the same noise signal for all experiments using a matrix.

`NoiseData`

is the noise signal, *e*(*t*),
for the model

$$y(t)=Gu(t)+He(t).$$

Here,*G* is the transfer function from the
input, *u*(*t*), to the output, *y*(*t*),
and *H* is the noise transfer function.

`NoiseData`

is used for simulation only when `AddNoise`

is
true.

`OutputTimes`

— Times at which the output is calculated

`[]`

(default) | vector | cell array

Times at which the output is calculated, specified as one of the following:

Empty matrix,

`[]`

. This is the default option, in which output times are not specified. For systems with inputs, the output sample times are chosen to be the same as those of the input signals. For autonomous systems (that is, systems with no inputs) a non-empty value for`OutputTimes`

must be specified, otherwise, an error is generated during simulation.Time span [

*t*,_{Min}*t*], where_{Max}*t*and_{Min}*t*are expressed in the time units of the model._{Max}Time vector. A column vector of doubles. For models with inputs, the time vector must be contained within the time span of the simulation inputs (that is entries cannot be outside the time range of the input signals). For discrete-time models, the time interval must match the model sample time.

Cell array. This option is used for multi-experiment simulations. Each element of the cell contains an array of time spans or time vectors, one array for each data experiment.

## Output Arguments

`opt`

— Option set for `sim`

command

`simOptions`

option set

Option set for `sim`

command, returned as
a `simOptions`

option set.

## Version History

**Introduced in R2012a**

### R2022b: `InputInterSample`

option allows intersample behavior specification for continuous models estimated from timetables or matrices.

`iddata`

objects contain an `InterSample`

property that
describes the behavior of the signal between sample points. The
`InputInterSample`

option implements a version of that property in
`simOptions`

so that intersample behavior can be specified also when
estimation data is stored in timetables or matrices.

## See Also

## 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)