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'.