GENERIC INTERFACE Vector (VRep);
(*
  Linear algebra operations over "VRep.T"s.

  Created 95-02-27 by J. Stolfi.
  Last edited by stolfi *)
  
IMPORT Wr, Random, Thread;

TYPE 
  T = VRep.T;
  ElemT = VRep.ElemT;
  RealT = ARRAY [0..N-1] OF REAL;
  LongRealT = ARRAY [0..N-1] OF LONGREAL;
  Tuple = ARRAY OF VRep.T;

CONST
  N: CARDINAL = VRep.N;                  (* Number of coordinates *)

PROCEDURE Zero(): T;
  (*
    The null vector. *)
    
PROCEDURE All(x: LONGREAL): T;
  (*
    A vector with all coordinates equal to "x" *)

PROCEDURE Axis(i: [0..N-1]): T;
  (*
    The "i"th element of the canonical basis: all coordinates are zero,
    except coordinate "i" which is one. *)
    
PROCEDURE Get(READONLY a: T; i: [0..N-1]): LONGREAL;
  (*
    Extracts coordinate "i" of "a", converting it to LONGREAL *)
    
PROCEDURE Set(VAR a: T; i: [0..N-1]; x: LONGREAL);
  (*
    Sets coordinate "i" of "a" to "x", rounded if necessary. *)

PROCEDURE Add(READONLY a, b: T): T;
  (*
    Returns "a + b". *)

PROCEDURE Sub(READONLY a, b: T): T;
  (*
    Returns "a - b". *)

PROCEDURE Neg(READONLY a: T): T;
  (*
    Returns "-a" *)

PROCEDURE Scale(s: LONGREAL; READONLY a: T): T;
  (*
    Returns "s * a"; *)

PROCEDURE Weigh(READONLY w: LongRealT; READONLY a: T): T;
  (*
    Scales each component "a[i]" by "w[i]". *)

PROCEDURE Mix(s: LONGREAL; READONLY a: T; t: LONGREAL; READONLY b: T): T;
  (*
    Returns "s * a + t * b". *)

PROCEDURE Norm(READONLY a: T): LONGREAL;
  (*
    Returns the Euclidean norm (length) of vector "a". *)
    
PROCEDURE LInfNorm(READONLY a: T): LONGREAL;
  (*
    Returns the $L_\infinity$ norm of vector "a", i.e. the max absolute coordinate. *)

PROCEDURE NormSqr(READONLY a: T): LONGREAL;
  (*
    Returns the square of the Euclidean length of vector "a", i.e. "Dot(a,a)". *)

PROCEDURE Dist(READONLY a, b: T): LONGREAL;
  (*
    Returns the Euclidean distance between points "a" and "b". *)
    
PROCEDURE DistSqr(READONLY a, b: T): LONGREAL;
  (*
    Returns the square of the Euclidean distance between points "a" and "b". *)
    
PROCEDURE LInfDist(READONLY a, b: T): LONGREAL;
  (*
    Returns the max absolute difference between the coordinates of "a" and "b". *)

PROCEDURE Dir(READONLY a: T): T;
  (*
    Returns the unit-length vector "a/Norm(a)". *)

PROCEDURE LInfDir(READONLY a: T): T;
  (*
    Returns the vector "a/LInfNorm(a)". *)

PROCEDURE Dot(READONLY a, b: T): LONGREAL;
  (*
    Returns the dot product of vectors "a" and "b". *)

PROCEDURE Cos(READONLY a, b: T): LONGREAL;
  (*
    Returns the cosine of the angle between "a" and "b". *)

PROCEDURE Sin(READONLY a, b: T): LONGREAL;
  (*
    Returns the (non-negative) sine of the angle between "a" and "b". *)

PROCEDURE Project(READONLY a, u: T): T;
  (*
    Returns the component of vector "a" that is parallel to "u",
    that is, "u * Dot(a,u)/Dot(u,u)". *)

PROCEDURE Orthize(READONLY a, u: T): T;
  (*
    Returns the component of vector "a" that is orthogonal to "u",
    that is, "a - u * Dot(a,u)/Dot(u,u)". *)
    
PROCEDURE ToReal(READONLY a: T): RealT;
PROCEDURE ToLongReal(READONLY a: T): LongRealT;
  (*
    Convert from "VRep.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 "VRep.T". *)

PROCEDURE URandom(rnd: Random.T; min, max: LONGREAL): T;
  (*
    A vector whose coordinates are independent random numbers,
    uniformly distributed in "[min __ max)". *)
    
PROCEDURE NRandom(rnd: Random.T; avg, dev: LONGREAL): T;
  (*
    A vector whose coordinates are independent Gaussian random 
    numbers with mean "avg" and standard deviation "dev". *)

PROCEDURE Print(
    wr: Wr.T;
    READONLY a: T;
    lp := "("; sep := " "; rp := ")";
    fmt: PROCEDURE(x: ElemT): TEXT := VRep.DefaultElemFmt;
  ) RAISES {Wr.Failure, Thread.Alerted};
  (*
    Prints "a" on the given writer, formatting each coordinate
    with "fmt".
    
    The strings "lp", "sep", and "rp" are printed respectively before,
    between, and after all the coordinates of "a". *)
    
PROCEDURE ToText(READONLY a: T): TEXT;
  (*
    Formats "a" using the default formatter. *)

END Vector.