Fault

Create or modify faults in models

Since R2023b

Description

Fault objects represent faults, such as noise, in the output of a model element. Use Fault objects to perform fault injection in your models. You can modify the fault by setting the object properties.

Creation

To create a Fault object:

• Use the Simulink.fault.addFault function.

• Create a fault interactively in a model, then get the associated Fault object by using the Simulink.fault.findFaults function.

Properties

Name — Name of fault

string scalar | character vector

Name of the fault, specified as a string scalar or character vector.

Data Types: char | string

Description — Description of fault

'' (default) | string scalar | character vector

Description of the fault, specified as a string scalar or character vector.

Data Types: char | string

ModelElement — Path of model element

character vector

This property is read-only.

Path or handle of model element, returned as a character vector. This argument is the path to a fault-capable model subelement.

Example: 'myModel/DC Motor/Armature winding'

Data Types: char

IsActive — Whether fault is active

1 | 0

This property is read-only.

Whether the fault is active, returned as 1 (true) or 0 (false). This property returns 1 only if the fault is active, the model element is enabled, and fault simulation is on. You can specify only one active fault for each model element.

To adjust this property, use the activate function.

Data Types: logical

IsTriggered — Whether fault is injected

1 | 0

This property is read-only.

Whether the fault is injected, returned as 1 (true) or 0 (false). This property returns 1 if the fault is injected at the current time step. Otherwise, it returns 0.

Data Types: logical

HasBehavior — Whether fault has behavior

1 | 0

This property is read-only.

Whether the faults have assigned behavior, returned as 1 (true) or 0 (false).

To adjust this property, use the addBehavior function to add behavior and the deleteBehavior function to delete the behavior.

Data Types: logical

TriggerType — Fault trigger type

"Always On" | "Timed" | "Conditional" | "Behavioral"

Fault trigger type, specified as "Always On", "Timed", "Conditional", "Manual" (since R2024b), or "Behavioral". If you specify TriggerType as "Conditional", create the conditional by using the Simulink.fault.addConditional function, then set the Conditional property of the Fault object to the new Conditional object.

You can adjust this property only if the fault has assigned behavior. To add behavior, use the addBehavior function.

Data Types: enumeration

Persistent — Whether fault trigger is irreversible

false or 0 | true or 1

Whether the fault trigger is irreversible, specified as a numeric or logical 0 (false) or 1 (true). When this property is true, the fault injects when the conditional first satisfies, then continues to inject until simulation ends. When this property is false, the fault injects only when the conditional expression is satisfied.

You can adjust this property only if the fault has assigned behavior and the TriggerType property is set to "Conditional". To add behavior, use the addBehavior function. To create conditionals, use the Simulink.fault.addConditional function. Assign the Conditional object to the Fault object by using dot notation.

Data Types: logical

StartTime — Time when fault triggers

numeric scalar

Time when the fault triggers during simulation, specified as a numeric scalar.

You can adjust this property only if the fault has assigned behavior and the TriggerType property is "Timed". To add behavior, use the addBehavior function.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Conditional — Conditional assigned to fault

Conditional object

Conditional assigned to the fault, specified as a Conditional object.

You can adjust this property only if the fault has assigned behavior and the TriggerType property is "Conditional". To add behavior, use the addBehavior function. To create conditionals, use the Simulink.fault.addConditional function. Assign the Conditional object to the Fault object by using dot notation.

Object Functions

activate	Set fault as active fault
addBehavior	Add signal behavior to fault
deleteBehavior	Delete behavior associated with fault
getAssociatedModel	Retrieve name of model fault
getBehavior	Get path of associated Fault Subsystem block
getFaultInfoFile	Get name of fault information file
getFaultModel	Get name of fault model
openBehavior	Open fault behavior

Examples

Add a Fault to Model Subelement

Open a model with a block that supports fault modeling.

openExample('simscape_shared/SimpleMotorArmatureWindingFaultExample')

Add a fault to the Armature winding model subelement in the DC Motor block.

Simulink.fault.addFault(...
"SimpleMotorArmatureWindingFault/DC Motor/Armature winding")

ans = 

  Fault with properties:

            Name: 'DCMotor_fault'
     Description: ''
    ModelElement: 'SimpleMotorArmatureWindingFault/DC Motor/Armature winding'
            Type: 'Simscape'
        IsActive: 0

Find Faults Without Behaviors

Open a model with a block that supports fault modeling.

openExample('simscape_shared/SimpleMotorArmatureWindingFaultExample')

Add a fault to the Armature winding model subelement in the DC Motor block.

Simulink.fault.addFault(...
"SimpleMotorArmatureWindingFault/DC Motor/Armature winding");

Find the faults that do not have behavior.

myFaults = Simulink.fault.findFaults(...
"SimpleMotorArmatureWindingFault",HasBehavior=false)

myFaults = 

  Fault with properties:

            Name: 'DCMotor_fault'
     Description: ''
    ModelElement: 'SimpleMotorArmatureWindingFault/DC Motor/Armature winding'
            Type: 'Simscape'
        IsActive: 0

Version History

Introduced in R2023b

R2024a: Manual trigger support

Manually control when faults inject during simulation by assigning them a manual trigger. To learn more, see Manually Trigger Faults in Models.