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. In Simulink^® models, this argument is the path to a block output or input port. In Simscape™ blocks, this argument is the path to a fault-capable model subelement. In System Composer™ models, this argument is the path to a component output or input port.

Example: 'myModel/Sine Wave/Outport/1'

Data Types: char

Type — Model element type

'Simulink' | 'Simscape' | 'System Composer'

This property is read-only.

Model element type that contains the fault, returned as either 'Simulink', 'Simscape', or 'System Composer'.

Data Types: enumeration

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" | "Manual" | "Behavioral"

Fault trigger type, specified as "Always On", "Timed", "Conditional", "Manual" (since R2024a), 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. You can set this property to "Behavioral" only for faults on Simscape blocks.

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.

TriggerActive — Status of manual trigger

false or 0 | true or 1 | []

Since R2024a

Status of the manual trigger, specified as a numeric or logical 0 (false) or 1 (true). You can adjust this property only if the fault has assigned behavior and the TriggerType property to "Manual". Otherwise, the property returns an empty value. To add behavior, use the addBehavior function. When the status is 0, the manual trigger is off. When the status is 1, the manual trigger is on.

Data Types: logical

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 and fault model

Examples

Add a Fault to a Model

Open the fault_analyzer_intro model.

openExample('faultanalyzer/FaultAnalyzerIntroExample')

Add a fault to the output port of the Sine Wave block.

fault = Simulink.fault.addFault(...
"fault_analyzer_intro/Sine Wave/Outport/1");

Add a Fault with Behavior

Open the fault_analyzer_intro model.

openExample('faultanalyzer/FaultAnalyzerIntroExample')

Add a fault to the output port of the Sine Wave block.

myFault = Simulink.fault.addFault(...
"fault_analyzer_intro/Sine Wave/Outport/1");

Assign noise behavior to the fault, storing the behavior in a fault model named myBehaviorModel on the path.

addBehavior(myFault,"myBehaviorModel",...
FaultBehavior="mwfaultlib/Add Noise");

Find Faults Without Behavior

Open the sldemo_fuelsys_fault_analyzer model in the Evaluate Fault Combinations on a Fault-Tolerant Fuel System example and set up the faults.

openExample('faultanalyzer/EvaluateFaultsForFuelSystemExample')
model = "sldemo_fuelsys_fault_analyzer";
open_system(model)
fuelSysFaultSetup

Add two faults to the first input port of the subsystem, To Controller, that do not have behavior.

Simulink.fault.addFault(...
model + "/To Controller/Inport/1",Name="myFault1");
Simulink.fault.addFault(...
model + "/To Controller/Inport/1",Name="myFault2");

Find the faults that do not have behavior.

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

Version History

Introduced in R2023b

R2024a: Manual trigger support

Manually control when faults inject during simulation by assigning them a manual trigger. See Manually Trigger Faults in Models.