Main Content

function

Reuse expressions in component equations and in member declarations of domains and components

expand all in page

Parent Section: none (top-level)

Syntax

function out = FunctionName(in1,in2)
   definitions
      out = Expression1(in1,in2);
   end
end

Description

The function keyword begins the Simscape™ function declaration, which is terminated by an end keyword.

The keyword function must be followed by the function header, which includes the function name, inputs, and outputs.

The body of the function must be enclosed inside the definitions block, which is terminated by an end keyword. The definitions block contains equations that express the output arguments of the function in terms of its input arguments. This block is required.

The following syntax declares a simple function. 

function out = FunctionName(in1,in2)
   definitions
      out = Expression1(in1,in2);
   end
end

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

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

Depending on whether the Simscape function is a main or local function:

  • Main function — You must place the function declaration in a file of the same name with a file name extension of .ssc. The file name must match the function name. For example, function foo must be in a file called foo.ssc. The file must begin with the function keyword. Only blank lines and comments can precede function.

  • Local function — Include the function declaration in a component, domain, or function file, after the final end keyword that concludes the description of the component, domain, or main function. The local function is accessible only by that component, domain, or main function.

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 == FunctionName(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 for Function Files

Examples

expand all

This example shows how you can write a function that computes the square of a sum of two numbers, for reuse in multiple components.

Declare a function that computes the square of a sum of two numbers:

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

Save the function in a file named SumSquared.ssc, on the MATLAB path.

Use the function in a component. The MyComp component calls the SumSquared function to compute the square of a sum of its parameters p1 and p2.

component MyComp
   outputs
      o = 0;
   end
   parameters
      p1 = 5;
      p2 = 2;
   end
   equations
      o == SumSquared(p1,p2);
   end
end

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.

In this example, the rotational spring component uses a local function to modify its torque equation. The component file includes the local function localTorque after the final end keyword that concludes the description of the component:

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

Model Examples

Simscape Functions

Simscape Functions

Write Simscape™ functions to compute numerical values with Simscape expressions and how to use Simscape functions to improve code reuse across components. The top two Simscape component blocks ( inside the "Use no Simscape functions" box ) are respectively created using two Simscape component files. Comparing these two component files, similar Simscape expressions can be observed on the right hand side of the equation to compute numerical values, which is essentially a modification of exp(i) to provide protection for large magnitude of i. Such expressions are common in standard diode modeling. Using Simscape functions, such expressions are abstracted out into a Simscape function file, and their usages inside the component files are replaced by calls to such Simscape functions. The bottom two Simscape component blocks ( inside the "Use Simscape functions" box ) are created using component files using Simscape functions.

Version History

Introduced in R2017b

See Also

Topics