Go to the previous, next section.

Vector/Matrix Functions

Many of the commands described here begin with the v prefix. (For convenience, the shift-V prefix is equivalent to v.) The commands usually apply to both plain vectors and matrices; some apply only to matrices or only to square matrices. If the argument has the wrong dimensions the operation is left in symbolic form.

Vectors are entered and displayed using `[a,b,c]' notation. Matrices are vectors of which all elements are vectors of equal length. (Though none of the standard Calc commands use this concept, a three-dimensional matrix or rank-3 tensor could be defined as a vector of matrices, and so on.)

Packing and Unpacking

Calc's "pack" and "unpack" commands collect stack entries to build composite objects such as vectors and complex numbers. They are described in this chapter because they are most often used to build vectors.

The v p (calc-pack) [pack] command collects several elements from the stack into a matrix, complex number, HMS form, error form, etc. It uses a numeric prefix argument to specify the kind of object to be built; this argument is referred to as the "packing mode." If the packing mode is a nonnegative integer, a vector of that length is created. For example, C-u 5 v p will pop the top five stack elements and push back a single vector of those five elements. (C-u 0 v p simply creates an empty vector.)

The same effect can be had by pressing [ to push an incomplete vector on the stack, using TAB (calc-roll-down) to sneak the incomplete object up past a certain number of elements, and then pressing ] to complete the vector.

Negative packing modes create other kinds of composite objects:

Two values are collected to build a complex number. For example, 5 RET 7 C-u -1 v p creates the complex number (5, 7). The result is always a rectangular complex number. The two input values must both be real numbers, i.e., integers, fractions, or floats. If they are not, Calc will instead build a formula like `a + (0, 1) b'. (The other packing modes also create a symbolic answer if the components are not suitable.)

Two values are collected to build a polar complex number. The first is the magnitude; the second is the phase expressed in either degrees or radians according to the current angular mode.

Three values are collected into an HMS form. The first two values (hours and minutes) must be integers or integer-valued floats. The third value may be any real number.

Two values are collected into an error form. The inputs may be real numbers or formulas.

Two values are collected into a modulo form. The inputs must be real numbers.

Two values are collected into the interval `[a .. b]'. The inputs may be real numbers, HMS or date forms, or formulas.

Two values are collected into the interval `[a .. b)'.

Two values are collected into the interval `(a .. b]'.

Two values are collected into the interval `(a .. b)'.

Two integer values are collected into a fraction.

Two values are collected into a floating-point number. The first is the mantissa; the second, which must be an integer, is the exponent. The result is the mantissa times ten to the power of the exponent.

This is treated the same as -11 by the v p command. When unpacking, -12 specifies that a floating-point mantissa is desired.

A real number is converted into a date form.

Three numbers (year, month, day) are packed into a pure date form.

Six numbers are packed into a date/time form.

With any of the two-input negative packing modes, either or both of the inputs may be vectors. If both are vectors of the same length, the result is another vector made by packing corresponding elements of the input vectors. If one input is a vector and the other is a plain number, the number is packed along with each vector element to produce a new vector. For example, C-u -4 v p could be used to convert a vector of numbers and a vector of errors into a single vector of error forms; C-u -5 v p could convert a vector of numbers and a single number M into a vector of numbers modulo M.

If you don't give a prefix argument to v p, it takes the packing mode from the top of the stack. The elements to be packed then begin at stack level 2. Thus 1 RET 2 RET 4 n v p is another way to enter the error form `1 +/- 2'.

If the packing mode taken from the stack is a vector, the result is a matrix with the dimensions specified by the elements of the vector, which must each be integers. For example, if the packing mode is `[2, 3]', then six numbers will be taken from the stack and returned in the form `[[a, b, c], [d, e, f]]'.

If any elements of the vector are negative, other kinds of packing are done at that level as described above. For example, `[2, 3, -4]' takes 12 objects and creates a 2x3 matrix of error forms: `[[a +/- b, c +/- d ... ]]'. Also, `[-4, -10]' will convert four integers into an error form consisting of two fractions: `a:b +/- c:d'.

There is an equivalent algebraic function, `pack(mode, items)' where mode is a packing mode (an integer or a vector of integers) and items is a vector of objects to be packed (re-packed, really) according to that mode. For example, `pack([3, -4], [a,b,c,d,e,f])' yields `[a +/- b, c +/- d, e +/- f]'. The function is left in symbolic form if the packing mode is illegal, or if the number of data items does not match the number of items required by the mode.

The v u (calc-unpack) command takes the vector, complex number, HMS form, or other composite object on the top of the stack and "unpacks" it, pushing each of its elements onto the stack as separate objects. Thus, it is the "inverse" of v p. If the value at the top of the stack is a formula, v u unpacks it by pushing each of the arguments of the top-level operator onto the stack.

You can optionally give a numeric prefix argument to v u to specify an explicit (un)packing mode. If the packing mode is negative and the input is actually a vector or matrix, the result will be two or more similar vectors or matrices of the elements. For example, given the vector `[a +/- b, c^2, d +/- 7]', the result of C-u -4 v u will be the two vectors `[a, c^2, d]' and `[b, 0, 7]'.

Note that the prefix argument can have an effect even when the input is not a vector. For example, if the input is the number -5, then c-u -1 v u yields -5 and 0 (the components of -5 when viewed as a rectangular complex number); C-u -2 v u yields 5 and 180 (assuming degrees mode); and C-u -10 v u yields -5 and 1 (the numerator and denominator of -5, viewed as a rational number). Plain v u with this input would complain that the input is not a composite object.

Unpacking mode -11 converts a float into an integer mantissa and an integer exponent, where the mantissa is not divisible by 10 (except that 0.0 is represented by a mantissa and exponent of 0). Unpacking mode -12 converts a float into a floating-point mantissa and integer exponent, where the mantissa (for non-zero numbers) is guaranteed to lie in the range [1 .. 10). In both cases, the mantissa is shifted left or right (and the exponent adjusted to compensate) in order to satisfy these constraints.

Positive unpacking modes are treated differently than for v p. A mode of 1 is much like plain v u with no prefix argument, except that in addition to the components of the input object, a suitable packing mode to re-pack the object is also pushed. Thus, C-u 1 v u followed by v p will re-build the original object.

A mode of 2 unpacks two levels of the object; the resulting re-packing mode will be a vector of length 2. This might be used to unpack a matrix, say, or a vector of error forms. Higher unpacking modes unpack the input even more deeply.

There are two algebraic functions analogous to v u. The `unpack(mode, item)' function unpacks the item using the given mode, returning the result as a vector of components. Here the mode must be an integer, not a vector. For example, `unpack(-4, a +/- b)' returns `[a, b]', as does `unpack(1, a +/- b)'.

The unpackt function is like unpack but instead of returning a simple vector of items, it returns a vector of two things: The mode, and the vector of items. For example, `unpackt(1, 2:3 +/- 1:4)' returns `[-4, [2:3, 1:4]]', and `unpackt(2, 2:3 +/- 1:4)' returns `[[-4, -10], [2, 3, 1, 4]]'. The identity for re-building the original object is `apply(pack, unpackt(n, x)) = x'. (The apply function builds a function call given the function name and a vector of arguments.)

Subscript notation is a useful way to extract a particular part of an object. For example, to get the numerator of a rational number, you can use `unpack(-10, x)_1'.

Building Vectors

Vectors and matrices can be added, subtracted, multiplied, and divided; see section Basic Arithmetic.

The | (calc-concat) command "concatenates" two vectors into one. For example, after [ 1 , 2 ] [ 3 , 4 ] |, the stack will contain the single vector `[1, 2, 3, 4]'. If the arguments are matrices, the rows of the first matrix are concatenated with the rows of the second. (In other words, two matrices are just two vectors of row-vectors as far as | is concerned.)

If either argument to | is a scalar (a non-vector), it is treated like a one-element vector for purposes of concatenation: 1 [ 2 , 3 ] | produces the vector `[1, 2, 3]'. Likewise, if one argument is a matrix and the other is a plain vector, the vector is treated as a one-row matrix.

The H | (calc-append) [append] command concatenates two vectors without any special cases. Both inputs must be vectors. Whether or not they are matrices is not taken into account. If either argument is a scalar, the append function is left in symbolic form. See also cons and rcons below.

The I | and H I | commands are similar, but they use their two stack arguments in the opposite order. Thus I | is equivalent to TAB |, but possibly more convenient and also a bit faster.

The v d (calc-diag) [diag] function builds a diagonal square matrix. The optional numeric prefix gives the number of rows and columns in the matrix. If the value at the top of the stack is a vector, the elements of the vector are used as the diagonal elements; the prefix, if specified, must match the size of the vector. If the value on the stack is a scalar, it is used for each element on the diagonal, and the prefix argument is required.

To build a constant square matrix, e.g., a @c{$3\times3$} 3x3 matrix filled with ones, use 0 M-3 v d 1 +, i.e., build a zero matrix first and then add a constant value to that matrix. (Another alternative would be to use v b and v a; see below.)

The v i (calc-ident) [idn] function builds an identity matrix of the specified size. It is a convenient form of v d where the diagonal element is always one. If no prefix argument is given, this command prompts for one.

In algebraic notation, `idn(a,n)' acts much like `diag(a,n)', except that a is required to be a scalar (non-vector) quantity. If n is omitted, `idn(a)' represents a times an identity matrix of unknown size. Calc can operate algebraically on such generic identity matrices, and if one is combined with a matrix whose size is known, it is converted automatically to an identity matrix of a suitable matching size. The v i command with an argument of zero creates a generic identity matrix, `idn(1)'. Note that in dimensioned matrix mode (see section Matrix and Scalar Modes), generic identity matrices are immediately expanded to the current default dimensions.

The v x (calc-index) [index] function builds a vector of consecutive integers from 1 to n, where n is the numeric prefix argument. If you do not provide a prefix argument, you will be prompted to enter a suitable number. If n is negative, the result is a vector of negative integers from n to -1.

With a prefix argument of just C-u, the v x command takes three values from the stack: n, start, and incr (with incr at top-of-stack). Counting starts at start and increases by incr for successive vector elements. If start or n is in floating-point format, the resulting vector elements will also be floats. Note that start and incr may in fact be any kind of numbers or formulas.

When start and incr are specified, a negative n has a different interpretation: It causes a geometric instead of arithmetic sequence to be generated. For example, `index(-3, a, b)' produces `[a, a b, a b^2]'. If you omit incr in the algebraic form, `index(n, start)', the default value for incr is one for positive n or two for negative n.

The v b (calc-build-vector) [cvec] function builds a vector of n copies of the value on the top of the stack, where n is the numeric prefix argument. In algebraic formulas, `cvec(x,n,m)' can also be used to build an n-by-m matrix of copies of x. (Interactively, just use v b twice: once to build a row, then again to build a matrix of copies of that row.)

The v h (calc-head) [head] function returns the first element of a vector. The I v h (calc-tail) [tail] function returns the vector with its first element removed. In both cases, the argument must be a non-empty vector.

The v k (calc-cons) [cons] function takes a value h and a vector t from the stack, and produces the vector whose head is h and whose tail is t. This is similar to |, except if h is itself a vector, | will concatenate the two vectors whereas cons will insert h at the front of the vector t.

Each of these three functions also accepts the Hyperbolic flag [rhead, rtail, rcons] in which case t instead represents the last single element of the vector, with h representing the remainder of the vector. Thus the vector `[a, b, c, d] = cons(a, [b, c, d]) = rcons([a, b, c], d)'. Also, `head([a, b, c, d]) = a', `tail([a, b, c, d]) = [b, c, d]', `rhead([a, b, c, d]) = [a, b, c]', and `rtail([a, b, c, d]) = d'.

Extracting Vector Elements

The v r (calc-mrow) [mrow] command extracts one row of the matrix on the top of the stack, or one element of the plain vector on the top of the stack. The row or element is specified by the numeric prefix argument; the default is to prompt for the row or element number. The matrix or vector is replaced by the specified row or element in the form of a vector or scalar, respectively.

With a prefix argument of C-u only, v r takes the index of the element or row from the top of the stack, and the vector or matrix from the second-to-top position. If the index is itself a vector of integers, the result is a vector of the corresponding elements of the input vector, or a matrix of the corresponding rows of the input matrix. This command can be used to obtain any permutation of a vector.

With C-u, if the index is an interval form with integer components, it is interpreted as a range of indices and the corresponding subvector or submatrix is returned.

Subscript notation in algebraic formulas (`a_b') stands for the Calc function subscr, which is synonymous with mrow. Thus, `[x, y, z]_k' produces x, y, or z if k is one, two, or three, respectively. A double subscript (`M_i_j', equivalent to `subscr(subscr(M, i), j)') will access the element at row i, column j of a matrix. The a _ (calc-subscript) command creates a subscript formula `a_b' out of two stack entries. (It is on the a "algebra" prefix because subscripted variables are often used purely as an algebraic notation.)

Given a negative prefix argument, v r instead deletes one row or element from the matrix or vector on the top of the stack. Thus C-u 2 v r replaces a matrix with its second row, but C-u -2 v r replaces the matrix with the same matrix with its second row removed. In algebraic form this function is called mrrow.

Given a prefix argument of zero, v r extracts the diagonal elements of a square matrix in the form of a vector. In algebraic form this function is called getdiag.

The v c (calc-mcol) [mcol or mrcol] command is the analogous operation on columns of a matrix. Given a plain vector it extracts (or removes) one element, just like v r. If the index in C-u v c is an interval or vector and the argument is a matrix, the result is a submatrix with only the specified columns retained (and possibly permuted in the case of a vector index).

To extract a matrix element at a given row and column, use v r to extract the row as a vector, then v c to extract the column element from that vector. In algebraic formulas, it is often more convenient to use subscript notation: `m_i_j' gives row i, column j of matrix m.

The v s (calc-subvector) [subvec] command extracts a subvector of a vector. The arguments are the vector, the starting index, and the ending index, with the ending index in the top-of-stack position. The starting index indicates the first element of the vector to take. The ending index indicates the first element past the range to be taken. Thus, `subvec([a, b, c, d, e], 2, 4)' produces the subvector `[b, c]'. You could get the same result using `mrow([a, b, c, d, e], [2 .. 4))'.

If either the start or the end index is zero or negative, it is interpreted as relative to the end of the vector. Thus `subvec([a, b, c, d, e], 2, -2)' also produces `[b, c]'. In the algebraic form, the end index can be omitted in which case it is taken as zero, i.e., elements from the starting element to the end of the vector are used. The infinity symbol, inf, also has this effect when used as the ending index.

With the Inverse flag, I v s [rsubvec] removes a subvector from a vector. The arguments are interpreted the same as for the normal v s command. Thus, `rsubvec([a, b, c, d, e], 2, 4)' produces `[a, d, e]'. It is always true that subvec and rsubvec return complementary parts of the input vector.

See section Selecting Sub-Formulas, for an alternative way to operate on vectors one element at a time.

Manipulating Vectors

The v l (calc-vlength) [vlen] command computes the length of a vector. The length of a non-vector is considered to be zero. Note that matrices are just vectors of vectors for the purposes of this command.

With the Hyperbolic flag, H v l [mdims] computes a vector of the dimensions of a vector, matrix, or higher-order object. For example, `mdims([[a,b,c],[d,e,f]])' returns `[2, 3]' since its argument is a @c{$2\times3$} 2x3 matrix.

The v f (calc-vector-find) [find] command searches along a vector for the first element equal to a given target. The target is on the top of the stack; the vector is in the second-to-top position. If a match is found, the result is the index of the matching element. Otherwise, the result is zero. The numeric prefix argument, if given, allows you to select any starting index for the search.

The v a (calc-arrange-vector) [arrange] command rearranges a vector to have a certain number of columns and rows. The numeric prefix argument specifies the number of columns; if you do not provide an argument, you will be prompted for the number of columns. The vector or matrix on the top of the stack is flattened into a plain vector. If the number of columns is nonzero, this vector is then formed into a matrix by taking successive groups of n elements. If the number of columns does not evenly divide the number of elements in the vector, the last row will be short and the result will not be suitable for use as a matrix. For example, with the matrix `[[1, 2], [3, 4]]' on the stack, v a 4 produces `[[1, 2, 3, 4]]' (a @c{$1\times4$} 1x4 matrix), v a 1 produces `[[1], [2], [3], [4]]' (a @c{$4\times1$} 4x1 matrix), v a 2 produces `[[1, 2], [3, 4]]' (the original @c{$2\times2$} 2x2 matrix), v a 3 produces `[[1, 2, 3], [4]]' (not a matrix), and v a 0 produces the flattened list `[1, 2, 3, 4]'.

The V S (calc-sort) [sort] command sorts the elements of a vector into increasing order. Real numbers, real infinities, and constant interval forms come first in this ordering; next come other kinds of numbers, then variables (in alphabetical order), then finally come formulas and other kinds of objects; these are sorted according to a kind of lexicographic ordering with the useful property that one vector is less or greater than another if the first corresponding unequal elements are less or greater, respectively. Since quoted strings are stored by Calc internally as vectors of ASCII character codes (see section Strings), this means vectors of strings are also sorted into alphabetical order by this command.

The I V S [rsort] command sorts a vector into decreasing order.

The V G (calc-grade) [grade, rgrade] command produces an index table or permutation vector which, if applied to the input vector (as the index of C-u v r, say), would sort the vector. A permutation vector is just a vector of integers from 1 to n, where each integer occurs exactly once. One application of this is to sort a matrix of data rows using one column as the sort key; extract that column, grade it with V G, then use the result to reorder the original matrix with C-u v r. Another interesting property of the V G command is that, if the input is itself a permutation vector, the result will be the inverse of the permutation. The inverse of an index table is a rank table, whose kth element says where the kth original vector element will rest when the vector is sorted. To get a rank table, just use V G V G.

With the Inverse flag, I V G produces an index table that would sort the input into decreasing order. Note that V S and V G use a "stable" sorting algorithm, i.e., any two elements which are equal will not be moved out of their original order. Generally there is no way to tell with V S, since two elements which are equal look the same, but with V G this can be an important issue. In the matrix-of-rows example, suppose you have names and telephone numbers as two columns and you wish to sort by phone number primarily, and by name when the numbers are equal. You can sort the data matrix by names first, and then again by phone numbers. Because the sort is stable, any two rows with equal phone numbers will remain sorted by name even after the second sort.

The V H (calc-histogram) [histogram] command builds a histogram of a vector of numbers. Vector elements are assumed to be integers or real numbers in the range [0..n) for some "number of bins" n, which is the numeric prefix argument given to the command. The result is a vector of n counts of how many times each value appeared in the original vector. Non-integers in the input are rounded down to integers. Any vector elements outside the specified range are ignored. (You can tell if elements have been ignored by noting that the counts in the result vector don't add up to the length of the input vector.)

With the Hyperbolic flag, H V H pulls two vectors from the stack. The second-to-top vector is the list of numbers as before. The top vector is an equal-sized list of "weights" to attach to the elements of the data vector. For example, if the first data element is 4.2 and the first weight is 10, then 10 will be added to bin 4 of the result vector. Without the hyperbolic flag, every element has a weight of one.

The v t (calc-transpose) [trn] command computes the transpose of the matrix at the top of the stack. If the argument is a plain vector, it is treated as a row vector and transposed into a one-column matrix.

The v v (calc-reverse-vector) [vec] command reverses a vector end-for-end. Given a matrix, it reverses the order of the rows. (To reverse the columns instead, just use v t v v v t. The same principle can be used to apply other vector commands to the columns of a matrix.)

The v m (calc-mask-vector) [vmask] command uses one vector as a mask to extract elements of another vector. The mask is in the second-to-top position; the target vector is on the top of the stack. These vectors must have the same length. The result is the same as the target vector, but with all elements which correspond to zeros in the mask vector deleted. Thus, for example, `vmask([1, 0, 1, 0, 1], [a, b, c, d, e])' produces `[a, c, e]'. See section Logical Operations.

The v e (calc-expand-vector) [vexp] command expands a vector according to another mask vector. The result is a vector the same length as the mask, but with nonzero elements replaced by successive elements from the target vector. The length of the target vector is normally the number of nonzero elements in the mask. If the target vector is longer, its last few elements are lost. If the target vector is shorter, the last few nonzero mask elements are left unreplaced in the result. Thus `vexp([2, 0, 3, 0, 7], [a, b])' produces `[a, 0, b, 0, 7]'.

With the Hyperbolic flag, H v e takes a filler value from the top of the stack; the mask and target vectors come from the third and second elements of the stack. This filler is used where the mask is zero: `vexp([2, 0, 3, 0, 7], [a, b], z)' produces `[a, z, c, z, 7]'. If the filler value is itself a vector, then successive values are taken from it, so that the effect is to interleave two vectors according to the mask: `vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])' produces `[a, x, b, 7, y, 0]'.

Another variation on the masking idea is to combine `[a, b, c, d, e]' with the mask `[1, 0, 1, 0, 1]' to produce `[a, 0, c, 0, e]'. You can accomplish this with V M a &, mapping the logical "and" operation across the two vectors. See section Logical Operations. Note that the ? : operation also discussed there allows other types of masking using vectors.

Vector and Matrix Arithmetic

Basic arithmetic operations like addition and multiplication are defined for vectors and matrices as well as for numbers. Division of matrices, in the sense of multiplying by the inverse, is supported. (Division by a matrix actually uses LU-decomposition for greater accuracy and speed.) See section Basic Arithmetic.

The following functions are applied element-wise if their arguments are vectors or matrices: change-sign, conj, arg, re, im, polar, rect, clean, float, frac. See section Index of Algebraic Functions.

The V J (calc-conj-transpose) [ctrn] command computes the conjugate transpose of its argument, i.e., `conj(trn(x))'.

The A (calc-abs) [abs] command computes the Frobenius norm of a vector or matrix argument. This is the square root of the sum of the squares of the absolute values of the elements of the vector or matrix. If the vector is interpreted as a point in two- or three-dimensional space, this is the distance from that point to the origin.

The v n (calc-rnorm) [rnorm] command computes the row norm, or infinity-norm, of a vector or matrix. For a plain vector, this is the maximum of the absolute values of the elements. For a matrix, this is the maximum of the row-absolute-value-sums, i.e., of the sums of the absolute values of the elements along the various rows.

The V N (calc-cnorm) [cnorm] command computes the column norm, or one-norm, of a vector or matrix. For a plain vector, this is the sum of the absolute values of the elements. For a matrix, this is the maximum of the column-absolute-value-sums. General k-norms for k other than one or infinity are not provided.

The V C (calc-cross) [cross] command computes the right-handed cross product of two vectors, each of which must have exactly three elements.

The & (calc-inv) [inv] command computes the inverse of a square matrix. If the matrix is singular, the inverse operation is left in symbolic form. Matrix inverses are recorded so that once an inverse (or determinant) of a particular matrix has been computed, the inverse and determinant of the matrix can be recomputed quickly in the future.

If the argument to & is a plain number x, this command simply computes 1/x. This is okay, because the `/' operator also does a matrix inversion when dividing one by a matrix.

The V D (calc-mdet) [det] command computes the determinant of a square matrix.

The V L (calc-mlud) [lud] command computes the LU decomposition of a matrix. The result is a list of three matrices which, when multiplied together left-to-right, form the original matrix. The first is a permutation matrix that arises from pivoting in the algorithm, the second is lower-triangular with ones on the diagonal, and the third is upper-triangular.

The V T (calc-mtrace) [tr] command computes the trace of a square matrix. This is defined as the sum of the diagonal elements of the matrix.

Set Operations using Vectors

Calc includes several commands which interpret vectors as sets of objects. A set is a collection of objects; any given object can appear only once in the set. Calc stores sets as vectors of objects in sorted order. Objects in a Calc set can be any of the usual things, such as numbers, variables, or formulas. Two set elements are considered equal if they are identical, except that numerically equal numbers like the integer 4 and the float 4.0 are considered equal even though they are not "identical." Variables are treated like plain symbols without attached values by the set operations; subtracting the set `[b]' from `[a, b]' always yields the set `[a]' even though if the variables `a' and `b' both equalled 17, you might expect the answer `[]'.

If a set contains interval forms, then it is assumed to be a set of real numbers. In this case, all set operations require the elements of the set to be only things that are allowed in intervals: Real numbers, plus and minus infinity, HMS forms, and date forms. If there are variables or other non-real objects present in a real set, all set operayou have names and telephone numbers as two columns and you wish to sort by phone number primarily, and by name when the numbers are equal. You can sort the data matrix by names first, and then again by phone numbers. Because the sort is stable, any two rows with equal phone numbers will remain sorted by name even after the second sort.

The V H (calc-histogram) [histogram] c