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: Element, Next: Member, Prev: Call, Up: Operators Element References ------------------ The element reference operation returns specified vector elements or matrix rows and columns. Applied to a table, the operation is performed on each of the table's members. Elements are referenced by following a vector or matrix expression with a bracket-enclosed list of the desired elements. For vector `v', the expression `v[w]' gives the elements specified by `w'. The expression within the brackets is expected to be a scalar or a vector--if it's a matrix, it will be converted into a vector if possible. So, for example, v[3:8] prints the third through eighth elements of `v'. If the vector inside the brackets has a numeric type, then it is converted to integer if necessary (by taking the real part and rounding) and then used to refer to the element numbers. The class of the element reference expression is determined by the class of the specifiers. Once any matrix specifiers are converted to vectors, the dimension of the result is equal to the sum of the dimensions of the specifiers. For example, `M[1;2]' is a scalar, `M[[1];2]' and `M[1;[2]]' are vectors, and `M[[1];[2]]' is a matrix. Notice that the class of the result does not depend on the class of the original entity. If the vector inside the brackets has character type, then it is taken to refer to the element labels instead of the element numbers. For example, if you set `x' as x = 1:3; x.eid = "this", "that", "other"; then `x["that"]' returns 2, the value of the element of `x' having the label `"that"'. If the labels do not have character type, they are temporarily converted to character type for the comparison. Element references work the same way for matrices, except that both rows and columns are specified. For example, M[ 1,3; 7:12 ] specifies rows 1 and 3, columns 7 through 12, of the matrix `M'. The specifiers need not be irredundant. For example, `M[1,1,1;]' returns three copies of the first row of `M'. Besides their use for element references, brackets are also used to form matrices.  File: algae.info, Node: Member, Next: Transpose, Prev: Element, Up: Operators Member References ----------------- Members of an entity are referenced with the "dot" operator. For example, `x.type' returns the value of `x''s member `type'. Notice that, if the right-hand operand is an identifier, then it is taken literally as the name of the desired member. You might have a variable called `type', but that is irrelevant when it comes to evaluating `x.type'. On the other hand, if the right-hand operand is an expression, then its value (converted to a character scalar) is taken as the desired member name. Since you can change an identifier into an expression simply by enclosing it in parentheses, the expression `x.(type)' does use the value of the variable `type' as the name of the member. Member names do not share the same limitations as variable names. In fact, any string of ASCII characters (excluding NUL) will work. This can be pretty useful. For example, you could set up a "vector" of entities (of any class) as in V = {}; V.(1) = A; V.(2) = B; V.(3) = C; V.(4) = D; and then refer to the individual "elements" (that is, the members of `V') by number. You could handle multiple dimensions by referring to element `"3,2,4"', for example.  File: algae.info, Node: Transpose, Next: Power, Prev: Member, Up: Operators Transpose --------- The transpose operator applies the conjugate transpose operation to a matrix. For integer, real, and character types, this means moving every element from row `i' and column `j' to row `j' and column `i'. If the matrix has complex type, the complex conjugate operation is applied as well. If you want the transpose of a complex matrix `M', and not its conjugate transpose, then use the expression `conj(M')'. If transpose is applied to a scalar or vector, the entity is first converted to a matrix and then transposed. For example, `(1,2)'' is the same as `[1;2]'--the vector is first converted into a matrix with one row and then transposed to form a matrix with one column. If this operator is applied to a table, then the operation is performed on each member of that table.  File: algae.info, Node: Power, Next: Not, Prev: Transpose, Up: Operators Power ----- The "power" operator `^' is a binary operator that raises its left operand to the power of its right operand. Thus `2^3' gives 8. It associates right-to-left, so the expressions `x^y^z' and `x^(y^z)' are equivalent. When vectors and matrices are involved, the "power" operator performs in an "element-by-element" sense. For example, if `M' is a matrix, then `M^2' squares each element of `M'. This is definitely not the same thing as `M*M'! In an expression such as `2^M', where the left operand is scalar and the right operand is a vector or matrix, the result has each element `i' of `M' replaced by `2^M[i]'. For example, 2^(0:3) prints the vector `(1,2,4,8)'. Notice that the precedence of `^' is higher than `-', so the expression `-1^2' returns `-1'. In mathematical usage, `0^0' is undefined--it yields an error in Algae. If both left and right operands are arrays, then they must have matching dimensions and labels. If this operator is applied to a table, then the operation is performed on each member of that table.  File: algae.info, Node: Not, Next: Negation, Prev: Power, Up: Operators Not --- The `!' operator is a unary, prefix operator that returns 1 if its operand is considered "false", and 0 otherwise. The "false" operands are: * NULL. * Numeric entities in which every element is zero. * Character entities in which every element is `""'. * Vectors and matrices with no elements. * Tables with no elements. If this operator is applied to a table, then the operation is performed on each member of that table.  File: algae.info, Node: Negation, Next: Multiplication, Prev: Not, Up: Operators Negation -------- The unary negation operator `-' multiplies its numeric argument by `-1'. The `+' operator is for user convenience--Algae ignores it in its unary context. For example, `+-1' gives a negative one. On the other hand, `1+-1' and `1-+1' both return 0. If one of these operators is applied to a table, then that operation is performed on each member of the table.  File: algae.info, Node: Multiplication, Next: Addition, Prev: Negation, Up: Operators Multiplication -------------- Both the `*' and the `@' operators perform multiplication. The difference is that `@' performs in an element-by-element sense, while `*' performs in an inner product sense. The operands of `@' must have matching dimensions and labels; each element of its left operand is multiplied by the corresponding element of the right operand. For example, ( 1, 2, 3 ) @ ( 4, 5, 6 ) returns the vector `(4,10,18)'. When `*' is applied to matrices, the number of columns of the left operand must equal the number of rows of the right operand, and the corresponding labels must match. The result is a matrix that has the same number of rows as the left operand and the same number of columns as the right operand. If one of the operands of `*' is a vector and the other is a matrix, the vector is (conceptually) converted to a matrix before the multiplication is performed. If on the left, it is converted to a matrix with one row; if on the right, it is converted to a matrix with one column. Multiplication of two vectors gives their inner product. The `/' operator performs division. Like `@', it performs in an element-by-element sense. If either operand of any of these operators is a scalar, then the operation is performed in an element-by-element sense. For example 2*(1,2,3) gives `(2,4,6)'--every element of the vector is multiplied by the scalar. The `%' operator performs the modulus operation, producing the remainder when the left operand is divided by the right operand. For example, `(2,2.5,3)%2' returns the vector `(0,0.5,1)'. The result has the same sign as the left operand. If this operator is applied to a table, then the operation is performed on each member of the table.  File: algae.info, Node: Addition, Next: Relation, Prev: Multiplication, Up: Operators Addition -------- The "addition" operators are the binary operators `+' and `-'. If their operands are numeric, then they perform the normal addition and subtraction operations. When the `+' operator is applied to character strings, it catenates them. The `-' operator is not defined for character strings. Between two tables, `+' combines their members in the resulting table. Conceptually, the members of the left operand are inserted in this new table first, followed by the members of the right operand. This means that if the operands have a member with the same name, the value of that member in the resulting table comes from the right operand. For example, if `t' is a table that contains the member "foo", then the result of t + { foo = NULL } is identical to `t' except that its member "foo" has the value NULL. When the `-' operator is applied to tables, the result is a table that has all the members of the left operand except those that are also in the right operand. For example {x;y;z}-{x;y} returns a table that has the single member "z". If just one of the operands is a table, then the operation is performed between the other operand and each member of the table.  File: algae.info, Node: Relation, Next: And, Prev: Addition, Up: Operators Relation -------- The relation operators `<', `>', `<=', `>=', `==', and `!=' return "true" (1) or "false" (0) to reflect the truth of the expression. For example, (1:5) < 3 returns `(1,1,0,0,0)'. If both operands are arrays, then their dimensions and labels must match. Unlike most of the operators, `==' and `!=' allow NULL as an operand. In that case, the other operand is simply checked to see if it is or is not a NULL. If one of these operators is applied to a table, then that operation is performed on each member of the table.  File: algae.info, Node: And, Next: Or, Prev: Relation, Up: Operators And --- The `&' operator performs the logical "and" operation in an element-by-element sense. For example, x = 1:5; x > 2 & x < 4 prints `(0,0,1,0,0)'. If this operator is applied to a table, then the operation is performed on each member of that table.  File: algae.info, Node: Or, Next: Short And, Prev: And, Up: Operators Or -- The `|' operator performs the logical "or" operation in an element-by-element sense. For example, x = 1:5; x < 2 | x > 4 prints `(1,0,0,0,1)'. If this operator is applied to a table, then the operation is performed on each member of that table.  File: algae.info, Node: Short And, Next: Short Or, Prev: Or, Up: Operators Short And --------- The `&&' operator performs the "short-circuit" logical "and" operation. Both operands are evaluated for "truth" as if they were the test of an `if' statement. If the left operand is "false", then the right operand is not evaluated. If both operands are "true", the result of the operation is 1; otherwise the result is 0. Note that this operation is quite different from that of the `&' operator, which works element-by-element. The following example code is from the `solve' function: if (options != NULL && members (options) == "pos") { A = chol (A); else A = factor (A); } The variable `options' is first checked to see if it's NULL. Only if it is not NULL is the `member' function called. That's just what we want, since it would be an error to call `member' with a NULL argument.  File: algae.info, Node: Short Or, Next: Generate, Prev: Short And, Up: Operators Short Or -------- The `||' operator performs the "short-circuit" logical "or" operation. Both operands are evaluated for "truth" as if they were the test of an `if' statement. If the left operand is "true", then the right operand is not evaluated. If either operand is "true", the result of the operation is 1; otherwise the result is 0. Note that this operation is quite different from that of the `|' operator, which works element-by-element. In the statement if (options == NULL || options.tol == NULL) { tol = 1e-6; } the variable `options' is first checked to see if it's NULL. Only if it is not NULL is the member reference `options.tol' evaluated.  File: algae.info, Node: Generate, Next: Append, Prev: Short Or, Up: Operators Generate -------- Numeric vectors may be generated with the `:' operator. An expression like `i:j' generates a vector that starts with the value of `i'. If `j' is greater than `i', each successive element is 1 greater than the previous one, with the last element less than or equal to `j'. If `j' is less than `i', each successive element is 1 less than the previous one, with the last element greater than or equal to `j'. The `:' operator also has a ternary form, as in `i:j:k'. This does the same thing as `i:j' except that successive elements differ by `k' instead of 1. For complex operands, the operation can be described conceptually in the complex plane. A line is drawn between the points `i' and `j'. Then the resulting vector contains the points located on that line segment beginning at `i', proceeding toward `j', spaced a distance `k' (or 1, if `k' is not given) apart.  File: algae.info, Node: Append, Next: Assign, Prev: Generate, Up: Operators Append ------ The `,' operator "appends" its operands. If the operands are vectors, then the result is a new vector containing both the operands. If the operands are matrices, then the result is a new matrix containing the left operand on the left and the right operand on the right. If this operator is applied to a table, then the operation is performed on each member of that table.  File: algae.info, Node: Assign, Prev: Append, Up: Operators Assign ------ The assignment operators are `=', `+=', `-=', `*=', `/=', `@=', and `%='. The `=' operator returns the value of the right operand, setting the left operand to that value in the process. For example, a = b = c = 1; assigns 1 to the variables `a', `b', and `c'. The assignment operators associate right to left, so first `c' is given the value 1. The result of that expression, `c = 1', is 1, so that value is used with `b' as if it read `b = 1'. Notice that a test like if (i = j) ... is entirely different than if (i == j) ... In the first example, `i' is assigned the value of `j' and then that value is tested by the `if' statement. In the second example, the `if' statement tests the equality of `i' and `j'. So if `i' is 1 and `j' is 2, the first example tests true (as well as changing the value of `i') and the second one tests false. Individual elements of an array may be changed; for example x[3;4:6] = 0, 0, 0; sets to 0 the elements of `x' in row 3 and columns 4 through 6. The right operand is converted to the same type as the left operand, if possible, and the dimensions must agree. However, if the right operand is a scalar, then it is filled to the appropriate size. Thus, the previous example could just as well be written x[3;4:6] = 0; One more thing about array assignments: If the variable on the left is a vector, but you specify two dimensions for it, then that variable will be converted into a matrix. Likewise, if the variable on the left is a matrix, but you specify only one dimension, then it will be converted into a vector. For example, in the code A = B = [ 1, 2, 3 ]; A[2] = B[;2] = 9; `A' and `B' both begin as matrices. The second element of each array is then changed to 9. In the end, though, `A' is changed to a vector because only one dimension was given for it. `B' remains as a matrix. The other assignment operators (`+=', `-=', etc.) are simply for convenience. The expression `i+=j' means the same thing as `i=i+j', and `i-=j' means the same thing as `i=i-j'. If the left-hand side is an expression, you should keep in mind that it will be evaluated twice. For example, x[ func() ] += 1 will actually make two calls to the function `func'.  File: algae.info, Node: Expressions, Next: Statements, Prev: Operators, Up: Language Expressions =========== Assignments are made in the normal fashion: `a=5' sets the variable `a' to contain the scalar 5. Variables are not declared prior to use, but rather take on the structure and type of whatever is assigned to them. You could, for example, enter a=1; a=[a,a]; in which case the variable `a' is first a scalar and then a matrix. A list of the previously defined variables (except functions) is given by the `who()' function, and a variable can be deleted by assigning NULL to it. In addition to simple variables, elements and members can also be specified on the left hand side of an assignment. For example, the statement A[ 1:4; 1:4 ] = 3; assigns 3 to all of the elements of the first 4-by-4 partition of matrix `A', leaving the other elements of `A' unchanged. Values can be assigned to members in the same way. For example, the statements A = [ 1,2,3; 4,5,6 ]; time = [ 1.1, 2.2, 3.3 ]; A.rid = [ "first"; "second" ] A.cid = time assign the row and column labels of `A'.  File: algae.info, Node: Statements, Next: Functions, Prev: Expressions, Up: Language Statements ========== Statements are terminated by a question mark, a semicolon, or a newline. Using a question mark or newline causes the value of the statement to be printed; with a semicolon the printing is suppressed. A newline terminates a statement only if it does not occur within parentheses, brackets, or braces. Statement termination is implied by the closing brace of an "if", "for", or "while" statement or "function" expression. Printing is enabled when the terminator is implied. For example, for (i in 1:10) { i } prints all of the integers from 1 to 10. When real or complex numbers are printed, Algae prints 4 significant digits by default. This can be changed with the `digits' function, or just by setting the global variable `$digits'. Comments are introduced with the `#' character. That character and any that follow it on the same line are ignored (excluding the newline).  File: algae.info, Node: Functions, Prev: Statements, Up: Language Functions ========= Functions are defined by a function expression, which consists of the keyword "function", followed by a parenthesized list of arguments, followed by a set of statements enclosed by braces. For example, Algae's `max' function is defined by something like max = function (x) { return x[imax(x)]; }; Functions are just another class of entity; the statement above defines a function and then assigns it to the variable `max'. The arguments are variables that are local to the function. On entry, they take on the values of the formal arguments in the calling expression. Passing more arguments than are in the function's definition is an error. If fewer arguments are passed, then NULL's are passed in place of the missing arguments. The function reference needn't be an identifier--a function expression works just fine. For example, child = (his_functions + her_functions).reproduce(); would combine the tables `his_functions' and `her_functions', reference the member `reproduce', call it with no arguments, and then assign the result to `child'. Notice that, since `.' and `()' have the same precedence, their left-to-right associativity causes the member reference to occur first and then the function call. In an expression like `sin(1).type', the function call is performed first. When a function is compiled, information is included that relates its operations to the file name and line numbers of the source code. If an error occurs, this information is useful in tracking down its cause. In some cases, this information is undesirable and may be removed with the `strip' function. The `message' function is such a case.  File: algae.info, Node: Data, Next: Standard Functions, Prev: Language, Up: Top Data **** Entities are the basic objects (constants and variables) in Algae. They contain members and elements. Members contain information about the entity, such as the number of rows in a matrix. An entity's elements, if it has any, contain the data such as the value of a scalar. There are five classes: `scalar' The `scalar' data structure contains a single element, its value, which may have any of the data types described above. Its members are: `class' The string `"scalar"'. `type' The type (like `"integer"' or `"real"'). Notice that a scalar is not the same as a one-element vector or matrix. `vector' The `vector' entity contains a one-dimensional array of elements. Its members are: `class' The string `"vector"'. `type' The type (like `"integer"' or `"real"'). `density' Either `"dense"' or `"sparse"'. `ne' The number of elements. `nn' The number of non-zero elements. `eid' The element labels. The element labels of a vector are themselves a vector. `matrix' The `matrix' data structure contains two-dimensional arrays of elements. It contains zero or more rows and columns. The members of a matrix are: `class' The string `"matrix"'. `type' The type (like `"integer"' or `"real"'). `symmetry' One of `"general"', `"symmetric"', or `"hermitian"'. `density' One of `"dense"', `"sparse"' or `"sparse_upper"'. `nr' The number of rows. `nc' The number of columns. `nn' The number of nonzero elements. For matrices with "sparse_upper" density, this number does not include the elements on the diagonal, all of which are stored. Sorry. `rid' The row labels. `cid' The column labels. The row and column labels of a matrix are vectors. The row label vector has the same number of elements as its matrix has rows, and likewise for the column label. `table' The `table' object is like a bucket that can contain any number of other objects. Several functions return tables. For example, the `eig' function returns a table that contains the matrices `values' and `vectors'. The entities contained in a table are members of it, so they can be extracted using the `.' operator. Thus `eig(A).values' returns the eigenvalues of `A'. `function' Functions are entities just like scalars and matrices, and can be operated on in the same manner. Functions have two members: `class', which is `"function"', and `ilk', which is either `"user"' or `"builtin"'. The `scalar', `vector', and `matrix' classes are known collectively as "arrays". These are the only classes that contain elements, and all have the member `type' that specifies the data type. There are four types: `integer' On most machines this is a 32-bit integer, like 42 or -273. `real' This is a floating point number like 3.1415. It is stored in 64 bits on most machines. `complex' This is a complex number having both real and imaginary parts. `character' This is a character string like `"Hello"'. Scalar constants are specified in a manner similar to that used in other programming languages. Numeric constants can be given in decimal form, such as `32' or `32.0', or in scientific notation, such as `3.2E1'. In the latter notation, the letters `e' and `E' may be used interchangeably to prefix the exponent. White space (space, tab, etc.) is significant in that context, of course, so that `1.2e+3' (1200.0) is definitely not the same as `1.2e +3' (4.2). A `character' constant is a sequence of one or more characters surrounded by matching double-quotes. Within the quotes, the backslash character may be used to introduce "escape sequences" for unusual characters like . For example, the string `"\""' is a string containing a single character (the right double-quote). The following escape sequences may be used: `\a' bell `\b' backspace `\e' escape `\f' formfeed `\n' newline `\r' carriage return `\t' tab `\v' vertical tab `\ooo' octal number `\xhh' hexadecimal number The escape sequence `\ooo' consists of a backslash followed by one, two, or three octal digits, which are taken to specify the value of the desired character. For example, `\33' is the ASCII "escape" character (which is also given by `\e'). Likewise, the sequence `\xhh' consists of a backslash followed by `x', followed by one or two hexadecimal digits, which specify the value of the desired character. For example, `\x1b' also specifies the ASCII "escape" character. If the character following the backslash is not one of those specified above, then that character is taken literally. For example, `\"' specifies the double-quote character--not the end of the character constant. Matrices may be generated by specifying their elements within brackets. Commas separate elements within rows and semicolons separate the rows. Thus `[1,2;3,4]' specifies the matrix [ 1 2 ] [ 3 4 ] A vector may be generated by using either of the forms `i:j' or `i:j:k'. It is obtained by starting with the value `i' and incrementing by `k' (or 1 if the first form is used) while remaining between `i' and `j', inclusive. (Notice that this is not the same format used by MATLAB.) For example, `[1:8:2]' is the same as `[1,3,5,7]'. All elements within a matrix have the same type (`integer', `real', etc.); conversion will be performed automatically if possible. The terms within the brackets may be constants, variables, or expressions. For example, `[1+2,3]' is the same as `[3,3]'. Matrices may be involved, as long as their dimensions are appropriate. For example, if the variable `A' is defined to be equal to the square matrix `[1,2;3,4]', then a new column could be appended to it with the expression `[A,[5;6]]' to yield [ 1 2 5 ] [ 3 4 6 ] Matrices may be partitioned by specifying the desired row and column numbers within brackets. For example, if `A' is a previously defined matrix then `A[1;1]' specifies a scalar having the value of the element in the first row and the first column of `A'. The semicolon within the parentheses separates the row specifiers from the column specifiers. Members of data structures are referred to by using the member operator `.'. For example, the number of rows in a matrix is stored in the member `nr', so `A.nr' returns the number of rows in the matrix `A'. The member operator associates left to right, so that `A.type.type' returns the string `"character"'.  File: algae.info, Node: Standard Functions, Next: Running Algae, Prev: Data, Up: Top The Standard Functions ********************** Functions are called by giving their name followed by a parenthesized list of their arguments. For example, `sqrt(a)' computes the square root of its argument `a'. The parentheses are required, whether they contain any arguments or not. Functions may take more than one number and kind of argument. * Menu: * Basic Math:: abs, sin, sqrt, ... * Arrays:: fill, sparse, zero, ... * Sets:: union, intersection, ... * Linear Algebra:: solve, factor, fft, ... * Numerical Analysis:: ode4, brent, ... * Basic I/O:: read, printf, ... * Entity I/O:: get, put, ... * Execution:: source, system, ... * Special Tools:: plot, npsol, ... * Miscellaneous:: who, what, time, ...  File: algae.info, Node: Basic Math, Next: Arrays, Prev: Standard Functions, Up: Standard Functions Basic Math ========== * Menu: * abs:: absolute value * acos:: arc cosine * acosh:: arc cosine hyperbolic * arg:: argument (phase) * asin:: arc sine * asinh:: arc sine hyperbolic * atan:: arc tangent * atanh:: arc tangent hyperbolic * atan2:: arc tangent (y/x) * ceil:: ceiling * conj:: complex conjugate * cos:: cosine * cosh:: hyperbolic cosine * erf:: error function * erfc:: complementary error function * exp:: exponential * floor:: floor * gcd:: greatest common divisor * imag:: imaginary part * integer:: round to nearest integer * lcm:: least common multiple * log:: natural logarithm * log10:: base-10 logarithm * primef:: prime factors * primes:: prime numbers * real:: real part * round:: round to nearest whole number * sin:: sine * sinh:: hyperbolic sine * sqrt:: square root * tan:: tangent * tanh:: hyperbolic tangent  File: algae.info, Node: abs, Next: acos, Prev: Basic Math, Up: Basic Math - Function: abs ( x ) The `abs' function returns the absolute value of its numeric argument. "Absolute value" is synonymous with "magnitude" for complex types. If X is non-scalar, every element is replaced by its absolute value. `x' must be a numeric scalar, vector, or matrix.  File: algae.info, Node: acos, Next: acosh, Prev: abs, Up: Basic Math - Function: acos ( x ) The `acos' function returns the arc cosine of its numeric argument. If it's argument is complex or has a magnitude greater than one, then the result is complex. Otherwise, the result is real. If X is non-scalar, every element is replaced by its arc cosine. The argument X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: acosh, Next: arg, Prev: acos, Up: Basic Math - Function: acosh ( x ) The `acosh' function returns the hyperbolic arc cosine of its numeric argument. If it's argument is complex or is less than 1.0, then the result is complex. Otherwise, the result is real. If X is non-scalar, every element is replaced by its hyperbolic arc cosine. The argument X must be a numeric scalar, vector, or matrix. Note that `acosh(0)' is not zero, so if `acosh' is applied to a sparse vector or matrix, then a dense array is the result.  File: algae.info, Node: arg, Next: asin, Prev: acosh, Up: Basic Math - Function: arg ( z ) The `arg' function returns the argument (phase angle) of its numeric argument. See also `abs'.  File: algae.info, Node: asin, Next: asinh, Prev: arg, Up: Basic Math - Function: asin ( x ) The `asin' function returns the arc sine of its numeric argument. If it's argument is complex or has a magnitude greater than one, then the result is complex. Otherwise, the result is real. If X is non-scalar, every element is replaced by its arc sine. The argument X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: asinh, Next: atan, Prev: asin, Up: Basic Math - Function: asinh ( x ) The `asinh' function returns the hyperbolic arc sine of its numeric argument. If X is non-scalar, every element is replaced by its hyperbolic arc sine. The argument X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: atan, Next: atanh, Prev: asinh, Up: Basic Math - Function: atan ( x ) The `atan' function returns the arc tangent of its numeric argument. If it's argument is complex, then the result is complex. Otherwise, the result is real. If X is non-scalar, every element is replaced by its arc tangent. The argument X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: atanh, Next: atan2, Prev: atan, Up: Basic Math - Function: atanh ( x ) The `atanh' function returns the hyperbolic arc tangent of its numeric argument. If it's argument is complex or has magnitude greater than 1.0, then the result is complex. Otherwise, the result is real. If X is non-scalar, every element is replaced by its hyperbolic arc tangent. The argument X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: atan2, Next: ceil, Prev: atanh, Up: Basic Math - Function: atan2 ( y; x ) The `atan2' function computes an angle corresponding to Y and X, the lengths of the opposite and adjacent sides. This is similar to `atan(y/x)', but with these differences: * The signs of Y and X are used to determine the quadrant in which the angle lies. The angle returned is in the range -pi to pi. * The argument X may be zero, as long as Y is nonzero. This is different than `atan(y/x)', because it avoids division by zero. * Complex type for either argument is not allowed. The arguments must be scalars, vectors, or matrices, with either integer or real type.  File: algae.info, Node: ceil, Next: conj, Prev: atan2, Up: Basic Math - Function: ceil ( x ) The `ceil' function returns the ceiling of its numeric argument. The ceiling of X is the smallest integer that is not less than X. If X is complex, the ceiling is applied to both real and imaginary parts. If X is non-scalar, every element is replaced by its ceiling. The type of X is not changed by `ceil'. X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: conj, Next: cos, Prev: ceil, Up: Basic Math - Function: conj ( x ) The `conj' function returns the complex conjugate of its numeric argument. If X is non-scalar, every element is replaced by its complex conjugate. X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: cos, Next: cosh, Prev: conj, Up: Basic Math - Function: cos ( x ) The `cos' function returns the cosine of its numeric argument. If X is non-scalar, every element is replaced by its cosine. X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: cosh, Next: erf, Prev: cos, Up: Basic Math - Function: cosh ( x ) The `cosh' function returns the hyperbolic cosine of its numeric argument. If X is non-scalar, every element is replaced by its hyperbolic cosine. X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: erf, Next: erfc, Prev: cosh, Up: Basic Math - Function: erf ( x ) The `erf' function returns the error function of its numeric argument. If X is non-scalar, every element is replaced by its error function result. The error function is defined as `2/sqrt(pi)' times the integral from 0 to X of `exp(-t^2) dt'. Among its useful properties, the error function is twice the integral of the Gaussian distribution with 0 mean and variance of 1/2. Complex arguments are not yet implemented.  File: algae.info, Node: erfc, Next: exp, Prev: erf, Up: Basic Math - Function: erfc ( x ) The `erfc' function returns the complementary error function of its numeric argument. If X is non-scalar, every element is replaced by its complementary error function result. The complementary error function `erfc(x)' is simply `1-erf(c)', but it is computed in a way that avoids round-off errors when X is large. Complex arguments are not yet implemented.  File: algae.info, Node: exp, Next: floor, Prev: erfc, Up: Basic Math - Function: exp ( x ) The `exp' function returns the exponential of its numeric argument. If X is non-scalar, every element is replaced by its exponential. X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: floor, Next: gcd, Prev: exp, Up: Basic Math - Function: floor ( x ) The `floor' function returns the floor of its numeric argument. The floor of X is the largest integer that is not greater than X. If X is complex, the floor is applied to both real and imaginary parts. If X is non-scalar, every element is replaced by its floor. The type of X is not changed by `floor'. X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: gcd, Next: imag, Prev: floor, Up: Basic Math - Function: gcd ( x ) This function computes the greatest common divisor (GCD) of the elements of its vector argument. The input is rounded to integer type. The scalar return value is the GCD. Its member "factors" contains an integer vector such that `gcd(x).factors*x' is equal to `gcd(x)'. See also `lcm' and `primef'.  File: algae.info, Node: imag, Next: integer, Prev: gcd, Up: Basic Math - Function: imag ( x ) The `imag' function returns the imaginary part of its numeric argument. If X is non-scalar, every element is replaced by its imaginary part. The value returned by `imag' has real type. See also `real'.  File: algae.info, Node: integer, Next: lcm, Prev: imag, Up: Basic Math - Function: integer ( x ) The `integer' function converts the real part of its numeric argument to integer type, rounding it if necessary. See also `round'.  File: algae.info, Node: lcm, Next: log, Prev: integer, Up: Basic Math - Function: lcm ( x ) This function computes the least common multiple (LCM) of the elements of its vector argument. The input is rounded to integer type. The scalar return value is the LCM. See also `gcd' and `primef'.  File: algae.info, Node: log, Next: log10, Prev: lcm, Up: Basic Math - Function: log ( x ) The `log' function returns the natural logarithm of its numeric argument. If X is non-scalar, every element is replaced by its logarithm. X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: log10, Next: primef, Prev: log, Up: Basic Math - Function: log10 ( x ) The `log10' function returns the base-10 logarithm of its numeric argument. If X is non-scalar, every element is replaced by its base-10 logarithm. X must be a numeric scalar, vector, or matrix.  File: algae.info, Node: primef, Next: primes, Prev: log10, Up: Basic Math - Function: primef ( n ) This function computes the prime factors of its scalar argument, returning them as elements of an integer vector. The argument N is rounded to integer, if necessary. If the argument is less than 2, a zero length vector is returned. See also `gcd', `lcm', and `primes'.  File: algae.info, Node: primes, Next: real, Prev: primef, Up: Basic Math - Function: primes ( n ) This function generates a vector of prime numbers that are less than or equal to the scalar argument. The argument N is rounded to an integer, if necessary. If the argument is less than 2, a zero length vector is returned. See also `gcd', `lcm', and `primes'.  File: algae.info, Node: real, Next: round, Prev: primes, Up: Basic Math - Function: real ( x ) This function returns the real part of X. The value returned by `real' has real type. See also `imag'.  File: algae.info, Node: round, Next: sin, Prev: real, Up: Basic Math - Function: round ( x ) The `round' function rounds its numeric argument to the nearest whole number. If X is complex, both real and imaginary parts are rounded. If X is non-scalar, every element is rounded. The type of X is not changed by `round'. If Algae has been compiled to use the system's rint(3m) function, then arguments with a fractional part of exactly 1/2 are rounded to the nearest even whole number. Otherwise, such arguments are rounded towards +infinity. See also `integer'.  File: algae.info, Node: sin, Next: sinh, Prev: round, Up: Basic Math - Function: sin ( x ) The `sin' function returns the sine of its numeric argument. If X is non-scalar, every element is replaced by its sine.  File: algae.info, Node: sinh, Next: sqrt, Prev: sin, Up: Basic Math - Function: sinh ( x ) The `sinh' function returns the hyperbolic sine of its numeric argument. If X is non-scalar, every element is replaced by its hyperbolic sine.  File: algae.info, Node: sqrt, Next: tan, Prev: sinh, Up: Basic Math - Function: sqrt ( x ) The `sqrt' function returns the square root of its numeric argument. If X is complex or negative, then the result is complex. Otherwise, the result is real. If X is non-scalar, every element is replaced by its square root.  File: algae.info, Node: tan, Next: tanh, Prev: sqrt, Up: Basic Math - Function: tan ( x ) The `tan' function returns the tangent of its numeric argument. If X is non-scalar, every element is replaced by its tangent.  File: algae.info, Node: tanh, Prev: tan, Up: Basic Math - Function: tanh ( x ) The `tanh' function returns the hyperbolic tangent of its numeric argument. If X is non-scalar, every element is replaced by its hyperbolic tangent.  File: algae.info, Node: Arrays, Next: Sets, Prev: Basic Math, Up: Standard Functions Arrays ====== * Menu: * band:: bandwidth reduction * bdiag:: block diagonal * btrans:: block transpose * circshift:: circular shift of array * combine:: union, but in original order * cram:: form an array, possibly sparse * dense:: dense storage * diag:: matrix diagonal * dice:: individual characters of a string * diff:: difference between elements * exsparse:: disassemble a sparse matrix * fill:: fill an array * find:: find elements in a vector * first:: first "true" element in a vector * form:: form an array * full:: full storage * gpskca:: profile or bandwidth reduction * grep:: search using regular expression * hermitian:: hermitian part of a matrix * ident:: identity matrix * imax:: find maximum element * imin:: find minimum element * isort:: sorted index * label:: add labels * last:: last "true" element in a vector * linspace:: uniformly spaced vector * logspace:: logarithmically spaced vector * lose:: lose elements in a vector * magic:: magic squares * matrix:: convert to a matrix * max:: maximum value * merge:: merge arrays * min:: minimum value * mksparse:: sparse matrix from coordinate data * norm:: vector and matrix norms * pick:: pick non-zero elements * product:: product of array elements * rand:: uniform random numbers * randn:: normal random numbers * reverse:: reverse elements of a vector * scalar:: convert to scalar * select:: select an element at random * seq:: integer sequence * shape:: array dimensions * sign:: signum function * sort:: sort a vector * sparse:: sparse storage * srand:: seed random numbers * sum:: sum elements * surprise:: random arrays with given properties * symmetric:: symmetric part of a matrix * tril:: lower triangle * triu:: upper triangle * unlabel:: remove labels * vector:: convert to a vector * zero:: make a zero array  File: algae.info, Node: band, Next: bdiag, Prev: Arrays, Up: Arrays - Function: band ( m ) The `band' function computes the upper and lower bandwidths and profiles of the square matrix M. The row bandwidth of a particular row is the number of elements to the left of the diagonal in that row, but not including any consecutive zero elements at the beginning of that row. Likewise, the column bandwidth of a particular column is the number of elements above the diagonal in that column, but not including any consecutive zero elements at the beginning of that column. Notice that, for a diagonal matrix, all row and column bandwidths are zero. The lower bandwidth is the largest of all the row bandwidths, and the upper bandwidth is the largest of all the column bandwidths. The lower profile is the sum of all the row bandwidths, and the upper profile is the sum of all the column bandwidths. This function returns a real vector with four elements. In order, these elements are as follows: lower bandwidth, lower profile, upper bandwidth, and upper profile. Profile reduction can be very effective in reducing the time and memory required to factor a matrix. The function `gpskca' provides one approach for doing this. See also `gpskca'.  File: algae.info, Node: bdiag, Next: btrans, Prev: band, Up: Arrays - Function: bdiag ( x; m; n ) The `bdiag' function mimics the `diag' function, but in a "block" sense. The matrix X is taken to be comprised of M rows and N columns of blocks that are themselves matrices. If either M or N is 0, then the matrix returned has the blocks of X on its diagonal and is elsewhere zero. Otherwise, the blocks of the diagonal of X are appended together. An example of the former case is: > M = magic (4) [ 9 7 6 12 ] [ 4 14 15 1 ] [ 16 2 3 13 ] [ 5 11 10 8 ] > bdiag (M; 0; 2) [ 9 7 . . ] [ 4 14 . . ] [ 16 2 . . ] [ 5 11 . . ] [ . . 6 12 ] [ . . 15 1 ] [ . . 3 13 ] [ . . 10 8 ] An example of the latter case is: > bdiag ( M; 2; 2 ) [ 9 7 3 13 ] [ 4 14 10 8 ] X must be scalar, vector, or matrix. After being converted to a matrix, if necessary, the number of rows of X must be evenly divisible by M (unless M is 0) and the number of columns of X must be evenly divisible by N (unless N is 0). See also `btrans' and `diag'.  File: algae.info, Node: btrans, Next: circshift, Prev: bdiag, Up: Arrays - Function: btrans ( x; m; n ) The `btrans' function mimics the transpose operator, but in a "block" sense. The matrix X is taken to be comprised of M rows and N columns of blocks that are themselves matrices. The blocks themselves are not transposed, but are simply moved across the diagonal. For example: > M = magic (4) [ 9 7 6 12 ] [ 4 14 15 1 ] [ 16 2 3 13 ] [ 5 11 10 8 ] > btrans (M; 2; 2) [ 9 7 16 2 ] [ 4 14 5 11 ] [ 6 12 3 13 ] [ 15 1 10 8 ] X must be scalar, vector, or matrix. After being converted to a matrix, if necessary, the number of rows of X must be evenly divisible by M and the number of columns of X must be evenly divisible by N. See also `bdiag'.  File: algae.info, Node: circshift, Next: combine, Prev: btrans, Up: Arrays - Function: circshift ( x; s ) The `circshift' function shifts the elements of the array X. The arg S is a vector--each of its elements specifies the shift distance for the corresponding dimension of X. A positive shift is down or right; a negative shift is up or left. If unspecified, the shift distance is zero (meaning no shift). If X is a table, the function is applied to each of its members. For example: > x = fill (3,3; 1:9) [ 1 2 3 ] [ 4 5 6 ] [ 7 8 9 ] > circshift (x; 1) [ 7 8 9 ] [ 1 2 3 ] [ 4 5 6 ] > circshift (x; 0,1) [ 3 1 2 ] [ 6 4 5 ] [ 9 7 8 ] > circshift (x; 1,1) [ 9 7 8 ] [ 3 1 2 ] [ 6 4 5 ]  File: algae.info, Node: combine, Next: cram, Prev: circshift, Up: Arrays - Function: combine ( u; v ) The `combine' function appends the vectors U and V, removing all but the first of any redundant elements. This is exactly like the `union' function, except that the result is not sorted.