vendor/gonum.org/v1/gonum/blas/gonum/doc.go

   1 // Copyright ©2015 The Gonum Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 // Ensure changes made to blas/native are reflected in blas/cgo where relevant.
   6
   7 /*
   8 Package native is a Go implementation of the BLAS API. This implementation
   9 panics when the input arguments are invalid as per the standard, for example
  10 if a vector increment is zero. Note that the treatment of NaN values
  11 is not specified, and differs among the BLAS implementations.
  12 gonum.org/v1/gonum/blas/blas64 provides helpful wrapper functions to the BLAS
  13 interface. The rest of this text describes the layout of the data for the input types.
  14
  15 Note that in the function documentation, x[i] refers to the i^th element
  16 of the vector, which will be different from the i^th element of the slice if
  17 incX != 1.
  18
  19 See http://www.netlib.org/lapack/explore-html/d4/de1/_l_i_c_e_n_s_e_source.html
  20 for more license information.
  21
  22 Vector arguments are effectively strided slices. They have two input arguments,
  23 a number of elements, n, and an increment, incX. The increment specifies the
  24 distance between elements of the vector. The actual Go slice may be longer
  25 than necessary.
  26 The increment may be positive or negative, except in functions with only
  27 a single vector argument where the increment may only be positive. If the increment
  28 is negative, s[0] is the last element in the slice. Note that this is not the same
  29 as counting backward from the end of the slice, as len(s) may be longer than
  30 necessary. So, for example, if n = 5 and incX = 3, the elements of s are
  31         [0 * * 1 * * 2 * * 3 * * 4 * * * ...]
  32 where ∗ elements are never accessed. If incX = -3, the same elements are
  33 accessed, just in reverse order (4, 3, 2, 1, 0).
  34
  35 Dense matrices are specified by a number of rows, a number of columns, and a stride.
  36 The stride specifies the number of entries in the slice between the first element
  37 of successive rows. The stride must be at least as large as the number of columns
  38 but may be longer.
  39         [a00 ... a0n a0* ... a1stride-1 a21 ... amn am* ... amstride-1]
  40 Thus, dense[i*ld + j] refers to the {i, j}th element of the matrix.
  41
  42 Symmetric and triangular matrices (non-packed) are stored identically to Dense,
  43 except that only elements in one triangle of the matrix are accessed.
  44
  45 Packed symmetric and packed triangular matrices are laid out with the entries
  46 condensed such that all of the unreferenced elements are removed. So, the upper triangular
  47 matrix
  48   [
  49     1  2  3
  50     0  4  5
  51     0  0  6
  52   ]
  53 and the lower-triangular matrix
  54   [
  55     1  0  0
  56     2  3  0
  57     4  5  6
  58   ]
  59 will both be compacted as [1 2 3 4 5 6]. The (i, j) element of the original
  60 dense matrix can be found at element i*n - (i-1)*i/2 + j for upper triangular,
  61 and at element i * (i+1) /2 + j for lower triangular.
  62
  63 Banded matrices are laid out in a compact format, constructed by removing the
  64 zeros in the rows and aligning the diagonals. For example, the matrix
  65   [
  66     1  2  3  0  0  0
  67     4  5  6  7  0  0
  68     0  8  9 10 11  0
  69     0  0 12 13 14 15
  70     0  0  0 16 17 18
  71     0  0  0  0 19 20
  72   ]
  73
  74 implicitly becomes (∗ entries are never accessed)
  75   [
  76      *  1  2  3
  77      4  5  6  7
  78      8  9 10 11
  79     12 13 14 15
  80     16 17 18  *
  81     19 20  *  *
  82   ]
  83 which is given to the BLAS routine as [∗ 1 2 3 4 ...].
  84
  85 See http://www.crest.iu.edu/research/mtl/reference/html/banded.html
  86 for more information
  87 */
  88 package gonum // import "gonum.org/v1/gonum/blas/gonum"