CVS difference for ais/ai-00296.txt

Differences between 1.1 and version 1.2
Log of other versions for file ais/ai-00296.txt

--- ais/ai-00296.txt	2002/06/11 05:15:50	1.1
+++ ais/ai-00296.txt	2003/01/23 03:11:15	1.2
@@ -1,4 +1,4 @@
-!standard G (00)                                        02-06-07  AI95-00296/00
+!standard G (00)                                        03-02-21  AI95-00296/01
 !class amendment 02-06-07
 !status received 02-06-07
 !priority Medium
@@ -7,19 +7,509 @@
 
 !summary
 
-The vector and matric operations in ISO/IEC 13813 should be added to
-Ada.Numerics in Annex G.
+The vector and matrix operations in ISO/IEC 13813 are added to Ada.Numerics in
+Annex G.
 
 !problem
 
+A number of secondary standards for Ada 83 were produced for the numerics area.
+Most of the functionality of these standards was incorporated into Ada 95 (some
+in the core language and some in the Numerics Annex) but two packages from
+ISO/IEC 13813 were not. These are generic packages for the manipulation of real
+and complex vectors and matrices.
+
+The UK was asked to review the situation and to make a recommendation; they
+recommended that if Ada were amended then consideration should be given to
+including the packages within the Numerics annex.
+
+The packages can be implemented entirely in Ada and thus present little burden
+to implementors. Providing secondary standards has not proved satisfactory
+because they are not sufficiently visible to the user community as a whole.
+
 !proposal
 
+It is proposed that two generic packages be added to the numerics annex. They
+are Ada.Numerics.Generic_Real_Arrays and Ada.Numerics.Generic_Complex_Arrays.
+They are included as a new subclause G.3 in order to avoid excessive
+renumbering of other clauses.
+
+However, if rearrangement of the Annex were deemed acceptable then it might be
+better to put the real arrays package in G.1 (any other non-complex numeric
+library packages might then also be in G.1), to renumber G.1 (Complex
+Arithmetic) as G.2 and G.2 (Numeric Performance Requirements) as G.3. The
+complex arrays package could then be G.2.5.
+
 !wording
 
+Add a new clause G.3 as follows
+
+G.3 Vector and matrix manipulation
+
+Types and operations for the manipulation of real vectors and matrices are
+provided in Generic_Real_Arrays, which is defined in G.3.1. Types and
+operations for the manipulation of complex vectors and matrices are provided in
+Generic_Complex_Arrays, which is defined in G.3.2. Both of these library units
+are generic children of the predefind package Numerics (see A.5).
+
+??? do we need non-generic equivalents ???
+
+G.3.1 Real Vectors and Matrices
+
+The generic library package Numerics.Generic_Real_Arrays has the following
+declaration:
+
+
+generic
+   type Real is digits <>;
+package Ada.Numerics.Generic_Real_Arrays is
+
+   pragma Pure(Generic_Real_Arrays);
+
+   -- Types
+
+   type Real_Vector is array (Integer range <>) of Real'Base;
+   type Real_Matrix is array (Integer range <>, Integer range <>) of Real'Base;
+
+   -- Subprograms for Real_Vector Types
+
+   -- Real_Vector arithmetic operations
+
+   function "+"   (Right : Real_Vector)       return Real_Vector;
+   function "-"   (Right : Real_Vector)       return Real_Vector;
+   function "abs" (Right : Real_Vector)       return Real_Vector;
+
+   function "+"   (Left, Right : Real_Vector) return Real_Vector;
+   function "-"   (Left, Right : Real_Vector) return Real_Vector;
+   function "*"   (Left, Right : Real_Vector) return Real_Vector;
+   function "/"   (Left, Right : Real_Vector) return Real_Vector;
+   function "**"  (Left        : Real_Vector;
+                   Right       : Integer)     return Real_Vector;
+
+   function "*"   (Left, Right : Real_Vector) return Real'Base;
+
+   -- Real_Vector scaling operations
+
+   function "*"   (Left  : Real'Base;   Right : Real_Vector) return Real_Vector;
+   function "*"   (Left  : Real_Vector; Right : Real'Base)   return Real_Vector;
+   function "/"   (Left  : Real_Vector; Right : Real'Base)   return Real_Vector;
+
+   -- Other Real_Vector operations
+
+   function Unit_Vector (Index : Integer;
+                         Order : Positive;
+                         First : Integer := 1) return Real_Vector;
+
+   -- Subprograms for Real_Matrix Types
+
+   -- Real_Matrix arithmetic operations
+
+   function "+"       (Right : Real_Matrix) return Real_Matrix;
+   function "-"       (Right : Real_Matrix) return Real_Matrix;
+   function "abs"     (Right : Real_Matrix) return Real_Matrix;
+   function Transpose (X     : Real_Matrix) return Real_Matrix;
+
+   function "+" (Left, Right : Real_Matrix) return Real_Matrix;
+   function "-" (Left, Right : Real_Matrix) return Real_Matrix;
+   function "*" (Left, Right : Real_Matrix) return Real_Matrix;
+
+   function "*" (Left, Right : Real_Vector) return Real_Matrix;
+
+   function "*" (Left  : Real_Vector; Right : Real_Matrix) return Real_Vector;
+   function "*" (Left  : Real_Matrix; Right : Real_Vector) return Real_Vector;
+
+   -- Real_Matrix scaling operations
+
+   function "*" (Left  : Real'Base;   Right : Real_Matrix) return Real_Matrix;
+   function "*" (Left  : Real_Matrix; Right : Real'Base)   return Real_Matrix;
+   function "/" (Left  : Real_Matrix; Right : Real'Base)   return Real_Matrix;
+
+   -- Other Real_Matrix operations
+
+   function Identity_Matrix (Order            : Positive;
+                             First_1, First_2 : Integer := 1) return Real_Matrix;
+
+end Ada.Numerics.Generic_Real_Arrays;
+
+
+Two types are defined and exported by Ada.Numerics.Generic_Real_Arrays. The
+composite type Real_Vector is provided to represent a vector with components of
+type Real; it is defined as an unconstrained, one-dimensional array with an
+index of type Integer. The composite type Real_Matrix is provided to represent
+a matrix with components of type Real; it is defined as an unconstrained,
+two-dimensional array with indices of type Integer.
+
+?? maybe indexes ??
+
+The effect of the various functions is as described below. In most cases the
+functions are described in terms of corresponding scalar operations of the type
+Real; any exception raised by those operations is propagated by the array
+operation. Moreover the accuracy of the result for each individual component is
+as defined for the scalar operation unless stated otherwise.
+
+function "+"   (Right : Real_Vector) return Real_Vector;
+function "-"   (Right : Real_Vector) return Real_Vector;
+function "abs" (Right : Real_Vector) return Real_Vector;
+
+Each operation returns the result of applying the corresponding operation of
+the type Real to each component of Right. These are the standard mathematical
+operations for vector identity, negation and absolute value respectively. The
+bounds of the result are those of Right.
+
+function "+" (Left, Right : Real_Vector) return Real_Vector;
+function "-" (Left, Right : Real_Vector) return Real_Vector;
+function "*" (Left, Right : Real_Vector) return Real_Vector;
+function "/" (Left, Right : Real_Vector) return Real_Vector;
+
+Each operation returns the result of applying the corresponding operation of
+the type Real to each component of Left and the matching component of Right.
+These are the standard mathematical operations for vector addition,
+subtraction, multiplication and division respectively. The bounds of the result
+are those of the left operand. The exception Constraint_Error is raised if
+Left'Length is not equal to Right'Length.
+
+function "**" (Left  : Real_Vector; Right : Integer) return Real_Vector;
+
+This operation returns the result of applying the corresponding operation "**"
+of the type Real with integer power Right to each component of Left. The bounds
+of the result are those of the left operand.
+
+function "*" (Left, Right  : Real_Vector) return Real'Base;
+
+This operation returns the inner (dot) product of Left and Right. The exception
+Constraint_Error is raised if Left'Length is not equal to Right'Length. This
+operation involves an inner product; an accuracy requirement is not specified.
+Constraint_Error is raised if an intermediate result is outside the range of
+Real'Base even though the mathematical final result would not be.
+
+function "*" (Left  : Real'Base; Right : Real_Vector) return Real_Vector;
+
+This operation returns the result of multiplying each component of Right by the
+scalar Left using the "*" operation of the type Real. This is the standard
+mathematical operation for scaling a vector Right by a real number Left. The
+bounds of the result are those of the right operand.
+
+function "*" (Left  : Real_Vector; Right : Real'Base) return Real_Vector;
+function "/" (Left  : Real_Vector; Right : Real'Base) return Real_Vector;
+
+Each operation returns the result of applying the corresponding operation of
+the type Real to each component of Left and to the scalar Right. These are
+standard mathematical operations for scaling a vector Left by a real number
+Right. The bounds of the result are those of the left operand.
+
+function Unit_Vector (Index : Integer;
+                      Order : Positive;
+                      First : Integer := 1) return Real_Vector;
+
+This function returns a "unit vector" with Order components and a lower bound
+of First. All components are set to 0.0 except for the Index component which is
+set to 1.0. The exception Constraint_Error is raised if Index < First, Index >
+First + Order - 1 or if First + Order - 1 > Integer'Last. This function is
+exact.
+
+function "+"   (Right : Real_Matrix) return Real_Matrix;
+function "-"   (Right : Real_Matrix) return Real_Matrix;
+function "abs" (Right : Real_Matrix) return Real_Matrix;
+
+Each operation returns the result of applying the corresponding operation of
+the type Real to each component of Right. These are the standard mathematical
+operations for matrix identity, negation and absolute value respectively. The
+bounds of the result are those of Right.
+
+function Transpose (X : Real_Matrix) return Real_Matrix;
+
+This function returns the transpose of a matrix X. The index ranges of the
+result are X'Range(2) and X'Range(1) (first and second index respectively).
+This function is exact.
+
+function "+" (Left, Right : Real_Matrix) return Real_Matrix;
+function "-" (Left, Right : Real_Matrix) return Real_Matrix;
+
+Each operation returns the result of applying the corresponding operation of
+type Real to each component of Left and the matching component of Right. These
+are also the standard mathematical operations for matrix addition and
+subtraction. The bounds of the result are those of Left. The exception
+Constraint_Error is raised if Left'Length(1) is not equal to Right'Length(1) or
+Left'Length(2) is not equal to Right'Length(2).
+
+function "*" (Left, Right : Real_Matrix) return Real_Matrix;
+
+This operation provides the standard mathematical operation for matrix
+multiplication. The index ranges of the result are Left'Range(1) and
+Right'Range(2) (first and second index respectively). The exception
+Constraint_Error is raised if Left'Length(2) is not equal to Right'Length(1).
+This operation involves an inner product; an accuracy requirement is not
+specified. Constraint_Error is raised if an intermediate result is outside the
+range of Real'Base even though the mathematical final result would not be.
+
+function "*" (Left, Right : Real_Vector) return Real_Matrix;
+
+This operation provides the standard mathematical operation for multiplication
+of a (column) vector Left by a (row) vector Right. The index ranges of the
+matrix result are Left'Range and Right'Range (first and second index
+respectively).
+
+function "*" (Left : Real_Vector; Right : Real_Matrix) return Real_Vector;
+
+This operation provides the standard mathematical operation for multiplication
+of a (row) vector Left by a matrix Right. The index range of the (row) vector
+result is Right'Range(2). The exception Constraint_Error is raised if
+Left'Length is not equal to Right'Length(1). This operation involves an inner
+product; an accuracy requirement is not specified. Constraint_Error is raised
+if an intermediate result is outside the range of Real'Base even though the
+mathematical final result would not be.
+
+function "*" (Left : Real_Matrix; Right : Real_Vector) return Real_Vector;
+
+This operation provides the standard mathematical operation for multiplication
+of a matrix Left by a (column) vector Right. The index range of the (column)
+vector result is Left'Range(1). The exception Constraint_Error is raised if
+Left'Length(2) is not equal to Right'Length. This operation involves an inner
+product; an accuracy requirement is not specified. Constraint_Error is raised
+if an intermediate result is outside the range of Real'Base even though the
+mathematical final result would not be.
+
+function "*" (Left : Real'Base; Right : Real_Matrix) return Real_Matrix;
+
+This operation returns the result of multiplying each component of Right by the
+scalar Left using the "*" operation of the type Real. This is the standard
+mathematical operation for scaling a matrix Right by a real number Left. The
+index ranges of the matrix result are those of Right.
+
+function "*" (Left  : Real_Matrix; Right : Real'Base) return Real_Matrix;
+function "/" (Left  : Real_Matrix; Right : Real'Base) return Real_Matrix;
+
+Each operation returns the result of applying the corresponding operation of
+the type Real to each component of Left and to the scalar Right. These are
+standard mathematical operations for scaling a matrix Left by a real number
+Right. The index ranges of the matrix result are those of Left.
+
+function Identity_Matrix (Order            : Positive;
+                          First_1, First_2 : Integer := 1) return Real_Matrix;
+
+This function returns a square "identity matrix" with Order**2 components and
+lower bounds of First_1 and First_2 (for the first and second index ranges
+respectively). All components are set to 0.0 except for the main diagonal,
+whose components are set to 1.0. The exception Constraint_Error is raised if
+First_1 + Order - 1 > Integer'Last or First_2 + Order - 1 > Integer'Last. This
+function is exact.
+
+
+G.3.2 Complex Vectors and Matrices
+
+The generic library package Numerics.Generic_Complex_Arrays has the following
+declaration:
+
+
+with Ada.Numerics.Generic_Real_Arrays, Ada.Numerics.Generic_Complex_Types;
+generic
+   with package Real_Arrays   is new Ada.Numerics.Generic_Real_Arrays   (<>);
+   use Real_Arrays;
+   with package Complex_Types is new Ada.Numerics.Generic_Complex_Types (Real);
+   use Complex_Types;
+package Ada.Numerics.Generic_Complex_Arrays is
+   pragma Pure(Generic_Complex_Arrays);
+
+   -- Types
+
+   type Complex_Vector is array (Integer range <>) of Complex;
+   type Complex_Matrix is array (Integer range <>,
+                                 Integer range <>) of Complex;
+
+   -- Subprograms for Complex_Vector types
+
+   -- Complex_Vector selection, conversion and composition operations
+
+   function Re (X : Complex_Vector) return Real_Vector;
+   function Im (X : Complex_Vector) return Real_Vector;
+
+   procedure Set_Re (X  : in out Complex_Vector;
+                     Re : in     Real_Vector);
+   procedure Set_Im (X  : in out Complex_Vector;
+                     Im : in     Real_Vector);
+
+   function Compose_From_Cartesian (Re     : Real_Vector) return Complex_Vector;
+   function Compose_From_Cartesian (Re, Im : Real_Vector) return Complex_Vector;
+
+   function Modulus  (X     : Complex_Vector) return Real_Vector;
+   function "abs"    (Right : Complex_Vector) return Real_Vector renames Modulus;
+   function Argument (X     : Complex_Vector) return Real_Vector;
+   function Argument (X     : Complex_Vector;
+                      Cycle : Real'Base)      return Real_Vector;
+
+   function Compose_From_Polar (Modulus, Argument : Real_Vector)
+      return Complex_Vector;
+   function Compose_From_Polar (Modulus, Argument : Real_Vector;
+                                Cycle             : Real'Base)
+      return Complex_Vector;
+
+   -- Complex_Vector arithmetic operations
+
+   function "+"       (Right  : Complex_Vector) return Complex_Vector;
+   function "-"       (Right  : Complex_Vector) return Complex_Vector;
+   function Conjugate (X      : Complex_Vector) return Complex_Vector;
+
+   function "+"  (Left, Right : Complex_Vector) return Complex_Vector;
+   function "-"  (Left, Right : Complex_Vector) return Complex_Vector;
+   function "*"  (Left, Right : Complex_Vector) return Complex_Vector;
+   function "/"  (Left, Right : Complex_Vector) return Complex_Vector;
+   function "**" (Left  : Complex_Vector;
+                  Right : Integer)              return Complex_Vector;
+
+   function "*"  (Left, Right : Complex_Vector) return Complex;
+
+   -- Mixed Real_Vector and Complex_Vector arithmetic operations
+
+   function "+" (Left  : Real_Vector;
+                 Right : Complex_Vector) return Complex_Vector;
+   function "+" (Left  : Complex_Vector;
+                 Right : Real_Vector)    return Complex_Vector;
+   function "-" (Left  : Real_Vector;
+                 Right : Complex_Vector) return Complex_Vector;
+   function "-" (Left  : Complex_Vector;
+                 Right : Real_Vector)    return Complex_Vector;
+   function "*" (Left  : Real_Vector;
+                 Right : Complex_Vector) return Complex_Vector;
+   function "*" (Left  : Complex_Vector;
+                 Right : Real_Vector)    return Complex_Vector;
+   function "/" (Left  : Real_Vector;
+                 Right : Complex_Vector) return Complex_Vector;
+   function "/" (Left  : Complex_Vector;
+                 Right : Real_Vector)    return Complex_Vector;
+
+   function "*" (Left  : Real_Vector;    Right : Complex_Vector) return Complex;
+   function "*" (Left  : Complex_Vector; Right : Real_Vector)    return Complex;
+
+   -- Complex_Vector scaling operations
+
+   function "*" (Left  : Complex;
+                 Right : Complex_Vector) return Complex_Vector;
+   function "*" (Left  : Complex_Vector;
+                 Right : Complex)        return Complex_Vector;
+   function "/" (Left  : Complex_Vector;
+                 Right : Complex)        return Complex_Vector;
+
+   function "*" (Left  : Real'Base;
+                 Right : Complex_Vector) return Complex_Vector;
+   function "*" (Left  : Complex_Vector;
+                 Right : Real'Base)      return Complex_Vector;
+   function "/" (Left  : Complex_Vector;
+                 Right : Real'Base)      return Complex_Vector;
+
+   -- Other Complex_Vector operations
+
+   function Unit_Vector (Index : Integer;
+                         Order : Positive;
+                         First : Integer := 1) return Complex_Vector;
+
+   -- Subprograms for Complex_Matrix Types
+
+   -- Complex_Matrix selection, conversion and composition operations
+
+   function Re (X : Complex_Matrix) return Real_Matrix;
+   function Im (X : Complex_Matrix) return Real_Matrix;
+
+   procedure Set_Re (X  : in out Complex_Matrix;
+                     Re : in     Real_Matrix);
+   procedure Set_Im (X  : in out Complex_Matrix;
+                     Im : in     Real_Matrix);
+
+   function Compose_From_Cartesian (Re     : Real_Matrix) return Complex_Matrix;
+   function Compose_From_Cartesian (Re, Im : Real_Matrix) return Complex_Matrix;
+
+   function Modulus  (X     : Complex_Matrix) return Real_Matrix;
+   function "abs"    (Right : Complex_Matrix) return Real_Matrix renames Modulus;
+
+   function Argument (X     : Complex_Matrix) return Real_Matrix;
+   function Argument (X     : Complex_Matrix;
+                      Cycle : Real'Base)      return Real_Matrix;
+
+   function Compose_From_Polar (Modulus, Argument : Real_Matrix)
+      return Complex_Matrix;
+   function Compose_From_Polar (Modulus, Argument : Real_Matrix;
+                                Cycle             : Real'Base)
+      return Complex_Matrix;
+
+   -- Complex_Matrix arithmetic operations
+
+   function "+"       (Right : Complex_Matrix) return Complex_Matrix;
+   function "-"       (Right : Complex_Matrix) return Complex_Matrix;
+   function Conjugate (X     : Complex_Matrix) return Complex_Matrix;
+   function Transpose (X     : Complex_Matrix) return Complex_Matrix;
+
+   function "+" (Left, Right : Complex_Matrix) return Complex_Matrix;
+   function "-" (Left, Right : Complex_Matrix) return Complex_Matrix;
+   function "*" (Left, Right : Complex_Matrix) return Complex_Matrix;
+
+   function "*" (Left, Right : Complex_Vector) return Complex_Matrix;
+
+   function "*" (Left  : Complex_Vector;
+                 Right : Complex_Matrix) return Complex_Vector;
+   function "*" (Left  : Complex_Matrix;
+                 Right : Complex_Vector) return Complex_Vector;
+
+   -- Mixed Real_Matrix and Complex_Matrix arithmetic operations
+
+   function "+" (Left  : Real_Matrix;
+                 Right : Complex_Matrix) return Complex_Matrix;
+   function "+" (Left  : Complex_Matrix;
+                 Right : Real_Matrix)    return Complex_Matrix;
+   function "-" (Left  : Real_Matrix;
+                 Right : Complex_Matrix) return Complex_Matrix;
+   function "-" (Left  : Complex_Matrix;
+                 Right : Real_Matrix)    return Complex_Matrix;
+   function "*" (Left  : Real_Matrix;
+                 Right : Complex_Matrix) return Complex_Matrix;
+   function "*" (Left  : Complex_Matrix;
+                 Right : Real_Matrix)    return Complex_Matrix;
+
+   function "*" (Left  : Real_Vector;
+                 Right : Complex_Vector) return Complex_Matrix;
+   function "*" (Left  : Complex_Vector;
+                 Right : Real_Vector)    return Complex_Matrix;
+   function "*" (Left  : Real_Vector;
+                 Right : Complex_Matrix) return Complex_Vector;
+   function "*" (Left  : Complex_Vector;
+                 Right : Real_Matrix)    return Complex_Vector;
+   function "*" (Left  : Real_Matrix;
+                 Right : Complex_Vector) return Complex_Vector;
+   function "*" (Left  : Complex_Matrix;
+                 Right : Real_Vector)    return Complex_Vector;
+
+   -- Complex_Matrix scaling operations
+
+   function "*" (Left  : Complex;
+                 Right : Complex_Matrix) return Complex_Matrix;
+   function "*" (Left  : Complex_Matrix;
+                 Right : Complex)        return Complex_Matrix;
+   function "/" (Left  : Complex_Matrix;
+                 Right : Complex)        return Complex_Matrix;
+
+   function "*" (Left  : Real'Base;
+                 Right : Complex_Matrix) return Complex_Matrix;
+   function "*" (Left  : Complex_Matrix;
+                 Right : Real'Base)      return Complex_Matrix;
+   function "/" (Left  : Complex_Matrix;
+                 Right : Real'Base)      return Complex_Matrix;
+
+   -- Other Complex_Matrix operations
+
+   function Identity_Matrix (Order            : Positive;
+                             First_1, First_2 : Integer := 1)
+      return Complex_Matrix;
+
+end Ada.Numerics.Generic_Complex_Arrays;
+
+To be concluded
+
 !example
 
+To be done
+
 !discussion
 
+To be done
+
+
 !ACATS Test
 
 ACATS test(s) need to be created.
@@ -162,3 +652,4 @@
 original standard, in the preparation of this recommendation.
 
 ****************************************************************
+

Questions? Ask the ACAA Technical Agent