annotations

Control appearance of Simscape block based on the component

Syntax

annotations
   [Id1, Id2] : ExternalAccess=value;
   UILayout = [UIGroup("Title 1",p1,p2) UIGroup("Title 2",p3)] 
   Icon = 'filename';
   [port1, port2] : Side=value;
   [param1, param2] : UnitDropdown = common
   [var1, int2] : LoggingUnit = 'unit expression'
end

Description

annotations begins the annotations section, which is terminated by an end keyword. The annotations section in a component file lets you provide annotations that control various cosmetic aspects of a Simscape™ block generated from this component.

Use the annotations section to:

• Define conditional visibility of component members, such as parameters, variables, nodes, inputs, and outputs, in block icons and dialog boxes. Possible values are: modify, observe, and none.

• Specify block interface layout by defining titled groups of component parameters, the order of these groups, and the order of parameters in each group. When you deploy the component as a custom Simscape block, these groups translate into dialog box tabs (and into Property Inspector tree nodes). UILayout is a class-level annotation, meaning that it can appear only once per component file. For more information, see Group and Reorder Block Parameters Using Annotation.

• Specify a custom block icon and change it based on the block variant.

• Control port location by placing it on a specific side of the block icon. Ports on a block icon correspond to nodes, inputs, and outputs declared in the underlying component file. Possible values are: left, right, top, and bottom.

• Prepopulate a unit drop-down list for a parameter in the block dialog box with commonly used units.

• Specify a preferred data logging unit for component members, such as intermediates, variables, inputs, and outputs. If specified, the same unit is also used for other display purposes, such as in the Variable Viewer or in the operating point.

  The specified logging unit must be commensurate with the intrinsic unit of the component member, such as the declared unit of a variable, typed input, or typed output. For intermediates and untyped inputs and outputs, the intrinsic unit is computed by the compiler.

Examples

The following example hides inapplicable parameters from the block dialog box based on the control parameter value.

component MyPipe
  parameters
    circular  = true;             % Circular pipe?
    d_in      = { 0.01, 'm' };    % Pipe internal diameter
    area      = { 1e-4, 'm^2' };  % Noncircular pipe cross-sectional area
    D_h       = { 1.12e-2, 'm' }; % Noncircular pipe hydraulic diameter
  end
  if circular 
  % Hide inapplicable parameters
    annotations
       [area, D_h] : ExternalAccess=none;
    end
    equations
       % First set of equations, for circular pipe 
    end
  else
  % Hide inapplicable parameter
    annotations
       d_in : ExternalAccess=none;
    end
    equations
       % Second set of equations, for noncircular pipe 
    end
  end
  [...] % Other parameters, variables, branches, equations
end

The next example exposes a thermal port H and changes the customized block icon based on the control parameter value.

parameters
    thermal_effects = false; % Model thermal effects?
end
nodes (ExternalAccess=none)
   H = foundation.thermal.thermal; 
end
if thermal_effects 
  % Use icon with additional thermal port
    annotations
       H : ExternalAccess=modify;
       Icon = 'pipe_thermal.jpg';
    end
end

The following example customizes the names and locations of block ports. The block contains two electrical ports, labeled + and -, located on the left and right sides of the block icon, respectively, and a thermal port H, located on the top side.

nodes
    H = foundation.thermal.thermal; 
    p = foundation.electrical.electrical; % +
    n = foundation.electrical.electrical; % -
end
annotations
    H : Side = top;
    p : Side = left;
    n : Side = right;
end

Note

You cannot conditionally switch port sides, that is, include Side annotations in branches of a conditional statement. For more information, see Control Port Locations Using Annotations.

The next example specifies that the drop-down list for the Gain parameter includes a list of common units, such as those available in the Simulink-PS Converter and the PS-Simulink Converter block dialog boxes.

annotations
    Gain : UnitDropdown = common
end
 

The following example specifies the preferred data logging unit for intermediate i. This intermediate is the product of two parameters, p1 and p2. The specified unit, J, is commensurate with the intrinsic unit of i, which is the product of two parameters' units, lb*ft.

component mycomp
 
parameters
  p1 = {10,'lb'};
  p2 = {5, 'ft'};
end
 
intermediates
  i = p1*p2;
end
 
annotations
  i : LoggingUnit = 'J'
end
 
...

Note

Once specified, this preferred data logging unit is also used for other display purposes, such as in the Variable Viewer or in the operating point.

Version History

Introduced in R2019a