gonum.org/v1/gonum@v0.14.0/blas/gonum/doc.go (about)

     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 gonum 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  
    32  	[0 * * 1 * * 2 * * 3 * * 4 * * * ...]
    33  
    34  where ∗ elements are never accessed. If incX = -3, the same elements are
    35  accessed, just in reverse order (4, 3, 2, 1, 0).
    36  
    37  Dense matrices are specified by a number of rows, a number of columns, and a stride.
    38  The stride specifies the number of entries in the slice between the first element
    39  of successive rows. The stride must be at least as large as the number of columns
    40  but may be longer.
    41  
    42  	[a00 ... a0n a0* ... a1stride-1 a21 ... amn am* ... amstride-1]
    43  
    44  Thus, dense[i*ld + j] refers to the {i, j}th element of the matrix.
    45  
    46  Symmetric and triangular matrices (non-packed) are stored identically to Dense,
    47  except that only elements in one triangle of the matrix are accessed.
    48  
    49  Packed symmetric and packed triangular matrices are laid out with the entries
    50  condensed such that all of the unreferenced elements are removed. So, the upper triangular
    51  matrix
    52  
    53  	[
    54  	  1  2  3
    55  	  0  4  5
    56  	  0  0  6
    57  	]
    58  
    59  and the lower-triangular matrix
    60  
    61  	[
    62  	  1  0  0
    63  	  2  3  0
    64  	  4  5  6
    65  	]
    66  
    67  will both be compacted as [1 2 3 4 5 6]. The (i, j) element of the original
    68  dense matrix can be found at element i*n - (i-1)*i/2 + j for upper triangular,
    69  and at element i * (i+1) /2 + j for lower triangular.
    70  
    71  Banded matrices are laid out in a compact format, constructed by removing the
    72  zeros in the rows and aligning the diagonals. For example, the matrix
    73  
    74  	[
    75  	  1  2  3  0  0  0
    76  	  4  5  6  7  0  0
    77  	  0  8  9 10 11  0
    78  	  0  0 12 13 14 15
    79  	  0  0  0 16 17 18
    80  	  0  0  0  0 19 20
    81  	]
    82  
    83  implicitly becomes (∗ entries are never accessed)
    84  
    85  	[
    86  	   *  1  2  3
    87  	   4  5  6  7
    88  	   8  9 10 11
    89  	  12 13 14 15
    90  	  16 17 18  *
    91  	  19 20  *  *
    92  	]
    93  
    94  which is given to the BLAS routine as [∗ 1 2 3 4 ...].
    95  
    96  See http://www.crest.iu.edu/research/mtl/reference/html/banded.html
    97  for more information
    98  */
    99  package gonum // import "gonum.org/v1/gonum/blas/gonum"