Main Content

Simscape Functions

Simscape™ functions model a class of pure first-order mathematical functions with explicit input-output relationship. These functions explicitly map the inputs of numerical values into outputs of numerical values by using declarative expressions. When a component calls a Simscape function, numerical input values are passed to the function, which then evaluates these declarative expressions to compute the output values.

There are two types of Simscape functions:

  • Main function — In general, the purpose of Simscape functions is to reuse expressions in equations of multiple components, as well as in member declarations of domain or component files. Each of these functions must be in a separate Simscape file, with the file name matching the function name.

  • Local function — In contrast, local Simscape functions reside inside a Simscape file that defines a component, domain, or another function, and are accessible only by that component, domain, or main function. For more information, see Local Simscape Functions.

Main Simscape Functions

Each main function must be in a separate Simscape file. The file name must match the function name. For example, function foo must be in a file called foo.ssc.

The Simscape function file must start with the keyword function, followed by the function header, which includes the function name, inputs, and outputs. For example:

function out = MyFunction(in1,in2)

If the function has multiple return values, the syntax is:

function [out1,out2] = MyFunction(in1,in2)

The body of the function must be enclosed inside the definitions section, for example:

function out = SumSquared(in1,in2)
   definitions
      out = in1^2 + 2*in1*in2 + in2^2;
   end
end

Syntax Rules

  • One or more output parameters are allowed.

  • If an output parameter is not used on the left-hand side of the definitions section, you get an error.

  • Zero or more input parameters are allowed.

  • When the function is called, the number of input arguments must match the number of input parameters.

  • Input parameters are positional. This means that the first input argument during the function call is passed to the first input parameter, and so on. For example, if you write an equation:

    o == SumSquared(5,2);

    then in1 is 5 and in2 is 2.

  • If the function has multiple return values, they are also positional. That is, the first output parameter gets assigned to the first return value, and so on.

  • If the function has multiple return values, the rules and restrictions are the same as for declaration functions. For more information, see Multiple Return Values.

  • The definitions section can contain intermediate terms and if-elseif-else statements. The same syntax rules as in the declaration section of a let statement apply. For more information, see Using Intermediate Terms in Equations.

  • The definitions section cannot contain expressions with dynamic semantics, such as integ, time, der, edge, initialevent, or delay.

Packaging Rules

Using Main Simscape Functions

The purpose of main Simscape functions is to reuse expressions in equations of multiple components, as well as in member declarations of domain or component files.

For example, exponential diode equations often use an expression that is a modification of exp(i), to provide protection for large magnitudes of i. For details, see Diode (Simscape Electrical) and NPN Bipolar Transistor (Simscape Electrical) block reference pages. The Simscape Functions example shows how you can write a Simscape function to reuse this expression, instead of repeating it in every block:

function out = userFunction(x,y,z)
definitions
    out = if x > y
        (x-z)*exp(y);
    elseif x < -z
        (x+y)*exp(-z);
    else
        exp(x)
    end
end
end

Then, the Diode block can call this function with y and z values of 80 and 79, respectively:

equations
   o == SimscapeFunction.Use.Functions.userFunction(i,80,79);
end

and the NPN Bipolar Transistor block can call the same function with values of 40 and 39:

equations
   o == SimscapeFunction.Use.Functions.userFunction(i,40,39);
end

Recommended Ways of Code Reuse

Simscape language has a variety of tools that facilitate code reuse. Simscape functions and declaration functions let you reuse expressions. Subclassing and composite components let you reuse equations.

To reuse expressions across multiple components:

  • Use main Simscape functions to reuse expressions in equations and member declarations.

  • Use declaration functions in member declarations to reuse expressions that are out of Simscape expression capability. For more information, see Declaration Functions.

FunctionalityAuthoring LanguageFile extensionUsage Supports Arguments with Units

Simscape function

Simscape

.ssc or .sscp

Member declaration and equations

Yes

Declaration function

MATLAB

.m or .p

Member declaration only

No

To reuse equations across multiple components:

  • Use subclassing to model the "is-a" relationship between the base component and the derived component. The equations in the base component are reused in the derived component. For more information, see Subclassing and Inheritance.

  • Use composite components to model the "has-a" relationship between the container component and the subcomponents. The equations in the member components are reused in the composite component. For more information, see About Composite Components.

Local Simscape Functions

Local Simscape functions reside inside a Simscape file that defines a component, domain, or another function, and are accessible only by that component, domain, or main function. For example, when you need to use a function in a single component only, defining it as a local function:

  • Reduces the overhead of creating and packaging separate files.

  • Restricts access, to ensure that only that specific component can use this function.

Include the local Simscape function in a component, domain, or function file, after the final end keyword that concludes the description of the component, domain, or main function. For example, this rotational spring component uses a local function to modify its torque equation:

component spring_with_local_function
  nodes
    r = foundation.mechanical.rotational.rotational;
    c = foundation.mechanical.rotational.rotational;
  end
  parameters
    k = { 10, 'N*m/rad' };
  end
  variables
    theta = { 0, 'rad' };
    t = { 0, 'N*m' };        % torque through
    w = { 0, 'rad/s' };      % velocity across
  end
  branches
    t : r.t -> c.t; % torque through from node r to node c
  end
  equations
    assert(k>0)     % spring rate must be greater than zero
    w == r.w - c.w; % velocity across between node r and node c
    t == localTorque(k,theta);
    w == theta.der;
  end
end

function out = localTorque(in1,in2)
   definitions
      out = (in1*in2)*9.76; % Modification made to torque relationship
   end
end

The syntax rules for local functions are the same as for main functions. See Syntax Rules.

You can have multiple local functions declared in the same component, domain, or function file.

Local functions can contain calls to other local functions, in the same file, or to main functions in other files. In case of a name conflict, local functions have higher call precedence than main functions.

See Also

Related Examples

More About