Main Content

Faults

Faults interface annotation for custom component

Since R2024b

expand all in page

Parent Section: annotations

Syntax

Faults = Fault(Name                     = 'FaultName', ...
               Switch                   = logical_p1, ...
               Values                   = [p1, p2], ...
               ExternalTrigger          = in1, ...
               TriggerType              = fault_trigger_type, ...
               BehavioralTriggerValues  = [p3, p4], ...
               Status                   = logical_p2,
               Transient                = true);

Description

In a custom component, you model fault behavior and triggering logic by using parameters, variables, equations, conditional expressions, and other Simscape™ language constructs. The Faults annotation provides the necessary information to the Simscape faults interface, which lets you model fault behaviors and trigger faults during simulation. 

annotations
  Faults = Fault(Name                     = 'FaultName', ...
                 Switch                   = logical_p, ...
                 Values                   = [p1, p2], ...
                 ExternalTrigger          = in1, ...
                 TriggerType              = fault_trigger_type, ...
                 BehavioralTriggerValues  = [p3, p4], ...
                 Status                   = logical,
                 Transient                = true);
end

Faults annotation elements are:

  • Name is the fault name. This element is required.

  • Switch is the logical parameter that enables the fault model. This element is required.

  • Values are the parameters that allow you to configure the fault behavior, for example, faulted resistance or failed voltage. These parameters appear in the faults interface, for example, in the Faults section of the block dialog box under the fault name, or under the corresponding fault behavior in the fault Property Inspector. This element is required.

  • ExternalTrigger is the input connected to a triggering source. Depending on the fault settings, this trigger can be always on, timed, conditional, and so on. The trigger can have a value of 0 (not faulted) or 1 (faulted). This element is required.

  • TriggerType is a parameter with a default value of enumeration class simscape.fault.triggertype. Supported values are: simscape.fault.triggertype.behavioral and simscape.fault.triggertype.external. This element is required only if you want to model behavioral faults because you need it to expose the Behavioral trigger option.

  • BehavioralTriggerValues are the parameters that allow you to configure the behavioral triggers, such as the maximum permissible current. These parameters appear in the faults interface when you set Trigger type to Behavioral.

  • Status is a variable, intermediate, or output that must be set to zero during nominal component behavior and to nonzero when a fault occurs. This element is required only if the TriggerType element is defined.

  • Transient is a logical attribute associated with the fault model. If true, the fault model supports switching from the faulted state back to nominal state. If false, the fault model only allows switching from nominal to faulted state once during simulation. The default is false.

You can list the annotation elements in any order.

A component can have only one Faults annotation section. You can define multiple faults as an array:

annotations
  Faults = [Fault(Name = 'Armature winding', Switch = ...)
            Fault(Name = 'Series field winding', Switch = ...)
            Fault(Name = 'Shunt field winding', Switch = ...)]
end

In a composite component, faults defined in its member components are exposed when the member component has these attributes: Access=public, ExternalAccess=observe. When you declare composite component members, this combination of attributes is the default, therefore, by default the member component faults are exposed. If you do not want the parent composite component to display the faults of a member component, set the member component Access attribute to protected. For example:

component RC
  components (Access = protected)
    r1 = foundation.electrical.elements.resistor(R=p1);
    c1 = foundation.electrical.elements.capacitor(c=p2);
  end
...
end

Examples

expand all

This example models an electrical fault as an instantaneous change in resistance based on an external trigger.

parameters
    R = {1, 'Ohm'}; % Resistance

    % Fault model parameters
    enableFault = false
    faultedResistance = {1000, 'Ohm'}
end
inputs
    externalFaultTrigger = 0
end

if ~enableFault
    equations
        v == i*R
    end
else
    equations
        if ~externalFaultTrigger
            v == i*R
        else
            v == i*faultedResistance
        end
    end
end

annotations
    Faults = Fault(Name                    = "Resistance", ...
                   Switch                  = enableFault, ...
                   Values                  = faultedResistance, ...
                   ExternalTrigger         = externalFaultTrigger)
end

This example models an electrical fault that, in addition to an external trigger, can also be triggered when current through the block exceeds a certain limit.

parameters
    R = {1, 'Ohm'}; % Resistance

    % Fault model parameters
    enableFault = false
    faultedResistance = {1000, 'Ohm'}

    % Behavioral fault trigger parameters
    triggerType = simscape.fault.triggertype.external
    failCurrent = {50, 'A'}
end
inputs
    externalFaultTrigger = 0
end

if ~enableFault
    equations
        v == i*R
    end
else  
    if triggerType == simscape.fault.triggertype.behavioral
    % behavioral trigger logic and status
        variables(Event=true)
            faulted = 0
        end
        % trigger the fault if current exceeds limit during simulation
        events
          when edge(i >= failCurrent) 
              faulted = 1
          end
        end
        % trigger the fault if current exceeds limit at start of simulation
        equations(Initial=true) 
            faulted == (i >= failCurrent)
        end
    else
    % external trigger status
        intermediates
            faulted = externalFaultTrigger
        end
    end
    equations
    % faulted is the fault status. It is either a variable or an intermediate,
    % depending on the trigger type if-else branch
        if ~faulted
            v == i*R
        else
            v == i*faultedResistance
        end
    end
end

annotations
    Faults = Fault(Name                    = "Resistance", ...
                   Switch                  = enableFault, ...
                   Values                  = faultedResistance, ...
                   ExternalTrigger         = externalFaultTrigger, ...
                   TriggerType             = triggerType, ...
                   BehavioralTriggerValues = failCurrent, ...
                   Status                  = faulted, ...
                   Transient               = true)
end

Version History

Introduced in R2024b

See Also

Topics