This is algae.info, produced by makeinfo version 4.3 from algae.texinfo.

INFO-DIR-SECTION Programming Languages
START-INFO-DIR-ENTRY
* algae: (algae).		Another Matrix Programming Language
END-INFO-DIR-ENTRY


File: algae.info,  Node: cram,  Next: dense,  Prev: combine,  Up: Arrays

 - Function: cram ( shape; x )
     This function uses the elements of X to make an entity described
     by the vector SHAPE.  If SHAPE is NULL or has no elements, a
     scalar is returned.  If SHAPE has one element, then a vector of
     length `shape[1]' is returned.  If SHAPE has two elements, then a
     matrix with `shape[1]' rows and `shape[2]' columns is returned.

     The elements of X are used, in order, to fill the new entity.  For
     matrices, this proceeds by rows.  If the entity returned has more
     elements than X, it is padded with zeros or null strings.  For
     example, `cram( 5; 1,2 )' returns the vector `(1,2,0,0,0)'.

     If the return value is an array, it may be either dense or sparse.
     The code will try to make a reasonable choice, but avoids
     spending much time in deciding.  For example, `cram( 1000; 1 )'
     returns a sparse vector since it is immediately apparent that most
     of its elements are zero.  On the other hand, `cram( 1000;
     (1:1000)<2 )' is dense even though it would be more efficient to
     store it sparse; since its second argument is a dense vector,
     `cram' would need to check most of its elements to realize that.

     The `form' function is identical to this function except that the
     arrays it returns are always dense.

     See also `fill', `form', and `zero'.


File: algae.info,  Node: dense,  Next: diag,  Prev: cram,  Up: Arrays

 - Function: dense ( x )
     The `dense' function converts its argument array to dense storage.
     See also `sparse'.


File: algae.info,  Node: diag,  Next: dice,  Prev: dense,  Up: Arrays

 - Function: diag ( x )
     The `diag' function performs two different tasks, depending on the
     class of X.  If X is a matrix, then its diagonal is returned as a
     vector.  If X is a vector, then a matrix is returned which has X
     as its diagonal and is zero elsewhere.  (If X is a scalar, it is
     returned intact.)

     See also `bdiag'.


File: algae.info,  Node: dice,  Next: diff,  Prev: diag,  Up: Arrays

 - Function: dice ( s )
     The `dice' function takes a character scalar S and returns a
     character vector, each element of which is a single character from
     S.  For example, the expression `dice("Go dawgs!")' yields

          (  "G", "o", " ", "d", "a", "w", "g", "s", "!" )

     See also `split'.


File: algae.info,  Node: diff,  Next: exsparse,  Prev: dice,  Up: Arrays

 - Function: diff ( v )
     The `diff' function takes a numeric vector V and returns a vector
     of differences between its elements.  If V has `n' elements, then
     the return vector is

          v[2]-v[1], v[3]-v[2], ..., v[n]-v[n-1]

     The return vector has one less element than V.  If V has labels,
     then the return vector contains all but the last one.

     One simple use for `diff' is to compute forward-difference
     approximations for the slope of a curve.  If `c' is a vector
     containing ordinates of the curve in its elements and abscissae in
     its labels, then the expression

          diff (c) / diff (unlabel (c.eid))

     returns an approximation to its slope.  (The call to `unlabel' is
     probably unnecessary in most cases, but it avoids trouble when the
     labels of `c' themselves have labels.)


File: algae.info,  Node: exsparse,  Next: fill,  Prev: diff,  Up: Arrays

 - Function: exsparse ( x )
     This function disassembles a matrix, returning it in its
     "coordinate" form, suitable for reassembly by the `mksparse'
     function.  A table is returned, containing the members SHAPE,
     ROWS, COLS, and VALUES.  The argument matrix X must be numeric.
     Despite the name of the function, it need not be sparse.

     See also `mksparse'.


File: algae.info,  Node: fill,  Next: find,  Prev: exsparse,  Up: Arrays

 - Function: fill ( shape; x )
     This function uses the elements of X to make an entity described
     by the vector SHAPE.  If SHAPE is NULL or has no elements, a
     scalar is returned.  If SHAPE has one element, then a vector of
     length `shape[1]' is returned.  If SHAPE has two elements, then a
     matrix with `shape[1]' rows and `shape[2]' columns is returned.

     The elements of X are used, in order, to fill the new entity.  For
     matrices, this proceeds by rows.  If the entity returned has more
     elements than X, then the elements of X are reused.  For example,
     `fill( 5; "a","b" )' returns the vector `("a","b","a","b","a")'.

     When the return value from `fill' is a vector or matrix, it will
     always be dense.  See the `cram' function for sparse return arrays.

     The `form' function differs from this function only in that it
     pads with zeros rather than reusing elements of X.

     See also `form', `cram', and `zero'.


File: algae.info,  Node: find,  Next: first,  Prev: fill,  Up: Arrays

 - Function: find ( a; b )
     The `find' function locates the elements of B that have the values
     given by A and returns a vector containing their element numbers.
     For example, `find( 2,3; 0,1,2,3,4 )' returns the vector `(3,4)'.
     One common use is in an expression like `A[find(77;A.rid);]',
     which returns the row (or rows) of A having the row label 77.

     If A is a scalar, then `find(a;b)' returns the element numbers of
     B, sorted from smallest to largest, for which the corresponding
     element of B is equal to A.  If A is a vector, then `find(a;b)'
     returns the same as `find(a[1];b),find(a[2];b),...'.

     See also `grep' and `lose'.


File: algae.info,  Node: first,  Next: form,  Prev: find,  Up: Arrays

 - Function: first ( v )
     The `first' function returns the index of the first "true" element
     in the vector V.  If none are found, 0 is returned.

     See also `find' and `last'.


File: algae.info,  Node: form,  Next: full,  Prev: first,  Up: Arrays

 - Function: form ( shape; x )
     This function uses the elements of X to make an entity described
     by the vector SHAPE.  If SHAPE is NULL or has no elements, a
     scalar is returned.  If SHAPE has one element, then a vector of
     length `shape[1]' is returned.  If SHAPE has two elements, then a
     matrix with `shape[1]' rows and `shape[2]' columns is returned.

     The elements of X are used, in order, to fill the new entity.  For
     matrices, this proceeds by rows.  If the entity returned has more
     elements than X, it is padded with zeros or null strings.  For
     example, `form( 5; "a","b" )' returns the vector
     `("a","b","","","")'.

     When the return value from `form' is a vector or matrix, it will
     always be dense.  See the `cram' function for sparse return arrays.

     The `fill' function differs from this function only in that it
     reuses the elements of X rather than padding with zeros.

     See also `fill', `cram', and `zero'.


File: algae.info,  Node: full,  Next: gpskca,  Prev: form,  Up: Arrays

 - Function: full ( x )
     The `full' function converts a matrix stored in "sparse_upper"
     form to the "sparse" form.


File: algae.info,  Node: gpskca,  Next: grep,  Prev: full,  Up: Arrays

 - Function: gpskca ( m; flag )
     The `gpskca' function attempts to find a symmetric permutation of
     the rows and columns of matrix M to reduce either its bandwidth or
     its profile.  If the FLAG argument is "true" (in the sense of the
     `test' function, then the Gibbs-Poole-Stockmeyer algorithm is used
     for bandwidth reduction; otherwise, the Gibbs-King algorithm is
     used for profile reduction.  See the description of the `band'
     function for a definition of these terms.

     The return value is the permutation, given as an integer vector
     with length equal to the order of M.  Consider the following
     example interaction:

          > a = symmetric (magic(6) > 25);
          > band (a)
              ( 4, 13, 4, 13 )
          > v = gpskca (a);
          > b = a[v;v];
          > band (b)
              ( 2, 9, 2, 9 )

     First, the sparse, symmetric matrix A is created.  The `band'
     function shows that it has a bandwidth of 4 and a profile of 13.
     Next, `gpskca' provides a permutation to reduce the profile.  The
     matrix B is set to equal A but with this permutation applied.
     Finally, `band' shows that this permutation reduces both the
     bandwidth (to 2) and the profile (to 9).

     The matrix M must be either symmetric or hermitian.  This function
     uses the GPSKCA subroutine written by John Lewis.

     See also `band'.


File: algae.info,  Node: grep,  Next: hermitian,  Prev: gpskca,  Up: Arrays

 - Function: grep ( expr; v )
     The `grep' function finds the elements of the vector V which match
     the pattern `expr'.  The pattern is an extended regular expression
     which is given to the UNIX function `egrep' to do the searching.

     The character strings in V must not contain a newline, or the
     results will generally be wrong.

     Here are some examples (user input is preceded by the `>' prompt):

          > grep ("a"; "ab", "ac", "bc")
              ( 1, 2 )
          
          > grep ("9$"; 1:40)
              ( 9, 19, 29, 39 )
          
          > m = magic (3)
              [ 8  1  6 ]
              [ 3  5  7 ]
              [ 4  9  2 ]
          > m.rid = "top", "middle", "bottom";
          > m[ grep ("top|bottom"; m.rid); ]
              [ 8  1  6 ]
              [ 4  9  2 ]

     This is a terribly inefficient implementation (maybe someday Algae
     will have builtin regular expressions), but maybe you'll find it
     useful.

     See also `find' and `lose'.


File: algae.info,  Node: hermitian,  Next: ident,  Prev: grep,  Up: Arrays

 - Function: hermitian ( x )
     This function returns the hermitian part of the square, numeric
     matrix X.  A hermitian matrix has complex-conjugate symmetry.  It's
     diagonal must necessarily be real.  The returned matrix is complex
     only if X is complex.

     If X has both row and column labels, they must match.

     See also `symmetric'.


File: algae.info,  Node: ident,  Next: imax,  Prev: hermitian,  Up: Arrays

 - Function: ident ( n )
     The `ident' function returns an identity matrix with N rows and
     columns.


File: algae.info,  Node: imax,  Next: imin,  Prev: ident,  Up: Arrays

 - Function: imax ( v )
     If V is a vector, this function returns the number of the element
     with the greatest value.  If multiple elements qualify, then the
     number of the first one is returned.

     If V is a matrix, then a vector is returned, each element giving
     the row number of the greatest value in the corresponding column.
     Again, if more than one element qualifies, the first one is given.

     If V is a table, then the `imax' function is applied to each of
     its members.

     The argument V may not be a scalar, and must not have complex
     type.  Note that `imax(v)' is not necessarily equal to `imin(-v)'.

     See also `imin', `max', `min', `isort', and `sort'.


File: algae.info,  Node: imin,  Next: isort,  Prev: imax,  Up: Arrays

 - Function: imin ( v )
     If V is a vector, this function returns the number of the element
     with the least value.  If multiple elements qualify, then the
     number of the last one is returned.

     If V is a matrix, then a vector is returned, each element giving
     the row number of the least value in the corresponding column.
     Again, if more than one element qualifies, the last one is given.

     If V is a table, then the `imin' function is applied to each of
     its members.

     The argument V may not be a scalar, and must not have complex
     type.  Note that `imin(v)' is not necessarily equal to `imax(-v)'.

     See also `imax', `max', `min', `isort', and `sort'.


File: algae.info,  Node: isort,  Next: label,  Prev: imin,  Up: Arrays

 - Function: isort ( v )
     This function sorts the elements of vector V in increasing order,
     and returns a vector containing the corresponding indices.  For
     example, `sort(20,40,10,30)' returns the vector `(3,1,4,2)'.  The
     expression `v[isort(v)]' actually returns the sorted vector V,
     although the builtin function `sort' does this more efficiently.
     Complex numbers are sorted primarily by real value and secondarily
     by imaginary value.

     See also `sort', `max', `min', and `set'.


File: algae.info,  Node: label,  Next: last,  Prev: isort,  Up: Arrays

 - Function: label ( x; a; b )
     The `label' function assigns labels to vectors and matrices.  If X
     is a vector, A is assigned as its element labels.  If X is a
     matrix, A and B are assigned as its row and column labels,
     respectively.  If X has any other class, an exception is raised.

     See also `unlabel'.


File: algae.info,  Node: last,  Next: linspace,  Prev: label,  Up: Arrays

 - Function: last ( v )
     The `last' function returns the index of the last "true" element
     in the vector V.  If none are found, 0 is returned.

     See also `find' and `first'.


File: algae.info,  Node: linspace,  Next: logspace,  Prev: last,  Up: Arrays

 - Function: linspace ( a; b; n )
     The `linspace' function generates a vector of N elements, spaced
     uniformly between A and B.  All three arguments must be (or be
     convertible to) scalars.  The argument N must be (or round to) an
     integer greater than one.

     The vector generation operator `:' also generates uniformly spaced
     vectors.  With the operator, the number of elements is determined
     from the specified spacing; with the `linspace' function, the
     spacing is determined from the number of elements specified.  Also
     notice that the last element of the vector returned by `linspace'
     is equal to B, which is not necessarily the case with the `:'
     operator.

     See also `logspace'.


File: algae.info,  Node: logspace,  Next: lose,  Prev: linspace,  Up: Arrays

 - Function: logspace ( a; b; n )
     The `logspace' function generates a vector of N elements, spaced
     logarithmically between A and B.  All three arguments must be (or
     be convertible to) scalars.  Both A and B must be nonzero, and N
     must be (or round to) an integer greater than one.

     Logarithmic spacing means that the logarithm of the result vector
     is a uniformly spaced vector.  This also means that the ratio
     between any two adjacent elements is constant.  Note that even if
     both A and B are real, the result will be complex if they have
     opposite signs, and that a complex result will not necessarily
     form a straight line in the complex plane.

     See also `linspace'.


File: algae.info,  Node: lose,  Next: magic,  Prev: logspace,  Up: Arrays

 - Function: lose ( a; b )
     The `lose' function locates elements of B that do not have the
     values given by A and returns a vector containing their element
     numbers.  For example, `lose( 2,3; 0,1,2,3,4 )' returns the vector
     `(1,2,5)'.  One common use is in an expression such as
     `A[lose(77;A.rid);]', which returns all of the rows of A that
     don't have the row label 77.

     If A is a scalar, then `lose(a;b)' returns the element numbers of
     B, sorted from smallest to largest, for which the corresponding
     element of B is not equal to A.  If A is a vector, then
     `lose(a;b)' returns the intersection of the results of
     `lose(a[1];b)', `lose(a[2];b)', etc.

     See also `find'.


File: algae.info,  Node: magic,  Next: matrix,  Prev: lose,  Up: Arrays

 - Function: magic ( n )
     The `magic' function returns a magic square of order N.  (What
     system would be complete without it?)  The elements of a magic
     square consist of all the integers 1 through N^2, arranged so that
     the row, column, and the two diagonal sums are equal.

     N must be greater than 0.  No magic square exists for order 2.


File: algae.info,  Node: matrix,  Next: max,  Prev: magic,  Up: Arrays

 - Function: matrix ( x )
     This function converts its argument X to a matrix if possible.
     Scalars become one-by-one matrices, vectors become matrices with
     one row, and matrices are unchanged.  If X is NULL, `matrix'
     returns a real matrix with zero rows and zero columns.

     See also `scalar' and `vector'.


File: algae.info,  Node: max,  Next: merge,  Prev: matrix,  Up: Arrays

 - Function: max ( v )
     If V is a vector, this function returns its greatest value.  If V
     is a matrix, then a vector is returned, each element giving the
     greatest value of any element in the corresponding column.

     If V is a table, then the `max' function is applied to each of its
     members.

     The argument V may not be a scalar, and must not have complex type.

     See also `min', `imax', `imin', `isort', and `sort'.


File: algae.info,  Node: merge,  Next: min,  Prev: max,  Up: Arrays

 - Function: merge ( x; y )
     This function merges two entities, X and Y, with respect to their
     labels.  The result has labels that consist of the union of the
     labels of X and Y.  Its elements come from the corresponding
     elements in X and Y; they are summed when the same element occurs
     in both.

     This is demonstrated by the following interactive session:

          > A = fill (3,3; 1:9)
                  [  1   2   3 ]
                  [  4   5   6 ]
                  [  7   8   9 ]
          > A.rid = A.cid = 1:3;
          > B = fill (3,3; 10:90:10)
                  [ 10  20  30 ]
                  [ 40  50  60 ]
                  [ 70  80  90 ]
          > B.rid = B.cid = 2:4;
          > merge (A; B)
                  [  1   2   3   0 ]
                  [  4  15  26  30 ]
                  [  7  48  59  60 ]
                  [  0  70  80  90 ]

     If X and Y are not vectors or matrices, they are simply summed.


File: algae.info,  Node: min,  Next: mksparse,  Prev: merge,  Up: Arrays

 - Function: min ( v )
     If V is a vector, this function returns its least value.  If V is
     a matrix, then a vector is returned, each element giving the least
     value of any element in the corresponding column.

     If V is a table, then the `min' function is applied to each of its
     members.

     The argument V may not be a scalar, and must not have complex type.

     See also `max', `imax', `imin', `isort', and `sort'.


File: algae.info,  Node: mksparse,  Next: norm,  Prev: min,  Up: Arrays

 - Function: mksparse ( t )
     This function returns a sparse matrix with dimensions and elements
     given by the members of table T.  If the member SHAPE exists, it
     should be a vector with two elements specifying the number of rows
     and columns of the matrix.  If it does not exist, the matrix is
     sized just large enough to include all of the given elements.  The
     members ROWS, COLS, and VALUES must all exist; these are vectors,
     all with the same length, corresponding elements of which specify
     respectively the row number, column number, and value of each
     specified element of the matrix.  If an element is not specified,
     it is zero.  If an element is given more than once, its value is
     the sum of the given values.

     The following interactive session provides an example:

          > mksparse ({shape=3,4; rows=1,2,3; cols=1,3,2; values=10,11,12})
          	[          10          .          .          . ]
          	[           .          .         11          . ]
          	[           .         12          .          . ]

     The VALUES vector must have numeric type.  If T is NULL, a real
     matrix with 0 rows and 0 columns is returned.

     See also `sparse' and `exsparse'.


File: algae.info,  Node: norm,  Next: pick,  Prev: mksparse,  Up: Arrays

 - Function: norm ( x; p )
     The `norm' function computes the P-norm of X, where P is 1, 2,
     "frobenius", or "infinity".  (The latter two may be abbreviated as
     "frob" and "inf".)  If P is not specified, the 2-norm is used.

     For complex X, the 1 and "infinity" norms deal not with the
     magnitude of each element, but with the sum of the absolute values
     of the real and imaginary parts.


File: algae.info,  Node: pick,  Next: product,  Prev: norm,  Up: Arrays

 - Function: pick ( x )
     This function returns a vector containing the indices of the
     non-zero elements of the numeric input vector X.  For example, the
     expression

          V [ pick (V < 0) ]

     returns all of the negative elements of `V'.

     See also `find'.


File: algae.info,  Node: product,  Next: rand,  Prev: pick,  Up: Arrays

 - Function: product ( x )
     The `product' function computes the product of the elements of an
     array.  If X is a scalar, it is returned unchanged.  If X is a
     vector, the product of all of its elements is returned.  If X is a
     matrix, a vector is returned, each element of which is the product
     of the elements in the corresponding columns of X.  If X is a
     table, the `product' function is applied to each of its members.


File: algae.info,  Node: rand,  Next: randn,  Prev: product,  Up: Arrays

 - Function: rand ( shape )
     This function generates pseudo-random numbers with a uniform
     distribution in the range from 0 to 1.  Called with no arguments,
     it returns a scalar.  Otherwise, the vector SHAPE specifies a
     vector or matrix; see the `readnum' function for more information.

     The random number generator may be "seeded" with the `srand'
     function.  If you don't call `srand', the seed is based on the
     system's clock.  Note that `rand' and `randn' share the same seed.

     See also `randn' and `srand'.


File: algae.info,  Node: randn,  Next: reverse,  Prev: rand,  Up: Arrays

 - Function: randn ( shape )
     This function generates pseudo-random numbers from a normal
     distribution with zero mean and unit variance.  Called with no
     arguments, it returns a scalar.  Otherwise, the vector SHAPE
     specifies a vector or matrix; see the `readnum' function for more
     information.

     The random number generator may be "seeded" with the `srand'
     function.  If you don't call `srand', the seed is based on the
     system's clock.  Note that `rand' and `randn' share the same seed.

     See also `rand' and `srand'.


File: algae.info,  Node: reverse,  Next: scalar,  Prev: randn,  Up: Arrays

 - Function: reverse ( v )
     The `reverse' function simply reverses the order of the elements in
     vector V.  For example, `reverse(1,2,3)' returns the vector
     `(3,2,1)'.


File: algae.info,  Node: scalar,  Next: select,  Prev: reverse,  Up: Arrays

 - Function: scalar ( x )
     This function converts its argument X to a scalar if possible.
     See also `matrix' and `vector'.


File: algae.info,  Node: select,  Next: seq,  Prev: scalar,  Up: Arrays

 - Function: select ( x )
     The `select' function selects one element at random from the given
     vector.  The result is a scalar.  The vector X must have at least
     one element.


File: algae.info,  Node: seq,  Next: shape,  Prev: select,  Up: Arrays

 - Function: seq ( n )
     The `seq' function returns a vector of consecutive integers from 1
     to N.  The argument N is first rounded to the nearest integer; if
     it is less than 1, a zero-length vector is returned.


File: algae.info,  Node: shape,  Next: sign,  Prev: seq,  Up: Arrays

 - Function: shape ( x )
     This function returns the "shape" (that is, the dimensions) of its
     argument X.  This return value has the same form as is used for
     the SHAPE arguments of functions like READNUM and RAND.  If X is a
     scalar, NULL is returned.  If X is a vector, a scalar is returned
     having the length of X as its value.  If X is a matrix, a vector
     is returned having the number of rows and the number of columns as
     its first and second elements, respectively.  If X has any other
     class, an exception is raised.


File: algae.info,  Node: sign,  Next: sort,  Prev: shape,  Up: Arrays

 - Function: sign ( v )
     The `sign' function returns an array with the same size as V.
     Each element of the returned array is either -1, 0, or +1,
     depending on whether the corresponding element of V is negative,
     zero, or positive, respectively.  The argument V must be a numeric
     scalar or array.


File: algae.info,  Node: sort,  Next: sparse,  Prev: sign,  Up: Arrays

 - Function: sort ( v )
     This function sorts the elements of vector V in increasing order.
     For example, `sort(20,40,10,30)' returns the vector
     `(10,20,30,40)'.  Complex numbers are sorted primarily by real
     value and secondarily by imaginary value.

     See also `isort', `max', `min', and `set'.


File: algae.info,  Node: sparse,  Next: srand,  Prev: sort,  Up: Arrays

 - Function: sparse ( x )
     This function converts its argument X to sparse storage.


File: algae.info,  Node: srand,  Next: sum,  Prev: sparse,  Up: Arrays

 - Function: srand ( s )
     The `srand' function is used to "seed" the random number generator
     `rand'.  (OK, they're really pseudo-random numbers.)  The seed S
     determines the sequence of numbers returned by `rand'.  If S is
     NULL (or if `srand' is never called at all), then the seed is
     taken from the system's clock.  See also `rand'.


File: algae.info,  Node: sum,  Next: surprise,  Prev: srand,  Up: Arrays

 - Function: sum ( x )
     The `sum' function sums elements of arrays.  If X is a scalar, it
     is returned unchanged.  If X is a vector, the sum of all of its
     elements is returned.  If X is a matrix, a vector is returned,
     each element of which is the sum of the elements in the
     corresponding columns of X.


File: algae.info,  Node: surprise,  Next: symmetric,  Prev: sum,  Up: Arrays

 - Function: surprise ( rows; cols; type; density; symmetry; other )
     The `surprise' function returns a more-or-less random matrix with
     characteristics given by the input arguments.  It may be useful for
     testing or timing purposes.

     Each of the arguments to `surprise' may be a vector, in which case
     one of its members is chosen at random for that characteristic.
     For example, if ROWS is the vector `4,5,6' then the resulting
     array will have either 4, 5, or 6 rows.

     The ROWS and COLS arguments specify the number of rows and columns
     in the array.  The choice of dimensions has a lower priority than
     the other characteristics, so any dimensions that are incompatible
     with other choices are discarded.  For example, consider the call

          surprise (3,4; 4,5; "real"; ; "general","symmetric")

     This specifies a real matrix that is either general or symmetric.
     If general symmetry is chosen, then the array will have either 3
     or 4 rows and either 4 or 5 columns.  However, if a symmetric
     array is chosen, then it must be square and the result will have 4
     rows and 4 columns.

     On the other hand, the specified dimensions can affect the choice
     of the other characteristics.  For example, in the call

          surprise (3; 4; "real"; ; "general","symmetric")

     the result will not be symmetric, because the dimensions preclude
     it.

     The TYPE argument may contain any or all of the character strings
     `"integer"', `"real"', or `"complex"'.  Only numeric types are
     supported.  The default is `"real"'.

     The DENSITY argument specifies the approximate ratio of nonzero to
     total array elements.  For diagonal arrays, only the diagonal
     elements are considered.  The default is 1.0.

     The SYMMETRY argument may be `"general"', `"symmetric"', or
     `"hermitian"'.  The default is `"general"'.

     The OTHER argument may be `"none"', `"diagonal"', or
     `"positive_definite"'.  The default is `"none"'.


File: algae.info,  Node: symmetric,  Next: tril,  Prev: surprise,  Up: Arrays

 - Function: symmetric ( x )
     This function returns the symmetric part of the square, numeric
     matrix X.  If X has both row and column labels, they must match.

     See also `hermitian'.


File: algae.info,  Node: tril,  Next: triu,  Prev: symmetric,  Up: Arrays

 - Function: tril ( a; k )
     The `tril' function returns the lower "triangular" part of the
     matrix A.  The return matrix is identical to A except that, for
     any `i', all elements `a[i;i+k+1]', `a[i;i+k+2]', etc. are zero.
     If K is NULL, it defaults to zero.  Here is an example:

          > tril (magic (4); 1)
                  [  9   7   0   0 ]
                  [  4  14  15   0 ]
                  [ 16   2   3  13 ]
                  [  5  11  10   8 ]


File: algae.info,  Node: triu,  Next: unlabel,  Prev: tril,  Up: Arrays

 - Function: triu ( a; k )
     The `triu' function returns the upper "triangular" part of the
     matrix A.  The return matrix is identical to A except that, for
     any `i', all elements `a[i;i+k-1]', `a[i;i+k-2]', etc. are zero.
     If K is NULL, it defaults to zero.  Here is an example:

          > triu (magic (4); 1)
                  [  0   7   6  12 ]
                  [  0   0  15   1 ]
                  [  0   0   0  13 ]
                  [  0   0   0   0 ]


File: algae.info,  Node: unlabel,  Next: vector,  Prev: triu,  Up: Arrays

 - Function: unlabel ( x )
     The `unlabel' function removes the labels from its argument.  If X
     is a vector or a matrix, it sets the labels to NULL and returns
     the result.  If X has any other class, it is returned unchanged.


File: algae.info,  Node: vector,  Next: zero,  Prev: unlabel,  Up: Arrays

 - Function: vector ( x )
     This function converts its argument X to a vector if possible.
     Scalars become one-element vectors.  If X is a matrix with either
     one row or one column, then it is converted to a vector.

     See also `scalar' and `matrix'.


File: algae.info,  Node: zero,  Prev: vector,  Up: Arrays

 - Function: zero ( shape )
     This function generates an integer scalar, vector, or matrix, all
     the elements of which are zero.  The vector SHAPE specifies the
     dimensions of the entity returned; see the `readnum' function for
     more information.

     If a vector or matrix is returned, it is stored in sparse form.
     This may or may not be the most efficient storage for your
     application; use the `dense' function to convert it if desired.

     See also `dense'.


File: algae.info,  Node: Sets,  Next: Linear Algebra,  Prev: Arrays,  Up: Standard Functions

Sets
====

* Menu:

* complement::		complement
* intersection::	intersection
* set::			make a set
* union::		union


File: algae.info,  Node: complement,  Next: intersection,  Prev: Sets,  Up: Sets

 - Function: complement ( a; b )
     The `complement' function returns the relative complement of A in
     B; that is, the set of elements of B which are not in A.  The
     return value is a set, which we define as a sorted, irredundant
     vector.  "Sorted" means sorted by increasing value; character
     strings are sorted by ASCII values and complex numbers are sorted
     with the real values as the primary key and the imaginary values
     as the secondary key.

     If B has labels, then the returned vector also has labels that
     correspond to the retained elements.  If B has no labels, the
     labels of the returned vector give the index of the corresponding
     element in B.

     If B has redundant elements, the element retained is not
     necessarily the first.  For example, `complement(1;2,2,2).eid'
     might be 1, 2, or 3.

     See also `intersection', `set', and `union'.


File: algae.info,  Node: intersection,  Next: set,  Prev: complement,  Up: Sets

 - Function: intersection ( a; b )
     The `intersection' function returns the intersection of set A in
     B; that is, the set of elements that are in both A and B.  The
     return value is a set, which we define as a sorted, irredundant
     vector.  "Sorted" means sorted by increasing value; character
     strings are sorted by ASCII values and complex numbers are sorted
     with the real values as the primary key and the imaginary values
     as the secondary key.

     The return vector has no labels.

     See also `complement', `set', and `union'.


File: algae.info,  Node: set,  Next: union,  Prev: intersection,  Up: Sets

 - Function: set ( x )
     This function changes X into a set, if possible.  A "set" is
     defined as a sorted, irredundant vector.  "Sorted" means sorted by
     increasing value; character strings are sorted by ASCII values and
     complex numbers are sorted with the real values as the primary key
     and the imaginary values as the secondary key.  "Irredundant"
     means that no two elements have the same value.

     If X has labels, then the returned vector also has labels that
     correspond to the retained elements.  If X has no labels, the
     labels of the returned vector give the index of the corresponding
     element in X.

     If X has redundant elements, the element retained is not
     necessarily the first.  For example, `set(1,1,1).eid' might be 1,
     2, or 3.

     See also `complement', `intersection', and `union'.


File: algae.info,  Node: union,  Prev: set,  Up: Sets

 - Function: union ( a; b )
     The `union' function returns the union of sets A and B.  The
     return value is a set, which we define as a sorted, irredundant
     vector.  "Sorted" means sorted by increasing value; character
     strings are sorted by ASCII values and complex numbers are sorted
     with the real values as the primary key and the imaginary values
     as the secondary key.

     The return vector will always have labels.  To understand them, you
     need to know that the function call `union(a;b)' is identical to
     the code `set(a,b)' provided that A and B are both vectors.  (The
     `union' function will convert them both to vectors if necessary.)

     See also `complement', `intersection', and `set'.


File: algae.info,  Node: Linear Algebra,  Next: Numerical Analysis,  Prev: Sets,  Up: Standard Functions

Linear Algebra
==============

* Menu:

* backsub::     back substitution
* chol::        Cholesky factorization
* eig::		eigenvalues and eigenvectors
* equilibrate:: matrix equilibration
* factor::	triangular factorization
* fft::		fast Fourier transform
* filter::      digital filter
* ifft::	inverse fast Fourier transform
* inv::		matrix inverse
* iram::        Arnoldi method for eigenvalue problems
* leastsq::     least squares solver
* mult::        efficient matrix products
* solve::	solve a linear system
* ssi::		subspace iteration for eigenvalues
* svd::		singular value decomposition
* transform::	linear transformation


File: algae.info,  Node: backsub,  Next: chol,  Prev: Linear Algebra,  Up: Linear Algebra

 - Function: backsub ( afac; b )
     The `backsub' function solves the set of linear equations `A*x=b'
     for X.  (Despite the name, it does both forward and backward
     substitution.)  The argument AFAC must contain the factorization
     of `A' returned as a table from either of the functions `factor'
     or `chol'.  The argument B provides the right-hand side.

     This function handles both LAPACK (dense) and SuperLU (sparse)
     factors.  It determines the appropriate solution method based on
     the members in the AFAC table.

     If BCSLIB-EXT (a sparse math library produced by Boeing Computer
     Services) is available on your system and Algae has been compiled
     for it, then the `backsub' function can use it.  If AFAC contains
     factors computed by BCSLIB-EXT routines (in `factor' or `chol'),
     then `backsub' will call the corresponding routines to perform the
     back substitution.

     See also `chol', `factor', and `solve'.


File: algae.info,  Node: chol,  Next: eig,  Prev: backsub,  Up: Linear Algebra

 - Function: chol ( m )
     The `chol' function computes the Cholesky factorization of the
     symmetric, positive definite matrix M.  The factors are returned
     in a table, which may contain a variety of members depending on
     the type and density of M.  For example, if M is a real, dense
     matrix, then `"L"' (the output of the LAPACK routine `DSYTRF'
     routine) and `"RCOND"' are returned.  For now, you'll have to go
     digging in the code if you really want to understand the output.
     The idea, though, is that functions like `backsub' can make sense
     of them so that you don't have to.

     Although its other members vary, the table returned by `chol'
     always contains a member named `"RCOND"'.  This non-negative real
     scalar is an estimate of the reciprocal of the condition number of
     M.  If `"RCOND"' is very small (that is, the condition number is
     very large), then the matrix M is ill-conditioned.  A warning
     message is produced if `"RCOND"' is less than 1.0E-8.

     The key difference between the `chol' and `factor' functions is
     that `chol' requires that the matrix be symmetric and positive
     definite.  In that case, no pivoting is required; this generally
     results in a savings in execution time over the `factor' function.

     Unless the matrix M happens to be diagonal (or BCSLIB-EXT is
     used), `chol' uses a dense method from LAPACK.  Consequently,
     `factor' is preferred over `chol' for large, sparse systems.

     If BCSLIB-EXT (a sparse math library produced by Boeing Computer
     Services) is available on your system and Algae has been compiled
     for it, then `chol' may use its routines to factor sparse matrices.
     In turn, the `backsub' and `solve' functions can use these factors
     to solve linear equations.  It is often useful to compute the
     factors of a matrix and then save them (using `put') for later use.
     Keep in mind, however, that if these factors were computed with the
     BCSLIB-EXT routines, then the Algae version with which you intend
     to use them must also support BCSLIB-EXT.  The table returned by
     `chol' contains the member `HOLD' iff a BCSLIB-EXT routine was
     used to produce it.  BCSLIB-EXT is never used on dense matrices.

     See also `backsub', `factor', and `solve'.


File: algae.info,  Node: eig,  Next: equilibrate,  Prev: chol,  Up: Linear Algebra

 - Function: eig ( a; b; opts )
     The `eig' function computes eigenvalues and eigenvectors for the
     standard and generalized eigenvalue problems
          A * x = lambda * x

     and
          A * x = lambda * B * x

     If A is the only matrix argument, then both LAMBDA and X are
     computed for the standard problem.  If a matrix B is given as the
     second argument, then the generalized problem is solved.

     A table of options OPTS may be given as the last argument.  If it
     contains the member `no_right', then the right eigenvectors X are
     not computed.  If it contains the member `left', then the
     corresponding left eigenvectors are computed.

     This function returns a table containing the eigenvalues in a
     member called `values' and, if appropriate, the (right)
     eigenvectors in a member called `vectors'.  If the `left' option
     was given and the problem is unsymmetric, then the left
     eigenvectors are returned in a member called `left_vectors'.

     The solution method used depends on the type and symmetry of the
     coefficient arrays.  Some of these methods entail strict
     requirements, such as positive definiteness, on the matrices.
     Each case is described below, along with the LAPACK routine called
     to solve it.  See the `LAPACK Users' Guide' for more information.

     For real, symmetric, standard problems, DSYEV is used.  The
     eigenvalues are real and in ascending order; the eigenvectors are
     orthonormal.

     For complex, hermitian, standard problems, ZHEEV is used.  The
     eigenvalues are real and in ascending order; the eigenvectors are
     orthonormal.

     For nonsymmetric, standard problems, DGEEV is used for real type
     and ZGEEV for complex type.  The eigenvalues are complex, and
     complex conjugate pairs appear consecutively with the eigenvalue
     having the positive imaginary part first.  The eigenvectors are
     normalized to have Euclidean norm equal to 1 and largest component
     real.

     For real, symmetric, generalized problems, DSYGV is used.  This
     method requires that A be symmetric and that B be symmetric and
     positive definite.  The eigenvalues are real and in ascending
     order.  The eigenvectors are B-orthonormal.

     For real, nonsymmetric, generalized problems, DGGEV is used.  This
     method performs full balancing on A and B.  The eigenvalues are
     complex, and complex conjugate pairs appear consecutively with the
     eigenvalue having the positive imaginary part first.  Note,
     however, that the eigenvalues are returned in a table; the member
     `num' contains their numerators and member `denom' contains their
     denominators.  The quotients may easily overflow or underflow, and
     the denominator (and maybe the numerator, too) may be zero.  A good
     beginning reference is the book `Matrix Computations' by G. Golub
     and C. Van Loan.  Each eigenvector is scaled so that the sum of the
     absolute values of the real and imaginary parts of the largest
     component is 1, except that for eigenvalues with numerator and
     denominator both zero, the corresponding eigenvector is zero.

     For complex, hermitian, generalized problems, ZHEGV is used.  This
     method requires that A be hermitian and that B be hermitian and
     positive definite.  The eigenvalues are real and in ascending
     order.  The eigenvectors are B-orthonormal.

     For complex, nonsymmetric, generalized problems, ZGGEV is used.
     The eigenvalues and eigenvectors are complex.  Note, however, that
     the eigenvalues are returned in a table; the member `num' contains
     their numerators and member `denom' contains their denominators.
     The quotients may easily overflow or underflow, and the
     denominator (and maybe the numerator, too) may be zero.  A good
     beginning reference is the book `Matrix Computations' by G. Golub
     and C. Van Loan.  Each eigenvector is scaled so that the sum of
     the absolute values of the real and imaginary parts of the largest
     component is 1, except that for eigenvalues with numerator and
     denominator both zero, the corresponding eigenvector is zero.

     See also `iram'.


File: algae.info,  Node: equilibrate,  Next: factor,  Prev: eig,  Up: Linear Algebra

 - Function: equilibrate ( A )
     The `equilibrate' function computes row and column scalings
     intended to equilibrate a matrix and reduce its condition number.
     The input matrix A need not be square, but it must be numeric and
     both dimensions must be nonzero.  If A is hermitian or real
     symmetric, it must be positive definite.

     If `equilibrate' succeeds, it returns a table containing the
     following members:

    R
          A vector containing the row scale factors.

    C
          A vector containing the column scale factors.

    ROWCND
          The (scalar) ratio of the smallest to the largest of the row
          scale factors.

    COLCND
          The (scalar) ratio of the smallest to the largest of the
          column scale factors.

    AMAX
          The (scalar) absolute value of the largest matrix element.

     Even if the matrix A is symmetric or hermitian, the row and column
     scale factors may or may not be identical.  If not, the resulting
     equilibrated matrix would no longer be symmetric or hermitian.
     You will have to decide whether the improvement in matrix
     condition is worth the loss of symmetry.  The row and column scale
     factors will be identical for dense, real, symmetric matrices and
     for dense, complex, hermitian matrices (both of which must also be
     positive definite); otherwise, there's no guarantee.

     Oftentimes, going on to apply the equilibration scale factors is
     not worth the effort.  Roughly speaking, if AMAX is not close to
     overflow or underflow and both ROWCND and COLCND are greater than
     0.1, it probably isn't worth doing.

     If `equilibrate' is unsuccessful, it returns a scalar integer
     instead of a table.  If this value is positive, it indicates the
     row causing the problem.  If it is negative, its absolute value
     indicates the column causing the problem.

     To apply the equilibration, the matrix must be pre- and
     post-multiplied by the scale factors.  If R and C are identical,
     you'll probably want to use the `transform' function to preserve
     symmetry.  Here is an example usage:

          e = equilibrate (A);
          if (equal (e.r; e.c))
          {
            Ae = transform (A; diag (e.r));
          else
            Ae = diag (e.r) * A * diag (e.c);
          }

     Notice, though, that this example does not check the result of
     `equilibrate' to determine if it succeeded, it applies the scale
     factors without checking to see if it's worth it, and it assumes
     that A obeys the requirement regarding positive definiteness.


File: algae.info,  Node: factor,  Next: fft,  Prev: equilibrate,  Up: Linear Algebra

 - Function: factor ( m )
     The `factor' function computes a triangular factorization of the
     matrix M.  The factors are returned in a table, which may contain
     a variety of members depending on the type, density, and
     definition of M.  For example, if M is a real, dense, symmetric
     matrix, then `"LD"' and `"IPIV"' (the output of the LAPACK routine
     `DSYTRF' routine) are returned.  For now, you'll have to go
     digging in the code if you really want to understand the output.
     The idea, though, is that functions like `backsub' can make sense
     of them so that you don't have to.

     For sparse systems, the SuperLU package is used.  These routines
     reorder the columns of the matrix to increase its sparsity, and
     perform dynamic pivoting of the rows for numerical stability.  (No
     advantage is taken of symmetry.)  For the column ordering, the
     Multiple Minimum Degree (MMD) algorithm is used if the matrix is
     symmetric; otherwise, the Column Approximate Minimum Degree
     (COLAMD) algorithm is used.  Currently, there is no provision to
     supply your own ordering.

     Although its other members vary, the table returned by `factor'
     always contains a member named `"RCOND"'.  This non-negative real
     scalar is an estimate of the reciprocal of the condition number of
     M.  If `"RCOND"' is very small (that is, the condition number is
     very large), then the matrix M is ill-conditioned.  A warning
     message is produced if `"RCOND"' is less than 1.0E-8.

     If BCSLIB-EXT (a sparse math library produced by Boeing Computer
     Services) is available on your system and Algae has been compiled
     for it, then `factor' may use its routines to factor sparse
     matrices.  In turn, the `backsub' and `solve' functions can use
     these factors to solve linear equations.  It is often useful to
     compute the factors of a matrix and then save them (using `put')
     for later use.  Keep in mind, however, that if these factors were
     computed with the BCSLIB-EXT routines, then the Algae version with
     which you intend to use them must also support BCSLIB-EXT.  The
     table returned by `factor' contains the member `HOLD' iff a
     BCSLIB-EXT routine was used to produce it.  BCSLIB-EXT is never
     used on dense matrices.

     The key difference between the `chol' and `factor' functions is
     that `chol' requires that the matrix be symmetric and positive
     definite.  In that case, no pivoting is required; this generally
     results in a savings in execution time over the `factor' function.

     See also `backsub', `chol', and `solve'.

