Documentation

Save and Restore Simulation State as SimState

SimState and Repetitive Simulations

When designing a system, you simulate a model repeatedly to analyze the behavior of a system for different inputs, boundary conditions, or operating conditions. In many applications, a startup phase with significant dynamic behavior is common to multiple simulations. For example, the cold start takeoff of a gas turbine engine occurs before each set of aircraft maneuvers. Ideally, you:

  1. Simulate the startup phase once.

  2. Save the simulation state at the end of the start-up phase.

  3. Use this state as the initial state for each set of conditions or maneuvers.

In this type of situation, use SimState to save the state of a simulation. For future simulations, you can restore the SimState and use it to set initial conditions for simulations going forward.

A SimState includes both the logged and internal states 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).

    Note:   You can also use the Final states option in the Configuration Parameters Data Import/Export pane to save a simulation state. However, this option saves only logged states—the continuous and discrete states of blocks. These states are only subsets of the complete simulation state of the model. They do not include information about hidden states of certain blocks — information that is not included in logged states but is still required for the proper execution of the block. Hence you cannot use Final states to save and restore the complete simulation state as the initial state of a new simulation.

Information Saved in a SimState

A SimState contains information about:

  • Logged states

  • State of the solver and execution engine

  • Zero-crossing signals for blocks that register zero crossings

  • Output values of certain blocks in the model

    Simulink analyzes block connections and other information to determine whether it is using the output values effectively as state information.

SimState also stores the hidden states of these blocks:

  • Transport Delay

  • Variable Transport Delay

  • From Workspace

  • For Each subsystem

  • Conditionally executed subsystems

  • Stateflow

  • MATLAB System

  • SimMechanics™ Second Generation

By storing this information, SimState ensures that the result of a simulation that starts from SimState is the same as a simulation that runs from the beginning.

Benefits of Using SimState

  • When SimState saves the state of a simulation, it saves information in addition to the logged states in the model. You need to restore all of this information to ensure that the simulation matches the uninterrupted simulation. For example, if solver information affected the simulation, then changing the state of a block without using SimState can produce different results.

  • You can save several SimStates during a simulation. You can then resume a simulation from any of those states.

  • SimState can help to restore the state of blocks such as the Transport Delay block, which is typically difficult to restore to a particular state. The state of the Transport Delay block is not saved in the structure format or the array format when you log data using the Final states configuration parameter without using Simstate. The blocks with hidden states are particularly difficult to restore, and SimState enables you to do so.

When You Can Save a SimState

You can save a SimState:

  • At the final Stop time

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

  • When you use get_param or a block, like the Stop block, to stop a simulation

Save SimState

Save a SimState at the beginning of the final step using one of these options.

Interactive

  1. In the Configuration Parameters dialog box, in the Data Import/Export pane, select the Final states check box. The Save complete SimState in final state check box becomes available.

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

  3. In the Final states text box, enter a variable name for the SimState.

  4. Simulate the model.

From the MATLAB Command Prompt

Use the sim command with set_param. Set the SaveCompleteFinalSimState parameter to on.

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

Restore SimState

The Start time does not change from the value in the simulation that generated SimState. It is a reference value for all time and time-dependent variables in both the original and the current simulation. For example, a block can save and restore the number of sample time hits that occurred since the beginning of simulation as its SimState.

Consider a model that you ran from 0–100 s and that you now want to run from 100–200 s. The Start time is 0 s for both the original simulation (0–100 s) and for the current simulation (100–200 s). The initial time of the current simulation is 100 s. Also, if the block had 10 sample time hits during the original simulation, Simulink recognizes that the next sample time hit is the 11th, relative to 0, not 100 s.

    Note:   If you change Start time before restoring a SimState, Simulink overwrites the Start time with the value saved in the SimState.

Restore a SimState using one of these options.

Interactive

  1. In the Configuration Parameters dialog box, in the Data Import/Export pane, under Load from workspace, select the Initial state check box. The text box becomes available.

  2. Enter the name of the variable containing the SimState in the text box.

  3. Set Stop time to a value greater than the time at which the SimState was saved.

From the MATLAB Command Prompt

Use set_param to specify the initial condition as the SimState.

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

Restore SimState Saved in an Earlier Version of Simulink

You can use SimState objects saved in releases starting with R2010a to restore the SimState of a model. However, this option restores only the logged states of the model. To see the version of Simulink used to save the SimState, examine the version parameter of the SimState object.

Simulink detects if the SimState object you provided as the initial state was saved in the current release. By default, Simulink displays an error message if the SimState was not saved in the current release. You can configure the diagnostic to allow Simulink to display the message as a warning and try to restore as many of the values as possible.

To enable this best-effort restoration, in the Configuration Parameters dialog box, in the Diagnostics pane, set the message for SimState object from earlier release to warning.

Change the States of a Block Within SimState

  • Use loggedStates to get or set the states of blocks. If xout is the state log that Simulink exports to the workspace, then the loggedStates field has the same structure as xout.signals.

  • You cannot change the states that are not logged. Simulink does not allow this modification as it could cause the state to be inconsistent with the simulation.

S-Functions

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

S-functions that have P-work vectors but do not declare their SimState compliance level or declare it to be unknown or disallowed do not support SimState. For more information, see S-Function Compliance with the SimState.

Model Changes and SimState

  • You cannot make any structural changes to the model between the time you save the SimState and the time 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.

  • The SimState interface checksum is primarily based on the configuration settings in a model. You can make some nonstructural changes to the model between saving and restoring a SimState. In the Configuration Parameters dialog box, in the Diagnostics pane, use the SimState interface checksum mismatch diagnostic to track such changes. You can then find out if the interface checksum of the restored SimState matches the current interface checksum.

    Mismatches can occur when you try to simulate using a solver that is different from the one that generated the saved SimState. Simulink permits solver changes. For example, you can use the ode15s solver to solve the initial stiff portion of a simulation and save the final SimState. You can then continue the simulation with the restored SimState using ode45. In other words, this diagnostic helps you see the solver changes but does not signal a problem with the simulation.

  • When you use a variable-step solver with the maximum step size set to auto, Simulink uses the maximum step size from the restored SimState for the new simulation. To ensure that the concatenated SimState trajectory of two simulations matches that of an uninterrupted simulation, specify a value for the maximum step size.

Limitations of SimState

Block Support

The following blocks do not support SimState:

  • 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.

  • SimMechanics First Generation blocks

  • SimEvents® blocks

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 SimState is required. If the block output is of custom type, Simulink cannot save the SimState and displays an error. For more information about SimState use with S-functions, see S-Functions.

Model reference offers partial support for SimState. For details, see Model Referencing.

Simulation

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

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

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

  • You cannot change the states of certain blocks that are not logged. For more information, see Change the States of a Block Within SimState.

Code Generation

The SimState feature does not support Simulink Coder™ or Embedded Coder® code generation.

Model Referencing

  • You cannot modify logged states of blocks that are inside a referenced model in Accelerator mode.

  • The following blocks do not support SimState when included in a model referenced in Accelerator mode:

    • Level 2 MATLAB S-Function

    • MATLAB System

    • n-D Lookup Table

    • S-Function (with custom SimState or PWork vectors)

    • To File

    • Simscape™ blocks

  • For additional information, see State Information for Referenced Models.

Model Function

You cannot input the SimState to the model function.

Was this topic helpful?