vector vector
Jump to Background, Description, or
Examples; explanation of how
commands are documented.
Operation Argument types Description of vector returned (number)
Arithmetic operations:
add int or real (2) arg1 + arg2 (per element). addMultiply real (3) Return arg1 + arg2 * arg3. degree real (1) Convert a vector of radians to degrees (scale elements by 180/
). divide int or real (2) arg1 / arg2 (per element). increment real (1 or 2) varName += arg1[?arg2?]. initialize int or real Initialize a vector. ?-keyword? (1, 2 or 3) If no keyword is given, the default is sequential. keyword sequential If only arg1 is given, return a vector or scalar containing the first arg1 positive integers. If arg2 is also given, return the arg1_th through the arg2_th positive integers. If arg3 is also given, return the arg1_th through the arg2_th positive integers in steps of arg3. If any of the arguments contains a decimal point, return the results as real. prime If only arg1 is given, return a vector or scalar containing the first arg1 prime numbers. If arg2 is also given, return the arg1_th through the arg2_th prime numbers. If arg3 is also given, return the arg1_th through the arg2_th prime numbers in steps of arg3. gaussian Return arg1 number of normalized Gaussian points. Optional mean and standard deviation can be given in arg2 and arg3. random Same as the vector operation random. diagonalmatrix Same as the vector operation diagonalMatrix. replicate Same as the vector operation fill. modulus int or real (2) Remainders of arg1 / arg2 (per element). multiply int or real (2) arg1 * arg2 (per element). multiplyIncrement real (2) varName += arg1 * arg2. multiplyMultiply real (3) Return arg1 * arg2 * arg3. multiplyMultiplyIncrement real (3) varName += arg1 * arg2 * arg3. negate real (1) varName *= -1 (per element). radian real (1) Convert a vector of degrees (scale elements by
Conversion operations:
abs real (1) Absolute values (per element). boolean int or real A vector of Booleans of (char) 0 or 1 (1) corresponding to the input elements that are 0 or not 0. ceiling real (1) Smallest integers not less than the vector elements (returned as reals). real Boolean or int A vector of reals of (double) 0 or 1 (1) corresponding to the input elements that are 0 or not 0. floor real (1) Largest integers not greater than the vector elements (returned as reals). integer Boolean or real Return a vector of integers of 0 or 1 for a (1) Boolean vector input and a vector of integers (truncated) for a real vector input. pack real (1) Return a symmetric matrix in packed form if the input is a symmetric matrix in unpacked form; return a copy of the input if it is a symmetric matrix in packed form. unpack real (1) Return a symmetric matrix in unpacked form if the input is a symmetric matrix in packed form; return a copy of the input if it is a symmetric matrix in unpacked form.
Geometric operations:
xRotate real (2) If arg2 is a matrix (3 x 3 or 4 x 4), then a rotation of arg1 is performed on arg2 about the x-axis. If arg1 is a matrix and arg2 the angle, then a post-multiply of the rotation matrix is performed. yRotate real (2) As for yRotate, but about the y-axis. zRotate real (2) As for zRotate, but about the z-axis. threeDot real (2) Dot product of a 3 x 1 vector and a 4 x 4 matrix. Special case - the fourth row and column of the matrix are ignored. translate real (2) Translation by a 3 x 1 vector, arg1 or arg2, of the 4 x 4 matrix, arg2 or arg1.
Logical operations:
not Boolean (1) Logical negation of arg1 (per element). and Boolean (2) Logical ``and'' operation of arg1 and arg2 (per element). or Boolean (2) Logical ``or'' operation of arg1 and arg2 (per element). xor Boolean (2) Logical ``exclusive or'' operation of arg1 and arg2 (per element). eq int or real (2) Logical 1 if arg1 == arg2, else 0 (per element). ne int or real (2) Logical 1 if arg1 != arg2, else 0 (per element). gt int or real (2) Logical 1 if arg1 > arg2, else 0 (per element). lt int or real (2) Logical 1 if arg1 < arg2, else 0 (per element). ge int or real (2) Logical 1 if arg1 >= arg2, else 0 (per element). le int or real (2) Logical 1 if arg1 <= arg2, else 0 (per element). ? Boolean (1); arg1 ? arg2 : (arg3 ? arg3 : 0) (per element). Boolean, int or real (1 or 2)
Statistical operations:
average real (1 or 2) (1) If only arg1 is provided, return average ?-keyword? of the elements. (2) Use arg2 as a set of weights to the elements of arg1 and return the weighted
. If bygroup is specified as a keyword, return the averages within the groups (see the object command for more information on grouping). count Boolean, int The number of items (i.e., scalars, vectors, or or real (1) matrices) in arg1. min int or real (1) Minimum values for each corresponding element ?-keyword? in the input vector items. keyword can be index or bygroup. If bygroup is specified, the vector returned contains the minimum elements within each group (see the object command on how groups are defined). If index is specified, the vector returned is an integer vector of the indices of the minimum elements (rather than the minimum elements themselves). max int or real (1) Maximum values for each corresponding element ?-keyword? in the input vector items. keyword can be index or bygroup. If bygroup is specified, the vector returned contains the maximum elements within each group (see the object command on how groups are defined). If index is specified, the vector returned is an integer vector of the indices of the maximum elements (rather than the maximum elements themselves). product int or real (1) If only arg1 provided, return the product ?-keyword? (1 or 2) of the items in arg1. (2) Use arg2 as a set of weights to the elements of arg1 and return the weighted
. If bygroup is specified as a keyword, return the products within the groups (see the object command for more information on grouping). The bygroup option does not support the input of optional weights. random int or real Vector of random numbers (between 0 and 1). The (1, 2 or 3) arguments are scalar integer values and the returned vector contains arg1 random scalars, or arg1 random unit vectors of dimension (arg2 * 1) if arg2 is supplied, or arg1 matrices of dimension (arg2 * arg3) of random numbers. standardDeviation ?-keyword? real (1) Standard deviations for each element over all the items in arg1. If bygroup is specified as a keyword, return the averages within the groups (see the object command for more information on grouping). sum int or real (1) If only arg1 is provided, return the sum ?-keyword? (1 or 2) of the items in arg1. (2) Use arg2 as a set of weights to the elements of arg1 and return the weighted
. If bygroup is specified as a keyword, perform the summation within the groups (see the object command for more information on grouping). The bygroup option does not support the input of optional weights.
Transcendental and arithmetic operations:
acos real (1) Arccosines (in radians) (per element). asin real (1) Arcsines (in radians) (per element). atan real (1) Arctangents (in radians) (per element). atan2 real (2) Arctangents (in radians) as results of the C function, atan2(arg2, arg1) (per element). cos real (1) Cosines (in radians) (per element). exp real (1) Exponentials (base e) (per element). log real (1) Logarithms (base e) (per element). log10 real (1) Logarithms (base 10) (per element). sin real (1) Sines (in radians) (per element). tan real (1) Tangents (in radians) (per element). power real (2) arg1 raised to the power of arg2. Results of the C function pow(arg1, arg2) (per element). sqrt real (1) Square roots (per element).
Vector and matrix operations:
cross real (2) Cross product of two 3 x 1 vectors. diagonalize real (1) Eigenvalues and optional eigenvectors, which ?-eigenvectors are returned to object varName2. varName2? diagonalMatrix int (1) Single-banded diagonal matrix of dimension ?real (1)? arg1. If vector is arg2, this is used to fill in the elements along the diagonal, otherwise zeros are used. dot real (2) Dot product for vector * vector, vector * matrix, matrix * vector, or matrix * matrix. Also supports the special case where the vector is 3 x 1 and the matrix is 4 x 4. norm real (1 or 2) Return the p-norm of a vector arg1 where p is given by arg2; returns the Euclidean norm if arg2 is not specified. fill Boolean, int, Vector composed of arg2 copies of vector arg1 or real (1); if arg2 is specified, else returns arg1. ?int or real (1)? identity int (1) Identity matrix with dimension arg1. Equivalent to operation diagonalMatrix arg1 1. index Replaced by object range command inverse real (1) Inverse of arg1. linearEquationSolver real (2) Solve a system of simultaneous, inhomogeneous linear equations with the matrix in arg1 and the inhomogeneous terms as a vector arg2. normalize real (1) Normalized vector. Does not support matrices. outer real (2) Outer product of two vectors. outerSum real (2 or 3) The sum of outer products of arg1 and arg2, with optional weights for each product if vector arg3 is supplied. reduce real (1) Reduce a vector from (n,i,j) to (n,i,1), or from (n,i,1) to (n,1,1), or from (n,1,1) to (1,1,1). transpose real (1) Transpose a matrix (n,i,j) to (n,j,i) or transpose a matrix (n,i,j) to (i,j,n). trace real (1) Trace of the square matrix arg1. vectorTranspose real (1) Transpose a vector (n,i,1) to (i,n,1).
Jump to Syntax,
Description, or ExamplesBTCL vector variables refer to data organized as lists of scalars, vectors, or matrices composed of Boolean, integer, or real values. Where the term ``number of items'' is used, it refers to how many scalars, vectors, or matrices are listed in the vector object. The term ``elements'' refers to the individual values within an item. In general, a vector object can be thought of as having three dimensions n,i,j, where n is the number of items, i is the number of rows, and j the number of columns. The total number of elements is thus n * i * j. Hence, a collection of scalars has dimensions n,1,1; a collection of vectors, n,i,1; and a collection of matrices, n,i,j.
The definition of some operations depends on the data stored. Where the term ``per element'' is used, the operation applies to corresponding individual elements in each vector object argument, irrespective of the underlying organization of the list as scalars, vectors, or matrices.
For some operations (such as the binary arithmetic operations add, subtract, multiply, and divide), the vector command supports input of vector objects with different dimensions. For example, in general, if arg1 is of dimensions n,i,j, and arg2 of dimensions n',i',j', the add operation accepts these arguments if n' equals n, or n equals 1, or n' equals 1, and the resulting vector has the maximum of n and n' as its item dimension. In other words, mapping between 1 and n or between n and n items is allowed. The same is true for the row and column dimensions. The vector command expands the argument that has the smaller value in any one of its dimensions accordingly, to match the corresponding larger dimensions. Please note that arguments with dimensions like 2,1,1 and 1,3,4 are allowed in this scheme.
Unlike ordinary TCL variables, which can contain lists of numbers or lists of lists, etc., as strings, BTCL vector variables actually contain a string code, which is used internally by BTCL to refer to arrays of numbers stored in memory. The BTCL vector command allows access to and manipulation of the values referred to by a BTCL vector variable. In general, a vector variable may refer to a great number of values--manipulating these values with the vector command instead of standard TCL strings provides very fast math operations on collections of scalars, vectors, or matrices.
A vector variable can be created only with the vector command but can be deleted using the BTCL unset command or by reassigning the variable name using a set or another vector command. When this occurs, the internal data associated with that vector object are also deleted. It is also possible to copy the value of a vector variable, i.e., the string code used to refer to the actual data, into an ordinary TCL variable and use this variable in a vector command as if it were the actual vector variable. However, deleting or reassigning the TCL variable has no effect on the original vector variable, and, conversely, deleting the original vector variable makes the string code stored in the TCL variable invalid as a reference to internal values. This distinction is made clearer in the description and Example 4 below.
Jump to Syntax,
Background, or ExamplesThe vector command takes positional arguments rather than named parameter arguments. It acts like the set command in that, to create a vector variable v, the syntax would be:
BTCL > vector v {1 2 3}
or
BTCL > vector v "1 2 3"where, in this case, v is set to a string code which refers internally to a list of three scalars. To find out what a vector variable v holds, the syntax is:
BTCL > vector v 1.0 2.0 3.0In general, a vector variable might refer to a great many values and so, unlike the BTCL set command, the data values just stored are not echoed back to you in interactive mode. Lists of scalars, vectors, or matrices are created, depending on the number of braces enclosing each sublist. The following are valid vector definitions:
BTCL > vector v1 "{1 0 0}" ; vector v1
{1.0 0.0 0.0}
BTCL > vector v2 "{1 0 0} {0 1 0} {0 0 1}" ; vector v2
{1.0 0.0 0.0} {0.0 1.0 0.0} {0.0 0.0 1.0}
BTCL > vector v3 "{1} {2} {3}" ; vector v3
1.0 2.0 3.0
v1 refers to a list of length 1 containing a vector of length 3; v2
refers to a list of length 3 containing vectors of length 3; v3 refers
to a list of length 3 containing scalars. Note that, in the last
example, a list of one-dimensional vectors is considered to be a list
of scalars. The following are valid matrix definitions:
BTCL > vector m1 "{{1 0 0} {0 1 0} {0 0 1}}" ; vector m1
{{1.0 0.0 0.0} {0.0 1.0 0.0} {0.0 0.0 1.0}}
BTCL > vector m2 "{{1 0} {0 1}} {{0 1} {-1 0}}" ; vector m2
{{1.0 0.0} {0.0 1.0}} {{0.0 1.0} {-1.0 0.0}}
BTCL > vector m3 "{{1}} {{2}} {{3}}" ; vector m3
{{1.0}} {{2.0}} {{3.0}}
m1 refers to a list of length 1 containing a 3 x 3 matrix; m2 refers
to a list of length 2 containing 2 x 2 matrices; m3 refers to a list
of length 3 containing 1 x 1 matrices. Note that, in this last
example, single-element matrices are still considered to be
matrices. This is because, under certain operations, they can act as
scaling matrices. When you create lists of vectors or matrices, all
elements of the list must have exactly the same dimensions (as in the
above examples). However, there is one special matrix definition that
allows you to specify a symmetric matrix, for example:
BTCL > vector sym "{{1} {0 1} {0 0 1} {0 0 0 1}}" ; vector sym
{{1.0} {0.0 1.0} {0.0 0.0 1.0} {0.0 0.0 0.0 1.0}}
The output of vector varName is suitable for defining a
new vector:
BTCL > vector v1 {{1 0 0}}
BTCL > vector v2 [vector v1]; vector v1
{1.0 0.0 0.0}
The contents of a normal TCL variable can also be used to
create/specify the contents of a BTCL vector variable.
BTCL > set a {{4 5 6}}
{4 5 6}
BTCL > vector v4 $a ; vector v4
{4.0 5.0 6.0}
However, when copying vectors, it is most efficient to use the
vector command:
BTCL > vector v5 $v4 ; vector v5
{4.0 5.0 6.0}
The BTCL vector command also takes several operations (listed
in the table above), which themselves take
arguments that are either string definitions or vector variables of
compatible dimensions. Refer to the examples
below.
Jump to Syntax,
Background, or Description
BTCL > vector v1 {{1 2 3}}
BTCL > vector v2 add $v1 "{4 5 6}"
BTCL > vector v2
{5.0 7.0 9.0}
In this example, the first line performs an assignment of the vector
variable v1 from a string definition. The second command line creates
a vector v2 from the vector sum of vector v1 and a string
definition. The third command line uses the vector command to
echo the value of the vector variable v2.
BTCL > vector v1 "{1 1 1} {1 1 1}"
BTCL > vector v2 "{2 3 4} {4 5 6}"
BTCL > vector v3 dot $v1 $v2
BTCL > vector v3
9.0 15.0
In this example, vector variables v1 and v2 are both assigned as lists
containing two vectors. Vector variable v3 is then assigned as the dot
product of these two vectors. Notice that v3 is a list of two scalers
corresponding to two results.
BTCL > vector sym "{{1} {1 2} {1 2 3}}"
BTCL > vector eigen diagonalize -eigenvectors eigenVec $sym
BTCL > echo eigen values = [vector eigen], eigen vectors = \n[vector eigenVec]
eigen values = {0.307979 0.643104 5.04892}, eigen vectors =
{{0.591009 -0.736976 0.327985} {0.736976 0.327985 -0.591009} {0.327985 0.591009 0.736976}}
In this example, a symmetric matrix vector variable called sym is
first created. It is then diagonalized using the vector
diagonalize operation to assign the eigenvalues to a vector
variable called eigen. This operation may also take an optional
keyword eigenvectors, which specifies that the next argument is
a vector variable name to which the eigenvectors are to be
assigned. Currently, the diagonalize operation is the only
vector operation that can take a named parameter in this
manner. Notice that the eigenvectors are returned as a matrix.
BTCL > proc v_dot {v1 v2} {
vector c dot $v1 $v2
return [vector c]
}
BTCL > v_dot "{1 2 3}" "{0 1 2}"
8.0
In this example, the vector arguments are passed like any ordinary
procedure arguments. The result of the function in this case is
returned as a string. Because vector variable c is created
locally, the ``vector pointer'' $c would not be valid outside this
procedure, since local variables are deallocated at the end of
procedures. For this example, passing the string value back is
acceptable, since in most cases you would be expecting a single value
back from the procedure. In general, it is a bad idea to pass around
the string values of vector variables, since they may be very long,
and the process of string conversion may introduce some inaccuracy (if
tcl_precision is not set to 17). To create a procedure that returns a general vector result, i.e., a vector function, it is far better to pass a variable name for the result, as in the following example:
BTCL > proc v_add {sum v1 v2} {
upvar 1 $sum c
vector c add $v1 $v2
}
BTCL > v_add x "1 2 3" "0 1 2"
BTCL > vector x
1.0 3.0 5.0
Here, we have used the advanced TCL command upvar which tells
the procedure to associate the local variable c with the
variable $sum in the context of the calling code (in this case at the
global level). In this example, setting the variable c inside
the procedure is equivalent to setting the variable x outside
the procedure.
Main
access page 
Advanced-Use access.
List of BTCL commands
subStructure command
vibrationalAnalysis command
Copyright Biosym/MSI