Main Content

annotations

Control appearance of Simscape block based on the component

expand all in page

Parent Section: 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'
   Faults = Fault(Name = 'FaultName',Switch = logical_param, ...) 
end

Description

annotations begins the annotations section, which is terminated by an end keyword. A component file can have multiple annotations sections, with each section containing one or more annotation declarations. However, component-level annotation, such as UILayout or Faults, can appear only once in a component file.

These annotation types control various cosmetic aspects of a Simscape™ block generated from the component:

  • ExternalAccess — 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.

  • UILayout — 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 component-level annotation, meaning that it can appear only once in a component file. For more information, see Group and Reorder Block Parameters Using Annotation.

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

  • Side — 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.

  • UnitDropdown — Prepopulate a unit drop-down list for a parameter in the block dialog box with commonly used units. The only accepted value is common.

These annotation types affect certain aspects of block functionality during simulation:

  • LoggingUnit — 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.

  • Faults — Categorize fault behavior and fault triggering information for your custom component. You model fault behavior and triggering logic by using other Simscape language constructs, such as parameters, equations, conditional assignments and expressions. The annotation provides the necessary information to the unified Faults interface, which lets you systematically model fault behaviors and trigger faults during simulation. Faults is a component-level annotation, meaning that it can appear only once in a component file. For more information, see Fault Annotations.

Examples

expand all

This 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

If the pipe is circular (control parameter Circular pipe? is set to true), the block dialog box displays only one parameter, Pipe internal diameter. If the control parameter is set to false, the pipe is noncircular and the dialog box displays the other two parameters instead.

This example customizes the names and locations of block ports. 

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

Custom block generated from this component 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.

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.

This 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

This 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

This 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

See Also

| | | | |

Topics