Log Data to Persistent Storage

When to Log to Persistent Storage

In some cases, logging simulation data can create large amounts of data that are too large for your computer to hold in working memory while also running efficiently. Such situations can include simulations that log many signals, simulations that run for a long time with many time steps, and parallel simulations. When your simulation configuration creates a large amount of data, you can log that data to persistent storage, rather than logging it to working memory.

You can store logged simulation data to persistent storage in a MAT-file. You control logging to persistent storage at the model level. You can enable and disable the feature by changing one model configuration parameter (Log Dataset data to file) without changing the model layout.

If you use Dataset format for logging, you can log each of these kinds of data to persistent storage:

Signal logging — Uses Dataset format only.
States — Defaults to Dataset format. You can use other formats.
Final states — Requires that you clear the Save final operating point parameter
Output — Defaults to Dataset format.
Data stores — Uses Dataset format only.

By default, logging to persistent storage is disabled, so that logged data is stored in the MATLAB^® workspace. For most models, logging to the workspace is simpler because it avoids loading and saving logging files. Compared to accessing data logged to memory, accessing data logged to persistent storage requires some additional steps. For short simulations, logging to the MATLAB workspace can be faster and possibly use less memory than logging to persistent storage.

Limitations for Logging to Persistent Storage

Only data logged in Dataset format is stored in the MAT-file. Data logged in other formats is stored in the MATLAB workspace.
To use persistent storage for logging final states data, you cannot enable the Configuration Parameters > Data Import/Export + Save final operating point.
The Simulation Stepper and fast restart do not support logging to persistent storage.
During simulation, you cannot load data from the persistent storage file directly into the model. Create objects that reference the data in the file and then load the referencing object.

Alternative Approaches for Reducing Logging Memory Usage

When you need to simulate a model that creates a large amount of data and you do not want to log the simulation data to persistent storage, consider using one of these alternatives.

Limit the amount of simulation data stored in the workspace.

You can limit the amount of simulation data stored in the workspace by using one or more of these techniques. For details, see Specify Signal Values to Log.

Technique	Description
Specify a decimation factor	Skip samples when exporting data.
Limit data points	Limit the number of samples saved to be only the most recent samples.
Specify intervals for logging	Specify ranges of time steps for logging.

If you limit the amount of simulation data stored in the workspace, the logged data may not contain some time steps that are critical for testing and analyzing the model.

Use a To File block for each signal that you want to log.
Connecting a To File block to signals that you want to log stores the logged data in a MAT-file, rather than in the MATLAB workspace. However, this approach:
- Is a per-signal approach that can clutter a model with multiple To File blocks attached to individual signals.
- Creates a separate MAT-file for each To File block, instead of the single file created when you log to persistent storage.

Log to Persistent Storage

Specify the kinds of logging to perform (for example, signal logging and output logging) and the variable names for the logging data.
In the model diagram, mark selected signals for signal logging.
Use Dataset format for logging the data. Data that is logged in any other format is stored in the workspace.
- Signal logging and data store logging use Dataset format only. The default format for output, states, and final states logging is Dataset.
- For final states logging, clear the Save final operating point configuration parameter.
Enable logging to persistent storage and specify an output MAT-file name.
- Select the Log Dataset data to file configuration parameter.
- Specify the MAT-file to use. Do not use a file name from one locale in a different locale.
To save the logged Dataset data using timeseries or timetable elements, set the Dataset signal format configuration parameter. The default format is timeseries. The timetable format is helpful for MATLAB combining logged data from multiple simulations. For details about the timetable format, see Dataset signal format.
Simulate the model.

Enable Logging to Persistent Storage Programmatically

You can programmatically log to persistent storage. To enable logging to persistent storage, use the LoggingToFile and LoggingFileName name-value pairs with either the sim command or set_param command.

To enable the logging approaches that you want to use, set these parameters to 'on', as applicable:

SignalLogging
SaveState
SaveFinalState
SaveOutput
DSMLogging

To log output, states, and final states data to persistent storage, set the SaveFormat parameter to 'Dataset'.

To log final states data to persistent storage, set the SaveOperatingPoint to 'off'.

How Simulation Data Is Stored

Logging to persistent storage saves logged simulation data in the specified MAT-file. The data is stored as a Simulink.SimulationData.Dataset objects for each type of logging that uses Dataset format. The Dataset elements are stored as either timeseries or timetable objects, depending on how you set the Dataset signal format parameter. For details about the timetable format, see Dataset signal format.

The Dataset object name in the file is the name of the variable that you used for logging. For example, if you use the default signal logging variable logsout, the Dataset object in the MAT-file is logsout.

Save Logged Data from Successive Simulations

The approach you use for saving data logged from successive simulations depends on whether you are performing parallel simulations.

Without Using Parallel Simulations

Each time you simulate a model without using parallel simulation, Simulink^® overwrites the contents of the MAT-file unless you change the name of the file between simulations. When you use a Simulink.SimulationData.DatasetRef object that references data in the MAT-file to retrieve data in the file, it retrieves the most recent version of the data. To preserve data from an earlier simulation, use one of these approaches:

Between simulations, use the Configuration Parameters > Data Import/Export pane to specify a different name for the MAT-file for logging.
Between simulations, save a copy of the MAT-file. Use a different file name than the name that you specify as the MAT-file for persistent storage, or move the MAT-file.
Programmatically specify a new file name for each simulation run.

If you run multiple simulations that overlap in time, use a unique MAT-file for each model that you log to persistent storage.

If you change the file name used for logging to persistent storage, then to access the logged data, use one of these approaches:

Create a Simulink.SimulationData.DatasetRef object.
To match the new file name, change the Location property of the DatasetRef objects.

For details about using DatasetRef objects to access logged data, see Load Big Data for Simulations.

With Parallel Simulations

For parallel simulations, for which you specify an array of input objects, if you log to file, Simulink:

Creates a MAT-file for each simulation
Creates Simulink.SimulationData.DatasetRef objects to access output data in the MAT-file and includes those objects in the SimulationOutput object data
Enables the CaptureErrors argument for simulation

For more information about parallel simulations, see Running Multiple Simulations.