Why MATINV Function Might Return -1 if Not Using OPTION BASE 1 (79371)

SUMMARY

In Basic Professional Development System (PDS) versions 7.0 and 7.1, the MatInv function finds the multiplicative inverse of a square matrix. If you pass an invertible square matrix to MatInv, MatInv returns zero (0, indicating a successful inversion), and the passed matrix is inverted. However, MatInv returns -1 if the matrix is not invertible, such as if the matrix contains a row or column of all zero values. Below is a common programming mistake that causes MatInv to return -1 (not invertible) instead of 0 (successfully inverted).

A common reason for MatInv to return -1 is if you fail to account for the default OPTION BASE 0 for arrays in your program, and you mistakenly assume your arrays start at element number 1. Because the default OPTION BASE (starting element) for Basic arrays is element 0, if you fail to assign array values starting at element 0, an empty row and column (where all elements contain values of 0) will exist in the array, which causes MatInv to return -1. To correct this programming mistake, you can use the OPTION BASE 1 statement at the top of the program to make your arrays start at element 1 by default.

MORE INFORMATION

The MatInv function returns three possible values:

0 = Normal completion. (The matrix is invertible.)

-1 = Determinant for the matrix is 0. (No inverse exists for the matrix.)

-2 = Matrix is not square. (Number of rows does not equal number of columns.)

A matrix is simply a two-dimensional array in Basic. A square matrix is defined as a matrix whose number of rows is equal to its number of columns. If matrix A is a square matrix, an inverse of A is a matrix, A ^ -1, with the property

   A * (A ^ -1) = I = (A ^ -1) * A

where I is the identity matrix (a matrix with the value 1 in every element on the diagonal, with all else zeros). If any row or column is all zeros, the matrix is not invertible.

When providing a square, invertible matrix to MatInv, you would expect a return code of 0. Without OPTION BASE 1, by default, arrays dimensioned in Basic start at element 0 (OPTION BASE 0). If you fill your array starting at element 1, extra unintentional 0 values are inadvertently introduced into the matrix at element 0. As a result, passing a square, apparently invertible matrix to MatInv can yield a return code of -1, instead of 0.

You can use any one of the following solutions to correct this programming mistake:

You can apply OPTION BASE 1 to the code, thus forcing Basic to dimension all arrays starting at element 1, rather than element 0.
You can dimension each array to start with element 1 and end at element 10 as follows:
```
      DIM A&(1 to 10)
						
```
If you choose the default OPTION BASE 0, and you DIM A&(0 to x) or DIM A&(x), you should start assigning values at array element 0 for each dimension (instead of starting at element 1). Make sure every element has a correctly assigned value.

For more information on the OPTION BASE statement, see page 243 of the "Microsoft Basic 7.0: Language Reference" for versions 7.0 and 7.1.

The following code example illustrates this behavior. When run as is, the program correctly returns 0 for MatInv. When OPTION BASE 1 is removed, MatInv correctly returns -1, because the array is no longer invertible.

' This program demonstrates a problem that can be
' encountered when using the MatInv function without OPTION
' BASE 1. The MatInv function and other matrix math routines
' are provided in the Matrix Math Toolbox in Microsoft Basic
' 7.00/7.10 for MS-DOS and MS OS/2.  To demonstrate, run the
' code first, as is.  Next, REMark out the OPTION BASE 1 and
' then run.
'
' To run this program in QBX.EXE (the QuickBasic Extended editor),
' load the MATBEFR.QLB Quick library as follows:
'
'     QBX /L MATBEFR.QLB
'
' MATFEFR.QLB and the related .LIB files are documented in
' the INCLUDE file 'MATB.BI' but NOT in "Microsoft Basic 7.0:
' Language Reference."

DECLARE FUNCTION MatInvD% (A() AS DOUBLE)

' The above DECLARE statement is all that is needed from the
' following include file: REM $INCLUDE: 'matb.bi'

DEFDBL A-Z
OPTION BASE 1   ' When OPTION BASE 1 is remarked out, the array
                ' elements start at 0, causing the array to have an
                ' extra row of zeros and an extra column of zeros.
DIM A(3, 3)

' The following is a 3x3 square matrix of values:
'   |  1  1  2  |
'   |  2  4 -3  |
'   |  3  6 -5  |
' For the above set of values, a multiplicative inverse does exist,
' as shown by the MatInv function.
' This 3x3 matrix of values can be placed in array a() as follows:
'     a(1,1)  a(1,2)  a(1,3)
'     a(2,1)  a(2,2)  a(2,3)
'     a(3,1)  a(3,2)  a(3,3)

A(1, 1) = 1
A(1, 2) = 1
A(1, 3) = 2
A(2, 1) = 2
A(2, 2) = 4
A(2, 3) = -3
A(3, 1) = 3
A(3, 2) = 6
A(3, 3) = -5
errcode% = MatInvD%(A())  ' Without OPTION BASE 1, errcode% will
                          ' return -1 ("no inverse of input matrix
                          ' exists")
CLS
PRINT "Errcode% :"; errcode%
PRINT "--------------------------------------------------------------"
PRINT " 0 = Normal completion; multiplicative inverse exists"
PRINT "-1 = Determinant for matrix is 0.  No inverse exists"
PRINT "-2 = Matrix not square; doesn't have same number of rows as columns"
PRINT "--------------------------------------------------------------"