Learn more about Simulink

mdlInitializeSizes - Specify the number of inputs, outputs, states, parameters, and other characteristics of the S-function

Required

Yes

C Syntax

#define MDL_INITIAL_SIZES

void mdlInitializeSizes(SimStruct *S)

C Arguments

S

SimStruct representing an S-Function block.

M Syntax

setup(s)

M Arguments

s

Instance of Simulink.MSFcnRunTimeBlock class representing the Level-2 M-File S-Function block.

C Description

This is the first S-function callback methods that the Simulink engine calls. This method performs the following tasks:

• Specify the number of parameters that this S-function supports, using ssSetNumSFcnParams.

  Use ssSetSFcnParamTunable(S,paramIdx, 0) when a parameter cannot change during simulation, where paramIdx starts at 0. When a parameter has been specified as not tunable, the engine issues an error during simulation (or when in external mode when using the Real-Time Workshop product) if an attempt is made to change the parameter.

• Specify the number of states that this function has, using ssSetNumContStates and ssSetNumDiscStates.

• Configure the block's input ports, including:

  • Specify the number of input ports that this S-function has, using ssSetNumInputPorts.

  • Specify the dimensions of the input ports.

    See ssSetInputPortDimensionInfo for more information.

  • For each input port, specify whether it has direct feedthrough, using ssSetInputPortDirectFeedThrough.

    A port has direct feedthrough if the input is used in either the mdlOutputs or mdlGetTimeOfNextVarHit function. The direct feedthrough flag for each input port can be set to either 1=yes or 0=no. It should be set to 1 if the input, u, is used in the mdlOutputs or mdlGetTimeOfNextVarHit routine. Setting the direct feedthrough flag to 0 tells the Simulink engine that u is not used in either of these S-function routines. Violating this leads to unpredictable results.

• Configure the block's output ports, including:

  • Specify the number of output ports that the block has, using ssSetNumOutputPorts.

  • Specify the dimensions of the output ports.

    See mdlSetOutputPortDimensionInfo for more information.

  If your S-function outputs are discrete (for example, the outputs only take specific values such as 0, 1, and 2), specify SS_OPTION_DISCRETE_VALUED_OUTPUT.

• Set the number of sample times (i.e., sample rates) at which the block operates.

  There are two ways of specifying sample times:

  • Port-based sample times

  • Block-based sample times

  See Sample Times for a complete discussion of sample time issues.

  For multirate S-functions, the suggested approach to setting sample times is via the port-based sample times method. When you create a multirate S-function, you must take care to verify that, when slower tasks are preempted, your S-function correctly manages data so as to avoid race conditions. When port-based sample times are specified, the block cannot inherit a constant sample time at any port.

• Set the size of the block's work vectors, using ssSetNumRWork, ssSetNumIWork, ssSetNumPWork, ssSetNumModes, ssSetNumNonsampledZCs.

• Set the simulation options that this block implements, using ssSetOptions.

  All options have the form SS_OPTION_<name>. See S-Function Options — Alphabetical List for information on each option. Use a bitwise OR operator to set multiple options, as in

  ssSetOptions(S, (SS_OPTION_name1 | SS_OPTION_name2))
  

Dynamically Sized Block Features

You can set the parameters NumContStates, NumDiscStates, NumInputs, NumOutputs, NumRWork, NumIWork, NumPWork, NumModes, and NumNonsampledZCs to a fixed nonnegative integer or tell the Simulink engine to size them dynamically:

• DYNAMICALLY_SIZED -- Sets lengths of states, work vectors, and so on to values inherited from the driving block. It sets widths to the actual input widths, according to the scalar expansion rules unless you use mdlSetWorkWidths to set the widths.

• 0 or positive number -- Sets lengths (or widths) to the specified values. The default is 0.

M Description

The Level-2 M-file S-function setup method performs nearly the same tasks as the C MEX S-function mdlInitializeSizes method, with two significant differences. The setup method does not initialize discrete state information, but it does specify the block sample times, eliminating the need for an mdlInitializeSampleTimes method. Use the following properties and methods of the run-time object s to configure the S-function:

• Specify the number of parameters that this S-function supports, using s.NumDialogPrms.

  Use s.DialogPrmsTunable to set the tunablility of each dialog parameter. When a parameter has been specified as not tunable, the Simulink engine issues an error during simulation (or when in external mode when using the Real-Time Workshop product) if an attempt is made to change the parameter.

• Specify the number of continuous states that this function has, using s.NumContStates. Specify discrete state information in the PostPropagationSetup method using a DWork vector.

• Configure the block's input ports, including:

  • Specify the number of input ports that this S-function has, using s.NumInputPorts.

  • Specify the dimensions of the ith input port, using s.InputPort(i).Dimensions.

  • If using port-based sample times, specify the sample time of the ith input port, using s.InputPort(i).SampleTime.

  • For each input port, specify whether it has direct feedthrough, using s.InputPort(i).DirectFeedthrough.

    A port has direct feedthrough if the input is used in the Outputs method to calculate the output or the next sample time, for an S-function with a variable sample time. The direct feedthrough flag for each input port can be set to either 1=yes or 0=no. It should be set to 1 if the input, u, is used in the Outputs method. Setting the direct feedthrough flag to 0 tells the engine that u is not used in this S-function method. Violating this leads to unpredictable results.

  See Simulink.BlockData and its parent and children classes for a list of all the properties and methods associated with a Level-2 M-file S-function input port.

• Configure the block's output ports, including:

  • Specify the number of output ports that the block has, using s.NumOutputPorts.

  • Specify the dimensions of the ith output port, using s.OutputPort(i).Dimensions.

  • If using port-based sample times, specify the sample time of the ith output port, using s.OutputPort(i).SampleTime.

• Set the block-based sample times (i.e., sample rates), using s.SampleTimes.

  See Sample Times for a complete discussion of sample time issues.

  For multirate S-functions, the suggested approach to setting sample times is via the port-based sample times method. When you create a multirate S-function, you must take care to verify that, when slower tasks are preempted, your S-function correctly manages data so as to avoid race conditions. When port-based sample times are specified, the block cannot inherit a constant sample time at any port.

See Using the setup Method for additional information and examples using the setup method.

C Example

static void mdlInitializeSizes(SimStruct *S)
{
    int_T nInputPorts  = 1;  /* number of input ports  */
    int_T nOutputPorts = 1;  /* number of output ports */
    int_T needsInput   = 1;  /* direct feedthrough     */

    int_T inputPortIdx  = 0;
    int_T outputPortIdx = 0;

    ssSetNumSFcnParams(S, 0);  /* Number of expected parameters */
    if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {
        /*
         * If the number of expected input parameters is not
         * equal to the number of parameters entered in the 
         * dialog box, return. The Simulink engine generates an
         * error indicating that there is aparameter mismatch.
         */
        return;
    }else {
		     mdlCheckParameters(S);

		     if (ssGetErrorStatus(s) != NULL)
		        return;
	   }


    ssSetNumContStates(    S, 0);
    ssSetNumDiscStates(    S, 0);


    /*
     * Configure the input ports. First set the number of input
     * ports. 
     */
    if (!ssSetNumInputPorts(S, nInputPorts)) return;    
    /*
     * Set input port dimensions for each input port index 
     * starting at 0.

    */
     if(!ssSetInputPortDimensionInfo(S, inputPortIdx,
        DYNAMIC_DIMENSION)) return;
    /*
     * Set direct feedthrough flag (1=yes, 0=no).
     */
    ssSetInputPortDirectFeedThrough(S, inputPortIdx, needsInput);

    /*
     * Configure the output ports. First set the number of 
     * output ports.
     */
    if (!ssSetNumOutputPorts(S, nOutputPorts)) return;

    /*
     * Set output port dimensions for each output port index 
     * starting at 0.
     */
    if(!ssSetOutputPortDimensionInfo(S,outputPortIdx,
        DYNAMIC_DIMENSION)) return;

    /*
     * Set the number of sample times.     */
    ssSetNumSampleTimes(S, 1);   

    /*
     * Set size of the work vectors.
     */
    ssSetNumRWork(S, 0);   /* real vector    */
    ssSetNumIWork(S, 0);   /* integer vector */
    ssSetNumPWork(S, 0);   /* pointer vector */
    ssSetNumModes(S, 0);   /* mode vector    */
    ssSetNumNonsampledZCs(S, 0);   /* zero crossings */

    ssSetOptions(S, 0);

} /* end mdlInitializeSizes */

Languages

C, C++, M

mdlInitializeSampleTimes

mdlOutputs

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS