Main Content

Declaration Functions

You can use declaration functions to compute derived parameter values or initialize variables, instead of doing this inside the setup function.

Note

Starting in R2019a, using setup is not recommended. Other constructs available in Simscape™ language let you achieve the same results without compromising run-time capabilities. For more information, see setup is not recommended.

Declaration function is a MATLAB® function used inside a member declaration section in a Simscape file. A declaration function can be any MATLAB function (even if it is not supported in the Simscape language equations section), including user-defined functions on the MATLAB path. For example:

component A
  parameters
    p1 = 1;
    p2 = 0;
  end
  parameters(Access = private)
    pDerived = gamma(p1) + p2;
  end
  variables(Access = private)
    vDerived = {value = {my_fcn(p1,p2) + 1, 'm'}, priority = priority.high };
  end
  equations
    ...
  end
end

Use the Access=private attribute for member declaration unless all the arguments of the declaration function are constants.

Exercise caution when using persistent variables inside a declaration function, because this may lead to inconsistent results for multiple simulation runs.

Multiple Return Values

Declaration functions can return multiple values. They follow the general MATLAB function conventions for multiple return values. For example, if my_fcn() is a declaration function that returns three values: 

[id1, ~, id3] = my_fcn();  % omit the second return value
[id1] = my_fcn();  % rules of single assignment apply, nonrequested return values ignored

The following restrictions apply:

  • You can use multiple value assignments on the left-hand side only for parameters and variables with the Access=private attribute.

  • When omitting return values using the placeholder attribute (~), at least one value must be assigned. Empty declarations produce an error in Simscape language.

Restriction on Values with Units

Inputs and outputs of a declaration function must be unitless, that is, have a unit of '1'. Therefore, you cannot directly pass parameter values, with units, as declaration function inputs.

For example, parameter p has the units of 'm'. To use it as an input for the myfcn function, use the value function to get the unitless value of the parameter.

parameters
      p = {1,'m'}
end
parameters(Access = private)
      pd = my_fcn(value(p,'m'));   % extract unitless value from p
end

In the previous example, pd is a unitless parameter. To declare it as a value with unit, use the {value,'unit'} syntax, for example:

      pd = {my_fcn(value(p,'m')),'m/s'};

For multiple input and return values with units, use this syntax:

      [y_value,z_value] = my_fcn(value(a,'V'),value(b,'V'));
      y = {y_value,'V'};
      z = {z_value,'V'};

For more information, see Declaring a Member as a Value with Unit.

Run-Time Compatibility

Member declarations for parameters and variables can include calls to MATLAB functions that generate code.

By default, the declaration function will be evaluated at run time if a run-time parameter appears in its input parameters. Otherwise, it will be evaluated at compile time.

In this example, my_fcn is a MATLAB function that supports code generation:

component A
  parameters
    p1 = 1;
    p2 = 0;
  end
  parameters(Access = private)
    pDerived = my_fcn(p1,p2);
  end
  equations
    ...
  end
end

If p1 or p2 is designated as Run-time in the block dialog, then my_fcn is evaluated at run time, and you can tune these parameter values without regenerating code.

If my_fcn does not support code generation, you can set the member attributeMATLABEvaluation=compiletime, to prevent the block user from accidentally designating any of the function input parameters as Run-time in the block dialog:

component A
  parameters
    p1 = 1;
    p2 = 0;
  end
  parameters(Access = private,MATLABEvaluation = compiletime)
    pDerived = my_fcn(p1,p2);
  end
  equations
    ...
  end
end

If you set this attribute, the declaration function will be evaluated only at compile time, and the block parameters p1 and p2 will be marked as Compile-time only.

To work with run-time parameters:

  • The declaration function must be in an unprotected MATLAB file

  • All MATLAB code called must be MATLAB Coder™ compatible

  • Subfunctions can be in protected MATLAB files, but to use them with run-time parameters:

    • Use coder.allowpcode('plain')

    • Turn on lint: %#codegen

For more information, see Run-Time Parameters.