source: project/wiki/eggref/5/blas @ 35680

Last change on this file since 35680 was 35680, checked in by Ivan Raikov, 2 years ago

blas doc

File size: 29.4 KB
Line 
1[[tags:egg]]
2[[toc:]]
3
4== blas
5
6An interface to level 1, 2 and 3 BLAS linear algebra routines.
7
8== Documentation
9
10
11=== Naming conventions for routines
12
13
14Every routine in the BLAS library comes in four flavors, each prefixed
15by the letters S, D, C, and Z, respectively. Each letter indicates the
16format of input data:
17
18* S stands for single-precision (32-bit IEEE floating point numbers),
19* D stands for double-precision (64-bit IEEE floating point numbers),
20* C stands for complex numbers (represented by pairs of 32-bit IEEE floating point numbers),
21* Z stands for double complex numbers (represented by pairs of 64-bit IEEE floating point numbers)
22
23
24In addition, each BLAS routine in this egg comes in three flavors:
25
26* Safe, pure
27
28''Safe'' routines check the sizes of their input arguments. For
29example, if a routine is supplied arguments that indicate that an
30input matrix is of dimensions ''M''-by-''N'', then the argument
31corresponding to that matrix is checked that it is of size ''M * N''.
32
33''Pure'' routines do not alter their arguments in any way. A new
34matrix or vector is allocated for the return value of the routine.
35
36* Safe, destructive (suffix: !)
37
38''Safe'' routines check the sizes of their input arguments. For
39example, if a routine is supplied arguments that indicate that an
40input matrix is of dimensions ''M''-by-''N'', then the argument
41corresponding to that matrix is checked that it is of size ''M * N''.
42
43''Destructive'' routines can modify some or all of their
44arguments. They are given names ending in exclamation mark. Please
45consult the BLAS documentation to determine which functions modify
46their input arguments.
47
48* Unsafe, destructive (prefix: '''unsafe-''', suffix: !)
49
50''Unsafe'' routines do not check the sizes of their input
51arguments. They invoke the corresponding BLAS routines
52directly. Unsafe routines do not have pure variants.
53
54
55
56For example, function ''xGEMM'' (matrix-matrix multiplication) comes in the following variants:
57
58<table><tr><th>'''BLAS name'''</th><th>'''Safe, pure'''</th><th>'''Safe, destructive'''</th><th>'''Unsafe, destructive'''</th></tr>
59<tr><td>''SGEMM''</td><td>''sgemm''</td><td>''sgemm!''</td><td>''unsafe-sgemm!''</td></tr>
60<tr><td>''DGEMM''</td><td>''dgemm''</td><td>''dgemm!''</td><td>''unsafe-dgemm!''</td></tr>
61<tr><td>''CGEMM''</td><td>''cgemm''</td><td>''cgemm!''</td><td>''unsafe-cgemm!''</td></tr>
62<tr><td>''ZGEMM''</td><td>''zgemm''</td><td>''zgemm!''</td><td>''unsafe-zgemm!''</td></tr>
63</table>
64
65
66=== Vector copy routines
67
68
69<procedure>scopy:: F32VECTOR -> F32VECTOR </procedure>
70
71<procedure>dcopy:: F64VECTOR -> F64VECTOR </procedure>
72
73<procedure>ccopy:: F32VECTOR -> F32VECTOR </procedure>
74
75<procedure>zcopy:: F64VECTOR -> F64VECTOR </procedure>
76
77
78
79These procedures return a copy of given input SRFI-4 vector. The
80returned vector is allocated with the corresponding SRFI-4
81constructor, and the input vector is copied to it by the corresponding
82BLAS copy procedure.
83
84
85
86=== BLAS level 1 routines
87
88
89==== Conventions
90
91
92The BLAS level 1 procedures in this egg differ from the actual
93routines they invoke by the position of the vector increment arguments
94({{INCX}} and {{INCY}}). In this egg, these arguments are optional;
95the default value of {{INCX}} and {{INCY}} is 1.
96
97In the procedure signatures below, these optional arguments are
98indicated by [ and ] (square brackets).
99
100==== Apply plane rotation
101
102
103<procedure>srot:: N * X * Y * C * S [INCX * INCY] -> F32VECTOR * F32VECTOR </procedure>
104
105<procedure>drot:: N * X * Y * C * S [INCX * INCY] -> F64VECTOR * F64VECTOR </procedure>
106
107
108
109{{xROT}} applies a plane rotation matrix to a sequence of ordered pairs: {{(x_i , y_i)}}, for {{i = 1, 2, ..., n}}.
110
111{{X}} and {{Y}} are vector of dimensions {{(N-1) * abs(incx) + 1}} and {{(N-1) * abs(incy) + 1}}, respectively.
112
113{{C}} and {{S}} are respectively the cosine and sine of the plane of rotation.
114
115
116
117==== Scale vector
118
119
120<procedure>sscal:: N * ALPHA * X [INCX] -> F32VECTOR </procedure>
121
122<procedure>dscal:: N * ALPHA * X [INCX] -> F64VECTOR </procedure>
123
124<procedure>cscal:: N * ALPHA * X [INCX] -> F32VECTOR </procedure>
125
126<procedure>zscal:: N * ALPHA * X [INCX] -> F64VECTOR </procedure>
127
128
129{{xSCAL}} scales a vector with a scalar: {{x := alpha * x}}.
130
131
132==== Swap the elements of two vectors
133
134
135<procedure>sswap:: N * X * Y [INCX * INCY] -> F32VECTOR </procedure>
136
137<procedure>dswap:: N * X * Y [INCX * INCY] -> F64VECTOR </procedure>
138
139<procedure>cswap:: N * X * Y [INCX * INCY] -> F32VECTOR </procedure>
140
141<procedure>zswap:: N * X * Y [INCX * INCY] -> F64VECTOR </procedure>
142
143
144{{xSWAP}} interchanges the elements of two vectors: {{x <-> y}}.
145
146
147==== Real vector dot product
148
149
150<procedure>sdot:: N * X * Y [INCX * INCY] -> NUMBER </procedure>
151
152<procedure>ddot:: N * X * Y [INCX * INCY] -> NUMBER </procedure>
153
154
155{{xDOT}} computes the dot product of two vectors of real values: {{dot := x'*y = \Sum_{i=1}^{n} (x_i * y_i)}}.
156
157
158
159==== Complex vector dot product
160
161
162<procedure>cdotu:: N * X * Y [INCX * INCY] -> NUMBER </procedure>
163
164<procedure>zdotu:: N * X * Y [INCX * INCY] -> NUMBER </procedure>
165
166
167{{xDOTU}} computes the dot product of two vectors of complex values: {{dotu := x'*y = \Sum_{i=1}^{n} (x_i * y_i)}}.
168
169
170
171==== Hermitian vector dot product
172
173
174<procedure>cdotc:: N * X * Y [INCX * INCY] -> NUMBER </procedure>
175
176<procedure>zdotc:: N * X * Y [INCX * INCY] -> NUMBER </procedure>
177
178
179{{xDOTC}} computes the dot product of the conjugates of two complex vectors: {{dotu := conjg(x')*y = \Sum_{i=1}^{n} (conjg(x_i) * y_i)}}, for {{i = 1, 2, ..., n}}.
180
181
182
183==== Vector multiply-add
184
185
186<procedure>saxpy:: N * ALPHA * X * Y [INCX * INCY] -> F32VECTOR </procedure>
187
188<procedure>daxpy:: N * ALPHA * X * Y [INCX * INCY] -> F64VECTOR </procedure>
189
190<procedure>caxpy:: N * ALPHA * X * Y [INCX * INCY] -> F32VECTOR </procedure>
191
192<procedure>zaxpy:: N * ALPHA * X * Y [INCX * INCY] -> F64VECTOR </procedure>
193
194
195{{xAXPY}} adds a scalar multiple of a vector to another vector: {{y := alpha * x + y}}.
196
197
198==== Vector multiply-add with optional offset
199
200
201<procedure>siaxpy:: N * ALPHA * X * Y [INCX * INCY * XOFS * YOFS] -> F32VECTOR </procedure>
202
203<procedure>diaxpy:: N * ALPHA * X * Y [INCX * INCY * XOFS * YOFS] -> F64VECTOR </procedure>
204
205<procedure>ciaxpy:: N * ALPHA * X * Y [INCX * INCY * XOFS * YOFS] -> F32VECTOR </procedure>
206
207<procedure>ziaxpy:: N * ALPHA * X * Y [INCX * INCY * XOFS * YOFS] -> F64VECTOR </procedure>
208
209
210{{xIAXPY}} adds a scalar multiple of a vector to another vector, where
211the beginning of each vector argument can be offset: {{y[yofs:n] :=
212alpha * x[xofs:n] + y[yofs:n]}}.
213
214
215==== Euclidean norm of a vector
216
217
218<procedure>snrm2:: N * X [INCX] -> NUMBER </procedure>
219
220<procedure>dnrm2:: N * X [INCX] -> NUMBER </procedure>
221
222<procedure>cnrm2:: N * X [INCX] -> NUMBER </procedure>
223
224<procedure>znrm2:: N * X [INCX] -> NUMBER </procedure>
225
226
227{{xNRM2}} computes the Euclidean (L2) norm of a vector.
228
229
230==== Sum of absolute values of the elements in a vector
231
232
233<procedure>sasum:: N * X [INCX] -> NUMBER </procedure>
234
235<procedure>dasum:: N * X [INCX] -> NUMBER </procedure>
236
237<procedure>casum:: N * X [INCX] -> NUMBER </procedure>
238
239<procedure>zasum:: N * X [INCX] -> NUMBER </procedure>
240
241
242
243{{xASUM}} sums the absolute values of the elements in a vector.
244
245
246
247==== Sum of absolute values of the elements in a vector
248
249
250<procedure>samax:: N * X [INCX] -> INDEX </procedure>
251
252<procedure>damax:: N * X [INCX] -> INDEX </procedure>
253
254<procedure>camax:: N * X [INCX] -> INDEX </procedure>
255
256<procedure>zamax:: N * X [INCX] -> INDEX </procedure>
257
258
259
260{{xAMAX}} searches a vector for the first occurrence of its maximum
261absolute value, and returns the index of that element.
262
263
264
265=== BLAS level 2 routines
266
267
268==== Conventions
269
270
271The BLAS level 2 procedures in this egg differ from the actual
272routines they invoke by the position of the leading dimension argument
273({{LDA}}) and the vector increment arguments ({{INCX}} and
274{{INCY}}). In this egg, these arguments are optional; the default
275value of {{LDA}}is the largest matrix dimension, depending on the
276semantics of the respective operation, and the default value of
277{{INCX}} and {{INCY}} is 1.
278
279In the procedure signatures below, these optional arguments are
280indicated by [ and ] (square brackets).
281
282Argument {{ORDER}} is one of {{RowMajor}} or {{ColMajor}} to
283indicate that the input and output matrices are in row-major or
284column-major form, respectively.
285
286Where present, argument {{TRANS}} can be one of {{NoTrans}} or
287{{Trans}} to indicate whether the input matrix is to be
288transposed or not.
289
290Where present, argument {{UPLO}} can be one of {{Upper}} or
291{{Lower}} to indicate whether the upper or lower triangular part
292of an input symmetric matrix is to referenced,or to specify the type
293of an input triangular matrix.
294
295Where present, argument {{DIAG}} can be one of {{NonUnit}} or
296{{Unit}} to indicate whether an input triangular matrix is unit
297triangular or not.
298
299==== General matrix-vector multiply-add
300
301
302<procedure>sgemv:: ORDER * TRANS * M * N * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F32VECTOR </procedure>
303
304<procedure>dgemv:: ORDER * TRANS * M * N * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F64VECTOR </procedure>
305
306<procedure>cgemv:: ORDER * TRANS * M * N * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F32VECTOR </procedure>
307
308<procedure>zgemv:: ORDER * TRANS * M * N * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F64VECTOR </procedure>
309
310
311
312{{xGEMV}} performs the matrix-vector multiply-add operation of the
313form {{y := alpha*op( A )*x + beta*y}}, where {{op( X )}} is one of
314{{op( A ) = A}} or {{op( A ) = A'}}.
315
316{{ALPHA}} and {{BETA}} are  scalars, and {{A}} is an {{M x N}} matrix.
317
318{{X}} is a vector of size {{(1 + ( N - 1 ) * abs(INCX))}} when
319argument {{TRANS}} is {{NoTrans}}, and {{(1 + ( M - 1 ) *
320abs(INCX))}} otherwise. {{Y}} is a vector of size {{(1 + ( M - 1 ) *
321abs(INCY))}} when argument {{TRANS}} is {{NoTrans}}, and {{(1 + (
322N - 1 ) * abs(INCY))}} otherwise.
323
324
325
326==== Banded matrix-vector multiply-add
327
328
329<procedure>sgbmv:: ORDER * TRANS * M * N * KL * KU * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F32VECTOR </procedure>
330
331<procedure>dgbmv:: ORDER * TRANS * M * N * KL * KU * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F64VECTOR </procedure>
332
333<procedure>cgbmv:: ORDER * TRANS * M * N * KL * KU * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F32VECTOR </procedure>
334
335<procedure>zgbmv:: ORDER * TRANS * M * N * KL * KU * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F64VECTOR </procedure>
336
337
338
339{{xGBMV}} performs the matrix-vector multiply-add operation of the
340form {{y := alpha*op( A )*x + beta*y}}, where {{op( X )}} is one of
341{{op( A ) = A}} or {{op( A ) = A'}}.
342
343{{ALPHA}} and {{BETA}} are scalars, and {{A}} is an {{M x N}} banded
344matrix, with {{KL}} sub-diagonals and {{KU}} super-diagonals.
345
346{{X}} is a vector of size {{(1 + ( N - 1 ) * abs(INCX))}} when
347argument {{TRANS}} is {{NoTrans}}, and {{(1 + ( M - 1 ) *
348abs(INCX))}} otherwise. {{Y}} is a vector of size {{(1 + ( M - 1 ) *
349abs(INCY))}} when argument {{TRANS}} is {{NoTrans}}, and {{(1 + (
350N - 1 ) * abs(INCY))}} otherwise.
351
352
353
354==== Hermitian matrix-vector multiply-add
355
356
357<procedure>chemv:: ORDER * UPLO * N * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F32VECTOR </procedure>
358
359<procedure>zhemv:: ORDER * UPLO * N * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F64VECTOR </procedure>
360
361{{xHEMV}} performs the matrix-vector multiply-add operation of the form {{y := alpha*op( A )*x + beta*y}}, where {{op( X )}} is one of {{op( A ) = A}} or {{op( A ) = A'}}.
362
363{{ALPHA}} and {{BETA}} are  scalars, and {{A}} is an {{N x N}} Hermitian matrix.
364
365{{X}} and {{Y}} are {{N}} element vectors.
366
367
368
369==== Hermitian banded matrix-vector multiply-add
370
371<procedure>chbmv:: ORDER * UPLO * N * K * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F32VECTOR </procedure>
372
373<procedure>zhbmv:: ORDER * UPLO * N * K * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F64VECTOR </procedure>
374
375
376{{xHBMV}} performs the matrix-vector multiply-add operation of the
377form {{y := alpha*op( A )*x + beta*y}}, where {{op( X )}} is one of
378{{op( A ) = A}} or {{op( A ) = A'}}.
379
380{{ALPHA}} and {{BETA}} are scalars, and {{A}} is an {{N x N}}
381Hermitian banded matrix, with {{K}} super-diagonals.
382
383{{X}} and {{Y}} are {{N}} element vectors.
384
385
386==== Symmetric matrix-vector multiply-add
387
388
389<procedure>ssymv:: ORDER * UPLO * N * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F32VECTOR </procedure>
390
391<procedure>dsymv:: ORDER * UPLO * N * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F64VECTOR </procedure>
392
393
394{{xSYMV}} performs matrix-vector multiply-add operation of the form
395{{y := alpha*A*x + beta*y}}.
396
397{{ALPHA}} and {{BETA}} are scalars, and {{A}} is an {{N x N}}
398symmetric matrix.
399
400{{X}} and {{Y}} are {{N}} element vectors.
401
402
403
404==== Banded symmetric matrix-vector multiply-add
405
406
407<procedure>ssbmv:: ORDER * UPLO * N * K * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F32VECTOR </procedure>
408
409<procedure>dsbmv:: ORDER * UPLO * N * K * ALPHA * A * X * BETA * Y [LDA * INCX * INCY] -> F64VECTOR </procedure>
410
411
412{{xSBMV}} performs matrix-vector multiply-add operation of the form
413{{y := alpha*A*B + beta*y}}.
414
415{{ALPHA}} and {{BETA}} are scalars, and {{A}} is an {{N x N}}
416symmetric banded matrix, with {{K}} super-diagonals.
417
418{{X}} and {{Y}} are {{N}} element vectors.
419
420
421==== Triangular matrix-vector multiply-add
422
423
424<procedure>strmv:: ORDER * UPLO * TRANS * DIAG * N * A * X [LDA * INCX] -> F32VECTOR </procedure>
425
426<procedure>dtrmv:: ORDER * UPLO * TRANS * DIAG * N * A * X [LDA * INCX] -> F64VECTOR </procedure>
427
428<procedure>ctrmv:: ORDER * UPLO * TRANS * DIAG * N * A * X [LDA * INCX] -> F32VECTOR </procedure>
429
430<procedure>ztrmv:: ORDER * UPLO * TRANS * DIAG * N * A * X [LDA * INCX] -> F64VECTOR </procedure>
431
432
433
434{{xTRMV}} performs matrix-vector multiply-add operation of the form
435{{y := alpha*op( A )*x}}, where {{op ( A ) = A}} or {{op ( A ) = A'}}
436
437{{ALPHA}} and {{BETA}} are scalars, and {{A}} is an {{N x N}} upper or
438lower triangular matrix.
439
440{{X}} is a vector of length {{(1 + (n - 1) * abs(INCX))}}.
441
442
443
444==== Banded triangular matrix-vector multiply-add
445
446
447<procedure>stbmv:: ORDER * UPLO * TRANS * DIAG * N * K * A * X [LDA * INCX] -> F32VECTOR </procedure>
448
449<procedure>dtbmv:: ORDER * UPLO * TRANS * DIAG * N * K * A * X [LDA * INCX] -> F64VECTOR </procedure>
450
451<procedure>ctbmv:: ORDER * UPLO * TRANS * DIAG * N * K * A * X [LDA * INCX] -> F32VECTOR </procedure>
452
453<procedure>ztbmv:: ORDER * UPLO * TRANS * DIAG * N * K * A * X [LDA * INCX] -> F64VECTOR </procedure>
454
455
456
457{{xTBMV}} performs matrix-vector multiply-add operation of the form
458{{y := alpha*A*B + beta*y}}, where {{op ( A ) = A}} or {{op ( A ) =
459A'}}
460
461{{ALPHA}} and {{BETA}} are scalars, and {{A}} is an {{N x N}} upper or
462lower triangular banded matrix, with {{K+1}} diagonals.
463
464{{X}} is a vector of length {{(1 + (n - 1) * abs(INCX))}}.
465
466
467
468==== Triangular matrix equation solve
469
470
471<procedure>strsv:: ORDER * UPLO * TRANS * DIAG * N * ALPHA * A * B * [LDA * INCB] -> F32VECTOR </procedure>
472
473<procedure>dtrsv:: ORDER * UPLO * TRANS * DIAG * N * A * B * [LDA * INCB] -> F64VECTOR </procedure>
474
475<procedure>ctrsv:: ORDER * UPLO * TRANS * DIAG * N * A * B * [LDA * INCB] -> F32VECTOR </procedure>
476
477<procedure>ztrsv:: ORDER * UPLO * TRANS * DIAG * N * A * B * [LDA * INCB] -> F64VECTOR </procedure>
478
479
480
481{{xTRSV}} solves one of the systems of equations {{A*x = b}} or {{A'*x = b}}.
482
483{{ALPHA}} and {{BETA}} are scalars, {{A}} is a upper or lower
484triangular matrix, and {{B}} is a {{N}} element vector.
485
486
487
488==== Banded triangular matrix equation solve
489
490
491<procedure>stbsv:: ORDER * UPLO * TRANS * DIAG * N * K * A * B * [LDA * INCB] -> F32VECTOR </procedure>
492
493<procedure>dtbsv:: ORDER * UPLO * TRANS * DIAG * N * K * A * B * [LDA * INCB] -> F64VECTOR </procedure>
494
495<procedure>ctbsv:: ORDER * UPLO * TRANS * DIAG * N * K * A * B * [LDA * INCB] -> F32VECTOR </procedure>
496
497<procedure>ztbsv:: ORDER * UPLO * TRANS * DIAG * N * K * A * B * [LDA * INCB] -> F64VECTOR </procedure>
498
499
500
501{{xTBSV}} solves one of the systems of equations {{A*x = b}} or {{A'*x = b}}.
502
503{{ALPHA}} and {{BETA}} are scalars, {{A}} is a upper or lower banded
504triangular matrix with {{K+1}} diagonals, and {{B}} is a {{N}} element
505vector.
506
507
508
509==== Rank 1 operation
510
511
512<procedure>sger:: ORDER * M * N * ALPHA * X * Y * A [LDA * INCX * INCY] -> F32VECTOR </procedure>
513
514<procedure>dger:: ORDER * M * N * ALPHA * X * Y * A [LDA * INCX * INCY] -> F64VECTOR </procedure>
515
516
517
518{{xGER}} performs the rank 1 operation {{A := alpha*x*y' + A}}.
519
520{{ALPHA}} is a scalar, {{X}} is an {{M}} element vector, {{Y}} is an
521{{N}} element vector, and {{A}} is an {{M x N}} matrix.
522
523
524
525==== Rank 1 operation with optional offset
526
527
528<procedure>siger:: ORDER * M * N * ALPHA * X * Y * A [LDA * INCX * INCY * XOFS * YOFS] -> F32VECTOR </procedure>
529
530<procedure>diger:: ORDER * M * N * ALPHA * X * Y * A [LDA * INCX * INCY * XOFS * YOFS] -> F64VECTOR </procedure>
531
532
533{{xIGER}} performs the rank 1 operation {{A := alpha*x[xofs:M]*y'[yofs:N] + A}}.
534
535{{ALPHA}} is a scalar, {{X}} is an {{M}} element vector, {{Y}} is an
536{{N}} element vector, and {{A}} is an {{M x N}} matrix.
537
538
539
540==== Rank 1 operation on complex matrices and vectors
541
542
543<procedure>cgeru:: ORDER * M * N * ALPHA * X * Y * A [LDA * INCX * INCY] -> F32VECTOR </procedure>
544
545<procedure>zgeru:: ORDER * M * N * ALPHA * X * Y * A [LDA * INCX * INCY] -> F64VECTOR </procedure>
546
547
548{{xGERU}} performs the rank 1 operation {{A := alpha*x*y' + A}}.
549
550{{ALPHA}} is a scalar, {{X}} is an {{M}} element vector, {{Y}} is an
551{{N}} element vector, and {{A}} is an {{M x N}} matrix.
552
553
554
555==== Rank 1 operation on complex matrices and vectors
556
557
558<procedure>cgerc:: ORDER * M * N * ALPHA * X * Y * A [LDA * INCX * INCY] -> F32VECTOR </procedure>
559
560<procedure>zgerc:: ORDER * M * N * ALPHA * X * Y * A [LDA * INCX * INCY] -> F64VECTOR </procedure>
561
562
563
564{{xGERC}} performs the rank 1 operation {{A := alpha*x*conjg(y') + A}}.
565
566{{ALPHA}} is a scalar, {{X}} is an {{M}} element vector, {{Y}} is an
567{{N}} element vector, and {{A}} is an {{M x N}} matrix.
568
569
570
571==== Hermitian rank 1 operation
572
573
574<procedure>cher:: ORDER * UPLO * N * ALPHA * X * A [LDA * INCX] -> F32VECTOR </procedure>
575
576<procedure>zher:: ORDER * UPLO * N * ALPHA * X * A [LDA * INCX] -> F64VECTOR </procedure>
577
578
579
580{{xHER}} performs the Hermitian rank 1 operation {{A := alpha*x*conjg(x') + A}}.
581
582{{ALPHA}} is a scalar, {{X}} is an {{N}} element vector, and {{A}} is
583an {{N x N}} Hermitian matrix.
584
585
586
587==== Hermitian rank 2 operation
588
589
590<procedure>cher2:: ORDER * UPLO * N * ALPHA * X * Y * A [LDA * INCX * INCY] -> F32VECTOR </procedure>
591
592<procedure>zher2:: ORDER * UPLO * N * ALPHA * X * Y * A [LDA * INCX * INCY] -> F64VECTOR </procedure>
593
594
595
596{{xHER2}} performs the Hermitian rank 2 operation {{A := alpha*x*conjg(y') + conjg(alpha)*y*conjg(x') + A}}.
597
598{{ALPHA}} is a scalar, {{X}} and {{Y}} are {{N}} element vectors, and
599{{A}} is an {{N x N}} Hermitian matrix.
600
601
602
603==== Symmetric rank 1 operation
604
605
606<procedure>ssyr:: ORDER * UPLO * N * ALPHA * X * A [LDA * INCX] -> F32VECTOR </procedure>
607
608<procedure>dsyr:: ORDER * UPLO * N * ALPHA * X * A [LDA * INCX] -> F64VECTOR </procedure>
609
610
611
612{{xSYR}} performs the symmetric rank 1 operation {{A := alpha*x*x' + A}}.
613
614{{ALPHA}} is a scalar, {{X}} is an {{N}} element vector, and {{A}} is
615an {{N x N}} symmetric matrix.
616
617
618
619==== Symmetric rank 2 operation
620
621
622<procedure>ssyr2:: ORDER * UPLO * N * ALPHA * X * Y * A [LDA * INCX * INCY] -> F32VECTOR </procedure>
623
624<procedure>dsyr2:: ORDER * UPLO * N * ALPHA * X * Y * A [LDA * INCX * INCY] -> F64VECTOR </procedure>
625
626
627
628{{xSYR2}} performs the symmetric rank 2 operation {{A := alpha*x*y' + alpha*y*x' + A}}.
629
630{{ALPHA}} is a scalar, {{X}} and {{Y}} are {{N}} element vectors, and
631{{A}} is an {{N x N}} symmetric matrix.
632
633
634
635=== BLAS level 3 routines
636
637
638==== Conventions
639
640
641The BLAS level 3 procedures in this egg differ from the actual
642routines they invoke by the position of the leading dimension
643arguments ({{LDA}}, {{LDB}}, and {{LDC}}). In this egg, these
644arguments are optional, and their default values are set to the
645largest matrix dimension, depending on the semantics of the respective
646operation.
647
648In the procedure signatures below, these optional arguments are
649indicated by [ and ] (square brackets).
650
651Argument {{ORDER}} is one of {{RowMajor}} or {{ColMajor}} to
652indicate that the input and output matrices are in row-major or
653column-major form, respectively.
654
655Where present, arguments {{TRANS}}, {{TRANSA}}, {{TRANSB}} can be one
656of {{NoTrans}} or {{Trans}} to indicate whether the
657respective input matrices are to be transposed or not.
658
659Where present, argument {{SIDE}} can be one of {{Left}} or
660{{Right}} to indicate whether an input symmetric matrix appears
661on the left or right in the respective operation.
662
663Where present, argument {{UPLO}} can be one of {{Upper}} or
664{{Lower}} to indicate whether the upper or lower triangular part
665of an input symmetric matrix is to referenced,or to specify the type
666of an input triangular matrix.
667
668Where present, argument {{DIAG}} can be one of {{NonUnit}} or
669{{Unit}} to indicate whether an input triangular matrix is unit
670triangular or not.
671
672==== General matrix multiply-add
673
674
675<procedure>sgemm:: ORDER * TRANSA * TRANSB * M * N * K * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F32VECTOR </procedure>
676
677<procedure>dgemm:: ORDER * TRANSA * TRANSB * M * N * K * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
678
679<procedure>cgemm:: ORDER * TRANSA * TRANSB * M * N * K * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F32VECTOR </procedure>
680
681<procedure>zgemm:: ORDER * TRANSA * TRANSB * M * N * K * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
682
683
684
685{{xGEMM}} performs matrix-matrix multiply-add operation of the form
686{{C := alpha*op( A )*op( B ) + beta*C}}, where {{op( X )}} is one of
687{{op( X ) = X}} or {{op( X ) = X'}}.
688
689{{ALPHA}} and {{BETA}} are scalars, and {{A}}, {{B}} and {{C}} are
690matrices, with {{op( A )}} an {{M x K}} matrix,
691{{op( B )}} a {{K x N}} matrix and {{C}} an {{M x N}} matrix.
692
693
694
695==== Symmetric matrix multiply-add
696
697
698<procedure>ssymm:: ORDER * SIDE * UPLO * M * N * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F32VECTOR </procedure>
699
700<procedure>dsymm:: ORDER * SIDE * UPLO * M * N * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
701
702<procedure>csymm:: ORDER * SIDE * UPLO * M * N * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F32VECTOR </procedure>
703
704<procedure>zsymm:: ORDER * SIDE * UPLO * M * N * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
705
706
707
708{{xSYMM}} performs matrix-matrix multiply-add operation of the form
709{{C := alpha*A*B + beta*C}} or {{C := alpha*B*A + beta*C}}.
710
711{{ALPHA}} and {{BETA}} are scalars, {{A}} is a symmetric matrix, and
712{{B}} and {{C}} are {{M x N}} matrices.
713
714
715
716==== Symmetric rank k operation
717
718
719<procedure>ssyrk:: ORDER * UPLO * TRANS * N * K * ALPHA * A * BETA * C [LDA * LDB * LDC] -> F32VECTOR </procedure>
720
721<procedure>dsyrk:: ORDER * UPLO * TRANS * N * K * ALPHA * A * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
722
723<procedure>csyrk:: ORDER * UPLO * TRANS * N * K * ALPHA * A * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
724
725<procedure>zsyrk:: ORDER * UPLO * TRANS * N * K * ALPHA * A * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
726
727
728
729{{xSYRK}} performs one of the symmetric rank k operations
730 {{C := alpha*A*A' + beta*C}} or {{C := alpha*A'*A + beta*C}}.
731
732{{ALPHA}} and {{BETA}} are scalars, {{A}} is an {{N x K}} or {{K x N}}
733matrix, and {{C}} is an {{N x N}} symmetric matrix.
734
735
736
737==== Hermitian rank k operation
738
739
740<procedure>cherk:: ORDER * UPLO * TRANS * N * K * ALPHA * A * BETA * C [LDA * LDB * LDC] -> F32VECTOR </procedure>
741
742<procedure>zherk:: ORDER * UPLO * TRANS * N * K * ALPHA * A * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
743
744
745
746{{xHERK}} performs one of the hermitian rank k operations
747{{C := alpha*A*conjg(A') + beta*C}} or {{C := alpha*conjg(A')*A + beta*C}}.
748
749{{ALPHA}} and {{BETA}} are scalars, {{A}} is an {{N x K}} or {{K x N}}
750matrix, and {{C}} is an {{N x N}} hermitian matrix.
751
752
753
754==== Symmetric rank 2k operation
755
756
757<procedure>ssyr2k:: ORDER * UPLO * TRANS * N * K * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F32VECTOR </procedure>
758
759<procedure>dsyr2k:: ORDER * UPLO * TRANS * N * K * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
760
761<procedure>csyr2k:: ORDER * UPLO * TRANS * N * K * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
762
763<procedure>zsyr2k:: ORDER * UPLO * TRANS * N * K * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
764
765
766
767{{xSYR2K}} performs one of the symmetric rank 2k operations
768{{C := alpha*A*B' + beta*C}} or {{C := alpha*B'*A + beta*C}}.
769
770{{ALPHA}} and {{BETA}} are scalars, {{A}} and {{B}} are {{N x K}} or
771{{K x N}} matrices, and {{C}} is an {{N x N}} symmetric matrix.
772
773
774
775==== Hermitian rank 2k operation
776
777
778<procedure>cher2k:: ORDER * UPLO * TRANS * N * K * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F32VECTOR </procedure>
779
780<procedure>zher2k:: ORDER * UPLO * TRANS * N * K * ALPHA * A * B * BETA * C [LDA * LDB * LDC] -> F64VECTOR </procedure>
781
782
783
784{{xHER2K}} performs one of the hermitian rank 2k operations
785{{C := alpha*A*conjg(B') + beta*C}} or {{C := alpha*conjg(B')*A + beta*C}}.
786
787{{ALPHA}} and {{BETA}} are scalars, {{A}} and {{B}} are {{N x K}} or
788{{K x N}} matrices, and {{C}} is an {{N x N}} hermitian matrix.
789
790
791
792==== Triangular matrix multiply
793
794
795<procedure>strmm:: ORDER * SIDE * UPLO * TRANSA * DIAG * M * N * ALPHA * A * B [LDA * LDB] -> F32VECTOR </procedure>
796
797<procedure>dtrmm:: ORDER * SIDE * UPLO * TRANSA * DIAG * M * N * ALPHA * A * B [LDA * LDB] -> F64VECTOR </procedure>
798
799<procedure>ctrmm:: ORDER * SIDE * UPLO * TRANSA * DIAG * M * N * ALPHA * A * B [LDA * LDB] -> F32VECTOR </procedure>
800
801<procedure>ztrmm:: ORDER * SIDE * UPLO * TRANSA * DIAG * M * N * ALPHA * A * B [LDA * LDB] -> F64VECTOR </procedure>
802
803
804
805{{xTRMM}} performs matrix-matrix multiply operation of the form
806{{B := alpha*op( A )*B}} or {{B := alpha*B*op( A )}}.
807
808{{ALPHA}} is a scalar, {{A}} is an upper or lower triangular matrix,
809and {{B}} is an {{M x N}} matrix.
810
811
812
813==== Triangular matrix equation solve
814
815
816<procedure>strsm:: ORDER * SIDE * UPLO * TRANSA * DIAG * M * N * ALPHA * A * B * [LDA * LDB * LDC] -> F32VECTOR </procedure>
817
818<procedure>dtrsm:: ORDER * SIDE * UPLO * TRANSA * DIAG * M * N * ALPHA * A * B * [LDA * LDB * LDC] -> F64VECTOR </procedure>
819
820<procedure>ctrsm:: ORDER * SIDE * UPLO * TRANSA * DIAG * M * N * ALPHA * A * B * [LDA * LDB * LDC] -> F32VECTOR </procedure>
821
822<procedure>ztrsm:: ORDER * SIDE * UPLO * TRANSA * DIAG * M * N * ALPHA * A * B * [LDA * LDB * LDC] -> F64VECTOR </procedure>
823
824
825
826{{xTRSM}} solves one of the matrix equations
827 {{op( A )*X = alpha*B}} or {{X*op( A ) = alpha*B}}.
828
829{{op( A )}} is one of {{op( A ) = A}} or {{op( A ) = A'}}.
830
831{{ALPHA}} and {{BETA}} are scalars, {{A}} is a upper or lower
832triangular matrix, and {{B}} is a {{M x N}} matrix.
833
834
835
836== Examples
837 
838 (import srfi-4 blas)
839 
840 (define order ColMajor)
841 (define transa NoTrans)
842 
843 (define m 4)
844 (define n 4)
845 
846 (define alpha 1)
847 (define beta 0)
848 
849 (define a                              ; column-major order!
850   (f64vector 1 2 3 4
851             1 1 1 1
852             3 4 5 6
853             5 6 7 8) )
854 
855 (define x (f64vector 1 2 1 1))
856 (define y (f64vector 0 0 0 0))
857   
858 (dgemv! order transa m n alpha a x beta y)
859 
860 (print y)
861
862== About this egg
863
864
865=== Author
866
867[[/users/felix-winkelmann|Felix Winkelmann]] and [[/users/ivan-raikov|Ivan Raikov]]
868
869=== Version history
870
871; 4.1 : Fixed use of memq [thanks to Moritz Heidkamp]
872; 4.0 : Using bind instead of easyffi
873; 3.1 : Updated test script to return proper exit code
874; 3.0 : Eliminated reduntant blas: prefix from names of exported symbols
875; 2.8 : Eliminated use of noop
876; 2.7 : Switched to wiki documentation
877; 2.6 : Ported to Chicken 4
878; 2.5 : Build script updated for better cross-platform compatibility
879; 2.4 : Added iger procedures; fixed a bug in the default arguments of level 2 routines
880; 2.3 : Added iaxpy procedures; fixed a bug in the default arguments of level 1 routines
881; 2.2 : Fixed a bug in the renaming of C routines
882; 2.1 : Added eggdoc property to meta file
883; 2.0 : An overhaul of the library to introduce safe, unsafe, and pure variants of each routine
884; 1.8 : Added icopy procedures [by Ivan Raikov]
885; 1.7 : Support for Mac OS X added [by Will Farr]
886; 1.6 : Fixed bug in blas library test code
887; 1.5 : Added support for CLAPACK [by Ivan Raikov]
888; 1.4 : Added support for atlas CBLAS library [by Stu Glaser]
889; 1.3 : Tries to find a proper CBLAS library (currently only GSL)
890; 1.2 : Adapted to new FFI macro-names
891; 1.1 : Adapted to new setup scheme
892
893=== License
894
895
896 Copyright (c) 2003-2006, Felix L. Winkelmann
897 Copyright (c) 2007-2018 Ivan Raikov
898 
899 All rights reserved.
900 
901 Redistribution and use in source and binary forms, with or without
902 modification, are permitted provided that the following conditions are
903 met:
904 
905   Redistributions of source code must retain the above copyright
906 notice, this list of conditions and the following disclaimer.
907 
908   Redistributions in binary form must reproduce the above copyright
909 notice, this list of conditions and the following disclaimer in the
910 documentation and/or other materials provided with the distribution.
911 
912   Neither the name of the author nor the names of its contributors may
913 be used to endorse or promote products derived from this software
914 without specific prior written permission.
915 
916 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
917 CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
918 BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
919 FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
920 COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
921 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
922 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
923 OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
924 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
925 TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
926 USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
927 DAMAGE.
928
Note: See TracBrowser for help on using the repository browser.