-------------------------------------------------------------
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