solverprofiler.profileModel

Programmatically analyze solver performance for model using Solver Profiler

Syntax

res = solverprofiler.profileModel(mdl)

res = solverprofiler.profileModel(mdl,Name,Value)

Description

res = solverprofiler.profileModel(mdl) analyzes the performance of the selected solver for the model mdl using the Solver Profiler.

The profiling results are always saved in a MAT file. The output argument res includes a high-level summary of the profiling results and the name of the MAT file that contains the complete profiling data.

The profiling data in the MAT file is not accessible in the MATLAB^® base workspace. To view and analyze the profiling data, open the MAT file in the Solver Profiler by using the Solver Profiler user interface or the solverprofiler.exploreResult function.

res = solverprofiler.profileModel(mdl,Name,Value) analyzes the performance of the selected solver based on one or more options specified using name-value arguments.

Examples

Programmatically Analyze Solver Performance for Model

Open the model slexAircraftExample.

mdl = "slexAircraftExample";
open_system(mdl);

Use the solverprofiler.profileModel function to analyze the performance of the selected solver for the model using the Solver Profiler.

res = solverprofiler.profileModel(mdl);

To see a high-level summary of the profiling results, view the summary field of the results structure. The summary shows that the profiling simulation had 600 solver resets and 193 solver exceptions.

res.summary

ans = struct with fields:
             solver: 'ode45'
             tStart: 0
              tStop: 60
             absTol: 1.0000e-06
             relTol: 1.0000e-04
               hMax: 0.1000
           hAverage: 0.0435
              steps: 1380
        profileTime: 0.0512
           zcNumber: 18
        resetNumber: 618
     jacobianNumber: 0
    exceptionNumber: 196

The solverprofiler.profileModel function saves data from the profiling session in a MAT-file. The file field of the results structure indicates the full path and filename. By default, the MAT-file is saved in the current working directory.

To analyze the profiling results in greater detail, load the MAT-file with the profiling session data into the Solver Profiler. In the Simulink® Toolstrip, on the Debug tab, click the Performance button arrow. Then, select Solver Profiler.

In the Solver Profiler, click the Load button arrow and select Load Session Data. Select the profiling session file and click Open. The Solver Profiler shows the data from the profiling simulation.

Alternatively, use the solverProfiler.exploreResult function to programmatically open the Solver Profiler and load the session data.

solverprofiler.exploreResult(res.file)

Input Arguments

mdl — Name of model to analyze

string | character vector

Name of model to analyze, specified as a string or a character vector.

Example: h = solverprofiler.profileModel("vdp") analyzes the currently selected solver for the model vdp using the Solver Profiler.

Name-Value Arguments

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.

Example: solverprofiler.profilemodel(mdl,StartTime=0,StopTime=10,SaveStates="on") analyzes the currently selected solver for the model mdl in a simulation from 0 to 10 seconds and logs state values.

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

Example: solverprofiler.profilemodel(mdl,"StartTime",0,"StopTime",10,"SaveStates","on") analyzes the currently selected solver for the model mdl in a simulation from 0 to 10 seconds and logs state values.

SaveStates — Option to save model states in MAT file that contains profiling results

'off' (default) | 'on'

Option to save model states in MAT file that contains profiling results, specified as 'off' or 'on'.

When you save model states with the profiling results, the states data is not accessible in the MATLAB base workspace after you load the contents of the MAT file. To view and analyze the data, open the MAT file that contains the model states and profiling results in the Solver Profiler.

When the MAT file contains states data, the Solver Profiler includes an option to open the State Explorer, where you can analyze the state values throughout the profiling simulation.

SaveSimscapeStates — Option to save Simscape™ states in MAT file that contains profiling results

'off' (default) | 'on'

Option to save Simscape states in MAT file that contains profiling results, specified as 'off' or 'on'.

When you save Simscape states with the profiling results, the states data is not accessible in the MATLAB base workspace after you load the contents of the MAT file. To view and analyze the data, open the MAT file that contains the states data and profiling results in the Solver Profiler.

When the MAT file contains Simscape states data, the Solver Profiler includes an option to open the Simscape Results Explorer, where you can analyze the Simscape state values throughout the profiling simulation. For more information, see Simscape Results Explorer (Simscape).

SaveJacobian — Option to save updates to Jacobian matrix in MAT file that contains profiling results

'off' (default) | 'on'

Option to save updates to Jacobian matrix in MAT file that contains profiling results, specified as 'off' or 'on'.

Enabling this option does not change the contents of the MAT file if the solver does not update the Jacobian matrix during the profiling simulation. This option is useful for simulations that use implicit solvers. For more information about implicit solvers, see Compare Solvers.

When you save Jacobian data in the profiling results, the results are not accessible in the MATLAB base workspace after you load the contents of the MAT file. To view and analyze the data, open the MAT file that contains the Jacobian data and profiling results in the Solver Profiler.

When the MAT file contains Jacobian data, the Solver Profiler includes a tab named Jacobian Analysis, where you can view and analyze the Jacobian matrix updates that happened during the profiling simulation.

SaveZCSignals — Option to save zero-crossing signal data in MAT file that contains profiling results

'off' (default) | 'on'

Option to save zero-crossing signal data in MAT file that contains profiling results, specified as 'off' or 'on'.

When you save zero-crossing signal data with the profiling results, the zero-crossing signal data is not accessible in the MATLAB base workspace after you load the contents of the MAT file. To view and analyze the data, open the MAT file that contains the zero-crossing signal data and profiling results in the Solver Profiler.

When the MAT file contains zero-crossing signal data, the Solver Profiler includes an option to open the Zero Crossing Explorer, where you can analyze the zero-crossing signal values throughout the profiling simulation.

StartTime — Start time for profiling simulation

Start time parameter value (default) | scalar

Start time for profiling simulation, specified as a scalar number with units of seconds. By default, the Solver Profiler uses the Start time parameter value for the model.

Specifying this name-value argument does not change the value of the Start time parameter for the model.

StopTime — Stop time for profiling simulation

Stop time parameter value (default) | scalar

Stop time for profiling simulation, specified as a scalar number with units of seconds. By default, the Solver Profiler uses the Stop time parameter value for the model.

Specifying a value for this name-value argument does not change the Stop time parameter for the model.

BufferSize — Maximum number of events to log

50000 (default) | positive scalar

Maximum number of events to log, specified as a positive scalar. By default, the Solver Profiler logs up to 50,000 events.

If the number of logged events reaches 50,000 when you profile your model and memory is still available, specify a larger value. If memory is limited, consider specifying a lower value.

TimeOut — Option to specify timeout for profiling simulation

positive scalar

Option to specify timeout for profiling simulation, specified as a positive scalar with units of seconds. In some cases, the profiling simulation might not be able to proceed. When you specify a timeout for the profiling simulation, the Solver Profiler stops the profiling simulation if the simulation does not make progress within the specified amount of time.

OpenSP — Option to open Solver Profiler user interface after profiling simulation completes

'off' (default) | 'on'

Option to open the Solver Profiler user interface after profiling simulation completes, specified as 'off' or 'on'.

DataFullFile — Path and name of MAT file that contains profiling results and data saved from profiling simulation

string | character vector

Path and name of MAT file that contains profiling results and data saved from profiling simulation, specified as a string or a character vector.

When you do not specify this name-value argument, the Solver Profiler saves the results in the current working directory in a MAT file named using the convention model_@_dd_Month_yyyy_hh_mm_ss.mat that includes the name of the model and a timestamp.

Output Arguments

res — High-level summary of profiling results

structure

High-level summary of profiling results, returned as a structure that contains these fields:

• file — Full path and name for MAT file that contains profiling results and data saved from profiling simulation

  By default, the MAT file that contains profiling results is stored in the current working folder. The default file name includes the name of the model and a time stamp with the naming pattern model_@_dd_Month_yyyy_hh_mm_ss.mat.

  Specify the name and location for the MAT file using the DataFullFile name-value argument.

• summary — Structure that contains a summary of model parameter values used in the profiling simulation and the profiling results

  The table summarizes the fields and information contained in the summary structure.

  Field	Values	Description
  solver	character vector	Solver used in profiling simulation. The profiling simulation uses the solver specified using the Solver configuration parameter for the model. The Solver Profiler supports only models that contain continuous states and does not support the variable-step discrete solver or the fixed-step discrete solver.
  tStart	scalar	Start time for profiling simulation, in seconds. When you do not specify the StartTime name-value argument, the profiling simulation uses the value of the Start time configuration parameter for the model. To use a different start time for the profiling simulation, specify the StartTime name-value argument. Specifying the StartTime name-value argument does not change the value of the Start time parameter for the model.
  tStop	scalar	Stop time for profiling simulation, in seconds. When you do not specify the StopTime name-value argument, the profiling simulation uses the value of the Stop time parameter for the model. To use a smaller stop time for the profiling simulation, specify the StopTime name-value argument as a value that is less than the value for the Stop time parameter. Specifying the StopTime name-value argument does not change the value of the Stop time parameter for the model.
  absTol	positive scalar	Absolute tolerance for the solver, specified using the Absolute tolerance configuration parameter for the model.
  relTol	positive scalar	Relative tolerance for the solver, specified using the Relative tolerance configuration parameter for the model.
  hMax	positive scalar	Maximum step size for the profiling simulation, specified using the Max step size configuration parameter for the model.
  hAverage	positive scalar	Average size of steps taken by the solver in the profiling simulation.
  steps	positive scalar	Total number of time steps in the profiling simulation.
  profileTime	positive scalar	Elapsed time in seconds for profiling simulation.
  zcNumber	nonnegative scalar	Number of zero crossings detected in the profiling simulation. Detecting and locating zero crossings improves simulation accuracy but adds computational complexity. A large number of zero crossings can slow simulation performance. For more information, see Zero-Crossing Detection.
  resetNumber	nonnegative scalar	Number of solver resets that occurred in the profiling simulation.
  jacobianNumber	nonnegative scalar	Number of times the solver updated the Jacobian matrix in the profiling simulation. For more information, see Explicit Versus Implicit Continuous Solvers.
  exceptionNumber	nonnegative scalar	Total number of solver exceptions that occurred during the profiling simulation. Solver exceptions occur when the solver is unable to compute the model states within the specified tolerance values. When a solver exception occurs, the solver adjusts the computation to try to satisfy the tolerance values. A large number of solver exceptions indicates repeated computations, which can slow simulation performance.

Data Types: struct

Version History

Introduced in R2017b