Main Content

solverprofiler.profileModel

Examine model for performance analysis using the Solver Profiler programmatic interface

collapse all in page

Syntax

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

Description

example

res = solverprofiler.profileModel(model) runs the Solver Profiler on the specified model and stores the results in res.

example

res = solverprofiler.profileModel(model, Name,Value)specifies the Solver Profiler parameters using one or more Name, Value arguments.

Examples

collapse all

Examine the model f14 using the default settings.

model = 'f14';
res = solverprofiler.profileModel(model);

Inspect the summary of the results.

res.summary
 struct with fields:

             solver: 'ode45'
             tStart: 0
              tStop: 60
             absTol: 1.0000e-06
             relTol: 1.0000e-04
               hMax: 0.1000
           hAverage: 0.0444
              steps: 1352
        profileTime: 0.9974
           zcNumber: 0
        resetNumber: 600
     jacobianNumber: 0
    exceptionNumber: 195

Open the results in the Solver Profiler to visualize them. This step is equivalent to enabling OpenSP when calling the function.

solverprofiler.exploreResult(res)

Examine the model ssc_actuator_custom_pneumatic with a fully specified configuration.

model = 'ssc_actuator_custom_pneumatic';
res = solverprofiler.profileModel(model, ...
    'SaveStates' , 'On', ...
    'SaveZCSignals', 'On',...
    'SaveSimscapeStates' , 'On', ...
    'SaveJacobian' , 'On', ...
    'StartTime' , 5, ...
    'StopTime' , 50, ...
    'BufferSize',  10000,...
    'TimeOut', 5,...
    'OpenSP', 'On',...
    'DataFullFile', fullfile(pwd, 'ssc_profiling_result.mat'));

Input Arguments

collapse all

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

Example: h = solverprofiler.profileModel('vdp')

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.

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

Example: 'StartTime',0,'StopTime',10,'SaveStates','On'

By default, the profiler does not save the states of the model. Enabling this parameter configures the profiler to save the states to a MAT-file.

Example: 'SaveStates','On'

Enable this parameter to save Simscape states to a MAT-file.

Example: 'SaveSimscapeStates', 'On'

Option to log the solver Jacobian matrices to memory. This option is useful for simulations that use implicit solvers. For a comparison of solvers, see Compare Solvers.

Example: 'SaveJacobian', 'On'

Option to save the zero-crossing signal to a MAT file, specified as either 'off' or 'on'.

Example: 'SaveZCSignals', 'On'

Time, in seconds, of the simulation that the profiler starts analyzing the model. This is not the same as the start time of the simulation.

Example: 'StartTime',5

Time, in seconds, of the simulation to which the profiler should profile the model. By default, the analysis continues until the end of the simulation. Changing this parameter does not change the stop time of the model which you specify in the Model Configuration Parameters.

A value less than the configured stop time of the model stops the profiling and simulation at StopTime.

Example: 'StopTime',30

Maximum number of events that are logged. If the number of logged events reaches this value and memory is available, increase BufferSize. If memory is limited, consider lowering the value.

Example: 'BufferSize',60000

Time, in seconds, to wait before the profiler stops running. This option is useful in situations where the simulation is unable to proceed. The profiler waits for the specified time and quits if no progress has been made.

Example: 'TimeOut', 10

Option to open the Solver Profiler dialog box after profiling has completed.

Example: 'OpenSP','On'

By default, the profiling results are saved in a MAT-file named model_@_dd_Month_yyyy_hh_mm_ss.mat in the current working folder. You can specify a different file name by which to save the results in the current working folder. To save the file in a different location, specify the full path of the file, including the file name.

Example: 'DataFullFile','C:\Users\myusername\Documents\profiled\vdp_results.mat'

Output Arguments

collapse all

Profiling results, returned as a structure with the fields:

Path and name of the MAT-file where the results of the profiling operation are stored as MAT file. By default, they are stored in the current working folder with a file name having the pattern: model_@_dd_Month_yyyy_hh_mm_ss.mat. To store them in a different location or by a different name, specify DataFullFile when calling solverprofiler.profileModel.

A high-level summary of the results of the profiling operation, returned as a structure. The summary provides an overview of the performance of the simulation and health of the model.

The summary structure contains these fields.

FieldPurposeValuesDescription
solverSolver used by simulationany of the solvers supported by Solver ProfilerSolver used by the simulation as configured in the Configuration Parameters for the model. For a list of all the solvers, see Solver. The Solver Profiler does not support models without any continuous states.
tStartStart time of simulationscalarStart time, in seconds, for the simulation of the model during the profiling operation.
tStopStop time of simulationscalarStop time, in seconds, of the simulation during the profiling operation. If StopTime is set to be earlier than the configured Stop Time of the model, the simulation stops at StopTime.
absTolAbsolute tolerance of the solverpositive scalarAbsolute tolerance of the solver as specified in the configuration settings for the model. For more information, see Absolute tolerance
relTolRelative tolerance of the solverpositive scalarRelative tolerance of the solver as specified in the configuration settings of the model. For more information, see Relative tolerance
hMaxMaximum step sizepositive scalarLargest time step that the solver can take. See Max step size.
hAverageAverage step sizepositive scalarAverage size of the time step taken by the solver.
stepsTotal steps takenpositive scalarTotal number of time steps taken by the solver.
profileTimeTime to profilepositive scalarTime, in seconds, taken by the Solver Profiler to examine the model.
zcNumberTotal number of zero crossingsnonnegative scalarNumber of times zero crossings occur during the simulation of the model. The detection of these zero crossings incurs computational cost and can slow down the simulation. For information on zero-crossing detection, see Zero-Crossing Detection.
resetNumberNumber of solver resetsnonnegative scalarNumber of times the solver has to reset its parameters.
jacobianNumberNumber of Jacobian updatesnonnegative scalarNumber of times the solver Jacobian matrix is updated during a simulation. For more information, see Explicit Versus Implicit Continuous Solvers.
exceptionNumberNumber of solver exceptionsnonnegative scalarTotal number of solver exceptions encountered during a simulation. These exceptions are events where the solver is unable to solve the model states to the specified accuracy. As a result, the solver runs adjusted trials which increase computational cost.

Data Types: struct

Version History

Introduced in R2017b

See Also

Topics