Main Content

To Workspace

Log data to workspace from Simulink model

expand all in page
  • To Workspace block

Libraries:
Simulink / Sinks
DSP System Toolbox / Sinks
HDL Coder / Sinks

Description

The To Workspace block logs the data connected to its input port to a workspace from a Simulink® model. Typically, logged data is returned in the base workspace. When you simulate a model programmatically inside a function, logged data is returned in the workspace for the function. During simulation, logged data streams to the Simulation Data Inspector. Logged data is written to the workspace when the simulation pauses or stops.

You can use the To Workspace block to log data for a signal, a bus, or an array of buses. The To Workspace block supports logging scalar and multidimensional data, including data for variable-size signals.

You can configure the name of the variable that stores the data the To Workspace block logs, and you can specify the format for the logged data. You can also control which values the To Workspace block logs by specifying block or model parameters. For more information, see Specify Signal Values to Log.

Access Logged Data

How simulation results are returned to the workspace depends on how you simulate and configure the model. Simulation results are returned in a single Simulink.SimulationOutput object in any of these situations:

  • You enable the Single simulation output parameter.

    By default, the Single simulation output parameter is enabled when you create a new model. You can enable the parameter using the Configuration Parameters dialog box. On the Modeling tab, under Settings, click Model Settings. Then, in the Configuration Parameters dialog box, select Data Import/Export and select Single simulation output.

  • You run a set of simulations using the Multiple Simulations pane.

  • You simulate the model programmatically using one or more Simulink.SimulationInput objects.

    You can configure simulations using SimulationInput objects when you run simulations using the sim, parsim, and batchsim functions.

  • You simulate the model using a sim function syntax that returns results as a single simulation output.

    For more information, see sim.

When simulation results are returned in a single output, the SimulationOutput object contains a variable for each To Workspace block in the model. To access the data logged by a To Workspace block:

  • Use a dot with the variable name specified using the Variable name parameter of the block. By default, models are configured to return a single simulation output using the variable name out, and the To Workspace block saves data to a variable named simout.

    toWksData = out.simout;

  • Use the get function with the name of the variable that contains the logged data.

    toWksData = get(out,simout);

In the model, the To Workspace block indicates how to access the data in the workspace. By default, the block shows out.simout. The block appearance updates when you:

  • Specify a different value for the Variable name parameter on the block.

  • Specify a different variable name for the single simulation output.

  • Clear the Single simulation output configuration parameter.

Examples

expand all

Open Live Script

The To Workspace block logs simulation data to the workspace.

For example, simulate the SineToWorkspace model.

The SineToWorkspace model

mdl = "SineToWorkspace";
out = sim(mdl);

Simulation results from the model are returned in a single Simulink.SimulationOutput object named out. To access results saved by the To Workspace block, use dot notation.

toWksData = out.simout
  timeseries

  Common Properties:
            Name: 'Sine Wave'
            Time: [51x1 double]
        TimeInfo: tsdata.timemetadata
            Data: [51x1 double]
        DataInfo: tsdata.datametadata

Extended Examples

Output Simulation Data with Blocks

Output Simulation Data with Blocks

How To Workspace and To File blocks write data to the workspace and to a file respectively.

Open Script
Variable-Size Signal Basic Operations

Variable-Size Signal Basic Operations

How variable-size signals can be generated and illustrates some of the operations you can apply to the signals. The purpose of this example is to introduce the basic operations associated with variable-size signals.

Open Model

Ports

Input

expand all

Input port that receives data to log to workspace. The To Workspace block supports logging real and complex data of any built-in data type or user-defined data types such as buses, enumerations, and fixed-point data.

Tips

Logging fixed-point data requires a license for Fixed-Point Designer™.

Data Types: single | double | half | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | Boolean | string | fixed point | enumerated | bus | image
Complex Number Support: Yes

Parameters

expand all

Specify a name for the variable that contains the logged data. By default, the To Workspace block saves logged data in a variable called simout. When a model contains multiple To Workspace blocks, the Variable name parameter value for each block must be unique.

For information about naming MATLAB® variables, see Variable Names.

Programmatic Use

Block Parameter: VariableName
Type: string | character vector
Value: Valid MATLAB variable name
Default: 'simout'

When you want to save or analyze only the data from the end of a simulation, specify the number of samples you want to log as a positive whole number greater than zero. By default, the To Workspace block logs data for the entire simulation, and the value for the Limit data points to last parameter is inf.

For more information about controlling which samples are logged during simulation, see Specify Signal Values to Log.

Programmatic Use

Block Parameter: MaxDataPoints
Type: string | character vector
Values: 'inf' | positive integer greater than zero
Default: 'inf'

Specify a decimation factor to reduce the effective sample rate for the logged data. For a decimation factor, n, the To Workspace block logs every nth sample value. For example, when you specify the Decimation value as 2, the To Workspace block logs every other data point.

For more information about controlling which samples are logged during simulation, see Specify Signal Values to Log.

Programmatic Use

Block Parameter: Decimation
Type: string | character vector
Values: scalar
Default: '1'

Specify the format for the data logged to the workspace. To log data for a bus or array of buses input, use Timeseries format.

Save Format ValueWorkspace Data FormatSimulation Workflow Support
Timeseries

Nonbus input logged as a timeseries object.

Bus input logged as a structure of timeseries objects. The hierarchy and names for fields in the structure matches the hierarchy and names specified in the Simulink.Bus object that defines the bus.

Array of buses input logged as an array of structures of timeseries objects.

Supported:

  • Normal mode simulation

  • Accelerator mode simulation

  • Rapid accelerator mode simulation (since R2022a)

  • External mode simulation that uses XCP communication provided StreamToWks is set to 'on' and MATFileLogging is set to 'off'

Not supported:

  • External mode simulation that uses TCP/IP or serial communication

  • Software-in-the-loop (SIL) simulation

  • Processor-in-the-loop (PIL) simulation

  • Code generation for Simulink Coder™ targets

Structure With Time

Nonbus input logged as a structure that contains these fields:

  • time — Column vector of simulation time hits for which input value was logged.

  • signals — Structure with sample values that contains the fields:

    • values — Array of sample values.

    • dimensions — Sample dimensions.

    • label — Name of signal line in model.

  • blockName — Name of the To Workspace block.

Always supported:

  • Normal mode simulation.

  • External mode simulation that uses XCP communication provided StreamToWks is set to 'on' and MATFileLogging is set to 'off'

Supported except when the To Workspace block is in a referenced model:

  • Accelerator mode simulation

  • Rapid accelerator mode simulation

  • External mode simulation that uses TCP/IP or serial communication

Supported if MAT-file logging (Simulink Coder) is enabled for generated code, except when the To Workspace block is in a referenced model:

  • Software-in-the-loop (SIL) simulation

  • Processor-in-the-loop (PIL) simulation

  • Code generation for Simulink Coder targets

Structure

Nonbus input logged as a structure that matches the Structure With Time format, but the time field of the structure is empty.

Array

Sample values for nonbus input saved as N-dimensional array, where N is one greater than the dimensions of the input. For example:

  • Scalar signal data is logged as a column vector.

  • Vector signal data is logged as a matrix.

  • Matrix signal data is logged as a 3-D array.

The structure of the values in the array depends on the dimensions of the input signal data:

  • For scalar and vector signals, each sample value is a row in the output array. The first dimension of the array aligns with time such that simout(1,:) returns the first logged signal value.

  • For matrix signals, the third dimension of the output array aligns with time such that simout(:,:,1) returns the first logged signal value.

  • For N-dimensional signals, the last dimension aligns with time, such that the number of elements in the last dimension is equal to the number of samples logged from simulation.

The output array contains only signal values and does not contain time data.

Tips

  • To log data as frame-based instead of sample-based:

    • Configure the Save format parameter to log data using the Structure format or the Array format.

    • Specify the Save 2-D signals as parameter as 2-D array (concatenate along first dimension)

  • When you want to load the logged data using a From Workspace block, consider using the Timeseries or Structure With Time formats. When you log data using the Array format, you need to incorporate the sample time values into the array before loading the data.

Programmatic Use

Block Parameter: SaveFormat
Type: string | character vector
Values: 'Timeseries' | 'Structure with Time' | 'Structure' | 'Array'
Default: 'Timeseries'

Specify whether to log 2-D input data as a 3-D array or a 2-D array.

Logging as a 3-D array is well suited for sample-based input data. Samples are concatenated along the third dimension, allowing easy access of 2-dimensional sample data.

Logging as a 2-D array is well suited for frame-based input data. Samples are concatenated along the first dimension, which in effect removes the frame buffering from the first dimension.

Input Data DimensionsSave 2-D Signal As...Workspace Data Dimensions
M-by-N2-D array (concatenate along first dimension)

K-by-N matrix, where K is equal to M times the number of samples logged from simulation.

For example, logging ten samples of a 2-by-4 matrix input creates a 20-by-4 matrix.

3-D array (concatenate along first dimension)

M-by-N-by-K array, where K is equal to the number of samples logged from simulation.

For example, logging ten samples of a 2-by-4 matrix input creates a 2-by-4-by-10 array.

Dependencies

To enable this parameter, set the Save format to Array or Structure.

Programmatic Use

Block Parameter: Save2DSignal
Type: string | character vector
Values: '2-D array (concatenate along first dimension)' | '3-D array (concatenate along third dimension)'
Default: '3-D array (concatenate along third dimension)'

Specify how to log fixed-point input data. By default, the To Workspace block logs fixed-point data as a fi (Fixed-Point Designer) object. When you clear this parameter, the To Workspace block logs fixed-point input data as double.

The To Workspace block always logs fixed-point data as a fi object when you:

  • Simulate the model in rapid accelerator mode.

  • Specify the Save format parameter as Timeseries.

Using the To Workspace block to log fixed-point data requires a license for Fixed-Point Designer.

Programmatic Use

Block Parameter: FixptAsFi
Type: string | character vector
Values: 'off' | 'on'
Default: 'off'

Specify when the block logs the input value during simulation. By default, the sample time is inherited (-1). For continuous sample time, specify the value as 0. To use a discrete sample time, specify the Sample time parameter as a scalar. For more information, see Specify Sample Time.

Programmatic Use

Block Parameter: SampleTime
Type: string | character vector
Values: scalar
Default: '-1'

Block Characteristics

Data Types

Boolean | bus | double | enumerated | fixed point | half | integer | single | string

Direct Feedthrough

no

Multidimensional Signals

yes

Variable-Size Signals

yes

Zero-Crossing Detection

no

Tips

  • You can convert data logged using the To Workspace block to Dataset format. Converting the data can make post-processing easier if you use other logging techniques, such as signal logging, that use the Dataset format. For more information, see Convert timeseries object to Dataset object.

  • When you call a function that simulates a model, data logged in simulation is returned to the function workspace. To return data logged from a simulation in a function to the base workspace, use the assignin function. For example, this function called myfunc simulates the model myModel, which includes a To Workspace block that logs data to the variable simout and sends the data logged by the To Workspace block to the base workspace.

    function myfunc
    out = sim("myModel");
    toWksData = get(out,"simout");
    assignin("base","toWksData",toWksData);
end

Extended Capabilities

PLC Code Generation
Generate Structured Text code using Simulink® PLC Coder™.

Fixed-Point Conversion
Design and simulate fixed-point systems using Fixed-Point Designer™.

Version History

Introduced before R2006a

expand all

See Also

| | |

Topics