------------------------------------------------------------- 1. Introduction ------------------------------------------------------------- MA75 solves weighted sparse linear least-squares problems. Given an m x n (m>=n) sparse matrix A of rank n, an m x m diagonal matrix W of weights, and an m-vector b, the routine calculates the solution vector x that minimizes the Euclidean norm of the weighted residual vector r = W * (A * x - b) by solving the normal equations A' * W^2 * A x = A' * W^2 * b. For the statistical analysis of the weighted least-squares problem the routine optionally returns the covariance matrix, (A' * W^2 * W)^{-1}, or its diagonal or one of its columns. ------------------------------------------------------------- 2. Requirements ------------------------------------------------------------- These instructions should work on Linux, Mac OS or Windows systems. They have been tested using the six most recent releases of Matlab. Please note that HSL software requires a Fortran compiler to be installed that is compatible with Matlab. Please see https://uk.mathworks.com/support/requirements/supported-compilers.html and look up the requirements for your OS and version of Matlab. The MATLAB environment variable must point to your system matlab directory (see INSTALL for further details) ----------------------------------------------------------------- 3. Installation ----------------------------------------------------------------- Instructions for installing the Matlab Interface for MA75 are located in INSTALL. ----------------------------------------------------------------- 4. Using the Matlab interface ----------------------------------------------------------------- There are two approaches for using MA75 under Matlab. (a) Just use ma75_backslash in place of Matlab's own x = A\b (b) Use the subroutines that allows a factorization to be preserved and multiple subsequent solves to be performed using it. Approach (a) is offered as a subset of the functions implemented in (b). ----------------------------------------------------------------- 4(a). As a replacement backslash routine ----------------------------------------------------------------- - If not already in the search paths, add the directory where you installed the interface to the search paths, e.g. >> addpath('ma75_matlab') >> javaaddpath('ma75_matlab') where ma75_matlab is the directory. [ You can add these paths permanently (see 'help pathtool')] - To find x which minimizes ||b - Ax||: >> x = ma75_backslash(A, b) ----------------------------------------------------------------- 4(b). The 'expert' interface ----------------------------------------------------------------- The expert interface has the concept of handles. These are integers that refer to factorizations held in memory. The factorization will continue to take up memory until the 'destroy' call is used on that particular handle. The use of these handles allows for storing multiple matrix factors simultaneously without the inefficiency of translating internal data formats to MATLAB arrays. - If not already in the search paths, add the directory where you installed the interface to the search paths, e.g. >> addpath('ma75_matlab') >> javaaddpath('ma75_matlab') where ma75_matlab is the directory. [ You can add these paths permanently (see 'help pathtool') ] - ma75_factor may be used to perform the factorization of a matrix A. This is equivalent to calling the Fortran routines MA75ID and MA75AD. >> handle = ma75_factor(A) Optionally a weighting, control and info structures may be used >> [handle, info] = ma75_factor(A, W, control) - ma75_solve may be used to find x which minimizes the weighted least squares problem, i.e. which solves x = (A' * W^2 * A)\(A' * W^2 * b). This is equivalent to calling the Fortran routine MA75BD. >> x = ma75_solve(handle,b) - ma75_cov may be used to calculate the covariance matrix, or its diagonal or a column. This is equivalent to the Fortran routines MA75DC or MA75DD. >> C = ma75_cov(handle) or ma75_cov(handle,'matrix') calculates the covariance matrix. >> c = ma75_cov(handle,'col',j) calculates the jth column of the covariance matrix >> d = ma75_cov(handle,'diag') calculates the diagonal of the covariance matrix - ma75_destroy removes the previously calculated factorization from memory. >> ma75_destroy(handle) ----------------------------------------------------------------- 5. Information structure ----------------------------------------------------------------- A limited subset of the Fortran information parameters may be accessed through the MATLAB interface. The full range of these parameters is available through the Fortran interface. On return from the ma75_factor routine, the output argument info is a structur that will have one or more of the following components set: info.dup_entries - Initially 0, for each entry in A which appears k times, this is incremented by k-1 zero_weights - Number of zero weights input atw2a_nz - Number of non-zeros in A^T * W^2 * A storage - The amount of storage in the arrays ATA and IATA A fuller description for the info components is available in the Fortran documentation. ----------------------------------------------------------------- 6. Example ----------------------------------------------------------------- The following MATLAB session shows an expample of using ma75 to solve a system using the backslash action. >> A = sparse( [2.0 3.0 0.0; 1.0 0.0 4.0; 0.0 1.0 0.0; 6.0 0.0 5.0]); >> W = [2.0; 1.0; 2.0; 1.0]; >> b = [2.0; 12.0; 2.0; 15.0]; >> [x,info] = ma75_backslash(A,W,b); x = -0.3075 0.9845 3.2550 info = dup_entries: 0 zero_weights: 0 atw2a_nz: 5 storage: 72 >> [x,info] = ma75_backslash(A,b); x = 0.7500 0.5000 9.7500 info = dup_entries: 0 zero_weights: 0 atw2a_nz: 5 storage: 72