Use Model Name as Programmatic Interface - MATLAB & Simulink (original) (raw)

You can use the name of a model as a programmatic interface for executing a specified simulation phase and computing values for individual states and times that you specify.

This functionality is not intended for running a model step by step, simulating a model programmatically, or for debugging. For those purposes, consider these alternatives:

To step through a simulation, use the Step Forward andStep Back buttons.
For more information, see Step Through Simulations Using the Simulink Editor.
To simulate a model programmatically, use the sim, parsim, and batchsim functions.
For low-level debugging, use the Simulink® debugger.

Model Requirements

When you use the model name as a programmatic interface to compute simulation values, the software ignores the effects of state transitions and conditional execution. Use this functionality only for models that implement simple dynamic systems. Such systems must meet these requirements:

All states in the model must have built-in nonbus data types.
For more information about built-in data types, see About Data Types in Simulink.
The model must contain a minimal amount of state logic, such as Stateflow® charts and conditionally executed subsystems.
The model must contain only blocks from Simulink libraries. The model cannot contain S-functions or Simscape™ blocks.
When you specify the state values as a vector, states in the model must have real double values.

Using this functionality for models that do not meet these requirements and models that use multitasking execution can produce unexpected results. For more information about multitasking and single task execution, see Time-Based Scheduling and Code Generation (Simulink Coder).

Input Arguments

To use a model name as a programmatic interface, you use the name of your model as though it were the name of a function. You always provide four inputs:

t — Simulation time, specified as a real, double scalar.
x — State values, specified as a vector of real double values or as a structure.
Specifying the states as a Simulink.op.ModelOperatingPoint object is not supported.
u — Input data, specified as a vector of real, double values.
phase — Simulation phase to execute, specified as one of these options:
- 'sizes' — Size computation phase, in which the software determines the sizes for the model input, output, and state vectors
- 'compile' — Compilation phase, in which the software propagates signal and sample time attributes
- 'update' — Update phase, in which the model computes the values of discrete states
- 'outputs' — Output phase, in which the model computes block and model output values
- 'derivs' — Derivatives phase, in which the model computes the derivatives for continuous states
- 'term' — Termination phase

The number, type, and dimensions of the output arguments depend on which simulation phase you execute.

When you use this functionality, you must manually execute each simulation phase in the appropriate order. For more information about how simulations run, see Simulation Phases in Dynamic Systems. This functionality is not meant to run a simulation step by step or as a replacement for the typical simulation workflow.

Execute Size Computation Phase

To run the sizes phase, use this syntax, specifying [] for the first three input arguments.

[sys,x0,blks,st] = modelName([],[],[],"sizes");

Before R2024a: You can also execute the sizes phase without specifying any input arguments.

In R2024a: The syntax with no input arguments is no longer supported.

The sizes phase returns four output arguments:

sys — System information, returned as a vector with seven elements:
- sys(1) — Number of continuous states in the system.
- sys(2) — Number of discrete states in the system.
- sys(3) — Number of model outputs.
- sys(4) — Number of model inputs.
- sys(5) — Reserved.
- sys(6) — Direct feedthrough flag for system. A value of 1 indicates that the system has direct feedthrough. A value of 0 indicates that the system does not have direct feedthrough.
- sys(7) — Number of continuous, discrete, fixed-in-minor-step, and controllable sample times in the system. The value at this index indicates the number of rows in the ts output.
x0 — Vector that contains the initial conditions for system states.
blks — Vector that contains the names of blocks associated with the system states. The order of elements inblks matches the order of elements inx0.
st — _m_-by-2 array of sample time information for the system, where m is equal to the value of sys(7). The first column of the array indicates the sample time and the second column indicates the offset. For more information about sample time, see Types of Sample Time.

Execute Compilation Phase

To run the compilation phase, use this syntax, specifying [] for the first three input arguments.

[sys,x0,blks,st] = modelName([],[],[],"compile");

The compilation phase returns the same four output arguments as the sizes phase:

sys — System information, returned as a vector with seven elements:
- sys(1) — Number of continuous states in the system.
- sys(2) — Number of discrete states in the system.
- sys(3) — Number of model outputs.
- sys(4) — Number of model inputs.
- sys(5) — Reserved.
- sys(6) — Direct feedthrough flag for system. A value of 1 indicates that the system has direct feedthrough. A value of 0 indicates that the system does not have direct feedthrough.
- sys(7) — Number of continuous, discrete, fixed-in-minor-step, and controllable sample times in the system. The value at this index indicates the number of rows in the ts output.
x0 — Vector that contains the initial conditions for system states.
blks — Vector that contains the names of blocks associated with the system states. The order of elements inblks matches the order of elements inx0.
st — _m_-by-2 array of sample time information for the system, where m is equal to the value of sys(7). The first column of the array indicates the sample time and the second column indicates the offset. For more information about sample time, see Types of Sample Time.

After running the compilation phase, you must run the termination phase before you can close the model. If you execute the compilation phase multiple times before executing the termination phase, you must execute the termination phase an equal number of times.

Compute Discrete State Values

To execute the update phase and compute the discrete state values, use this syntax. You specify the time at which you want to calculate the discrete states and the current state and input values to use in the computation.

dStates = modelName(t,x,u,"update");

The update phase returns the discrete state values dStates as a structure or an array, depending on how you specify the current state values,x.

When you specify x as empty ([]) or as a structure, the update phase returns dStates as a structure that contains both discrete and continuous state values for all states with built-in data types.
When you specify x as a vector or an array, the update phase returns dStates as a vector or an array that contains only the discrete state values for states that have real, double values.

Compute Output Values

To compute the model outputs, use this syntax. You specify the time at which you want to calculate the discrete states and the current state and input values to use in the computation.

out = modelName(t,x,u,"outputs");

Compute Continuous State Derivatives

To compute the derivatives for continuous states, use this syntax. You specify the time at which you want to calculate the discrete states and the current state and input values to use in the computation.

derivs = modelName(t,x,u,"derivs");

Execute Termination Phase

When you are done analyzing the model behavior, use this syntax to execute the termination phase so you can close the model. Specify [] for the first three input arguments.

modelName([],[],[],"term");