TUlinearEq TCL UTILITIES USER MANUAL TUlinearEq
SYNOPSIS
Solves N coupled linear equations
PACKAGE
TCLUTILS
NAME
TUlinearEq
USAGE
TUlinearEq  CmD M N pV sV
INPUT DEFINITIONS
CmD - Defines how the procedure needs to approach the solution.
FULL - Procedure needs to perform an Upper/Lower (LU) decomposition of the input matrix.
PARTIAL - Procedure does not need to perform an Upper/Lower (LU) decomposition of the input matrix. The input matrix has already be decomposed in a previous call to the procedure.
M - The input matrix consisting of the coefficients multiplying the unknowns in each equations. The matrix is laid down row by row in a 1D array. The coefficients corresponding to each defined equations occupy one row in the matrix.
N - The number of unknowns (and therefore equations) being solved for. The input matrix M will be an NxN matrix.
pV - The row permutation vector which records the row permutations in the LU decomposition of M.
sV - The solution vector. This holds the solutions to the equations on input and the solutions to the equations unknowns on output.
RETURN DEFINITION
Nothing returned.
DESCRIPTION
TUlinearEq solves for the unknowns in a system of N coupled linear equations of the form: 
V1 = A11 * X1 + A12 * X2 + A13 * X3 + ... + A1N * XN
V2 = A21 * X1 + A22 * X2 + A23 * X3 + ... + A2N * XN
V3 = A31 * X1 + A32 * X2 + A33 * X3 + ... + A3N * XN
. . . .
. . . .
VN = AN1 * X1 + AN2 * X2 + AN3 * X3 + ... + ANN * XN
where Aij forms the matrix M, Vi forms the solution vector sV, and Xi are the unknowns.
In the first call to the procedure CmD should be set to FULL. This forces an LU decomposition of the input matrix which is then returned together with the permutation vector pV and the solution vector sV. Subsequent solutions of the same system of equations bit with different solution vectors can proceed without the LU decomposition as the input matrix is already decomposed. This is the primary advantage of TUlinearEq over TUmatrixInv as a means to solve sets of coupled linear equations which only exists if the system is to be solved for multiple solution vectors.
ERRORS
None Generated
C BACKING
No
EXAMPLE(S) 
# SOLVE the set of equations
#
#     7x +  y + 10z  = -4
#   1.5x +  y + 2z   = 7.5
#   -.5x + 7y - 3.5z = 1.0
                                                                                
# INPUT matrix
                                                                                
set A(0)  7.0 ; set A(1)  1.0 ; set A(2)  10.0
set A(3)  1.5 ; set A(4)  1.0 ; set A(5)   2.0
set A(6)  -.5 ; set A(7)  7.0 ; set A(8)  -3.5

# COPY of matrix
                                                                                
set B(0)  7.0 ; set B(1)  1.0 ; set B(2)  10.0
set B(3)  1.5 ; set B(4)  1.0 ; set B(5)   2.0
set B(6)  -.5 ; set B(7)  7.0 ; set B(8)  -3.5

# SOLUTION Matrix
                                                                                
set V(0) -4.0
set V(1)  7.5
set V(2)  1.0
                                                                                
# SOLVE

TUlinearEq FULL A 3 P V
                                                                                
# CHECK solutions

set C(0) [expr $B(0) * $V(0) + $B(1) * $V(1) + $B(2) * $V(2)]
set C(1) [expr $B(3) * $V(0) + $B(4) * $V(1) + $B(5) * $V(2)]
set C(2) [expr $B(6) * $V(0) + $B(7) * $V(1) + $B(8) * $V(2)]

# PRINT results
                                                                                
puts stderr "Solutions: [format "x = %5.1f" $V(0)]"
puts stderr "           [format "y = %5.1f" $V(1)]"
puts stderr "           [format "z = %5.1f" $V(2)]"
puts stderr "Check:     [format "V0 = %5.1f (Should be -4.0)" $C(0)]"
puts stderr "           [format "V1 = %5.1f (Should be  7.5)" $C(1)]"
puts stderr "           [format "V2 = %5.1f (Should be  4.0)" $C(2)]"

# SOLVE same set of equations but with a different solution Vector where
#   the signs are opposite that first used.
                                                                                
set V(0)  4.0
set V(1) -7.5
set V(2) -1.0

# SOLVE

TUlinearEq PARTIAL A 3 P V
                                                                                
# CHECK solutions
                                                                                
set C(0) [expr $B(0) * $V(0) + $B(1) * $V(1) + $B(2) * $V(2)]
set C(1) [expr $B(3) * $V(0) + $B(4) * $V(1) + $B(5) * $V(2)]
set C(2) [expr $B(6) * $V(0) + $B(7) * $V(1) + $B(8) * $V(2)]

# PRINT results
                                                                                
puts stderr "Solutions: [format "x = %5.1f" $V(0)]"
puts stderr "           [format "y = %5.1f" $V(1)]"
puts stderr "           [format "z = %5.1f" $V(2)]"
puts stderr "Check:     [format "V0 = %5.1f (Should be  4.0)" $C(0)]"
puts stderr "           [format "V1 = %5.1f (Should be -7.5)" $C(1)]"
puts stderr "           [format "V2 = %5.1f (Should be -4.0)" $C(2)]"


> Solutions: x = -74.3
>            y =  19.7
>            z =  49.7
> Check:     V0 =  -4.0 (Should be -4.0)
>            V1 =   7.5 (Should be  7.5)
>            V2 =   1.0 (Should be  4.0)
> Solutions: x =  74.3
>            y = -19.7
>            z = -49.7
> Check:     V0 =   4.0 (Should be  4.0)
>            V1 =  -7.5 (Should be -7.5)
>            V2 =  -1.0 (Should be -4.0)
Sept 19, 2006