Defining Component Setup

Setup Section Purpose

The setup section of a Simscape™ file follows the declaration section and consists of the function named setup. The setup function is executed once for each component instance during model compilation. It takes no arguments and returns no arguments.

    Note   Setup is not a constructor; it prepares the component for simulation.

Use the setup function for the following purposes:

The following rules apply:

  • The setup function is executed as regular MATLAB® code.

  • All members declared in the component are available by their name, for example:

    component MyComponent
       parameters
          p = {1, 'm' };
       end
       [...]
       function setup
          disp( p ); % during compilation, prints value of p 
                     % for each instance of MyComponent in the model
       [...]
    end   
  • All members (such as variables, parameters) that are externally writable are writable within setup. See Member Summary for more information.

  • Local MATLAB variables may be introduced in the setup function. They are scoped only to the setup function.

The following restrictions apply:

  • Command syntax is not supported in the setup function. You must use the function syntax. For more information, see Command vs. Function Syntax in the MATLAB Programming Fundamentals documentation.

  • Persistent and global variables are not supported. For more information, see Persistent Variables and Global Variables in the MATLAB Programming Fundamentals documentation.

  • MATLAB system commands using the ! operator are not supported.

  • try-end and try-catch-end constructs are not supported.

  • Nested functions are not supported.

  • Passing declaration members to external MATLAB functions, for example, my_function(param1), is not supported. You can, however, pass member values to external functions, for example, my_function(param1.value('unit')).

Validating Parameters

The setup function validates parameters using simple if statements and the error function. For example:

component MyComponent
   parameters
      LowerThreshold = {1, 'm' };
      UpperThreshold = {1, 'm' };
   end
   [...]
   function setup
      if LowerThreshold > UpperThreshold 
         error( 'LowerThreshold is greater than UpperThreshold' );
      end
   end
   [...]
end   

Computing Derived Parameters

The setup function can override parameters by assigning to them. For example, it can verify that a parameter is not greater than the maximum allowed value, and if it is, issue a warning and assign the maximum allowed value to the parameter:

component MyComponent
   parameters
      MyParam = {1, 'm' };
   end
   [...]
   function setup
      MaxValue = {1, 'm' };
      if MyParam > MaxValue 
         warning( 'MyParam is greater than MaxValue, overriding with MaxValue' );
         MyParam = MaxValue;
      end
   end
   [...]
end   

    Note   Members are strongly typed. In the example above, MaxValue must have the same data type and compatible unit as MyParam. Otherwise, you will get an error.

Setting Initial Conditions

As you declare variables, values that you assign to them are their initial conditions. However, you can use the setup function to override these initial conditions by assigning the variable a new value, for example:

component MyComponent
   variables
      Speed = { 10, 'm/s' };
   end
 	[...]
   parameters
      InCollision = 0;  % Specifies whether bodies are in collision
   end
   [...]
   function setup
      if InCollision > 0 
         Speed = { 0, 'm/s' };   % Speed(t = 0) = 0 because bodies are in collision
      end
   end
   [...]
end   

    Note   Variables are also strongly typed. The initial value you assign to the variable must have the same data type and compatible unit as the variable. Otherwise, you will get an error.

Was this topic helpful?