with Standard_Natural_Vectors;
with Standard_Floating_Vectors;
with Standard_Floating_Matrices;

package Standard_Floating_QR_Decomposition is

-- DESCRIPTION :
--   This package provides an implementation of QR-decomposition for
--   matrices of standard floating numbers.

  procedure QRD ( x : in out Standard_Floating_Matrices.Matrix;
                  qraux : in out Standard_Floating_Vectors.Vector;
                  jpvt : in out Standard_Natural_Vectors.Vector;
                  piv : in boolean );

  -- DESCRIPTION :
  --   Uses Householder transformations to compute the QR decomposition of x.
  --   Column pivoting based on 2-norms of reduced columns is optional.

  -- REQUIRED : jpvt'range = x'range(2) = qraux'range,
  --            x'length(1) >= x'length(2)

  -- ON ENTRY :
  --   x          matrix whose decomposition is to be computed;
  --   jpvt       controls the selection of the pivot columns.
  --              The k-th column x(k) of x is placed in one of three classes
  --              according to the value of jpvt(k):
  --                if jpvt(k) > 0, then x(k) is an initial column.
  --                if jpvt(k) = 0, then x(k) is a free column.
  --                if jpvt(k) < 0, then x(k) is a final column.
  --              before the decomposition is computed, initial columns are
  --              moved to the beginning of the array x and final columns to
  --              the end.  Both initial and final columns are frozen in place
  --              during the computation and only free columns are moved.
  --              At the k-th stage of the reduction, if x(k) is occupied by a
  --              free column it is interchanged with the free column of
  --              largest reduced norm.  jpvt is not referenced if not piv.
  --   piv        column pivoting is performed if and only if piv is true.

  -- ON RETURN :
  --   x          x contains in its upper triangle the upper triangular matrix
  --              R of the QR factorization.  Below its diagonal x contains
  --              information from which the orthogonal part of the
  --              decomposition can be recovered.  Note that if pivoting has
  --              been requested, the decomposition is not that of the original
  --              matrix x but that of x with its columns permuted as described
  --              by jpvt.
  --   qraux      qraux contains further information required to recover
  --              the orthogonal part of the decomposition.
  --   jpvt       jpvt(k) contains the index of the column of the original
  --              matrix that has been interchanged into the k-th column,
  --              if pivoting was requested.
  
  -- ACKNOWLEDGMENT :
  --   This Ada Version is a translation of the LINPACK version, dated 08/14/78,
  --   written by G.W. Stewart, University of Maryland, Argonne National Lab.

  procedure Permute_Columns ( x : in out Standard_Floating_Matrices.Matrix;
                              jpvt : in Standard_Natural_Vectors.Vector );

  -- DESCRIPTION :
  --   Permutes the columns of the matrix x according to jpvt:
  --     x := (x(jpvt(1)),x(jpvt(2)), ... ,x(jpvt(k))), k = jpvt'last.
  --   This routine is useful to the Least Squares computation.

  procedure Permute ( x : in out Standard_Floating_Vectors.Vector;
                      jpvt : in Standard_Natural_Vectors.Vector );

  -- DESCRIPTION :
  --   Permutes the columns of the vector x according to jpvt:
  --     x := (x(jpvt(1)),x(jpvt(2)), ... ,x(jpvt(k))), k = jpvt'last.
  --   This routine is useful to the Least Squares computation.

  procedure Basis ( qr : in out Standard_Floating_Matrices.Matrix;
                    x : in Standard_Floating_Matrices.Matrix );

  -- DESCRIPTION :
  --   Retrieves the orthogonal part of the decomposition.
  --   The columns of qr on output correspond to the column span of x.

  -- IMPORTANT :
  --   Note that this does not work when pivoting was requested.

  -- REQUIRED : qr'range(1) = qr'range(2) = x'range(1).

  -- ON ENTRY :
  --   qr         contains output of the routine qrd;
  --   x          original matrix as part of the input of qrd.

  -- ON RETURN : 
  --   qr         orthogonal part of the QR-decomposition.

end Standard_Floating_QR_Decomposition;