FC_BandAlgorithm

FC_BandAlgorithm - General Information

Overview

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

Task

Solve the equation system that is specified by a band algorithm.

Description

A band matrix is a matrix that only contains the main diagonals and several secondary diagonals from zero different elements. Equation systems with band matrixes are commonly used (e.g. when calculating splines). They are frequently very large (> 1000 unknowns), so that the storage of the associated matrix in a square array would equate to an enormous waste of storage space (in the case of a 1000x1000 matrix for a spline, out of the 1000000 matrix elements only 3000 would be different from zero). Instead of this, one saves the matrix in an array that has the same number of lines as the matrix but only a few columns and respectively adapts itself to the Gauss Algorithm.

Interface

Input	Data type	Description
i_diDim	DINT	Number of equations of the solving system or lines / columns of the corresponding matrix. Must be >= 2 .
i_diBands	DINT	Number of bands of the equation system. The bands are the secondary diagonals that the uneven 0 elements receive where counting is only carried out on the main diagonal that contains several of those diagonals. For example, the matrix above has 2 bands.
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 in which the matrix of the linear equation system is stored. This area has to be connected and provide a minimum memory space for i_diDim * (3 * i_diBands + 1) LREALs. This array provides more space than would be required for saving the matrix elements other than zero. The additional elements are required for the pivoting. The allocation of this space is described below.
i_plrVector	POINTER TO LREAL	Pointer to the beginning of the memory area where the inhomogeneous vector ("right side") of the linear equation system is stored. This area has to be connected and provide a minimum storage space for i_diDim LREALs.
i_plrSolutionVector	POINTER TO LREAL	Pointer on the beginning of the memory area where the solution vector of the linear equation system has to be copied. This area has to be connected and provide a minimum storage space for i_diDim LREALs. The POU calculates the vector SolutionVector so that the equation matrix * SolutionVector = Vector is fulfilled.

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 POU requires i_diDim * (3 * i_diBands + 2) * SIZEOF(LREAL) bytes of dynamic memory. Therefore, it must be ensured that the parameter LMCx00C\C\Configuration\Program\DynIECDataSize (total available dynamic memory) is set to an adequate value.

oThe correct size of the storage area that the pointers i_plrMatrix, i_plrVector and i_plrSolutionVector are pointing to must be carefully checked. Otherwise, the POU causes memory access errors.

i_plrMatrix : i_diDim * (3 * i_diBands + 1) LREALs

i_plrVector : i_diDim LREALs

i_plrSolutionVector : i_diDim LREALs

oThe functions FC_GetMatrixElement(), FC_GetVectorElement(), FC_SetMatrixElement() and FC_SetVectorElement() are available for allocating and reading the elements of the matrix and the vectors involved. With this POU, the column value i_diNumCols = 3 * i_diBands + 1 must be set for the allocation of the matrix.

oThe allocation of the matrix elements to the elements of the array A, which this represents, elements is as follows (D = i_diDim, B = i_diBands has been set for a shorter notation):

Allocation of the elements of a band matrix to the elements of the array of the band matrix POU

Visualization using the band matrix above as an example.

diDim : DINT := 10;
diBands : DINT := 2;
diCols : DINT := 7;
alrA : ARRAY[0..9,0..6] OF LREAL;
alrB : ARRAY[0..9] OF LREAL := 10(2.0); (* Beispiel für "rechte Seite" *)
alrX : ARRAY[0..9] OF LREAL;
etDiag : PD_GlobalDiagnostic.ET_Diag;
etDiagExt : PD_PacDriveLib.ET_DiagExt;

Allocation of the matrix:

FOR i := 0 TO (diDim - 1) DO
   FOR j := 0 TO (3 * diBands) DO
      FC_SetMatrixElement(
         i_plrMatrixStart:=ADR(alrA[0,0]),
         i_diNumCols:=diCols,
         i_diRow:=i,
         i_diCol:=j,
         i_lrValue:=0.0);
   END_FOR
END_FOR
FOR i := 0 TO (diDim - 1) DO
   FC_SetMatrixElement(
      i_plrMatrixStart:=ADR(alrA[0,0]),
      i_diNumCols:=diCols,
      i_diRow:=i,
      i_diCol:=diBands,
      i_lrValue:=1.0);
END_FOR
FOR i := 1 TO (diDim - 1) DO
   FC_SetMatrixElement(
      i_plrMatrixStart:=ADR(alrA[0,0]),
      i_diNumCols:=diCols,
      i_diRow:=i,
      i_diCol:=diBands-1,
      i_lrValue:=0.5);
END_FOR
FOR i := 0 TO (diDim - 2) DO
   FC_SetMatrixElement(
      i_plrMatrixStart:=ADR(alrA[0,0]),
      i_diNumCols:=diCols,
      i_diRow:=i,
      i_diCol:=diBands+1,
      i_lrValue:=0.5);
END_FOR
FOR i := 0 TO (diDim - 3) DO
   FC_SetMatrixElement(
      i_plrMatrixStart:=ADR(alrA[0,0]),
      i_diNumCols:=diCols,
      i_diRow:=i,
      i_diCol:=diBands+2,
      i_lrValue:=1.0/3.0);
END_FOR

FC call-up:

FC_BandAlgorithm (
   i_diDim := diDim,
   i_diBands := diBands,
   i_lrZeroLimit := 1E-12,
   i_plrMatrix := ADR(alrA[0,0]),
   i_plrVector := ADR(alrB[0,0]),
   i_plrSolutionVector := ADR(alrX[0,0]),
   q_etDiag => etDiag,
   q_etDiagExt => etDiagExt );

After calling up the function, the solution of the equation system is available in array alrX.

Diagnostic Messages

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

BandsRange

Enumeration name:	BandsRange
Enumeration value:	73
Description:	Bands is outside the valid range

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

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 equation system has been successfully solved.

PointerMatrixInvalid

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

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

PointerSolutionVectorInvalid

Enumeration name:	PointerSolutionVectorInvalid
Enumeration value:	71
Description:	The pointer SolutionVector is invalid.

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

PointerVectorInvalid

Enumeration name:	PointerVectorInvalid
Enumeration value:	70
Description:	The pointer Vector is invalid.

Issue	Cause	Solution
-	At the input i_plrVector, a null pointer has been transferred.	At the input i_plrVector, the address of the memory containing the vector 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.