1------------------------------------------------------------------------------
2--                                                                          --
3--                         GNAT RUN-TIME COMPONENTS                         --
4--                                                                          --
5--       S Y S T E M . G E N E R I C _ A R R A Y _ O P E R A T I O N S      --
6--                                                                          --
7--                                 S p e c                                  --
8--                                                                          --
9--          Copyright (C) 2006-2021, Free Software Foundation, Inc.         --
10--                                                                          --
11-- GNAT is free software;  you can  redistribute it  and/or modify it under --
12-- terms of the  GNU General Public License as published  by the Free Soft- --
13-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
14-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
15-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
16-- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
17--                                                                          --
18-- As a special exception under Section 7 of GPL version 3, you are granted --
19-- additional permissions described in the GCC Runtime Library Exception,   --
20-- version 3.1, as published by the Free Software Foundation.               --
21--                                                                          --
22-- You should have received a copy of the GNU General Public License and    --
23-- a copy of the GCC Runtime Library Exception along with this program;     --
24-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
25-- <http://www.gnu.org/licenses/>.                                          --
26--                                                                          --
27-- GNAT was originally developed  by the GNAT team at  New York University. --
28-- Extensive contributions were provided by Ada Core Technologies Inc.      --
29--                                                                          --
30------------------------------------------------------------------------------
31
32package System.Generic_Array_Operations is
33pragma Pure (Generic_Array_Operations);
34
35   ---------------------
36   -- Back_Substitute --
37   ---------------------
38
39   generic
40      type Scalar is private;
41      type Matrix is array (Integer range <>, Integer range <>) of Scalar;
42      with function "-" (Left, Right : Scalar) return Scalar is <>;
43      with function "*" (Left, Right : Scalar) return Scalar is <>;
44      with function "/" (Left, Right : Scalar) return Scalar is <>;
45      with function Is_Non_Zero (X : Scalar) return Boolean is <>;
46   procedure Back_Substitute (M, N : in out Matrix);
47
48   --------------
49   -- Diagonal --
50   --------------
51
52   generic
53      type Scalar is private;
54      type Vector is array (Integer range <>) of Scalar;
55      type Matrix is array (Integer range <>, Integer range <>) of Scalar;
56   function Diagonal (A : Matrix) return Vector;
57
58   -----------------------
59   -- Forward_Eliminate --
60   -----------------------
61
62   --  Use elementary row operations to put square matrix M in row echolon
63   --  form. Identical row operations are performed on matrix N, must have the
64   --  same number of rows as M.
65
66   generic
67      type Scalar is private;
68      type Real is digits <>;
69      type Matrix is array (Integer range <>, Integer range <>) of Scalar;
70      with function "abs" (Right : Scalar) return Real'Base is <>;
71      with function "-" (Left, Right : Scalar) return Scalar is <>;
72      with function "*" (Left, Right : Scalar) return Scalar is <>;
73      with function "/" (Left, Right : Scalar) return Scalar is <>;
74      Zero : Scalar;
75      One  : Scalar;
76   procedure Forward_Eliminate
77     (M   : in out Matrix;
78      N   : in out Matrix;
79      Det : out Scalar);
80
81   --------------------------
82   -- Square_Matrix_Length --
83   --------------------------
84
85   generic
86      type Scalar is private;
87      type Matrix is array (Integer range <>, Integer range <>) of Scalar;
88   function Square_Matrix_Length (A : Matrix) return Natural;
89   --  If A is non-square, raise Constraint_Error,  else return its dimension
90
91   ----------------------------------
92   -- Vector_Elementwise_Operation --
93   ----------------------------------
94
95   generic
96      type X_Scalar is private;
97      type Result_Scalar is private;
98      type X_Vector is array (Integer range <>) of X_Scalar;
99      type Result_Vector is array (Integer range <>) of Result_Scalar;
100      with function Operation (X : X_Scalar) return Result_Scalar;
101   function Vector_Elementwise_Operation (X : X_Vector) return Result_Vector;
102
103   ----------------------------------
104   -- Matrix_Elementwise_Operation --
105   ----------------------------------
106
107   generic
108      type X_Scalar is private;
109      type Result_Scalar is private;
110      type X_Matrix is array (Integer range <>, Integer range <>) of X_Scalar;
111      type Result_Matrix is array (Integer range <>, Integer range <>)
112        of Result_Scalar;
113      with function Operation (X : X_Scalar) return Result_Scalar;
114   function Matrix_Elementwise_Operation (X : X_Matrix) return Result_Matrix;
115
116   -----------------------------------------
117   -- Vector_Vector_Elementwise_Operation --
118   -----------------------------------------
119
120   generic
121      type Left_Scalar is private;
122      type Right_Scalar is private;
123      type Result_Scalar is private;
124      type Left_Vector is array (Integer range <>) of Left_Scalar;
125      type Right_Vector is array (Integer range <>) of Right_Scalar;
126      type Result_Vector is array (Integer range <>) of Result_Scalar;
127      with function Operation
128             (Left  : Left_Scalar;
129              Right : Right_Scalar) return Result_Scalar;
130   function Vector_Vector_Elementwise_Operation
131     (Left  : Left_Vector;
132      Right : Right_Vector) return Result_Vector;
133
134   ------------------------------------------------
135   -- Vector_Vector_Scalar_Elementwise_Operation --
136   ------------------------------------------------
137
138   generic
139      type X_Scalar is private;
140      type Y_Scalar is private;
141      type Z_Scalar is private;
142      type Result_Scalar is private;
143      type X_Vector is array (Integer range <>) of X_Scalar;
144      type Y_Vector is array (Integer range <>) of Y_Scalar;
145      type Result_Vector is array (Integer range <>) of Result_Scalar;
146      with function Operation
147             (X : X_Scalar;
148              Y : Y_Scalar;
149              Z : Z_Scalar) return Result_Scalar;
150   function Vector_Vector_Scalar_Elementwise_Operation
151     (X : X_Vector;
152      Y : Y_Vector;
153      Z : Z_Scalar) return Result_Vector;
154
155   -----------------------------------------
156   -- Matrix_Matrix_Elementwise_Operation --
157   -----------------------------------------
158
159   generic
160      type Left_Scalar is private;
161      type Right_Scalar is private;
162      type Result_Scalar is private;
163      type Left_Matrix is array (Integer range <>, Integer range <>)
164        of Left_Scalar;
165      type Right_Matrix is array (Integer range <>, Integer range <>)
166        of Right_Scalar;
167      type Result_Matrix is array (Integer range <>, Integer range <>)
168        of Result_Scalar;
169      with function Operation
170             (Left  : Left_Scalar;
171              Right : Right_Scalar) return Result_Scalar;
172   function Matrix_Matrix_Elementwise_Operation
173     (Left  : Left_Matrix;
174      Right : Right_Matrix) return Result_Matrix;
175
176   ------------------------------------------------
177   -- Matrix_Matrix_Scalar_Elementwise_Operation --
178   ------------------------------------------------
179
180   generic
181      type X_Scalar is private;
182      type Y_Scalar is private;
183      type Z_Scalar is private;
184      type Result_Scalar is private;
185      type X_Matrix is array (Integer range <>, Integer range <>) of X_Scalar;
186      type Y_Matrix is array (Integer range <>, Integer range <>) of Y_Scalar;
187      type Result_Matrix is array (Integer range <>, Integer range <>)
188        of Result_Scalar;
189      with function Operation
190             (X : X_Scalar;
191              Y : Y_Scalar;
192              Z : Z_Scalar) return Result_Scalar;
193   function Matrix_Matrix_Scalar_Elementwise_Operation
194     (X : X_Matrix;
195      Y : Y_Matrix;
196      Z : Z_Scalar) return Result_Matrix;
197
198   -----------------------------------------
199   -- Vector_Scalar_Elementwise_Operation --
200   -----------------------------------------
201
202   generic
203      type Left_Scalar is private;
204      type Right_Scalar is private;
205      type Result_Scalar is private;
206      type Left_Vector is array (Integer range <>) of Left_Scalar;
207      type Result_Vector is array (Integer range <>) of Result_Scalar;
208      with function Operation
209             (Left  : Left_Scalar;
210              Right : Right_Scalar) return Result_Scalar;
211   function Vector_Scalar_Elementwise_Operation
212     (Left  : Left_Vector;
213      Right : Right_Scalar) return Result_Vector;
214
215   -----------------------------------------
216   -- Matrix_Scalar_Elementwise_Operation --
217   -----------------------------------------
218
219   generic
220      type Left_Scalar is private;
221      type Right_Scalar is private;
222      type Result_Scalar is private;
223      type Left_Matrix is array (Integer range <>, Integer range <>)
224        of Left_Scalar;
225      type Result_Matrix is array (Integer range <>, Integer range <>)
226        of Result_Scalar;
227      with function Operation
228             (Left  : Left_Scalar;
229              Right : Right_Scalar) return Result_Scalar;
230   function Matrix_Scalar_Elementwise_Operation
231     (Left  : Left_Matrix;
232      Right : Right_Scalar) return Result_Matrix;
233
234   -----------------------------------------
235   -- Scalar_Vector_Elementwise_Operation --
236   -----------------------------------------
237
238   generic
239      type Left_Scalar is private;
240      type Right_Scalar is private;
241      type Result_Scalar is private;
242      type Right_Vector is array (Integer range <>) of Right_Scalar;
243      type Result_Vector is array (Integer range <>) of Result_Scalar;
244      with function Operation
245             (Left  : Left_Scalar;
246              Right : Right_Scalar) return Result_Scalar;
247   function Scalar_Vector_Elementwise_Operation
248     (Left  : Left_Scalar;
249      Right : Right_Vector) return Result_Vector;
250
251   -----------------------------------------
252   -- Scalar_Matrix_Elementwise_Operation --
253   -----------------------------------------
254
255   generic
256      type Left_Scalar is private;
257      type Right_Scalar is private;
258      type Result_Scalar is private;
259      type Right_Matrix is array (Integer range <>, Integer range <>)
260        of Right_Scalar;
261      type Result_Matrix is array (Integer range <>, Integer range <>)
262        of Result_Scalar;
263      with function Operation
264             (Left  : Left_Scalar;
265              Right : Right_Scalar) return Result_Scalar;
266   function Scalar_Matrix_Elementwise_Operation
267     (Left  : Left_Scalar;
268      Right : Right_Matrix) return Result_Matrix;
269
270   -------------------
271   -- Inner_Product --
272   -------------------
273
274   generic
275      type Left_Scalar is private;
276      type Right_Scalar is private;
277      type Result_Scalar is private;
278      type Left_Vector is array (Integer range <>) of Left_Scalar;
279      type Right_Vector is array (Integer range <>) of Right_Scalar;
280      Zero : Result_Scalar;
281      with function "*"
282             (Left  : Left_Scalar;
283              Right : Right_Scalar) return Result_Scalar is <>;
284      with function "+"
285             (Left  : Result_Scalar;
286              Right : Result_Scalar) return Result_Scalar is <>;
287   function Inner_Product
288     (Left  : Left_Vector;
289      Right : Right_Vector) return Result_Scalar;
290
291   -------------
292   -- L2_Norm --
293   -------------
294
295   generic
296      type X_Scalar is private;
297      type Result_Real is digits <>;
298      type X_Vector is array (Integer range <>) of X_Scalar;
299      with function "abs" (Right : X_Scalar) return Result_Real is <>;
300      with function Sqrt (X : Result_Real'Base) return Result_Real'Base is <>;
301   function L2_Norm (X : X_Vector) return Result_Real'Base;
302
303   -------------------
304   -- Outer_Product --
305   -------------------
306
307   generic
308      type Left_Scalar is private;
309      type Right_Scalar is private;
310      type Result_Scalar is private;
311      type Left_Vector is array (Integer range <>) of Left_Scalar;
312      type Right_Vector is array (Integer range <>) of Right_Scalar;
313      type Matrix is array (Integer range <>, Integer range <>)
314        of Result_Scalar;
315      with function "*"
316             (Left  : Left_Scalar;
317              Right : Right_Scalar) return Result_Scalar is <>;
318   function Outer_Product
319     (Left  : Left_Vector;
320      Right : Right_Vector) return Matrix;
321
322   ---------------------------
323   -- Matrix_Vector_Product --
324   ---------------------------
325
326   generic
327      type Left_Scalar is private;
328      type Right_Scalar is private;
329      type Result_Scalar is private;
330      type Matrix is array (Integer range <>, Integer range <>)
331        of Left_Scalar;
332      type Right_Vector is array (Integer range <>) of Right_Scalar;
333      type Result_Vector is array (Integer range <>) of Result_Scalar;
334      Zero : Result_Scalar;
335      with function "*"
336             (Left  : Left_Scalar;
337              Right : Right_Scalar) return Result_Scalar is <>;
338      with function "+"
339             (Left  : Result_Scalar;
340              Right : Result_Scalar) return Result_Scalar is <>;
341   function Matrix_Vector_Product
342     (Left  : Matrix;
343      Right : Right_Vector) return Result_Vector;
344
345   ---------------------------
346   -- Vector_Matrix_Product --
347   ---------------------------
348
349   generic
350      type Left_Scalar is private;
351      type Right_Scalar is private;
352      type Result_Scalar is private;
353      type Left_Vector is array (Integer range <>) of Left_Scalar;
354      type Matrix is array (Integer range <>, Integer range <>)
355        of Right_Scalar;
356      type Result_Vector is array (Integer range <>) of Result_Scalar;
357      Zero : Result_Scalar;
358      with function "*"
359             (Left  : Left_Scalar;
360              Right : Right_Scalar) return Result_Scalar is <>;
361      with function "+"
362             (Left  : Result_Scalar;
363              Right : Result_Scalar) return Result_Scalar is <>;
364   function Vector_Matrix_Product
365     (Left  : Left_Vector;
366      Right : Matrix) return Result_Vector;
367
368   ---------------------------
369   -- Matrix_Matrix_Product --
370   ---------------------------
371
372   generic
373      type Left_Scalar is private;
374      type Right_Scalar is private;
375      type Result_Scalar is private;
376      type Left_Matrix is array (Integer range <>, Integer range <>)
377        of Left_Scalar;
378      type Right_Matrix is array (Integer range <>, Integer range <>)
379        of Right_Scalar;
380      type Result_Matrix is array (Integer range <>, Integer range <>)
381        of Result_Scalar;
382      Zero : Result_Scalar;
383      with function "*"
384             (Left  : Left_Scalar;
385              Right : Right_Scalar) return Result_Scalar is <>;
386      with function "+"
387             (Left  : Result_Scalar;
388              Right : Result_Scalar) return Result_Scalar is <>;
389   function Matrix_Matrix_Product
390     (Left  : Left_Matrix;
391      Right : Right_Matrix) return Result_Matrix;
392
393   ----------------------------
394   -- Matrix_Vector_Solution --
395   ----------------------------
396
397   generic
398      type Scalar is private;
399      Zero : Scalar;
400      type Vector is array (Integer range <>) of Scalar;
401      type Matrix is array (Integer range <>, Integer range <>) of Scalar;
402      with procedure Back_Substitute (M, N : in out Matrix) is <>;
403      with procedure Forward_Eliminate
404             (M   : in out Matrix;
405              N   : in out Matrix;
406              Det : out Scalar) is <>;
407   function Matrix_Vector_Solution (A : Matrix; X : Vector) return Vector;
408
409   ----------------------------
410   -- Matrix_Matrix_Solution --
411   ----------------------------
412
413   generic
414      type Scalar is private;
415      Zero : Scalar;
416      type Matrix is array (Integer range <>, Integer range <>) of Scalar;
417      with procedure Back_Substitute (M, N : in out Matrix) is <>;
418      with procedure Forward_Eliminate
419             (M   : in out Matrix;
420              N   : in out Matrix;
421              Det : out Scalar) is <>;
422   function Matrix_Matrix_Solution (A : Matrix; X : Matrix) return Matrix;
423
424   ----------
425   -- Sqrt --
426   ----------
427
428   generic
429      type Real is digits <>;
430   function Sqrt (X : Real'Base) return Real'Base;
431
432   -----------------
433   -- Swap_Column --
434   -----------------
435
436   generic
437      type Scalar is private;
438      type Matrix is array (Integer range <>, Integer range <>) of Scalar;
439   procedure Swap_Column (A : in out Matrix; Left, Right : Integer);
440
441   ---------------
442   -- Transpose --
443   ---------------
444
445   generic
446      type Scalar is private;
447      type Matrix is array (Integer range <>, Integer range <>) of Scalar;
448   procedure Transpose (A : Matrix; R : out Matrix);
449
450   -------------------------------
451   -- Update_Vector_With_Vector --
452   -------------------------------
453
454   generic
455      type X_Scalar is private;
456      type Y_Scalar is private;
457      type X_Vector is array (Integer range <>) of X_Scalar;
458      type Y_Vector is array (Integer range <>) of Y_Scalar;
459      with procedure Update (X : in out X_Scalar; Y : Y_Scalar);
460   procedure Update_Vector_With_Vector (X : in out X_Vector; Y : Y_Vector);
461
462   -------------------------------
463   -- Update_Matrix_With_Matrix --
464   -------------------------------
465
466   generic
467      type X_Scalar is private;
468      type Y_Scalar is private;
469      type X_Matrix is array (Integer range <>, Integer range <>) of X_Scalar;
470      type Y_Matrix is array (Integer range <>, Integer range <>) of Y_Scalar;
471      with procedure Update (X : in out X_Scalar; Y : Y_Scalar);
472   procedure Update_Matrix_With_Matrix (X : in out X_Matrix; Y : Y_Matrix);
473
474   -----------------
475   -- Unit_Matrix --
476   -----------------
477
478   generic
479      type Scalar is private;
480      type Matrix is array (Integer range <>, Integer range <>) of Scalar;
481      Zero : Scalar;
482      One  : Scalar;
483   function Unit_Matrix
484     (Order   : Positive;
485      First_1 : Integer := 1;
486      First_2 : Integer := 1) return Matrix;
487
488   -----------------
489   -- Unit_Vector --
490   -----------------
491
492   generic
493      type Scalar is private;
494      type Vector is array (Integer range <>) of Scalar;
495      Zero : Scalar;
496      One  : Scalar;
497   function Unit_Vector
498     (Index : Integer;
499      Order : Positive;
500      First : Integer := 1) return Vector;
501
502end System.Generic_Array_Operations;
503