The faultdiagnosistoolbox package

class faultdiagnosistoolbox.DiagnosisModel(modeldef, name='')

Diagnosis model.

Parameters:

• model_def (dict) – A dictionary with the following keys:

• type (string) – type of model (Symbolic, VarStruc, MatrixStruc)

• x (list) – list of unknown variables in the model

• f (list) – list of fault variables

• z (list) – list of known variables

• rels (list) – list of model equations (in case of symbolic model)

• X/F/Z (arraylike) – structure matrices (in case of MatrixStruc model)

• parameters (list) – list of parameters (optional) For the induction motor model, this corresponds to

Example

Consider a dynamic model described by the equations below with unknown variables x = (i_a, i_b, lambda_a, lambda_b, w, di_a, di_b, dlambda_a, dlambda_b, dw, q_a, q_b, Tl), three measurements y1, y2, y3, and known input controls u_a, u_b, i.e., z = (u_a, u_b, y1, y2, y3), and two sensor faults f=(f_a, f_b).

To define a symbolic model, define model variables,

>>> model_def = {'type': 'Symbolic',
                 'x': ['i_a', 'i_b', 'lambda_a', 'lambda_b', 'w',
                     'di_a', 'di_b', 'dlambda_a', 'dlambda_b', 'dw', 'q_a', 'q_b', 'Tl'],
                 'f': ['f_a', 'f_b'],
                 'z': ['u_a', 'u_b', 'y1', 'y2', 'y3'],
                 'parameters': ['a', 'b', 'c', 'd', 'L_M', 'k', 'c_f', 'c_t']}

and make variables symolic using SymPy, for example as:

>>> sym.var(model_def['x'])
>>> sym.var(model_def['f'])
>>> sym.var(model_def['z'])
>>> sym.var(model_def['parameters'])

Then, the model equations can be represented by

>>> model_def['rels'] = [
    -q_a + w*lambda_a,
    -q_b + w*lambda_b,
    -di_a + -a*i_a + b*c*lambda_a + b*q_b + d*u_a,
    -di_b + -a*i_b + b*c*lambda_b + b*q_a + d*u_b,
    -dlambda_a + L_M*c*i_a - c*lambda_a-q_b,
    -dlambda_b + L_M*c*i_b - c*lambda_b-q_a,
    -dw + -k*c_f*w + k*c_t*(i_a*lambda_b - i_b*lambda_a) - k*Tl,
    fdt.DiffConstraint('di_a','i_a'),
    fdt.DiffConstraint('di_b','i_b'),
    fdt.DiffConstraint('dlambda_a','lambda_a'),
    fdt.DiffConstraint('dlambda_b','lambda_b'),
    fdt.DiffConstraint('dw','w'),
    -y1 + i_a + f_a,
    -y2 + i_b + f_b,
    -y3 + w]

Now, the model can be defined using

>>> model = fdt.DiagnosisModel(model_def, name ='Induction motor')

AddSensors(sensors, name=None, fault=None)

Add sensor equations to a model.

Parameters:

• sensors (Description of sensors to add s can be a list of strings) –

  with the names of sensors to add or indices into the known variables (model.x) which sensors to add.

  It is only possible to add sensors measuring single variables in x. If functions of variables in x are measured, extend the model with a new variable first.

  If the corresponding variable can be faulty, see class method SensorLocationsWithFaults, a fault will be added automatically.

• name (List with names of new sensor variables)

• fault (List with names of fault variables for new sensors)

AlgebraicVariables() → tuple[list, list[int]]

Return variables and index to algebraic variables in model.

DetectabilityAnalysis(causality='mixed')

Perform a structural detectability analysis.

Parameters:

causality (Can be 'mixed' (default), 'int', or 'der' for mixed,) –

integral, or derivative causality analysis respectively. For details, see

Frisk, E., Bregon, A., Aaslund, J., Krysander, M., Pulido, B., Biswas, G., “Diagnosability analysis considering causal interpretations for differential constraints”, IEEE Transactions on Systems, Man and Cybernetics, Part A: Systems and Humans, 2012, 42(5), 1216-1229.

Returns:

• df (Detectable faults)

• ndf (Non-detectable faults)

DifferentialConstraints() → bool

Return indices to the differential constraints.

DynamicVariables() → tuple[list, list[int]]

Return variables and index to dynamic variables in model.

FSM(eqs_sets, plot=False) → ndarray

Return the fault signature matrix for a set of equation sets.

Parameters:

• eqs_sets (list of sets of equations, e.g., MSO sets)

• Plot (If True, plot the fault signature matrix (dafault: False))

GetDMParts() → DMResult

Return Dulmage-Mendelsohn decomposition of structure for unknown variables.

IsDynamic() → bool

Return True if model is dynamic.

IsHighIndex(eq=None) → bool

Return true if the model is high structural differential index.

Parameters:

eq (Set of equations to analyze. (default: all equations))

IsLowIndex(eq=None) → bool

Return true if the model is low structural differential index.

Parameters:

eq (Set of equations to analyze. (default: all equations))

IsObservable(eq=None) → bool

Return true if the model is observable.

Parameters:

eq (Set of equations to analyze. (default: all equations))

IsPSO(eq=None) → bool

Return True if the model is a PSO set.

Parameters:

(optional) (eq)

IsStatic() → bool

Return True if model is static.

IsUnderdetermined() → bool

Return true if the model has underdetermined parts.

IsolabilityAnalysis(ax=None, permute=True, causality='mixed')

Perform structural single fault isolability analysis of model.

Parameters:

• ax – If not None, plot the isolability matrix in the specified axis

• permute – If True, permute the fault variables such that the isolability matrix gets a block structure for easier interpretation when plotted. Does not affect the output argument im, only the plot (default True)

• causality –

  Can be ‘mixed’ (default), ‘int’, or ‘der’ for mixed, integral, or derivative causality analysis respectively. For details, see

  Frisk, E., Bregon, A., Aaslund, J., Krysander, M., Pulido, B., Biswas, G., “Diagnosability analysis considering causal interpretations for differential constraints”, IEEE Transactions on Systems, Man and Cybernetics, Part A: Systems and Humans, 2012, 42(5), 1216-1229.

Returns:

Isolability matrix, im(i,j)=1 if fault i can be isolated from fault j, 0 otherwise

Return type:

im

IsolabilityAnalysisArrs(arrs, permute=True, ax=None)

Perform structural single fault isolability analysis of a set of ARRs.

Parameters:

• arrs – List of ARRs, e.g., list of MSO sets

• ax – If not None, plot the isolability matrix in the specified axis

• permute – If True, permute the fault variables such that the isolability matrix gets a block structure for easier interpretation when plotted. Does not affect the output argument im, only the plot (default True)

Returns:

im – from fault j, 0 otherwise

Return type:

Isolability matrix, im(i,j)=1 if fault i can be isolated

IsolabilityAnalysisFSM(FSM, permute=True, ax=None)

Perform structural single fault isolability analysis of a fault sensitivity matrix (FSM).

Parameters:

• FSM – Fault sensitivity matrix

• ax – If not None, plot the isolability matrix in the specified axis

• permute – If True, permute the fault variables such that the isolability matrix gets a block structure for easier interpretation when plotted. Does not affect the output argument im, only the plot (default True)

Returns:

Isolability matrix, im(i,j)=1 if fault i can be isolated from fault j, 0 otherwise

Return type:

im

Lint()

Print model information and checks for inconsistencies in model definition.

LumpDynamics()

Lump the dynamics variables.

If model is symbolic, it will be converted into a structural model

MSO() → list[ndarray]

Return the set of MSO sets.

For details of the algorithm see the journal publication Krysander, Mattias, Jan Aslund, and Mattias Nyberg. “An efficient algorithm for finding minimal overconstrained subsystems for model-based diagnosis.” Systems, Man and Cybernetics, Part A: Systems and Humans, IEEE Transactions on 38.1 (2008): 197-206.

MSOCausalitySweep(mso, diffres='int', causality=None) → list[str]

Determine casuality for MSO set residual generator.

Determine causality for sequential residual generator for each n residual equations for a given MSO set.

Parameters:

• mso – list of equations

• diffres – Can be ‘int’ or ‘der’ (default ‘int’). Determines how to treat differential constraints when used as a residual equation.

• causality – Can be ‘int’ or ‘der’. When causality is specified, the call returns a boolean vector indicating if it is possible to realize the residual generator in derivative or integral causality respectively with the corresponding equations as residual equation. If this option is given, the diffres key have no effect.

MSOdifferentialOrder(mso)

Determine the number of required differentiations of each equation, each known variable in the model to obtain an ARR.

Parameters:

• model (DiagnosisModel) – Model object

• mso (np.array) – Array of equations

Returns:

Array of the required number of differentiations of each equation.

zIdx (np.array): The known variables included as an array of indices.

zOrder (np.array): Array of the highest order of derivatives of each known variable.

fIdx (np.array): The fault variables included as an array of indices.

fOrder (np.array): Array of the lowest order of derivatives of each fault variable.

Return type:

eqOrder (np.array)

MTES() → list[ndarray]

Return the set of MTES sets.

For details of the algorithm see the paper A Structural Algorithm for Finding Testable Sub-models and Multiple Fault Isolability Analysis. Mattias Krysander, Jan Åslund, and Erik Frisk (2010). 21st International Workshop on Principles of Diagnosis (DX-10). Portland, Oregon, USA.

MTESRedundancy() → int

Return the redundancy of an MTES for the model.

Matching(eqs) → Matching

Return a matching for a set of equations.

Parameters:

eqs (Set of equations)

MeasurementEquations(m)

Return indices to measurement equations.

Parameters:

m (List of names for measurement variables (strings))

Pantelides() → tuple[int, ndarray]

Compute structural index and differentiation vector for exactly determined models

idx, nu = model.Pantelides()

Returns:

• idx (Structural index of model)

• nu (Differentiation vector as defined in) – Pantelides, Constantinos C. “The consistent initialization of differential-algebraic systems.” SIAM Journal on Scientific and Statistical Computing 9.2 (1988): 213-231.

PlotDM(ax=None, eqclass=False, fault=False, verbose=False)

Plot Dulmage-Mendelsohn decomposition of model structure.

Plots a Dulmage-Mendelsohn decomposition, originally described in Dulmage, A. and Mendelsohn, N. “Coverings of bipartite graphs.” Canadian Journal of Mathematics 10.4 (1958): 516-534.

Parameters:

• eqclass (If True, perform canonical decomposition of M+ and) – plot equivalence classes

• fault (If true, indicates fault equations in canonical) – decomposition of M+

• verbose (If True, use full variable names in plot. If not specified, heuristic) – decides based on model size of variable names should be printed.

PlotMatching(Gamma, verbose=False)

Plot a matching.

Plot the structure in an upper-triangular incidence matrix with the matched variables in the diagonal.

Parameters:

Gamma (A matching computed by the Matching class method)

PlotModel(ax=None, verbose=False)

Plot the model structure.

PossibleSensorLocations(x=None)

Set possible sensor locations.

Parameters:

x (Specification of possible sensor locations) – The sensor positions x can be given either as indices into model.x or variable names (default: all positions)

Redundancy(eqs=None) → int

Return the redundancy of the model.

SensorLocationsWithFaults(x=None)

Set possible sensor locations that has faults in new sensors.

Parameters:

x (Index to those sensor locations that can become faulty.) – If no input argument is given, no sensors may become faulty. The sensor positions x can be given either as indices into model.x or variable names

SensorPlacementDetectability()

Compute all minimal sensor sets that achieves maximal fault detectability of the faults in the model.

Krysander, Mattias, and Erik Frisk, “Sensor placement for fault diagnosis.” Systems, Man and Cybernetics, Part A: Systems and Humans, IEEE Transactions on 38.6 (2008): 1398-1410.

Returns:

• res - list of all minimal sensor sets, represented by strings

• idx - same as res, but represented with indicices into model.f

SensorPlacementIsolability(isolabilityspecification=None)

Compute all minimal sensor sets that achieves maximal fault isolability of the faults in the model.

Krysander, Mattias, and Erik Frisk, “Sensor placement for fault diagnosis.” Systems, Man and Cybernetics, Part A: Systems and Humans, IEEE Transactions on 38.6 (2008): 1398-1410.

Parameters:

isolabilityspecification (Isolability specification, a 0/1-matrix with) – a 0 in position (i,j) if fault fi should be isolable from fault fj; 1 otherwise. Structural isolability is a symmetric relation; and if the specification is not symmetric; the specification is made symmetric. Defaults to the identity matrix, i.e., full isolability among faults.

Returns:

• res - list of all minimal sensor sets, represented by strings

• idx - same as res, but represented with indicices into model.f

SeqResGen(Gamma, resEq, name, diffres='int', language='Python', batch=False, api='Python', user_functions=None, external_src=None, external_headers=None)

(Experimental) Generate Python/C code for sequential residual generator.

Given a matching and a residual equation, generate code implementing the residual generator. Generates Python/C file. How to call/compile the generated file is described in the generated file (or the user manual).

Parameters:

• Gamma – Matching

• resEq – Index to equation to use as residual equation

• name – Name of residual equation. Will also be used as a basis for filename.

• diffres – Can be ‘int’ or ‘der’ (default ‘int’). Determines how to treat differential constraints when used as a residual equation.

• language – Defaults to Matlab but also C code can be generated

• batch – Generate a batch mode residual generator, only applicable when generating C code. Instead of computing the residual for one data samnple, batch mode runs the residual generator for a whole data set. This can significantly decrease computational time.

• user_functions – Translation dictionary, from user function name to generated code

• external_src – List of Python files with external functions used in residual generator

• external_headers – List of external header files to include in generated C source

Structural()

Convert the model to a structural model.

SubModel(m, v, clear=True, remove=False, verbose=False)

Extract submodel.

Parameters:

• eqs – Set of indices to or logicals for equations to keep/remove

• vars – Set of indices to or logicals for variables to keep/remove

• clear – If true, non used varaibles in the submodel will be eliminated (default: true)

• verbose – If true, verbose output (default: false)

• remove – If true, supplied equations are removed instead of kept (default: false)

TestSelection(arr, method='aminc', isolabilitymatrix='') → list[ndarray]

A minimal hitting set based test selection.

Find sets of tests, based on a set of equations or a fault sensitivity matrix, FSM, that achieves isolability performance specifications

Simple test selection strategy that finds sets of tests that, ideally, fulfills specified isolability performance specifications. Note that this is a purely structural method, no noise or model uncertainty considerations are used.

Parameters:

• arr (An array of arrays, interpreted as a set of equations) – sets used to design residuals. For eample the ouput of the MSO or MTES functions

• isolabilitymatrix (Matrix specifying required isolability) – performance. A 0 in position (i,j) represents that fault i is isolable from fault j, a 1 indicates that fault i is not isolable from fault j. A fault can not be isolable from itself and therefore must the diagonal always be 1.

• method (Choice of test seleciton method.) –

  ‘aminc’ - Searches for a subset minimal sets of tests

  that fulfills requirements (default) Uses aminc, an approximative minimal cardinality hitting set approach from: Cormen, L., Leiserson, C. E., and Ronald, L. (1990). Rivest, “Introduction to Algorithms.”, 1990.

  Information also in De Kleer, Johan. “Hitting set algorithms for model-based diagnosis.” 22th International Workshop on Principles of Diagnosis, DX, 2011.

  ’full’ - Finds all subset minimal sets of tests

  that fulfills requirements. Warning, might easily lead to computationally intractable problems.

copy()

Return a new copy of the model object.

ne() → int

Return number of equations in model.

nf() → int

Return number of fault variables in model.

nx() → int

Return number of unknown variables in model.

nz() → int

Return number of known variables in model.

srank() → int

Return the structural rank of the incidence matrix for the unknown variables.

Dulmage-Mendelsohn an MSO functionality.

faultdiagnosistoolbox.dmperm.GetDMParts(X) → DMResult

Compute Dulmage-Mendelsohn decomposition.

faultdiagnosistoolbox.dmperm.srank(A) → int

Compute structural rank of matrix.

Minimal Hitting Set functionality.

faultdiagnosistoolbox.MHS.MHS(conflist) → list[ndarray]

Return Minimal Hitting Set for a set of sets.

Parameters:

conflist (list) – list of lists of integers

Returns:

mmhs – list of minimal hitting sets

Return type:

list

Some utility functions for the diagnosis toolbox.

faultdiagnosistoolbox.diag_util.DiagnosesAndConfusionMatrix(data, residx=None) → tuple[ndarray, ndarray]

Compute consistency based diagnoses and corresponding confusion matrix based on a dataset.

faultdiagnosistoolbox.diag_util.IsolabilityMatrix(fsm: ndarray) → ndarray

Compute isolability matrix based on a fault signature matrix

faultdiagnosistoolbox.diag_util.PlotConfusionMatrix(C, ax=None)

Plot a confusion matrix in a suitable colormap.

Test selection using random forest machine learning models.

faultdiagnosistoolbox.testselection_rf.RandomForestTestSelection(data, n_estimators=100)

Select residuals for fault isolation using Random Forests.

Implementation of the residual selection approach described in the paper

Frisk, Erik, and Mattias Krysander. “Residual Selection for Consistency Based Diagnosis Using Machine Learning Models.” IFAC Safeprocess, Warszaw, Poland (2018) (https://doi.org/10.1016/j.ifacol.2018.09.547)

The method computes a sorted list of residuals, where the most important residuals are first in the list. The method also computes performance indices that can be used to determine how many in the sorted list of residuals that should be selected.

Parameters:

• data (dict) – Dictionary with data and supporting information needed by the algorithm. The dictionary must have the following keys modes: an array of size m with names of no-fault and fault modes where the no-fault mode is assumed the first element in the list. res: an (N x n) numpy array with N samples of the n residuals. mode: an (N x 1) numpy array with the fault mode at each sample where a value of 0 corresponds to fault free operation. fsm: a fault signature matrix of size (n x m)

• n_estimators (int) – Number of decision trees in the ensemble model. Defaults to 100

Returns:

• result (dict) – A dictionary containing the resulting test selection. The dictionary contains the keys sortidx: A sorted list of indices to residuals with the most important residuals first. pfa : Performance curve for the false alarm probability pmd : Performace curve for missed detection pfi : Performance curve for fault isolation pmfi : Maximal isolation performance per fault mode residualimportance : List of relative residual importance. The list is not sorted.

• C (arraylike) – A confusion matrix when computing consistency based diagnoses using all residuals.

• rf (RandomForestClassifier) – The random forest object

• Crf (arraylike) – The confusion matrix for the random forest classifier.

Example

Let data be thresholded residual data

>>> ts, C, rf, Crf = RandomForestTestSelection(data, n_estimators=100)

Then plot performance as a function of selected number of residuals using >>> plt.plot(range(1, n), ts[‘pfa’], ‘r’, label=’False alarm probability’) >>> plt.plot(range(1, n), ts[‘pmd’], ‘b’, >>> label=’Missed detection probability’) >>> plt.plot(range(1, n), ts[‘pfi’], ‘y’, >>> label=’False isolation probability’)

based on the plots, determine ntest, the number of tests to select, and then plot the corresponding fault isolation performance

>>> _, C_select = DiagnosesAndConfusionMatrix(data, residx=ts['sortidx'][0:ntests])
>>> PlotConfusionMatrix(C_select)

that could be compared to

>>> PlotConfusionMatrix(C)