NAG Library Function Document nag_complex_tridiag_lin_solve (f04ccc)

Transcription

1 f04 Simultaneous Linear Equations f04ccc Purpose NAG Library Function Document nag_complex_tridiag_lin_solve (f04ccc) nag_complex_tridiag_lin_solve (f04ccc) computes the solution to a complex system of linear equations AX ¼ B, where A is an n by n tridiagonal matrix and X and B are n by r matrices. An estimate of the condition number of A and an error bound for the computed solution are also returned. 2 Specification #include <nag.h> #include <nagf04.h> void nag_complex_tridiag_lin_solve (Nag_OrderType order, Integer n, Integer nrhs, Complex dl[], Complex d[], Complex du[], Complex du2[], Integer ipiv[], Complex b[], Integer pdb, double *rcond, double *errbnd, NagError *fail) 3 Description The LU decomposition with partial pivoting and row interchanges is used to factor A as A ¼ PLU, where P is a permutation matrix, L is unit lower triangular with at most one nonzero subdiagonal element, and U is an upper triangular band matrix with two superdiagonals. The factored form of A is then used to solve the system of equations AX ¼ B. Note that the equations A T X ¼ B may be solved by interchanging the order of the arguments du and dl. 4 References Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (999) LAPACK Users Guide (3rd Edition) SIAM, Philadelphiahttp:// Higham N J (2002) Accuracy and Stability of Numerical Algorithms (2nd Edition) SIAM, Philadelphia 5 Arguments : order Nag_OrderType Input On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., rowmajor ordering or column-major ordering. C language defined storage is specified by order ¼ Nag_RowMajor. See Section in the Essential Introduction for a more detailed explanation of the use of this argument. Constraint: order ¼ Nag_RowMajor or Nag_ColMajor. 2: n Integer Input On entry: the number of linear equations n, i.e., the order of the matrix A. Constraint: n 0. 3: nrhs Integer Input On entry: the number of right-hand sides r, i.e., the number of columns of the matrix B. Constraint: nrhs 0. f04ccc.

2 f04ccc NAG Library Manual 4: dl½dimš Complex Input/Output Note: the dimension, dim, of the array dl must be at least maxð; n Þ. On entry: must contain the ðn Þ subdiagonal elements of the matrix A. On exit: iffail:code ¼ NE_NOERROR, dl is overwritten by the ðn Þ multipliers that define the matrix L from the LU factorization of A. 5: d½dimš Complex Input/Output Note: the dimension, dim, of the array d must be at least maxð; nþ. On entry: must contain the n diagonal elements of the matrix A. On exit: iffail:code ¼ NE_NOERROR, d is overwritten by the n diagonal elements of the upper triangular matrix U from the LU factorization of A. 6: du½dimš Complex Input/Output Note: the dimension, dim, of the array du must be at least maxð; n Þ. On entry: must contain the ðn Þ superdiagonal elements of the matrix A On exit: iffail:code ¼ NE_NOERROR, du is overwritten by the ðn Þ elements of the first superdiagonal of U. 7: du2½n 2Š Complex Output On exit: if fail:code ¼ NE_NOERROR, du2 returns the ðn 2Þ elements of the second superdiagonal of U. 8: ipiv½nš Integer Output On exit: iffail:code ¼ NE_NOERROR, the pivot indices that define the permutation matrix P; at the ith step row i of the matrix was interchanged with row ipiv½i Š. ipiv½i Š will always be either i or ði þ Þ; ipiv½i Š ¼i indicates a row interchange was not required. 9: b½dimš Complex Input/Output Note: the dimension, dim, of the array b must be at least maxð; pdb nrhsþ when order ¼ Nag_ColMajor; maxð; pdb nþ when order ¼ Nag_RowMajor. The ði; jþth element of the matrix B is stored in b½ðj Þpdb þ i Š when order ¼ Nag_ColMajor; b½ði Þ pdb þ j Š when order ¼ Nag_RowMajor. On entry: the n by r matrix of right-hand sides B. On exit: iffail:code ¼ NE_NOERROR or NE_RCOND, the n by r solution matrix X. 0: pdb Integer Input On entry: the stride separating matrix row or column elements (depending on the value of order) in b. Constraints: if order ¼ Nag_ColMajor, pdb maxð; nþ; if order ¼ Nag_RowMajor, pdb maxð; nrhsþ. : rcond double * Output On exit: if no constraints are violated, an estimate of the reciprocal of the condition number of the matrix A, computed as rcond ¼ = kak A. f04ccc.2

3 f04 Simultaneous Linear Equations f04ccc 2: errbnd double * Output On exit: iffail:code ¼ NE_NOERROR or NE_RCOND, an estimate of the forward error bound for a computed solution ^x, such that k^x xk = kxk errbnd, where ^x is a column of the computed solution returned in the array b and x is the corresponding column of the exact solution X. If rcond is less than machine precision, then errbnd is returned as unity. 3: fail NagError * Input/Output The NAG error argument (see Section 3.6 in the Essential Introduction). 6 Error Indicators and Warnings NE_ALLOC_FAIL Dynamic memory allocation failed. NE_BAD_PARAM On entry, argument NE_INT On entry, n ¼ hvaluei. Constraint: n 0. On entry, nrhs ¼ hvaluei. Constraint: nrhs 0. On entry, pdb ¼ hvaluei. Constraint: pdb > 0. hvaluei had an illegal value. NE_INT_2 On entry, pdb ¼ hvaluei, n ¼ hvaluei. Constraint: pdb maxð; nþ. NE_INTERNAL_ERROR An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please consult NAG for assistance. An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance. NE_RCOND A solution has been computed, but rcond is less than machine precision so that the matrix A is numerically singular. NE_SINGULAR Diagonal element hvaluei of the upper triangular factor is zero. The factorization has been completed, but the solution could not be computed. 7 Accuracy The computed solution for a single right-hand side, ^x, satisfies an equation of the form ða þ EÞ^x ¼ b, where kek ¼ OðÞA k k and is the machine precision. An approximate error bound for the computed solution is given by f04ccc.3

4 f04ccc NAG Library Manual k^x xk A ð Þ kek, kxk kak where A ð Þ ¼ A kak, the condition number of A with respect to the solution of the linear equations. nag_complex_tridiag_lin_solve (f04ccc) uses the approximation kek ¼ A k k to estimate errbnd. See Section 4.4 of Anderson et al. (999) for further details. 8 Further Comments The total number of floating-point operations required to solve the equations AX ¼ B is proportional to nr. The condition number estimation typically requires between four and five solves and never more than eleven solves, following the factorization. In practice the condition number estimator is very reliable, but it can underestimate the true condition number; see Section 5.3 of Higham (2002) for further details. The real analogue of nag_complex_tridiag_lin_solve (f04ccc) is nag_real_tridiag_lin_solve (f04bcc). 9 Example This example solves the equations where A is the tridiagonal matrix 0 A ¼ and AX ¼ B, :3 þ :3i 2:0 :0i :0 2:0i :3 þ :3i 2:0 þ :0i :0 þ :0i :3 þ 3:3i :0 þ :0i :0 3:0i 0:3 þ 4:3i :0 :0i :0 þ :0i 3:3 þ :3i 0 2:4 5:0i 2:7 þ 6:9i 3:4 þ 8:2i 6:9 5:3i B ¼ 4:7 þ 9:7i 6:0 0:6i B 3:9 7:7i 3:9 þ 9:3i A. :0 þ :6i 3:0 þ 2:2i An estimate of the condition number of A and an approximate error bound for the computed solutions are also printed. 9. Program Text /* nag_complex_tridiag_lin_solve (f04ccc) Example Program. * * Copyright 2004 Numerical Algorithms Group. * * Mark 8, */ #include <stdio.h> #include <nag.h> #include <nag_stdlib.h> #include <nagf04.h> #include <nagx04.h> int main(int argc, char *argv[]) FILE *fpin, *fpout; char *outfile = 0; /* Scalars */ double errbnd, rcond; C A f04ccc.4

5 f04 Simultaneous Linear Equations f04ccc Integer exit_status, i, j, n, nrhs, pdb; /* Arrays */ char *clabs = 0, *rlabs = 0; Complex *b = 0, *d = 0, *dl = 0, *du = 0, *du2 = 0; Integer *ipiv = 0; /* Nag types */ NagError fail; Nag_OrderType order; #ifdef NAG_COLUMN_MAJOR #define B(I, J) b[(j-)*pdb + I - ] order = Nag_ColMajor; #else #define B(I, J) b[(i-)*pdb + J - ] order = Nag_RowMajor; #endif exit_status = 0; INIT_FAIL(fail); /* Check for command-line IO options */ fpin = nag_example_file_io(argc, argv, "-data", NULL); fpout = nag_example_file_io(argc, argv, "-results", NULL); (void) nag_example_file_io(argc, argv, "-nag_write", &outfile); "nag_complex_tridiag_lin_solve (f04ccc) Example Program Results\n\n"); /* Skip heading in data file */ fscanf(fpin, "%ld%ld%*[^\n] ", &n, &nrhs); if (n > 0 && nrhs > 0) /* Allocate memory */ if (!(clabs = NAG_ALLOC(2, char))!(rlabs = NAG_ALLOC(2, char))!(b = NAG_ALLOC(n*nrhs, Complex))!(d = NAG_ALLOC(n, Complex))!(dl = NAG_ALLOC(n-, Complex))!(du = NAG_ALLOC(n-, Complex))!(du2 = NAG_ALLOC(n-2, Complex))!(ipiv = NAG_ALLOC(n, Integer))) "Allocation failure\n"); exit_status = -; #ifdef NAG_COLUMN_MAJOR pdb = n; #else pdb = nrhs; #endif else "%s\n", "n and/or nrhs too small"); exit_status = ; return exit_status; /* Read A and B from data file */ for (i = ; i <= n - ; ++i) fscanf(fpin, " ( %lf, %lf )", &du[i - ].re, &du[i - ].im); for (i = ; i <= n; ++i) f04ccc.5

6 f04ccc NAG Library Manual fscanf(fpin, " ( %lf, %lf )", &d[i - ].re, &d[i - ].im); for (i = ; i <= n - ; ++i) fscanf(fpin, " ( %lf, %lf )", &dl[i - ].re, &dl[i - ].im); for (i = ; i <= n; ++i) for (j = ; j <= nrhs; ++j) fscanf(fpin, " ( %lf, %lf )", &B(i, j).re, &B(i, j).im); /* Solve the equations AX = B for X */ /* nag_complex_tridiag_lin_solve (f04ccc). * Computes the solution and error-bound to a complex * tridiagonal system of linear equations */ nag_complex_tridiag_lin_solve(order, n, nrhs, dl, d, du, du2, ipiv, b, pdb, &rcond, &errbnd, &fail); if (fail.code == NE_NOERROR) /* Print solution, estimate of condition number and approximate */ /* error bound */ /* nag_gen_complx_mat_print_comp (x04dbc). * Print complex general matrix (comprehensive) */ if (outfile) fclose(fpout); nag_gen_complx_mat_print_comp(order, Nag_GeneralMatrix, Nag_NonUnitDiag, n, nrhs, b, pdb, Nag_BracketForm, 0, "Solution", Nag_IntegerLabels, 0, Nag_IntegerLabels, 0, 80, 0, outfile, &fail); if (outfile &&!(fpout = fopen(outfile, "a"))) exit_status = 2; if (fail.code!= NE_NOERROR) "Error from nag_gen_complx_mat_print_comp (x04dbc).\n%s\n", fail.message); exit_status = ; "\n"); "%s\n%8s%0.e\n", "Estimate of condition number", "",.0/rcond); "\n\n"); "%s\n%8s%0.e\n\n", "Estimate of error bound for computed solutions", "", errbnd); else if (fail.code == NE_RCOND) /* Matrix A is numerically singular. Print estimate of */ /* reciprocal of condition number and solution */ "\n"); "%s\n%8s%0.e\n\n\n", "Estimate of reciprocal of condition number", "", rcond); /* nag_gen_complx_mat_print_comp (x04dbc), see above. */ if (outfile) fclose(fpout); f04ccc.6

7 f04 Simultaneous Linear Equations f04ccc nag_gen_complx_mat_print_comp(order, Nag_GeneralMatrix, Nag_NonUnitDiag, n, nrhs, b, pdb, Nag_BracketForm, 0, "Solution", Nag_IntegerLabels, 0, Nag_IntegerLabels, 0, 80, 0, outfile, &fail); if (outfile &&!(fpout = fopen(outfile, "a"))) exit_status = 2; if (fail.code!= NE_NOERROR) "Error from nag_gen_complx_mat_print_comp (x04dbc).\n%s\n", fail.message); exit_status = ; else if (fail.code == NE_SINGULAR) /* The upper triangular matrix U is exactly singular. Print */ /* details of factorization */ "%s\n\n", "Details of factorization"); "%s", " Second super-diagonal of U"); "\n"); for (i = ; i <= n - 2; ++i) "(%7.4f, %7.4f)%s", du2[i - ].re, du2[i - ].im, i%4 == 0 i == n - 2?"\n":" "); "\n\n"); "%s\n", " First super-diagonal of U"); for (i = ; i <= n - ; ++i) "(%7.4f, %7.4f)%s", du[i - ].re, du[i - ].im, i%4 == 0 i == n -?"\n":" "); "\n\n"); "%s\n", " Main diagonal of U"); for (i = ; i <= n; ++i) "(%7.4f, %7.4f)%s", d[i - ].re, d[i - ].im, i%4 == 0 i == n?"\n":" "); "\n\n"); "%s\n", " Multipliers"); for (i = ; i <= n - ; ++i) "(%7.4f, %7.4f)%s", dl[i - ].re, dl[i - ].im, i%4 == 0 i == n -?"\n":" "); "\n\n"); "%s\n", " Vector of interchanges"); for (i = ; i <= n; ++i) "%9ld%s", ipiv[i - ], i%8 == 0 i == n?"\n":" "); "\n"); else f04ccc.7

8 f04ccc NAG Library Manual "Error from nag_complex_tridiag_lin_solve (f04ccc).\n%s\n", fail.message); exit_status = ; END: if (fpin!= stdin) fclose(fpin); if (fpout!= stdout) fclose(fpout); if (clabs) NAG_FREE(clabs); if (rlabs) NAG_FREE(rlabs); if (b) NAG_FREE(b); if (d) NAG_FREE(d); if (dl) NAG_FREE(dl); if (du) NAG_FREE(du); if (du2) NAG_FREE(du2); if (ipiv) NAG_FREE(ipiv); return exit_status; #undef B 9.2 Program Data nag_complex_tridiag_lin_solve (f04ccc) Example Program Data 5 2 :Values of N and NRHS ( 2.0, -.0) ( 2.0,.0) ( -.0,.0) (.0, -.0) :End of DU ( -.3,.3) ( -.3,.3) ( -.3, 3.3) ( -0.3, 4.3) ( -3.3,.3) :End of D (.0, -2.0) (.0,.0) ( 2.0, -3.0) (.0,.0) :End of DL ( 2.4, -5.0) ( 2.7, 6.9) ( 3.4, 8.2) ( -6.9, -5.3) (-4.7, 9.7) ( -6.0, -0.6) ( 3.9, -7.7) ( -3.9, 9.3) ( -.0,.6) ( -3.0, 2.2) :End of B 9.3 Program Results nag_complex_tridiag_lin_solve (f04ccc) Example Program Results Solution 2 (.0000,.0000) ( , ) 2 ( , ) (.0000, ) 3 ( , ) ( ,.0000) 4 ( , ) ( ,.0000) 5 (.0000, ) ( , ) Estimate of condition number.8e+02 Estimate of error bound for computed solutions 2.0e-4 f04ccc.8 (last)