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
States — Defaults to
Datasetformat. You can use other formats.
Final states — Requires that you clear the Save final operating point parameter
Output — Defaults to
Data stores — Uses
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
Datasetformat 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.
Datasetformat for logging the data. Data that is logged in any other format is stored in the workspace.
Signal logging and data store logging use
Datasetformat only. The default format for output, states, and final states logging is
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
timetableelements, set the Dataset signal format configuration parameter. The default format is
timetableformat is helpful for MATLAB combining logged data from multiple simulations. For details about the
timetableformat, 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
name-value pairs with either the
sim command or
To enable the logging approaches that you want to use, set these parameters to
'on', as applicable:
To log output, states, and final states data to persistent storage, set the
SaveFormat parameter to
To log final states data to persistent storage, set the
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
elements are stored as either
objects, depending on how you set the Dataset signal format parameter.
For details about the
timetable format, see Dataset signal format.
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
Dataset object in the MAT-file is
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:
To match the new file name, change the
Locationproperty of the
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
objects to access output data in the MAT-file and includes those objects in the
CaptureErrorsargument for simulation
For more information about parallel simulations, see Running Multiple Simulations.
timetable| Dataset signal format |