# Documentation

## How S-Functions Work

### Introduction

To create S-functions, you need to understand how S-functions work. Such knowledge requires an understanding of how the Simulink® engine simulates a model, including the mathematics of blocks. This section begins by explaining the mathematical relationships between the inputs, states, and outputs of a block.

A Simulink block consists of a set of inputs, a set of states, and a set of outputs, where the outputs are a function of the simulation time, the inputs, and the states.

The following equations express the mathematical relationships between the inputs, outputs, states, and simulation time

where $x=\left[{x}_{c};{x}_{d}\right].$

### Simulation Stages

Execution of a Simulink model proceeds in stages. First comes the initialization phase. In this phase, the Simulink engine incorporates library blocks into the model, propagates signal widths, data types, and sample times, evaluates block parameters, determines block execution order, and allocates memory. The engine then enters a simulation loop, where each pass through the loop is referred to as a simulation step. During each simulation step, the engine executes each block in the model in the order determined during initialization. For each block, the engine invokes functions that compute the block states, derivatives, and outputs for the current sample time.

The following figure illustrates the stages of a simulation. The inner integration loop takes place only if the model contains continuous states. The engine executes this loop until the solver reaches the desired accuracy for the state computations. The entire simulation loop then continues until the simulation is complete. See Simulation Phases in Dynamic Systems in Using Simulink for more detailed information on how the engine executes a model. See Simulink Engine Interaction with C S-Functions for a description of how the engine calls the S-function API during initialization and simulation.

How the Simulink Engine Performs Simulation

### S-Function Callback Methods

An S-function comprises a set of S-function callback methods that perform tasks required at each simulation stage. During simulation of a model, at each simulation stage, the Simulink engine calls the appropriate methods for each S-Function block in the model. Tasks performed by S-function callback methods include:

• Initialization — Prior to the first simulation loop, the engine initializes the S-function, including:

• Initializing the `SimStruct`, a simulation structure that contains information about the S-function

• Setting the number and dimensions of input and output ports

• Setting the block sample times

• Allocating storage areas

• Calculation of next sample hit — If you created a variable sample time block, this stage calculates the time of the next sample hit; that is, it calculates the next step size.

• Calculation of outputs in the major time step — After this call is complete, all the block output ports are valid for the current time step.

• Update of discrete states in the major time step — In this call, the block performs once-per-time-step activities such as updating discrete states.

• Integration — This applies to models with continuous states and/or nonsampled zero crossings. If your S-function has continuous states, the engine calls the output and derivative portions of your S-function at minor time steps. This is so the solvers can compute the states for your S-function. If your S-function has nonsampled zero crossings, the engine also calls the output and zero-crossings portions of your S-function at minor time steps so that it can locate the zero crossings.

 Note:   See Simulation Phases in Dynamic Systems for an explanation of major and minor time steps.