Generic package: Ada.Numerics.Generic_Complex

Generic package: Ada.Numerics.Generic_Complex_Arrays

Dependencies

pragma License (Unrestricted);

with Ada.Numerics.Generic_Real_Arrays;
with Ada.Numerics.Generic_Complex_Types;

Description

Implementation Requirements

Accuracy requirements for the functions Solve, Inverse and Determinant are implementation defined.

For operations not involving an inner product, the accuracy requirements are those of the corresponding operations of the type Real'Base and Complex in both the strict mode and the relaxed mode (see G.2).

For operations involving an inner product, no requirements are specified in the relaxed mode. In the strict mode the accuracy should be at least that of the canonical implementation of multiplication and addition using the corresponding operations of type Real'Base and Complex and performing the cumulative addition using ascending indices. Implementations shall document any techniques used to reduce cancellation errors such as extended precision arithmetic.

Implementation Permissions

The nongeneric equivalent packages may, but need not, be actual instantiations of the generic package for the appropriate predefined type.

Although many operations are defined in terms of operations from Numerics.Generic_Complex_Types, they need not be implemented by calling those operations provided that the effect is the same.

Implementation Advice

Implementations should implement the Solve and Inverse functions using established techniques. Implementations may choose to refine the result by performing an iteration on the residuals; if this is done then it should be documented.

It is not the intention that any special provision should be made to determine whether a matrix is ill-conditioned or not. The naturally occurring overflow (including division by zero) which will result from executing these functions with an ill-conditioned matrix and thus raise Constraint_Error is sufficient.

Implementations should not perform operations on mixed complex and real operands by first converting the real operand to complex. See G.1.1(56,57).

Header

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

Type Summary

`Complex_Matrix`
`Complex_Vector`

Other Items:

type Complex_Vector is array (Integer range <>) of Complex;

type Complex_Matrix is array (Integer range <>,
                              Integer range <>) of Complex;

function Re (X : Complex_Vector) return Real_Vector;

function Im (X : Complex_Vector) return Real_Vector;

Each function returns a vector of the specified cartesian components of X. The index range of the result is X'Range.

procedure Set_Re (X  : in out Complex_Vector;
                  Re : in     Real_Vector);

procedure Set_Im (X  : in out Complex_Vector;
                  Im : in     Real_Vector);

Each procedure replaces the specified (cartesian) component of each of the components of X by the value of the matching component of Re or Im; the other (cartesian) component of each of the components is unchanged. The exception Constraint_Error is raised if X'Length is not equal to Re'Length or Im'Length.

function Compose_From_Cartesian (Re : Real_Vector)
   return Complex_Vector;

function Compose_From_Cartesian (Re, Im : Real_Vector)
   return Complex_Vector;

Each function constructs a vector of Complex results (in cartesian representation) formed from given vectors of cartesian components; when only the real components are given, imaginary components of zero are assumed. The index range of the result is Re'Range. The exception Constraint_Error is raised if Re'Length is not equal to Im'Length.

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;

Each function calculates and returns a vector of the specified polar components of X or Right using the corresponding function in Numerics.Generic_Complex_Types. The index range of the result is X'Range or Right'Range.

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;

Each function constructs a vector of Complex results (in cartesian representation) formed from given vectors of polar components using the corresponding function in Numerics.Generic_Complex_Types on matching components of Modulus and Argument. The index range of the result is Modulus'Range. The exception Constraint_Error is raised if Modulus'Length is not equal to Argument'Length.

function "+" (Right : Complex_Vector) return Complex_Vector;

function "-" (Right : Complex_Vector) return Complex_Vector;

Each operation returns the result of applying the corresponding operation in Numerics.Generic_Complex_Types to each component of Right. The index range of the result is Right'Range.

function Conjugate (X : Complex_Vector) return Complex_Vector;

This function returns the result of applying the appropriate function Conjugate in Numerics.Generic_Complex_Types to each component of X. The index range of the result is X'Range.

function "+"  (Left, Right : Complex_Vector) return Complex_Vector;

function "-"  (Left, Right : Complex_Vector) return Complex_Vector;

Each operation returns the result of applying the corresponding operation in Numerics.Generic_Complex_Types to each component of Left and the matching component of Right. The index range of the result is Left'Range. The exception Constraint_Error is raised if Left'Length is not equal to Right'Length.

function "*" (Left, Right : Complex_Vector) return Complex;

This operation returns the inner 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.

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;

Each operation returns the inner product of Left and Right. The exception Constraint_Error is raised if Left'Length is not equal to Right'Length. These operations involve an inner product.

function "*" (Left  : Complex;
              Right : Complex_Vector) return Complex_Vector;

This operation returns the result of multiplying each component of Right by the complex number Left using the appropriate operation "*" in Numerics.Generic_Complex_Types. The index range of the result is Right'Range.

function "*" (Left  : Complex_Vector;
              Right : Complex)        return Complex_Vector;

function "/" (Left  : Complex_Vector;
              Right : Complex)        return Complex_Vector;

Each operation returns the result of applying the corresponding operation in Numerics.Generic_Complex_Types to each component of the vector Left and the complex number Right. The index range of the result is Left'Range.

function "*" (Left  : Real'Base;
              Right : Complex_Vector) return Complex_Vector;

This operation returns the result of multiplying each component of Right by the real number Left using the appropriate operation "*" in Numerics.Generic_Complex_Types. The index range of the result is Right'Range.

function "*" (Left  : Complex_Vector;
              Right : Real'Base)      return Complex_Vector;

function "/" (Left  : Complex_Vector;
              Right : Real'Base)      return Complex_Vector;

Each operation returns the result of applying the corresponding operation in Numerics.Generic_Complex_Types to each component of the vector Left and the real number Right. The index range of the result is Left'Range.

function Unit_Vector (Index : Integer;
                      Order : Positive;
                      First : Integer := 1) return Complex_Vector;

This function returns a "unit vector" with Order components and a lower bound of First. All components are set to (0.0,0.0) except for the Index component which is set to (1.0,0.0). The exception Constraint_Error is raised if Index First + Order - 1, or if First + Order - 1 Integer'Last.

function Re (X : Complex_Matrix) return Real_Matrix;

function Im (X : Complex_Matrix) return Real_Matrix;

Each function returns a matrix of the specified cartesian components of X. The index ranges of the result are those of X.

procedure Set_Re (X  : in out Complex_Matrix;
                  Re : in     Real_Matrix);

procedure Set_Im (X  : in out Complex_Matrix;
                  Im : in     Real_Matrix);

Each procedure replaces the specified (cartesian) component of each of the components of X by the value of the matching component of Re or Im; the other (cartesian) component of each of the components is unchanged. The exception Constraint_Error is raised if X'Length(1) is not equal to Re'Length(1) or Im'Length(1) or if X'Length(2) is not equal to Re'Length(2) or Im'Length(2).

function Compose_From_Cartesian (Re : Real_Matrix) return Complex_Matrix;

function Compose_From_Cartesian (Re,
                                 Im : Real_Matrix) return Complex_Matrix;

Each function constructs a matrix of Complex results (in cartesian representation) formed from given matrices of cartesian components; when only the real components are given, imaginary components of zero are assumed. The index ranges of the result are those of Re. The exception Constraint_Error is raised if Re'Length(1) is not equal to Im'Length(1) or Re'Length(2) is not equal to Im'Length(2).

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;

Each function calculates and returns a matrix of the specified polar components of X or Right using the corresponding function in Numerics.Generic_Complex_Types. The index ranges of the result are those of X or Right.

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;

Each function constructs a matrix of Complex results (in cartesian representation) formed from given matrices of polar components using the corresponding function in Numerics.Generic_Complex_Types on matching components of Modulus and Argument. The index ranges of the result are those of Modulus. The exception Constraint_Error is raised if Modulus'Length(1) is not equal to Argument'Length(1) or Modulus'Length(2) is not equal to Argument'Length(2).

function "+" (Right : Complex_Matrix) return Complex_Matrix;

function "-" (Right : Complex_Matrix) return Complex_Matrix;

Each operation returns the result of applying the corresponding operation in Numerics.Generic_Complex_Types to each component of Right. The index ranges of the result are those of Right.

function Conjugate (X : Complex_Matrix) return Complex_Matrix;

This function returns the result of applying the appropriate function Conjugate in Numerics.Generic_Complex_Types to each component of X. The index ranges of the result are those of X.

function Transpose (X : Complex_Matrix) return Complex_Matrix;

This function returns the transpose of a matrix X. The first and second index ranges of the result are X'Range(2) and X'Range(1) respectively.

function "+" (Left, Right : Complex_Matrix) return Complex_Matrix;

function "-" (Left, Right : Complex_Matrix) return Complex_Matrix;

Each operation returns the result of applying the corresponding operation in Numerics.Generic_Complex_Types to each component of Left and the matching component of Right. The index ranges 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 : Complex_Matrix) return Complex_Matrix;

This operation provides the standard mathematical operation for matrix multiplication. The first and second index ranges of the result are Left'Range(1) and Right'Range(2) respectively. The exception Constraint_Error is raised if Left'Length(2) is not equal to Right'Length(1). This operation involves inner products.

function "*" (Left, Right : Complex_Vector) return Complex_Matrix;

This operation returns the outer product of a (column) vector Left by a (row) vector Right using the appropriate operation "*" in Numerics.Generic_Complex_Types for computing the individual components. The first and second index ranges of the matrix result are Left'Range and Right'Range respectively.

function "*" (Left  : Complex_Vector;
              Right : Complex_Matrix) return Complex_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 inner products.

function "*" (Left  : Complex_Matrix;
              Right : Complex_Vector) return Complex_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 inner products.

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;

Each operation returns the result of applying the corresponding operation in Numerics.Generic_Complex_Types to each component of Left and the matching component of Right. The index ranges 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  : Real_Matrix;
              Right : Complex_Matrix) return Complex_Matrix;

function "*" (Left  : Complex_Matrix;
              Right : Real_Matrix)    return Complex_Matrix;

Each operation provides the standard mathematical operation for matrix multiplication. The first and second index ranges of the result are Left'Range(1) and Right'Range(2) respectively. The exception Constraint_Error is raised if Left'Length(2) is not equal to Right'Length(1). These operations involve inner products.

function "*" (Left  : Real_Vector;
              Right : Complex_Vector) return Complex_Matrix;

function "*" (Left  : Complex_Vector;
              Right : Real_Vector)    return Complex_Matrix;

Each operation returns the outer product of a (column) vector Left by a (row) vector Right using the appropriate operation "*" in Numerics.Generic_Complex_Types for computing the individual components. The first and second index ranges of the matrix result are Left'Range and Right'Range respectively.

function "*" (Left  : Real_Vector;
              Right : Complex_Matrix) return Complex_Vector;

function "*" (Left  : Complex_Vector;
              Right : Real_Matrix)    return Complex_Vector;

Each 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). These operations involve inner products.

function "*" (Left  : Real_Matrix;
              Right : Complex_Vector) return Complex_Vector;

function "*" (Left  : Complex_Matrix;
              Right : Real_Vector)    return Complex_Vector;

Each 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. These operations involve inner products.

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;

Each operation returns the result of applying the corresponding operation in Numerics.Generic_Complex_Types to each component of the matrix Left and the complex number Right. The index ranges of the result are those of Left.

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;

Each operation returns the result of applying the corresponding operation in Numerics.Generic_Complex_Types to each component of the matrix Left and the scalar Right. The index ranges of the result are those of Left.

function Solve (A : Complex_Matrix;
                X : Complex_Vector) return Complex_Vector;

This function returns a vector Y such that X is (nearly) equal to A * Y. This is the standard mathematical operation for solving a single set of linear equations. The index range of the result is X'Range. Constraint_Error is raised if A'Length(1), A'Length(2) and X'Length are not equal. Constraint_Error is raised if the matrix A is ill-conditioned.

function Solve (A, X : Complex_Matrix) return Complex_Matrix;

This function returns a matrix Y such that X is (nearly) equal to A * Y. This is the standard mathematical operation for solving several sets of linear equations. The index ranges of the result are those of X. Constraint_Error is raised if A'Length(1), A'Length(2) and X'Length(1) are not equal. Constraint_Error is raised if the matrix A is ill-conditioned.

function Inverse (A : Complex_Matrix) return Complex_Matrix;

This function returns a matrix B such that A * B is (nearly) the unit matrix. The index ranges of the result are those of A. Constraint_Error is raised if A'Length(1) is not equal to A'Length(2). Constraint_Error is raised if the matrix A is ill-conditioned.

function Determinant (A : Complex_Matrix) return Complex;

This function returns the determinant of the matrix A. Constraint_Error is raised if A'Length(1) is not equal to A'Length(2).

function Identity_Matrix (Order            : Positive;
                          First_1, First_2 : Integer := 1)
                                             return Complex_Matrix;

This function returns a square "unit 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,0.0) except for the main diagonal, whose components are set to (1.0,0.0). The exception Constraint_Error is raised if First_1 + Order - 1 Integer'Last or First_2 + Order - 1 Integer'Last.

function Unit_Matrix (Order            : Positive;
                      First_1, First_2 : Integer := 1)
                                         return Complex_Matrix;

This function returns a square "unit 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 (1.0,0.0). The exception Constraint_Error is raised if First_1 + Order - 1 Integer'Last or First_2 + Order - 1 Integer'Last.

end Ada.Numerics.Generic_Complex_Arrays;