setup

(Not recommended) Prepare component for simulation

setup is not recommended. For more information, see Version History.

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 Choose Command Syntax or 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   

Version History

Introduced in R2008b

R2019a: setup is not recommended

Starting in R2019a, run-time capable domain parameters have been implemented. Unlike component parameters, domain parameters propagate to other components connected to the circuit. Therefore, when you set the parameter as Run-time in the source component, it is possible that another component connected to the same circuit is using this parameter in the context which prevents it from being run-time configurable. For example, if one of the components connected to the circuit uses a domain parameter in its setup function, you get an error when trying to simulate the model.

There are no plans to remove setup at this time. However, to avoid errors with run-time domain parameters, it is recommended that you avoid using the setup function in your custom components. Other constructs available in Simscape language let you achieve the same results without compromising run-time capabilities.

Task	Recommended Technique
Validate parameters	Use an assert construct. For more information, see Programming Run-Time Errors and Warnings.
Compute derived parameters	Use declaration functions. For more information, see Declaration Functions.
Set initial conditions	Assign variable priority and target value. For more information, see Variable Priority for Model Initialization.
Designate source for domain parameters	Use direct assignment to a domain parameter in the component node declaration. For more information, see Source Components.