generateSimulationEnsemble

Generate ensemble data by running a Simulink model

collapse all in page

Syntax

[status,E] = generateSimulationEnsemble(simin)
[status,E] = generateSimulationEnsemble(simin,location)
[status,E] = generateSimulationEnsemble(simin,location,Name,Value)

Description

[status,E] = generateSimulationEnsemble(simin) generates data for a simulation ensemble by running the Simulink® model specified by simin. This input argument is a vector of Simulink.SimulationInput objects that also specifies other parameters to change from simulation to simulation to generate the ensemble. The function writes the simulation data log files to the current folder. Each file contains the corresponding Simulink.SimulationInput object and all the variables that the model is configured to log for the simulation. The output arguments indicate whether any simulations generate errors and return any such errors. Use simulationEnsembleDatastore to create an ensemble datastore for interacting with the simulated data.

For general information about data ensembles, see Data Ensembles for Condition Monitoring and Predictive Maintenance.

[status,E] = generateSimulationEnsemble(simin,location) also specifies a path to a location at which to store the simulation results.

example

[status,E] = generateSimulationEnsemble(simin,location,Name,Value) uses additional options specified by one or more Name,Value pair arguments.

Examples

collapse all

This example uses:

Open Live Script

Generate a simulation ensemble datastore of data representing a machine operating under fault conditions by simulating a Simulink® model of the machine while varying a fault parameter.

Load the Simulink model. This model is a simplified version of the gear-box model described in Using Simulink to Generate Fault Data. For this example, only one fault mode is modeled, a gear-tooth fault. 

mdl = 'TransmissionCasingSimplified';
open_system(mdl)

The gear-tooth fault is modeled as a disturbance in the Gear Tooth fault subsystem. The magnitude of the disturbance is controlled by the model variable ToothFaultGain, where ToothFaultGain = 0 corresponds to no gear-tooth fault (healthy operation). To generate the ensemble of fault data, you use generateSimulationEnsemble to simulate the model at different values of ToothFaultGain, ranging from -2 to zero. This function uses an array of Simulink.SimulationInput objects to configure the Simulink model for each member in the ensemble. Each simulation generates a separate member of the ensemble in its own data file. Create such an array, and use setVariable to assign a tooth-fault gain value for each run.

toothFaultValues  = -2:0.5:0; % 5 ToothFaultGain values 

for ct = numel(toothFaultValues):-1:1
    simin(ct) = Simulink.SimulationInput(mdl);
    simin(ct) = setVariable(simin(ct),'ToothFaultGain',toothFaultValues(ct));
end

For this example, the model is already configured to log certain signal values, Vibration and Tacho (see Save Signal Data Using Signal Logging (Simulink)). generateSimulationEnsemble further configures the model to:

  • Save logged data to files in the folder you specify.

  • Use the timetable format for signal logging.

  • Store each Simulink.SimulationInput object in the saved file with the corresponding logged data.

Specify a location for the generated data. For this example, save the data to a folder called Data within your current folder. The indicator status is 1 (true) if all the simulations complete without error. 

mkdir Data
location = fullfile(pwd,'Data');
[status,E] = generateSimulationEnsemble(simin,location);
[09-Aug-2025 10:18:37] Running simulations...
[09-Aug-2025 10:18:41] Completed 1 of 5 simulation runs
[09-Aug-2025 10:18:43] Completed 2 of 5 simulation runs
[09-Aug-2025 10:18:45] Completed 3 of 5 simulation runs
[09-Aug-2025 10:18:47] Completed 4 of 5 simulation runs
[09-Aug-2025 10:18:49] Completed 5 of 5 simulation runs

Inside the Data folder, examine one of the files. Each file is a MAT file containing the following MATLAB® variables:

  • SimulationInput — The Simulink.SimulationInput object that was used to configure the model for generating the data in the file. You can use this to extract information about the conditions (such as faulty or healthy) under which this simulation was run.

  • logsout — A Dataset object containing all the data that the Simulink model is configured to log.

  • PMSignalLogName — The name of the variable that contains the logged data ('logsout' in this example). The simulationEnsembleDatastore command uses this name to parse the data in the file.

  • SimulationMetadata — Other information about the simulation that generated the data logged in the file.

Now you can create the simulation ensemble datastore using the generated data. The resulting simulationEnsembleDatastore object points to the generated data. The object lists the data variables in the ensemble, and by default all the variables are selected for reading. Examine the DataVariables and SelectedVariables properties of the ensemble to confirm these designations.

ensemble = simulationEnsembleDatastore(location)
ensemble = 
  simulationEnsembleDatastore with properties:

           DataVariables: [4×1 string]
    IndependentVariables: [0×0 string]
      ConditionVariables: [0×0 string]
       SelectedVariables: [4×1 string]
                ReadSize: 1
              NumMembers: 5
          LastMemberRead: [0×0 string]
                   Files: [5×1 string]


ensemble.DataVariables
ans = 4×1 string
    "SimulationInput"
    "SimulationMetadata"
    "Tacho"
    "Vibration"


ensemble.SelectedVariables
ans = 4×1 string
    "SimulationInput"
    "SimulationMetadata"
    "Tacho"
    "Vibration"

You can now use ensemble to read and analyze the generated data in the ensemble datastore. See simulationEnsembleDatastore for more information.

Input Arguments

collapse all

Simulation configurations, specified as a vector of Simulink.SimulationInput (Simulink) objects. The simulation configurations specify parameters for each generated member of the ensemble, such as:

  • Simulink model to run

  • Values of model variables

  • Block parameters

  • Model initial state

Thus, for example, you can create a vector of Simulink.SimulationInput objects in which all simulation configurations are identical except for the parameters that model the presence and severity of faults in your system. You can then use the vector to generate an ensemble of simulated data representing a range of healthy and faulty operating conditions.

Folder path at which to store simulation data, specified as a string or a character vector. If you do not provide location, the function uses the current folder (the path returned by pwd).

In the specified folder, the function writes one MAT file per simulation. Each file includes the following variables:

  • SimulationInput — The Simulink.SimulationInput object that was used to configure the model for generating the data in this file. You can use this object to extract information about the conditions (such as faulty or healthy) under which this simulation was run.

  • SimulationMetadata — Other information about the simulation that generated the logged data in the file.

  • A Dataset object containing all the signal and state data that the Simulink model is configured to log. By default, this variable is called logsout, but the name is configurable in the model.

  • PMSignalLogName — The name of the variable that contains the logged data ('logsout' by default). The simulationEnsembleDatastore command uses this name to parse the data in the file.

For more information about data logging, see Save Signal Data Using Signal Logging (Simulink).

Example: pwd + "\simResults"

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'UseParallel',true

Whether to run simulations in parallel, specified as the comma-separated pair consisting of 'UseParallel' and:

  • false — Do not run simulations in parallel.

  • true — Use a parallel pool to run multiple simulations in parallel (requires Parallel Computing Toolbox™).

Whether to display simulation progress in the MATLAB® command window, specified as the comma-separated pair consisting of 'ShowProgress' and:

  • true — Display a simulation progress line each time an individual simulation run completes.

  • false — Do not display simulation progress.

Output Arguments

collapse all

Simulation error status, returned as a logical value:

  • 1 (true) if all simulations run to completion without error

  • 0 (false) otherwise

Simulation errors, returned as a structure array with fields:

  • 'SimulationInput' — Simulink.SimulationInput for the simulation run that generated the error

  • 'ErrorDiagnostic' — String containing the error

Extended Capabilities

expand all

Version History

Introduced in R2018a

See Also

| (Simulink)

Topics