FC_MatrixInversion

FC_MatrixInversion - General Information

Overview

Type:	Function
Available as of:	V1.0.3.0
Versions:	Current version

Task

Calculates the inversion matrix of a given quadratic matrix.

Description

Returns the inverse matrix of a quadratic matrix of the dimension i_diDim x i_diDim. The pointer i_plrMatrix must point to the start of the memory area in which the matrix is stored. The pointer i_plrInvMatrix must point to the beginning of the memory area from where the result of the calculation, i.e. the inverse matrix should be copied. If a matrix cannot be inverted, it is referred to as a singular matrix.

Interface

Input	Data type	Description
i_diDim	DINT	Line-/ column value of the matrix whose inverse has to be calculated. Must be >= 2 .
i_lrZeroLimit	LREAL	Numeric zero limit. Matrix elements that are much smaller than this value are considered as zero. Used to limit the rounding error reproduction. The best value depends on the numeric properties of the matrix. Must be > 0.0. A common value is, e.g. 1E-12.
i_plrMatrix	POINTER TO LREAL	Pointer on the beginning of the memory area where the matrix is stored whose inverse matrix has to be calculated.
i_plrInvMatrix	POINTER TO LREAL	Pointer on the beginning of the memory area in which the inverse matrix has to be copied.

Output	Data type	Description
q_etDiag	GD.ET_Diag	General library-independent statement on the diagnostic. A value not equal to ET_Diag.Ok corresponds to an diagnostic message.
q_etDiagExt	ET_DiagExt	POU-specific output on the diagnostic. q_etDiag = ET_Diag.Ok -> Status message q_etDiag <> ET_Diag.Ok -> Diagnostic message

Output

Data type

Description

q_etDiag

GD.ET_Diag

General library-independent statement on the diagnostic.

A value not equal to ET_Diag.Ok corresponds to an diagnostic message.

q_etDiagExt

ET_DiagExt

POU-specific output on the diagnostic.

q_etDiag = ET_Diag.Ok -> Status message

q_etDiag <> ET_Diag.Ok -> Diagnostic message

Notes

oThis function block requires i_diDim * i_diDim * SIZEOF(LREAL) bytes of dynamic memory. Therefore, it must be ensured that the parameter LMCx00C\C\Configuration\IEC-Program\DynIECDataSize (total available dynamic memory) is set to an adequate value.

oThe correct size of the storage spaces that the pointers i_plrMatrix and i_plrInvMatrix are pointed to (at least i_diDim * i_diDim LREALs), must be carefully checked otherwise the function block causes memory access errors.

oThe functions FC_GetMatrixElement() and FC_SetMatrixElement() are available for allocating and reading the elements of the involved matrices.

oIf the matrices are give by arrays and if the inverse matrix should be stored direct in an array, this can also be allocated directly (without using the previously specified help function). The first index of the array is then the line index of the matrices and the second the gap index.

Diagnostic Messages

q_etDiag	q_etDiagExt	Enumeration value	Description
OK	Ok	0	Ok
ControllerConditionInvalid	DynIecDataSizeTooSmall	75	There is not enough dynamic memory reserved.
InputParameterInvalid	DimRange	72	Dim is outside the valid range.
InputParameterInvalid	MatrixSingular	77	The matrix is singular.
InputParameterInvalid	PointerInvMatrixInvalid	83	The pointer InvMatrix is invalid.
InputParameterInvalid	PointerMatrixInvalid	69	The pointer Matrix is invalid.
InputParameterInvalid	ZeroLimitRange	74	ZeroLimit is outside the valid range.
UnexpectedProgramBehavior	UnexpectedFeedback	1	An unintended detected error occurred during execution.

DimRange

Enumeration name:	DimRange
Enumeration value:	72
Description:	Dim is outside the valid range.

Issue	Cause	Solution
-	At the input i_diDim, an invalid value has been transferred.	The following must hold: i_diDim > 1

DynIecDataSizeTooSmall

Enumeration name:	DynIecDataSizeTooSmall
Enumeration value:	75
Description:	There is not enough dynamic memory reserved.

Issue	Cause	Solution
-	There is no or not enough dynamic memory available.	Increase the available dynamic memory Controller > Configuration > Program > DynIECDataSize.

MatrixSingular

Enumeration name:	MatrixSingular
Enumeration value:	77
Description:	The matrix is singular.

Issue	Cause	Solution
-	The matrix at the input i_plrMatrix is singular.	At the input i_plrMatrix, a regular matrix has to be transferred.

Enumeration name:	Ok
Enumeration value:	0
Description:	Ok

The inverse matrix has been calculated successfully.

PointerInvMatrixInvalid

Enumeration name:	PointerInvMatrixInvalid
Enumeration value:	83
Description:	The pointer InvMatrix is invalid.

Issue	Cause	Solution
-	At the input i_plrInvMatrix, a null pointer has been transferred.	At the input i_plrInvMatrix, the address of the memory containing the inverted matrix must be transferred.

PointerMatrixInvalid

Enumeration name:	PointerMatrixInvalid
Enumeration value:	69
Description:	The pointer Matrix is invalid.

Issue	Cause	Solution
-	At the input i_plrMatrix, a null pointer has been transferred.	At the input i_plrMatrix, the address of the memory containing the matrix must be transferred.

UnexpectedFeedback

Enumeration name:	UnexpectedFeedback
Enumeration value:	1
Description:	An unintended detected error occurred during execution.

Issue	Cause	Solution
-	An error occurred in the internal execution.	Please inform the support team about this error.

ZeroLimitRange

Enumeration name:	ZeroLimitRange
Enumeration value:	74
Description:	ZeroLimit is outside the valid range.

Issue	Cause	Solution
-	At the input i_lrZeroLimit, a number <= 0 has been applied.	i_lrZeroLimit must be greater than 0.