Documentation

Defining Component Setup

Setup Section Purpose

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.

Use the setup function for the following purposes:

Rules and Restrictions

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

Simple Setup

In general, you cannot specify 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 it as simple:

function setup %#simple
   [...]
end

In this case, many of the parameters used in the setup function can be selected as run-time parameters. In the following example, p can be a run-time parameter:

component C
  parameters
    p = 0;
  end
  parameters(Access=private)
    pDerived = 0;
  end
  variables(Access=private)
    vDerived = 0;
  end
  function setup %#simple
    if p < 0
      error('id:id', 'invalid p');
    end
    pDerived = p^2 + 2 * p;
    vDerived.value = pDerived + 1;
    vDerived.priority = simscape.priority.high;
  end
  equations
    ...
  end
end

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 assignment 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.

Related Examples

Was this topic helpful?