GENERIC INTERFACE Matrix (VRep, MRep);
(*
  Linear maps from some vector space "VRep.T" to itself,
  represented as "MRep.T"s.

  It is assumed that "VRep.T" is something that has "VRep.N" numeric
  components.  Conceptually, an "MRep.T" can be thought of as a
  "VRep.N" by "VRep.N" array of floats, but concretely it could be
  something else --- say, a triangular matrix, a quaternion, a
  procedure, etc.
  
  Created by J. Stolfi, with contributions by Marcos C. Carrard. *)

IMPORT Wr, Thread;
  
CONST
  N = VRep.N;

TYPE 
  T = MRep.T;
  ElemT = MRep.ElemT;
  RealT = ARRAY [0..N-1] OF ARRAY [0..N-1] OF REAL;
  LongRealT = ARRAY [0..N-1] OF ARRAY [0..N-1] OF LONGREAL;
 
PROCEDURE Null(): T;
  (*
    The null matrix *)
    
PROCEDURE Identity(): T;
  (*
    The identity matrix; *)
    
PROCEDURE Get(READONLY m: T; i, j: [0..N-1]): LONGREAL;
  (*
    Extracts coefficient "[i,j]" of "m", converting it to LONGREAL *)
    
PROCEDURE Set(VAR a: T; i, j: [0..N-1]; x: LONGREAL);
  (*
    Sets coefficient "[i,j]" of "m" to "x", rounded if necessary. *)

PROCEDURE MapRow(READONLY a: VRep.T; READONLY m: T): VRep.T;        
  (*
    Returns the product of "a", viewed as a row vector, by the matrix "m". *)

PROCEDURE MapCol(READONLY m: T; READONLY a: VRep.T): VRep.T;        
  (* 
    Returns the product of matrix "m" by the vector "a",
    viewed as a column vector. *)

PROCEDURE Mul(READONLY m, n: T): T;                     
  (*
    Returns the product of matrices "m" and "n", in that order.
    Only defined if the matrices are square. *)

PROCEDURE Det(READONLY m: T): LONGREAL;                     
  (*
    Returns the determinant of matrix "m". *)

PROCEDURE Inv(READONLY m: T): T;
  (*
    Returns the inverse of matrix "m".
    Assumes its determinant is non-zero. *)
                                                       
PROCEDURE Adj(READONLY m: T): T;
  (*
    Returns the adjoint of matrix "m", i.e. a matrix "a"
    such that "m * a = I * Det(m)" *)
                                                       
PROCEDURE ToReal(READONLY m: T): RealT;
PROCEDURE ToLongReal(READONLY m: T): LongRealT;
  (*
    Convert from "MRep.T" to plain array of "REAL" or "LONGREAL". *)
    
PROCEDURE FromReal(READONLY c: RealT): T;
PROCEDURE FromLongReal(READONLY c: LongRealT): T;
  (*
    Convert from plain array of "REAL" or "LONGREAL" to "MRep.T". *)

PROCEDURE Print(
    wr: Wr.T; 
    READONLY m: T; 
    olp := "( "; osep := "\n  "; orp := " )";
    ilp := "("; isep := " "; irp := ")";
    fmt: PROCEDURE (x: ElemT): TEXT := MRep.DefaultElemFmt;
    align: BOOLEAN := TRUE;
  ) RAISES {Wr.Failure, Thread.Alerted};
  (*
    Prints the matrix "m" to the given writer, formatting
    each coefficient with "fmt".
    
    The ``inner'' delimiters "ilp", "isep", and "irp" are printed
    before the first element, between elements, and after the last element
    in each row.  The ``outer'' delimiters "olp", "osep", and "orp" are printed 
    before the first row, between rows, and after the last row.
    
    If "align" is true, the entries in each column will be padded 
    with blanks as needed to align them vertically.  *)

PROCEDURE ToText(READONLY m: T): TEXT;
  (*
    Formats "m" in some standard format. *)

END Matrix.