setup

(Not recommended) Prepare component for simulation

setup is not recommended. For more information, see Compatibility Considerations.

Syntax

function setup
[...]
end

function setup %#simple
[...]
end

Description

function setup
[...]
end

The setup section of a Simscape™ file 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.

The body of the setup function can contain assignment statements, if and error statements, and across and through functions. The setup function is executed once for each component instance during model compilation. It takes no arguments and returns no arguments.

Use the setup function for the following purposes:

  • Validating parameters

  • Computing derived parameters

  • Setting initial conditions

The following rules apply:

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

  • All parameters and variables 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

  • You can use variable names only on the left-hand side of the assignments in the setup section. Parameter names can be used on either side.

  • All parameters and variables that are externally writable are writable within setup.

  • In case of conflict, assignments in the setup section override those made in the declaration section. To ensure proper block operation, if you assign a value to a member in the setup section, declare this member with an attribute that prevents it from appearing in the block dialog box, such as (ExternalAccess=observe). Otherwise, the assignment made in the setup section will override the values specified in the dialog box by the block user. See Attribute Lists 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.

  • Persistent and global variables are not supported. For more information, see Persistent Variables and Global Variables.

  • 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')).

Simple Setup

In general, you cannot designate a block parameter as run-time if the underlying component uses it in the setup function. However, if the setup is restricted to simple operations like error-checking, you can declare the setup function as simple:

function setup %#simple
[...]
end

In this case, many of the parameters used in the setup function can be designated as run-time parameters.

When you declare setup function as simple, the following rules apply:

  • All expressions used in a simple setup function must restrict themselves to those supported elsewhere in Simscape language. For a complete list of supported functions, see equations.

  • A value, parameter or variable, may be assigned to only once on any given path through the setup function.

  • All reads from a parameter must appear after it is assigned in a setup function.

  • All assignments must end in a semicolon.

  • All members that are assigned to must be private parameters or variables of the current component. Simple setup cannot assign to members of child components or members of a base class.

  • You can declare local MATLAB variables in a simple setup function, but these variables cannot be structures.

  • Arguments of error and warning functions must be literal strings.

In general, making a setup function simple means that all parameters are run-time capable. The exception are those parameters that drive conditional assignment: 

 if p1 > 0
   p3 = f1(p2);
 else
   p3 = f2(p2);
 end

In this case, p1 must be compile-time. However, only those parameters that affect conditional assignment are compile-time. Those that affect error conditions are run-time capable.

Examples

The following setup function validates parameters using an if statement and the error function.

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

To avoid using setup, rewrite this example as follows:

component MyComponent
   parameters
      LowerThreshold = {1, 'm' };
      UpperThreshold = {1, 'm' };
   end
   [...]
   equations
      assert(LowerThreshold<UpperThreshold,'LowerThreshold is greater than UpperThreshold');
      [...]
   end
   [...]
end

Compatibility Considerations

expand all

Not recommended starting in R2019a

See Also

Topics

Introduced in R2008b

Simscape Documentation

Support