Sample Session

The following sample session illustrates some basic features of NAP. The input command lines begin with the standard Tcl prompt "%". 

    % nap "x = {2 2.5 5}"
    ::NAP::13-13
    % nap "y = x * x"
    ::NAP::14-14
    % $y
    4 6.25 25

The first command assigns to x a vector containing the three elements 2, 2.5 and 5. The second command assigns to y a vector containing the three elements which are the squares of the corresponding elements of x. The command "$y" returns the value of y.

Nap stores each variable in memory using a data-structure called an n-dimensional array object (NAO). Each NAO has an associated Tcl command called its object-oriented command (OOC) which is used to

  • obtain data and other information from the NAO
  • write data from the NAO to files
  • modify the NAO.

    An OOC-name (command-name of an OOC) is used

  • to execute the OOC (like any other Tcl command)
  • as a unique identifier for the NAO associated with the OOC.
    An OOC-name has the form ::NAP::seq-slot, where
  • ::NAP:: is the Tcl namespace used by NAP
  • seq is the sequence number assigned in order of creation
  • slot is the index of an internal table used to provide fast access.
    In the above example, both OOC-names (::NAP::13-13 and ::NAP::14-14) have slots equal to their sequence number, but this is not the case in general since the slots of deleted NAOs may be reused.

    An assignment ("=") operator has on its left a standard Tcl variable name which is assigned the (string) value of the OOC-name. Continuing the above example, these string values can be displayed using the standard Tcl command set. 

      
  % set x
  ::NAP::13-13
  % set y
  ::NAP::14-14

    Thus the command "$y" is equivalent to the command "::NAP::14-14".   Confirming this: 

      
    % ::NAP::14-14
    4 6.25 25

    If an OOC has no arguments (as above) then it returns the value of the NAO (abbreviated if the NAO is large). Arguments can be specified as in: 

    
  % $x all
::NAP::13-13  f64  MissingValue: NaN  References: 1  Unit: (NULL)
Dimension 0   Size: 3      Name: (NULL)    Coordinate-variable: (NULL)
Value:
2 2.5 5

    This illustrates the "all" method (sub-command), which provides a more detailed description of the NAO than the default method. The  following example uses the "set value" method to change the value of element 1 of x from 2.5 to 7. Note that element 1 is the second element because the subscript origin is 0 (as in other aspects of Tcl) rather than 1 (as in languages such as Fortran). 

    % $x set value 7 1
% $x all
::NAP::13-13  f64  MissingValue: NaN  References: 1  Unit: (NULL)
Dimension 0   Size: 3      Name: (NULL)    Coordinate-variable: (NULL)
Value:
2 7 5

    The similarity between the "expr" and "nap" commands for simple arithmetic is shown by: 

    % expr "2 * (1 - 0.25)"
1.5
% nap "2 * (1 - 0.25)"
::NAP::25-25
% ::NAP::25-25
1.5
% ::NAP::25-25
invalid command name "::NAP::25-25"

    Note that the command "::NAP::25-25" worked the first time but failed when it was repeated. The NAOs reference count was zero, as it was not referenced by anything (e.g. a Tcl variable). So the NAO and its associated OOC were automatically deleted after the first execution of the OOC.

    The need to type the additional command "::NAP::25-25" can be obviated using the Tcl bracket ("[]") notation. Tcl executes the bracketed command, substitutes its result and then executes the generated command. So the above can be replaced by: 

    % [nap "2 * (1 - 0.25)"]
1.5

    The following example illustrates array indexing. The six commands do the following:

    1. Assign to the variable score a 32-bit floating-point vector containing the five values 56, 75, 47, 99 and 49.
    2. Display score.
    3. Index a vector by a scalar "2" to give a scalar.
    4. Index a vector by a vector "{2 0 4}" to give a vector.
    5. Illustrate the operator ".." which defines an arithmetic progression.
    6. Use such an arithmetic progression as an index. 
    % nap "score = f32{56 75 47 99 49}"
::NAP::16-16
% $score all
::NAP::16-16  f32  MissingValue: NaN  References: 1  Unit: (NULL)
Dimension 0   Size: 5      Name: (NULL)    Coordinate-variable: (NULL)
Value:
56 75 47 99 49
% [nap "score(2)"] all
::NAP::20-20  f32  MissingValue: NaN  References: 0  Unit: (NULL)
Value:
47
% [nap "score({2 0 4})"] all
::NAP::25-25  f32  MissingValue: NaN  References: 0  Unit: (NULL)
Dimension 0   Size: 3      Name: (NULL)    Coordinate-variable: (NULL)
Value:
47 56 49
% [nap "0 .. 3"]
0 1 2 3
% [nap "score(0 .. 3)"]
56 75 47 99

    The following three commands respectively illustrate:

    1. function sum, which has the functionality of mathematical "Σ"
    2. function count, which gives the number of non-missing elements
    3. the use of these functions to calculate an arithmetic-mean 
    % [nap "sum(score)"]
326
% [nap "count(score)"]
5
% [nap "sum(score) / count(score)"]
65.2

    The following two commands respectively illustrate:

    1. the definition of a tcl procedure to calculate an arithmetic-mean using NAP
    2. the calling of this procedure as a NAP function 
    % proc mean x {nap "sum(x)/count(x)"}
% [nap "mean(score)"]
65.2

    Procedures defining NAP functions have arguments and results which are OOC-names. All the facilities of Tcl and NAP can be used. So recursion is allowed, as shown by the following factorial example: 

    % proc factorial n {
    if {[[nap "n > 1"]]} {
	nap "n * factorial(n-1)"
    } else {
	nap "1"
    }
}
% [nap "factorial(4)"]
24

    Note the double brackets (inside braces) in the first line of the body of the above procedure. The inner brackets produce an OOC-name. The outer brackets execute this OOC to produce the string "0" or "1".

    Author: Harvey Davies       © 2002, CSIRO Australia.       Legal Notice and Disclaimer
    CVS Version Details: $Id: sample.html,v 1.8 2004/10/26 05:27:22 dav480 Exp $