Save and Restore Simulation State as SimState

Overview of the SimState

In real-world applications, you simulate a Simulink® model repeatedly to analyze the behavior of a system for different input, boundary conditions, or operating conditions. In many applications, a start-up phase with significant dynamic behavior is common to multiple simulations. For example, the cold start take-off of a gas turbine engine occurs before each set of aircraft maneuvers. Ideally, you would simulate this start-up phase once, save the simulation state at the end of the start-up phase, and then use this simulation state or SimState as the initial state for each set of conditions or maneuvers.

The Simulink SimState feature allows you to save all run-time data necessary for restoring the simulation state of a model. A SimState includes both the logged and internal state of every block (e.g., continuous states, discrete states, work vectors, zero-crossing states) and the internal state of the Simulink engine (e.g., the data of the ODE solver).

You can save a SimState:

  • At the final Stop time

  • When you interrupt a simulation with the Pause or Stop button

  • When you use a block (e.g., the Stop block) to stop a simulation

At a later time, you can restore the SimState and use it as the initial conditions for any number of simulations.

    Note:   The Final states option of the Data Import/Export pane in Simulink saves only logged states—the continuous and discrete states of blocks—which are a subset of the complete simulation state of the model. Hence you cannot use the Final states to save and restore the complete simulation state as the initial state of a new simulation.

Save the SimState

Saving the SimState Interactively

To save the complete SimState at the beginning of the final step:

  1. In the Simulink model window, select Simulation > Configuration Parameters.

  2. Navigate to the Data Import/Export pane.

  3. Select the Final states check box. The Save complete SimState in final state check box becomes active.

  4. Select the Save complete SimState in final state check box.

  5. In the adjacent field, enter a variable name for the SimState.

  6. Simulate the model by selecting Simulation > Run.

Saving the SimState Programmatically

You can save the SimState at the beginning of the final step programmatically using the sim command in conjunction with the set_param command with the SaveCompleteFinalSimState parameter set to on:

set_param(mdl, 'SaveFinalState', 'on', 'FinalStateName',...
 [mdl 'SimState'],'SaveCompleteFinalSimState', 'on')
simOut = sim(mdl, 'StopTime', tstop)
set_param(mdl, 'SaveFinalState', 'off')

    Note:   For models with variable step solvers, saving the final simulation state as SimState affects the heuristic that automatically chooses the maximum step size. When you save or restore a SimState in these models, setting the maximum step size to auto results in the time trajectory getting offset from whenSimState save is off.

Restore the SimState

Restoring the SimState Interactively

You can restore the SimState interactively.

In the Data Import/Export pane:

  1. Under Load from workspace, select the check box next to Initial state. The adjacent field becomes active.

  2. Enter the name of the variable containing the SimState in the field.

In the Solver pane of the Configuration Parameters window:

  1. Keep the Start time set to its original value.

  2. Set the Stop time to the sum of the original simulation time plus the new additional simulation time.

  3. Click OK.

The Start time must maintain its original value because it is a reference value for all time and time-dependent variables in both the original and the current simulations. For example, a block may save and restore the number of sample time hits that occurred since the beginning of simulation as the SimState . For clarity, consider a model that you ran from 0 s to 100 s and that you now wish to run from 100 s to 200 s. The Start time is 0 s for both the original simulation (0 s to 100 s) and for the current simulation (100 s to 200 s). And 100 s is the initial time of the current simulation. Also, if the block had ten sample time hits during the original simulation, Simulink recognizes that the next sample time hit will be the eleventh relevant to 0 s (not 100 s).

Restoring the SimState Programmatically

Use the set_param command to specify the initial condition as the SimState.

set_param(mdl, 'LoadInitialState', 'on', 'InitialState',...
[mdl 'SimState']);
simOut = sim(mdl, 'StopTime', tstop)

Restoring a SimState Saved in an Earlier Version of Simulink

You can now use SimState objects saved in earlier releases (R2010a or later) to restore the SimState of a model. You can see the version of Simulink used to save the SimState by examining the 'version' field of the SimState object. Simulink detects if the SimState object provided as the initial state was saved in the current release. By default, the Simulink software reports an error message if the SimState was not saved in the current release. You may configure the diagnostic to allow Simulink to report the message as a warning and try to restore as many of the values as possible. To enable this best-effort restoration, go to the Diagnostics pane of the Configuration Parameter dialog box and set the message for SimState object from earlier release to warning. You can also set the diagnostic programmatically using the set_param command.

set_param(mdl,  'SimStateOlderReleaseMsg', 'warning');

Change the States of a Block within the SimState

You can use the loggedStates to get or set the SimState. The loggedStates field has the same structure as xout.signals if xout is the state log that Simulink exports to the workspace.

SimState Interface Checksum Diagnostic

The SimState interface checksum is primarily based upon the configuration settings of your model. A diagnostic, 'SimState interface checksum mismatch', resides on the Diagnostics pane of the Configuration Parameters dialog box. You can set this diagnostic to 'none', 'warning', or 'error" to receive a warning or an error if the interface checksum of the restored SimState does not match the current interface checksum of the model. Such mismatches may occur when you try to simulate using a solver that is different from the one that generated the saved SimState. Simulink permits such solver changes. For example, you can use a solver such as ode15s, to solve the initial stiff portion of a simulation, save the final SimState, and then continue the simulation with the restored SimState and using ode45. In other words, this diagnostic is purely to serve your own purposes for detecting solver changes.

Limitations of the SimState

  • When you enable or disable signal logging in a model, this action invalidates any SimState saved prior to this action. This is because enabling or disabling signal logging changes the structural checksum of the model.

  • The following blocks do not support SimState:

    • S-functions that have P-work vectors but do not declare their SimState compliance level or declare it to be unknown or disallowed (see S-Function Compliance with the SimState)

    • SimMechanics™ First Generation blocks

    • Model blocks configured for Accelerator mode

    • SimEvents® blocks

  • You can use only the Normal or the Accelerator simulation mode.

  • You cannot save the SimState in Normal mode and restore it in Accelerator mode, or vice versa.

  • You can save the SimState only at the final stop time or at the execution time at which you pause or stop the simulation.

  • By design, Simulink does not save user data, run-time parameters, or logs of the model.

  • The SimState feature does not support code generation, including Model Reference in accelerated modes.

  • You cannot make any structural changes to the model between the time at which you save the SimState and the time at which you restore the simulation using the SimState. For example, you cannot add or remove a block after saving the SimState without repeating the simulation and saving the new SimState.

  • You cannot input the SimState to a model function.

  • Simulink tries to save the output of a block as part of a SimState. For s-functions, this happens even if the functions declare that no SimStates is required. If the block output is of custom type, Simulink cannot save the SimState and displays an error.

  • In the Stack and Queue blocks, the default setting for the Push full stack option is Dynamic reallocation. This default setting does not support SimState. Other settings (Ignore, Warning and Error) support SimState.

  • There are other limitations when using SimState. As an alternative, you can save partial state information. For a comparison of the two ways to save state data, see Comparison of SimState and Final State Logging.

Using SimState within S-Functions

Special APIs for C and Level-2 MATLAB® S-functions are available, which enable the S-functions to work with the SimState. For information on how to implement these APIs within S-functions, see S-Function Compliance with the SimState.

Was this topic helpful?