Documentation

Import and Export States

State Information

Some blocks maintain state information that they use during simulation. For example, the state information for a Unit Delay block is the output signal value from the previous simulation step, which the block uses for calculating the output signal value for the current simulation step.

You can use saved state information to capture a known state. Some examples of uses of saved state information include:

  • Stopping a simulation for a model and using the saved state information as input when you restart the simulation.

  • Simulating one model and using the saved state information as input for the simulation of another model that builds on the results of the first model.

Save State Information

You can save state information by either:

  • Saving the final state of a simulation, using the SimState

  • Saving partial state information at the end of a simulation or for each simulation step in array, structure, or structure with time format, using final state logging

For more information, see:

Comparison of SimState and Final State Logging

CharacteristicSimStateFinal State Logging

Simulation mode

Normal or Accelerator

Supports all simulation modes

Model reference

Model reference Accelerator mode not supported

See Import and Export State Information for Referenced Models.

Supports all simulation modes

See Import and Export State Information for Referenced Models.

Resumed simulation

Supported

Not supported

Saved state data

Complete state information

Does not save user data, run-time parameters, or logs of the model

Only logged states — the continuous and discrete states of blocks — which are a subset of the complete simulation state of the model

Does not save user data, run-time parameters, or logs of the model

Block output

Simulink® tries to save the output of a block as part of a SimState even if S-functions declare that no SimStates exist in the block. If the block output is of custom type, Simulink displays an error.

No block output

Readability

To examine a simplified view of the data, consider using looking at the loggedStates property of the Simulink.SimState.ModelSimState class.

Use structure with time format for best readability

Restoring state data

Cannot save in Normal mode and restore in Accelerator, or vice versa

Can save and restore in different simulation modes. If logged state information is not sufficient, you may obtain different results in the two different simulation modes.

See Import Saved State Information.

Structural changes

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 can make structural changes between simulation and restoring the simulation.

Input to model functions

You cannot input the SimState to model functions.

To input to model functions, use Array format with non-complex data of type double.

Code generation

Not supported

Supported

For both SimState and final state logging, Simulink saves state information only at the final time stop or at the execution time at which the simulation paused or stopped.

Save Complete State Information with SimState

To save complete state information, save the SimState for a simulation.

  1. Select the Configuration Parameters > Data Import/Export > Final states check box.

  2. Also in the Data Import/Export pane, select the Save complete SimState in final state parameter.

  3. In the edit box adjacent to the Save complete SimState in final state parameter, enter a variable name for the SimState.

  4. Simulate the model.

For more information about using the SimState, see Save and Restore Simulation State as SimState.

Save Partial Final State Information

To save just the logged states (the continuous and discrete states of blocks):

  1. Select the Configuration Parameters > Data Import/Export > Final states check box.

  2. In the Final states edit box, you can specify a different variable for the state information, if you do not want to use the default xFinal variable.

  3. Also in the Data Import/Export pane, set the Format parameter to Structure or Structure with time. For details, see Format for Saved State Information

  4. Simulate the model.

Save State Information For Each Simulation Step

You can save state information for logged states for each simulation step during a simulation. That level of state information can be helpful for debugging.

  1. Select the Configuration Parameters > Data Import/Export > States check box.

  2. In the States edit box, you can specify a different variable for the state information, if you do not want to use the default xout variable.

  3. Also in the Data Import/Export pane, set the Format parameter to Structure or Structure with time, unless you need to use array format for compatibility with a legacy model. For details, see Format for Saved State Information.

  4. Simulate the model.

Format for Saved State Information

If you do not use the SimState for saving state information, then use Configuration Parameters > Data Import/Export > Format to specify the data format for the saved state information.

You can set Format to:

  • Array (default)

  • Structure

  • Structure with time

The Array option for the Configuration Parameters > Data Import/Export > Format option supports compatibility with models developed in earlier releases, when Simulink supported only the array format for saving state information.

The array format reflects the order of signals. The order of saved state information can change between simulations when you change any of the following:

  • The model (even without changing the signal

  • The simulation mode

  • The code generation mode

The Structure and Structure with time formats are easier to read and consistent across simulations. Also, these two formats are useful when using state information to initialize a model for simulation, allowing you to:

  • Associate initial state values directly with the full path name to the states. This association eliminates errors that can occur if Simulink reorders the states, but the order of the initial state array does not change correspondingly.

  • Assign a different data type to the initial value of each state.

  • Initialize only a subset of the states.

Examine State Information Saved Without the SimState

If you enable the Configuration Parameters > Data Import/Export > Final states or States parameters, Simulink saves the state information in the format that you specify with the Format parameter. The default variable for Final state information is xFinal, and the variable for state information for States information is xout.

If a model has no states saved, then xFinal and xout are empty variables. To determine whether a model has states saved, use the isempty(xout) command.

For example, suppose that you saved final state information in a structure with time format, and use the default xFinal variable for the saved state information.

To find the simulation time and number of states, at the MATLAB® command line, type;

xFinal
xFinal = 

       time: 20
    signals: [1x2 struct]

In this case, the simulation time is 20 and there are two states. To examine the first state, type

xFinal.signals(1)
ans = 

               values: 2.0108
           dimensions: 1
                label: 'CSTATE'
            blockName: 'vdp/x1'
            stateName: ''
    inReferencedModel: 0

The values and blockName fields of first state structure shows that the final value for the output signal of the x1 block was 2.018.

    Note:   If you write a script to analyze state information, use a combination of label and blockName values to uniquely identify a specific state. Do not rely on the order of the states.

Import Initial States

To import states, enable Configuration Parameters > Data Import/Export > Initial state and specify a variable that contains the initial state values. For example, you could specify a variable that contains state information saved from a previous simulation.

You can import state information to initialize a simulation:

  1. Enable Configuration Parameters > Data Import/Export > Initial state.

  2. In the Initial state edit box, enter the name of the variable for the state information that you want to use for initialization. You can create your own state information in MATLAB or you can use state information saved from a previous simulation. For details about using saved state information, see Import Saved State Information.

    The initial values that the variable specifies override the initial state values that the blocks in the model specify in initial condition parameters.

Import Saved State Information

You can import saved state information as the initial state.

  1. Enable Configuration Parameters > Data Import/Export > Initial state.

  2. In the Initial state edit box, enter the name of the variable in the Final states edit box. The state information that Simulink loads depends on the setting of Configuration Parameters > Data Import/Export > Save complete SimState in final state.

    Setting for the "Save complete SimState in final state" parameterState Information
    EnabledComplete state information. For details, see Save and Restore Simulation State as SimState.
    ClearedState information for logged states (the continuous and discrete states of blocks), in the format specified in Configuration Parameters > Data Import/Export > Format. For details, see Format for Saved State Information.

For example, the following commands create an initial state structure that initialize the x2 state of the vdp model. The x1 state is not initialized in the structure. Therefore, during simulation, Simulink uses the value in the Integrator block associated with the state.

% Open the vdp model
vdp

% Use getInitialState to obtain an initial state structure
states = Simulink.BlockDiagram.getInitialState('vdp');

% Set the initial value of the signals structure element 
% associated with x2 to 2.
states.signals(2).values = 2; 

% Remove the signals structure element associated with x1
states.signals(1) = [];

To use the states variable, for the vdp model, enable the Configuration Parameters > Data Import/Export > Initial state option (in the Load from workspace area). Enter states into the associated edit field. When you run the model, note that both states have the initial value of 2. The initial value of the x2 state is assigned in the states structure, while the initial value of the x1 state is assigned in its Integrator block.

Import and Export State Information for Referenced Models

Saved State Information

When Simulink saves states from a referenced model in the structure-with-time format, Simulink adds a Boolean subfield (named inReferencedModel) to the signals field of the saved data structure. The value of this additional field is true (1) if the signals field records the final state of a block that resides in the reference model, and a 0 otherwise. For example:

xout.signals(1)
ans = 

               values: [101x1 double]
           dimensions: 1
                label: 'DSTATE'
            blockName: [1x66 char]
    inReferencedModel: 1

If the signals field records a reference model state, its blockName subfield contains a compound path of a top model path and a reference model path. The top model path is the path from the model root to the Model block that references the reference model. The reference model path is the path from the reference model root to the block whose state the signals field records. The compound path uses a | character to separate the top and reference model paths. For example:

>> xout.signals(1).blockName
ans =

sldemo_mdlref_basic/CounterA|sldemo_mdlref_counter/Previous Output

State Initialization

Use the structure or structure with time format to initialize the states of a top model and the models that it references.

Was this topic helpful?