Log Data to Persistent Storage - MATLAB & Simulink (original) (raw)

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 () 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 > + 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 isDataset.
- 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 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 istimeseries. The timetable format is helpful for MATLAB combining logged data from multiple simulations. For details about thetimetable 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 orset_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 theSaveFormat parameter to 'Dataset'.

To log final states data to persistent storage, set theSaveOperatingPoint 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 variablelogsout, the Dataset object in the MAT file islogsout.

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 aSimulink.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 > 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, seeLoad 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](../slref/simulink.simulationdata.datasetref.html) 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.