Simulink®Choosing a Solver   Configuration Sets
  

Importing and Exporting Simulation Data

On this page…

Importing and Exporting Capabilities

Importing Data from a Workspace

Exporting Data to the MATLAB® Workspace

Importing and Exporting States

Limiting Output

Specifying Output Options

Importing and Exporting Capabilities

During simulation you can import input signal and initial state data from a workspace, and export output signal and state data to a workspace. This capability allows you to use standard or custom MATLAB® functions to generate a simulated system's input signals and to graph, analyze, or otherwise postprocess the system's outputs.

Back to Top

Importing Data from a Workspace

The Simulink® software can input data from a workspace and apply it to the model's top-level input ports during a simulation run. To specify this option:

  1. Select the Input box in the Load from workspace area of the Data Import/Export Pane pane.

  2. Enter an external input specification in the adjacent edit box and click Apply.

The Simulink software resolves symbols used in the external input specification as described in Resolving Symbols. See the documentation of the sim command for some data import capabilities that are available only for programmatic simulation.

The input data can take any of the following forms:

The Simulink software linearly interpolates or extrapolates input values as necessary if the Interpolate data option is selected for the corresponding Inport.

Importing Time-Series Data

Any root-level Inport block can import data specified by a time-series object (see Simulink.Timeseries) residing in a workspace. In addition, any root-level input port defined by a bus object (see Simulink.Bus) can import data from a time-series array object (see Simulink.TSArray) that has the same structure as the bus object. Time-series objects are a derivation of standard MATLAB time-series objects and, therefore, can be manipulated using the MATLAB Time Series Tools. See "Using Time Series Tools" in the MATLAB Data Analysis documentation for further details.

Importing time-series objects allows you to import data logged by a previous simulation run (see Logging Signals). For example, suppose that you have a model that references several other models. You could use data logged from the inputs of the referenced models when simulating the top model as inputs for the referenced models simulated by themselves. This allows you to test the referenced models independently of the top model and each other.

To import data from time-series objects and time-series array objects, enter a comma-separated list of variables or expressions into the Input edit field on the Data Import/Export pane of the Configuration Parameters dialog box (see Configuration Parameters Dialog Box). Each variable or expression in the Input list should evaluate to the appropriate time-series object or time-series array object that corresponds to one of the model's root-level input ports, with the first item corresponding to the first root-level input port, the second to the second root-level input port, and so on. The model sldemo_mdlref_counter_bus, referenced by the top model sldemo_mdlref_bus, contains an example of importing time-series objects.

To use this demo, open sldemo_mdlref_bus and run the simulation. The top model is configured to store logged signals into a variable named topOut. Currently, two signals are being logged: COUNTERBUS and OUTPUTBUS. After running the simulation, you can view the logged signals by typing topOut at the MATLAB prompt.

topOut =
 
Simulink.ModelDataLogs (sldemo_mdlref_bus):
  Name                   Elements  Simulink Class

  COUNTERBUS                2      TsArray
  OUTPUTBUS                 2      TsArray

The variable topOut is a Simulink.ModelDataLogs object that contains, in this case, two Simulink.TsArray objects corresponding to the two logged bus signals. The Simulink.TsArray object COUNTERBUS can be used as the input to the submodel sldemo_mdlref_counter_bus to run this model independently of the top model. This is accomplished by entering topOut.COUNTERBUS into the Input edit field on the Data Import/Export pane of the Configuration Parameters dialog box, as shown below.

By using the time-series array object as the input to sldemo_mdlref_counter_bus, independently running this model produces the same output as when run within the top model sldemo_mdlref_bus.

Importing Data Arrays

This import format consists of a real (noncomplex) matrix of data type double. The first column of the matrix must be a vector of times in ascending order. The remaining columns specify input values. In particular, each column represents the input for a different Inport block signal (in sequential order) and each row is the input value for the corresponding time point.

The total number of columns of the input matrix must equal n + 1, where n is the total number of signals entering the model's input ports.

The default input expression for a model is [t,u] and the default input format is Array. So if you define t and u in the MATLAB workspace, you need only select the Input option to input data from the model workspace. For example, suppose that a model has two input ports, In1 that accepts two signals, and In2 that accepts one signal. Also, suppose that the MATLAB workspace defines t and u as follows:

t = (0:0.1:1)';
u = [sin(t), cos(t), 4*cos(t)];

In1 accepts the signals sin(t) and cos(t), and In2 accepts the signal 4*cos(t).

Using a MATLAB® Time Expression to Import Data

You can use a MATLAB time expression to import data from a workspace. To use a time expression, enter the expression as a string (i.e., enclosed in single quotes) in the Input field of the Data Import/Export pane. The time expression can be any MATLAB expression that evaluates to a row vector equal in length to the number of signals entering the model's input ports. For example, suppose that a model has one vector Inport that accepts two signals. Furthermore, suppose that timefcn is a user-defined function that returns a row vector two elements long. The following are valid input time expressions for such a model:

'[3*sin(t), cos(2*t)]' 

'4*timefcn(w*t)+7'

The expression is evaluated at each step of the simulation, applying the resulting values to the model's input ports. Note that the Simulink software defines the variable t when it runs the simulation. Also, you can omit the time variable in expressions for functions of one variable. For example, the expression sin is interpreted as sin(t).

Importing Data Structures

The Simulink software can read data from the workspace in the form of a structure whose name is specified in the Input text field. You can import structures that include only signal data or both signal and time data. The type of data structure is evaluated based on the structure itself.

Importing Signal-and-Time Data Structures.   To import structures that include both signal and time data, the input structure must have two top-level fields: time and signals. The time field contains a column vector of the simulation times. The signals field contains an array of substructures, each of which corresponds to a model input port.

Each signals substructure must contain two fields named values and dimensions, respectively. The values field must contain an array of inputs for the corresponding input port where each input corresponds to a time point specified by the time field. The dimensions field specifies the dimensions of the input. If each input is a scalar or vector (1-D array) value, the dimensions field must be a scalar value that specifies the length of the vector (1 for a scalar). If each input is a matrix (2-D array), the dimensions field must be a two-element vector whose first element specifies the number of rows in the matrix and whose second element specifies the number of columns.

If the inputs for a port are scalar or vector values, the values field must be an M-by-N array where M is the number of time points specified by the time field and N is the length of each vector value. For example, the following code creates an input structure for loading 11 time samples of a two-element signal vector of type int8 into a model with a single input port:

a.time = (0:0.1:1)';
c1 = int8([0:1:10]');
c2 = int8([0:10:100]');
a.signals(1).values = [c1 c2];
a.signals(1).dimensions = 2;

To load this data into the model's input port, you would select the Input option on the Data Import/Export pane and enter a in the input expression field.

If the inputs for a port are matrices (2-D arrays), the values field must be an M-by-N-by-T array where M and N are the dimensions of each matrix input and T is the number of time points. For example, suppose that you want to input 51 time samples of a 4-by-5 matrix signal into one of your model's input ports. Then, the corresponding dimensions field of the workspace structure must equal [4 5] and the values array must have the dimensions 4-by-5-by-51.

As another example, consider the following model, which has two inputs.

Suppose that you want to input a sine wave into the first port and a cosine wave into the second port. To do this, define a vector, a, as follows, in the MATLAB workspace:

a.time = (0:0.1:1)';
a.signals(1).values = sin(a.time);
a.signals(1).dimensions = 1;
a.signals(2).values = cos(a.time);
a.signals(2).dimensions = 1;

Select the Input box for this model, and enter a in the adjacent text field.

Importing Signal-Only Structures.   The Structure format is the same as the Structure with time format except that the time field is empty. For example, in the preceding example, you could set the time field as follows:

a.time = []

In this case, the input for the first time step is read from the first element of an input port's value array, the value for the second time step from the second element of the value array, etc. If you enter the structure without time, the Inport block must have a discrete sample time.

Per-Port Structures.   This format consists of a separate structure-with-time or structure-without-time for each port. Each port's input data structure has only one signals field. To specify this option, enter the names of the structures in the Input text field as a comma-separated list, in1, in2,..., inN, where in1 is the data for your model's first port, in2 for the second input port, and so on.

Specifying Time Vectors for Discrete Systems

In some cases, the Simulink software calculates block sample hits at sample times different from those specified by a time vector generated in MATLAB. Typically, these are small floating point inaccuracies that can cause the Simulink product to apparently miss a specified time step in lieu of a different sample point. In order to avoid these numerical inaccuracies, generate the time vector either in MATLAB or in Simulink based on the fundamental sample time of the model.

For example, if the model has a fundamental sample time Ts (see "Determining Step Size for Discrete Systems") of 0.001 then the time vector Tvector should be calculated with the command

Tvector = Ts*[n1, n2, n3...];

where n1, n2, n3, etc. are integers that, when multiplied by the fundamental sample time, yield the desired time vector.

Back to Top

Exporting Data to the MATLAB® Workspace

You can export a model's states and root-level outputs to the MATLAB workspace during simulation of the model. To do this, select the type of data that you want to export on the Save to workspace area of the Data Import/Export Pane pane of the Configuration Parameters dialog box. The field adjacent to each type specifies the name of a MATLAB workspace variable to be used by the Simulink software to store the exported data.

Each field initially specifies a default variable. You can edit the fields to specify names of your own choosing.

Select Signal logging to enable signal logging for the model. See Logging Signals for more information. See the documentation of the sim command for some data export capabilities that are available only for programmatic simulation.

The Save options area enables you to specify the format and restrict the amount of output saved.

See the documentation of the sim command for some capabilities that are available only for programmatic simulation. Format options for model states and outputs are listed below.

Format Options

Array.   If you select this option, a model's states and outputs are saved in a state and output array, respectively.

The state matrix has the name specified in the Save to workspace area (for example, xout). Each row of the state matrix corresponds to a time sample of the model's states. Each column corresponds to an element of a state. For example, suppose that your model has two continuous states, each of which is a two-element vector. Then the first two elements of each row of the state matrix contains a time sample of the first state vector. The last two elements of each row contain a time sample of the second state vector.

The model output matrix has the name specified in the Save to workspace area (for example, yout). Each column corresponds to a model output port, each row to the outputs at a specific time.

Structure with time.   If you select this format, the model's states and outputs are saved in structures having the names specified in the Save to workspace area (for example, xout and yout).

The structure used to save outputs has two top-level fields:

Each substructure has four fields:

The following is an example of the structure-with-time format for a nonreferenced model.

>> xout.signals(1)

ans = 

               values: [296206x1 double]
           dimensions: 1
                label: 'CSTATE'
            blockName: 'vdp/x1'
    inReferencedModel: 0

The structure used to save states has a similar organization. The states structure has two top-level fields:

Each signals structure has four fields: values, dimensions, label, and blockName. The values field contains time samples of a state of the block specified by the blockName field. The label field for built-in blocks indicates the type of state: either CSTATE (continuous state) or DSTATE (discrete state). For S-Function blocks, the label contains whatever name is assigned to the state by the S-Function block.

The time samples of a state are stored in the values field as a matrix of values. Each row corresponds to a time sample. Each element of a row corresponds to an element of the state. If the state is a matrix, the matrix is stored in the values array in column-major order. For example, suppose that the model includes a 2-by-2 matrix state and that 51 samples of the state are logged during a simulation run. The values field for this state would contain a 51-by-4 matrix where each row corresponds to a time sample of the state and where the first two elements of each row correspond to the first column of the sample and the last two elements correspond to the second column of the sample.

Structure.   This format is the same as the preceding except that the Simulink software does not store simulation times in the time field of the saved structure.

Per-Port Structures.   This format consists of a separate structure-with-time or structure-without-time for each output port. Each output data structure has only one signals field. To specify this option, enter the names of the structures in the Output text field as a comma-separated list, out1, out2,..., outN, where out1 is the data for your model's first port, out2 for the second input port, and so on.

Back to Top

Importing and Exporting States

You can import the initial values of a system's states, i.e., its initial conditions, at the beginning of a simulation and save the final values of the states at the end of the simulation. This feature allows you to save a steady-state solution and restart the simulation at that known state.

Saving Final States

To save the final values of a model's states, check Final states in the Save to workspace area of the Data Import/Export pane and enter a name in the adjacent edit field. The states are saved in a workspace variable having the specified name. The saved data has the format that you specify in the Save options area of the Data Import/Export pane.

When saving states from a referenced model in the structure-with-time format, a boolean subfield is added named inReferencedModel to the signals field of the saved data structure. This field's value is true (1) if the signals field records the final state of a block that resides in the submodel, and a 0 otherwise. For example,

>> xout.signals(1)

ans = 

               values: [101x1 double]
           dimensions: 1
                label: 'DSTATE'
            blockName: [1x66 char]
    inReferencedModel: 1

If the signals field records a submodel state, its blockName subfield contains a compound path comprising a top model path and a submodel path. The top model path is the path from the model root to the Model block that references the submodel. The submodel path is the path from the submodel root to the block whose state the signals field records. The compound path uses a | character to separate the top and submodel paths, e.g.,

>> xout.signals(1).blockName

ans =

sldemo_mdlref_basic/CounterA|sldemo_mdlref_counter/Previous Output

Loading Initial States

To load states, check Initial state in the Load from workspace area of the Data Import/Export pane and specify the name of a variable that contains the initial state values, for example, a variable containing states saved from a previous simulation. The initial values specified by the workspace variable override the initial values specified by the model itself, i.e., the values specified by the initial condition parameters of those blocks in the model that have states.

Use the structure or structure-with-time option to specify initial states if you want to accomplish any of the following.

For example, the following commands create an initial state structure that can be used to initialize the x2 state of the vdp model. The x1 state is not initialized in the structure and, therefore, the value entered into the state's associated Integrator block is used during the simulation.

% Open the vdp demo model
vdp

% Use getInitialState to obtain an initial state structure
states = Simulink.BlockDiagram.getInitialState('vdp');

% Set the initial value of the signals structure element 
% associated with x2 to 2.
states.signals(2).values = 2; 

% Remove the signals structure element associated with x1
states.signals(1) = [];

To use this states variable, open the Configuration Parameters dialog box for the vdp model. Check Initial state in the Load from workspace area of the Data Import/Export pane and type states into the associated edit field. When you run the model, note that both states have the initial value of 2. The initial value of the x2 state is assigned in the states structure, while the initial value of the x1 state is assigned in its Integrator block.

Back to Top

Limiting Output

Saving data to a workspace can slow down the simulation and consume memory. To avoid this, you can limit the number of samples saved to the most recent samples or you can skip samples by applying a decimation factor. To set a limit on the number of data samples saved, select the check box labeled Limit data points to last and specify the number of samples to save. To apply a decimation factor, enter a value in the field to the right of the Decimation label. For example, a value of 2 saves every other point generated.

Back to Top

Specifying Output Options

The Output options list on the Data Import/Export configuration pane (Data Import/Export Pane) enables you to control how much output the simulation generates. You can choose from three options:

Refining Output

The Refine output choice provides additional output points when the simulation output is too coarse. This parameter provides an integer number of output points between time steps; for example, a refine factor of 2 provides output midway between the time steps as well as at the steps. The default refine factor is 1.

To get smoother output, it is much faster to change the refine factor instead of reducing the step size. When the refine factor is changed, the solvers generate additional points by evaluating a continuous extension formula at those points. This option changes the simulation step size so that time steps coincide with the times that you have specified for additional output.

The refine factor applies to variable-step solvers and is most useful when you are using ode45. The ode45 solver is capable of taking large steps; when graphing simulation output, you might find that output from this solver is not sufficiently smooth. If this is the case, run the simulation again with a larger refine factor. A value of 4 should provide much smoother results.

Producing Additional Output

The Produce additional output choice enables you to specify directly those additional times at which the solver generates output. When you select this option, an Output times field is displayed on the Data Import/Export pane. Enter a MATLAB expression in this field that evaluates to an additional time or a vector of additional times. This option causes the solver to produce hit times at the output times you have specified, in addition to the times it needs to accurately simulate the model.

Producing Specified Output Only

The Produce specified output only choice provides simulation output only at the simulation start time, simulation stop time, and the specified output times. For example, if the simulation start time is set to 0 and the simulation stop time is set to 60, entering [10: 10: 50] in the Output times field results in simulation output at these times:

0, 10, 20, 30, 40, 50, 60

This option changes the simulation step size so that time steps coincide with the times that you have specified for producing output. The solver may hit other time steps to accurately simulate the model, however the output will not include these points. This choice is useful when you are comparing different simulations to ensure that the simulations produce output at the same times.

Comparing Output Options

A sample simulation generates output at these times:

0, 2.5, 5, 8.5, 10

Choosing Refine output and specifying a refine factor of 2 generates output at these times:

0, 1.25, 2.5, 3.75, 5, 6.75, 8.5, 9.25, 10

Choosing the Produce additional output option and specifying [0:10] generates output at these times

0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

and perhaps at additional times, depending on the step size chosen by the variable-step solver.

Choosing the Produce specified output only option and specifying [0:10] generates output at these times:

0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

Back to Top

  

Choosing a SolverChoosing a Solver Configuration SetsConfiguration Sets

 © 1984-2008- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS