_________________________________________________________________
NAME
narray - create and manipulate multi-dimensional arrays
SYNOPSIS
narray create arrayName ?-type type? ?dimN dimN-1 ... ? dim0
narray fromlist arrayName ?-type type? list
narray ncload arrayName filename variable
narray define defnName ?-stride n? formal-args body
_________________________________________________________________
DESCRIPTION
This command creates multi-dimensional numeric arrays in
Tcl. A narray consists of an array of elements and a set of
variables. Operations on narrays include setting and get-
ting the value of array elements and variables, and mapping
functions written in the narray language over array ele-
ments. These functions can be applied on the fly, or given
a name and called later.
If this extension has been compiled with netCDF support then
arrays may be loaded and saved to netCDF files.
This manual page documents version 0.15 of the narray exten-
sion.
NARRAY CREATION
Narray's can be created with the following commands:
narray create arrayName ?-type type? ?dimN dimN-1 ... ? dim0
Creates a command arrayName that represents a multi-
dimensional array with elements of type type and dimen-
sions of length dim0 ?dim1 ...?. type can be int,
float, or double. Returns arrayName.
narray fromlist arrayName ?-type type? list
Creates a command arrayName that represents a multi-
dimensional array from the Tcl list list.
narray ncload arrayName filename variable
Create a command arrayName by loading the variable
variable from the netCDF file filename. The new array
will be of the type closest to the netCDF type of the
variable. Returns arrayName.
NARRAY LAYOUT AND INDEXES
An narray is stored in memory as a vector of array elements.
An index into a narray, index0 ?index1 ...? references the
index0 + ?index1 * dim0 + ...? element. Each indexN can be
greater than dimN or even negative, as long as the sum
index0 + ?index1 * dim0 + ...? is within the bounds of the
vector. In addition, there may be fewer indexes than dimen-
sions. References to elements outside the bounds of the
array have the value 0.
NARRAY VARIABLES
There are 3 kinds of narray variables:
[1] Numeric variables that have the same type as elements
of the narray. From Tcl, these can be accessed through
the vref and vset commands. In narray code they can
appear in expressions and on the left hand side of
assignments, and are written as variableName.
[2] String variables that hold strings. From Tcl, these
can be accessed through the svref and svset commands.
In narray code they can appear in expressions and on
the left hand side of assignments, and are written as
$variableName.
[3] Array variables that reference other narray's. From
Tcl, they can be set through the avset command. In
narray code they can only appear in array references,
as in arrayVariable[?index, ...?].
NARRAY COMMANDS
The narray command creates a new Tcl command whose name is
the same as the name of the narray. This command may be
used to invoke various operations on the narray. It has the
following general form:
arrayName option ?arg arg ...?
9
The following commands are possible for narray's:
arrayName aref ?indexN indexN-1 ...? index0
Return the element at index0 ?index1 ...?.
arrayName aset ?indexN indexN-1 ...? index0 value
Set the element at index0 ?index1 ...? to value.
arrayName vref variable
Return the value of the variable variable.
arrayName vset variable value
Set the variable variable to value.
arrayName vars
Return a list of variables in arrayName.
Return the value of the string variable variable.
arrayName svset variable value
Set the string variable variable to value.
arrayName svars
Return a list of string variables in arrayName.
arrayName avset variable otherArrayName
Set the array variable variable to otherArrayName.
There is no corresponding avref because there is no way
to map internal array pointers to Tcl arrayName's.
arrayName avars
Return a list of array variables in arrayName.
arrayName map ?map_options? code
Compile code and apply it to arrayName. See the sec-
tion on map options for information on what options map
can take.
arrayName eval ?map_options? code
Compile code and evaluate it once. @N expressions will
be 0 in code, and -stride has no effect.
arrayName call defnName ?args ...?
Compile and call the code associated with defnName.
See the section on definitions for more details.
arrayName dimensions
Return the dimensions of arrayName.
arrayName status
Return some status information about arrayName
(currently, the kilobytes used by the narray and its
debug status.)
arrayName debug level
Set the debug flags of arrayName to level. The debug
flags are a bitwise OR of:
1 Print parsing information
2 Trace stack machine execution
4 Print compiled code before executing it
9
arrayName ncsave filename variable_name dim0_name ?dim1_name ...?
Save arrayName to the netCDF file filename. The netCDF
file will contain the one variable variable_name and
have dimensions named dim0_name ?dim1_name ...?. Any
previous file filename will be clobbered.
MAP OPTIONS
These options apply to the map and eval narray commands.
arrayName map ?-array arrayVar otherArrayName?
Make the narray otherArrayName available in arrayVar.
arrayName map ?-variable varName value?
Set the variable varName to value before invoking the
body of the map.
arrayName map ?-stride stride_length?
Map abs(stride_length)) elements at a time.
stride_length defaults to 1. If stride_length is less
than zero, then start with the last element of array-
Name and map in the reverse direction.
NARRAY LANGUAGE
The arrayName map (and eval) command compiles and applies a
sequence of code to each element in a narray. Valid state-
ments in the language are:
expression ; An expression followed by a ; or newline
is a statement.
lvalue = expression ;
lvalue += expression ;
lvalue -= expression ;
lvalue *= expression ;
lvalue /= expression ;
These are similar to the C constructs.
Unlike C, however, multiple assignments
cannot be chained together (for example,
x = y = z; is illegal.)
for ( expression ; expression ; expression ) { statements ... }
A for loop, as in C.
if expression { statements ... }
An if statement. The {}'s are required.
while expression { statements ... }
A while statement. The {}'s are
required.
pre { statements ... }
Execute statements ... before the rest
of the code is mapped over the array.
Multiple pre sections can appear and are
post { statements ... }
Execute statements ... after the rest of
the code has been mapped over the array.
Multiple post sections can appear and
are executed in order.
The following forms may appear on the left hand side of an
assigment (the lvalue's above):
var The variable var. Variables may contain
numeric values only.
[?indexN, indexN-1, ..., index0?]
Accesses elements of the narray. As a
special case, [] is equivalent to [@-1],
which is the current element. For exam-
ple, [@-1+1] is the next element, [@-1-
1] is the previous element, and [1,@-1]
is the element in the same column but
next row in a 2D matrix.
arrayVar[?index0, index1, ...?]
Accesses elements of the narray array-
Var.
Expressions are like C expressions:
lvalue Any thing that can appear on the left-
hand side of an assignment can be used
in a expression.
-x
~x
x + y
x - y
x * y
x / y
x % y
x & y
x | y
x ^ y
out as integer operations, and in float
arrays as float operations, and in dou-
ble arrays as double operations. Bit
operations on floating point numbers
work by converting the numbers to int's,
doing the operation, and then converting
back.
x == y
x != y
x <= y
x => y
x < y
x > y
x && y
x || y Standard comparison operations, except
that && and || do not short-circuit.
expression ? expression : expression
A conditional expression, as in C.
@N If N is less than 0, then linear index
of the current element (the sum index0 +
?index1 * dim0 + ...? ). Otherwise, the
value of the N'th index of the current
element. For example, @0 is the column
number and @1 is the row number (for a
2D matrix.) If N is greater than or
equal to the number of dimensions, then
the value is 0.
@#N When N is negative, the number of dimen-
sions. Otherwise the length of the N'th
dimension. If N is greater than or
equal to the number of dimensions, then
the value is 0.
arrayVar@#N Equivalent to @#N, but for the narray
bound to arrayVar.
func(?arg0, ...?) The result of calling the element func-
tion func. Arguments to element func-
tions can be either expressions or
cial characters can be quoted as in C.
Element functions differ from narray
functions in that they are applied to
the elements of a narray, instead of to
the narray as a whole.
The following element functions are availabe:
sin(x) The sine of x.
cos(x) The cosine of x.
tan(x) The tangent of x.
asin(x) The arc sine of x.
acos(x) The arc cosine of x.
atan(x) The arg tangent of x.
sinh(x) The hyperbolic sine of x.
cosh(x) The hyperbolic cosine of x.
tanh(x) The hyperbolic tangent of x.
exp(x) e ^ x.
log(x) The natural log of x.
log10(x) The base 10 log of x.
sqrt(x) The square root of x.
ceil(x) The smallest integral value not less
than x.
floor(x) The largest integral value not greater
than x.
fabs(x) The absolute value of x. Also can be
called as abs(x).
atan2(x, y) The arc tangent function of two vari-
ables.
pow(x, y) x raised to the y power.
fmod(x, y) The floating-point remainder of x / y.
1.0).
srand48(seed) Initialize drand48 with seed.
printf(format_string, ?arg?, ...)
A limited form of printf that under-
stands the d, f, g, and s formats.
fprintf(file_handle, format_string, ?arg?, ...)
Like printf, but output goes to the Tcl
file handle file_handle.
tcl_eval(string, ?arg?, ...)
Concatenate string and any arguments
(numeric arguments are converted to
strings and preceded by a space) and
evaulate in Tcl in the current context.
tcl_append_result(?arg?, ...)
Concatenate any arguments (numeric argu-
ments are converted to strings and pre-
ceded by a space) and append to the Tcl
interpreter's result.
error(?arg?, ...) Throw an error. The concatenation of
any arguments (as in tcl_eval) is the
error message.
bio_write(file_handle, template, ...)
Writes binary data to the Tcl file han-
dle file_handle. template is a sequence
of type characters that specifies the
type of the arguments in ... and how to
write them to file_handle:
c Write a C char, the next argument
should be numeric.
s Write a C short, the next argument
should be numeric.
i Write a C int, the next argument
should be numeric.
l Write a C long, the next argument
should be numeric.
z Write a zero-terminated string, the
next argument should be a string.
the next argument should be a
string.
bio_read(file_handle, template)
Reads binary data from the Tcl file han-
dle file_handle. template specifies the
type of data to read. Returns the thing
read.
ARRAY FUNCTIONS
Functions on arrays can be defined with the following com-
mand:
narray define defnName ?-stride n? formal-args body
Create a new defintion defnName in Tcl. The defintion
is available to all narray's in the interpreter.
formal-args is a list of formal argument specifiers.
Each element can of the form varName or {-variable var-
Name}, meaning this argument is a variable that will be
bound to varName, or of the form {-array arrayVar},
meaning this argument is another narray that will be
bound to arrayVar.
Functions can then be invoked by:
arrayName call defnName ?args ...?
Call the array function defnName by setting narray
variables the the values of the -variable arguments,
binding each of the -array arguments to the array vari-
ables, and the compiling and invoking the text of the
defnName. There is no support for recursive functions.
(That is, if the array function uses tcl_eval to call
itself again the calling sequence will clobber the
arguments. narray does not currently save and restore
array function arguments.)
LIBRARY ARRAY FUNCTIONS
The file narray.tcl defines several array functions. These
functions follow a few conventions:
[1] All arguments start with an underscore _.
[2] All variables private to the function start with an
underscore.
[3] If a function arrayFn to returns a scalar, then it
returns it using tcl_append_result and in the variable
_arrayFn. For example, dot returns the dot product in
the variable _dot.
arrayName call s+ n Add the scalar n to each element of
arrayName.
arrayName call s- n Subtract the scalar n to each element of
arrayName.
arrayName call s* n Multiply each element of arrayName by
the scalar n.
arrayName call s/ n Divide each element of arrayName by the
scalar n.
arrayName call + otherArray
Add the arrays arrayName and otherArray
element by element.
arrayName call - otherArray
Subtract the arrays arrayName and oth-
erArray element by element.
arrayName call dot otherArray
Put the dot product of the arrays array-
Name and otherArray in the variable _dot
of arrayName. Returns the value of
_dot.
arrayName call outer* otherArray
Compute the outer product of arrayName
and otherArray.
arrayName call m* arrayA arrayB
Store the result of multiplying the 2D
array's arrayA and arrayB in arrayName.
arrayName call copy otherArray
Copy otherArray to arrayName.
arrayName call zero Set all elements of arrayName to 0.
arrayName call transpose
Transpose the 2D array arrayName.
arrayName call tolist
Convert the array arrayName to a Tcl
list.
LIBRARY COMMANDS
The file narray.tcl contains these useful library routines:
pnarray arrayName ?format?
use the string variable _format, otherwise use "%g".
narray_delete arrayName
Delete the narray arrayName. This is the same as
rename arrayName {}.
narray_variable create var ?dimN dimN-1 ...? dim0
Create a narray with dimensions of length dim0 ?dim1
...? with an automatically generated name of the form
narrayN. var is set to the name of the variable and
variable traces are set up to 1, delete the narray when
var is unset, and 2, disallow writes to var.
narray_variable ncload var filename variable
narray_variable fromlist var list
Same as narray_variable create except create the narray
with ncload or fromlist.
narray_init
Does nothing. narray_init can be used to ensure that
narray.tcl has been auto-loaded so that the library
array functions can be used.
BLT SUPPORT
If narray was compiled with BLT support and you've called
the C initialization function NArray_BLTInit (for example,
you are using nablt_wish), then the following function is
available:
narray_blt_export_graph arrayName pathName elementName
Set the data of elementName of the BLT graph pathName
to arrayName. arrayName can be either be 1D or 2D. In
the 1D case, the elements of arrayName will be the y
values of elementName. In the 2D case the 0'th dimen-
sion must be of length 2, these will be the x and y
values of the point.
VARIABLES
The following Tcl variables are set by this extension:
narray_library
The location of the Tcl library. This can be overrid-
den by the environment variable NARRAY_LIBRARY.
narray_version
The version number of the narray extension, in the form
major.minor.
narray_priv
ABOUT NETCDF
From the netCDF WWW page
(http://www.unidata.ucar.edu/packages/netcdf/index.html):
netCDF is an interface for scientific data access and a
library that provides an implementation of the inter-
face. The netCDF library also defines a machine-
independent format for representing scientific data.
Together, the interface, library, and format support
the creation, access, and sharing of scientific data.
The netCDF software was developed at the Unidata Pro-
gram Center in Boulder, Colorado. The source can be
obtained by anonymous FTP from: ftp.unidata.ucar.edu in
the pub/netcdf/ directory.
BUGS AND QUIRKS
Simple expressions must end with a semi-colon or newline.
For example, arrayName map { sum += []; } will compile, but
arrayName map { sum += [] } is a syntax error.
The parser/code generator does not use a representation that
makes for easy optimizations.
The parser doesn't attempt to generate useful error mes-
sages. Use debug level 1 to track down syntax errors.
The bytecode interpreter was developed in an ad hoc fashion
and without (much) regard to performance.
Most of the code was written for ease-of-implementation
rather than doing things the "right" way.
This version (0.15) has many changes over the previous
released version (0.10). It's likely there are other
unknown bugs.
AUTHOR
Sam Shen <slshen@lbl.gov> -- Please send me any comments,
suggestions, and bug reports/fixes.
NArray Last change: narray 12