The LatFunction-based module uses the name of an input port, such as Pressure, to create an internal variable with the same name, Pressure, in the Shape language. If the input port contains a non-alphanumeric character (a space is considered a non-alphanumeric character), the LatFunction-based module turns that character into an underscore. For instance, an input port called Temperature Array is assigned the internal variable name Temperature_Array.

A LatFunction-based module creates internal array variables only for those input ports that have data. It does not create internal variable names for ports that do not contain data. The size and shape of the internal array depend on the port data type, which can be either parameter or lattice.

Parameters on input ports can be of two types:

A scalar, such as the value of a slider widget, is sent to Shape as a scalar. A character string is sent to Shape as a 1D array of integers representing the character string in the ASCII collating sequence.

A LatFunction-based module sends a lattice to Shape in each of three forms: the data array, the coordinate array, and the combined lattice. The variable name indicates the form: the suffixes _lat and _coord signify the combined lattice and the coordinate array, respectively. For instance, a Pressure port yields data Pressure coordinates Pressure_coord, and lattice Pressure_lat.

The Shape ports themselves have names derived from the Explorer ports. Input ports take the prefix iport_ followed by the Explorer port name; output ports use the prefix oport_. For instance, the port names iport_Pressure and oport_Temperature_Array correspond to the example in the previous paragraphs.

A LatFunction-based module assumes it must produce data for all of its output ports. Thus, for each output port name, the LatFunction-based module uses the internal variable of the same name to create an output lattice.

Name mapping differs for input and output ports. For input ports, only the data goes into the variable; for output ports, the variable contains data and may also contain coordinates.

A LatFunction-based module distinguishes the different output possibilities as follows:

Thus, Pressure_lat can be seen as a list of two arrays, one that contains data and one that contains location coordinates. If the output array Temperature has two arrays, they are assumed to be coordinates and data (see Figure 1-2).

Figure 10-2. How Shape Assigns Variable Names

To get coordinates from input to output ports, you must build them into the Shape internal variable by using make_lat(coordinates, data). The order of the arguments is significant: coordinates come first.

For example, suppose a reactor vessel has radially symmetrical pressure coordinates with pressure data at the nodes. To compute the gradient of the pressure using LatFunction, use the following procedure:

When the LatFunction script finishes, the output port contains the pressure gradient based on the same coordinate system as the input pressure. An output port can use output_data_flush to send multiple data sets downstream during one module firing.

In Shape, lattices are first class values. They behave much like arrays in C or Fortran, and they also resemble arrays in Fortran 90. For example, in this and the following sections, you can wire LatFunction's First Out port to PrintLat, then type:

First_Out:=<varname>

whenever you want to print out the variable varname at the end of a computation. The examples show the Shape syntax of the computed result with an arrow symbol (for instance, ==> [[1,2],[3,4],[5,6]]). They also show Shape arrays printed in a more conventional array layout, such as:

The array [[[1,2], [3,4]], [[5,6], [7,8]]] could be displayed equivalently as

For example, in this fragment, the vectors u, v, and r are declared and allocated, then individual values are assigned as in C. Finally, the sum of u and v is copied (with the = operator) to r.

int u[3];   int v[3];   int r[3];     
u[0] = 1;   u[1] = 5;   u[2] = 10;    
v[0] = 2;   v[1] = 3;   v[2] = -3;    
r = u + v;     
r;     
==>[3, 8, 7] 

A Shape array is the same as the data array of an Explorer lattice. Its dimensions are identical to those of the Explorer lattice, with nDataVar treated as the fastest varying dimension. nDataVar defines the number of data variables per node in a lattice. For a 2D lattice of three data variables, with dimensions 10 x 20, the shape of the Shape array is [20, 10, 3].

All nD lattices in Explorer are (n+1)D Shape arrays by default, with the nDataVar size taken as the extent of the fastest varying, n+1, dimension.

The rank of a lattice is the number of dimensions it has. The shape of a lattice is the vector whose entries are the lengths in each dimension. For example, [1, 2, 3] has rank 1 and shape [3], and [[1, 2], [3, 4], [5, 6]] has rank 2 and shape [3, 2]. Rank 1 arrays are often called vectors and rank 2 arrays are often called matrices. An array with rank 0 is a scalar.

Arithmetic with arrays is almost always done element-wise, as follows:

u := [1, 2, 3]; 
v := [4, 5, 6]; 
u * v;
==>[4, 10, 18]

Arrays are automatically promoted to higher rank as required. Promotion entails augmenting the rank of an array and copying array values to fill in the new array elements. Lattices promote on the right, in the most rapidly varying dimension. That is, arrays with the following shapes are compatible with respect to promotion: [5, 4, 3], [5, 4], and [5]. Data values are copied to consecutive array locations during promotion.

For instance, given u from the above example:

u + 2;      
==>[3, 4, 5]      

m := [[1, 2], [3, 4]];      
m * [3, 4];   
==>[[3,6],[12,16]]  

---

Note: The fragment above is not matrix-vector multiplication

---

 m + 1;      
 ==>[[2,3],[4,5]]

m = [1, 2];      
==>[[1,1],[2,2]]  

You can change the direction in which lattices promote: refer to the Inside, Outside, and InsideOut functions listed under “Miscellaneous” in Table 1-3 as well as in “Promotion of Arrays” and “Promotion of Arrays” .

It is an error to operate on arrays of differing lengths in any dimension. For example, [1, 2, 3] + [3, 4] is an error.

The define operator, denoted var:= value, binds a variable without requiring that the variable be previously defined. Define is not present in C, but it provides functionality similar to that of C pointers.

The := operator, unlike =, copies no data. Instead, the value is simply given a new alias, or name. The define operator is important because:

Define is commonly used to change a small part of a lattice. For example, after:

int m[10, 10];           // a 10 by 10 array
d := diagonal(m);        // point to diagonal of m
d += 1;                  // increment the diagonal of m

m is now a 10 x 10 identity matrix. In the first line, m is declared to be a 10 x 10 matrix and is initialized with zeros. In the second line, the vector d is defined as the diagonal of the matrix. Finally, the scalar 1 is promoted to a vector and added to each entry of d. Since d is an alias for part of m (the diagonal), the result is that 1 has been added to each entry of the main diagonal of m.

Arrays promote on assignment and during binary operations. Arrays are promoted by padding the shape on the right, that is, in the fastest varying dimension. The promotion iterates each element of the source until the newly padded dimensions have been filled with the value, then moves on to the next source value.

int b[2,3,4];              // declare a 3D array of zeros
a := [[1,2,3],[4,5,6]];    // define a 2D array

b = a;
==> [[[1,1,1,1],[2,2,2,2],[3,3,3,3]],
    [[4,4,4,4],[5,5,5,5],[6,6,6,6]]]

b + a;
==> [[[2,2,2,2],[4,4,4,4],[6,6,6,6]],
    [[8,8,8,8],[10,10,10,10],[12,12,12,12]]]

Arrays are promoted by compressing the shape on the right, that is, in the fastest varying dimension. The reduction selects the first element of the source array in all of the newly reduced dimensions on assignment. On updating assignment (for example, +=) the dimensions are compressed by the reduction operator.

Reduction assignment by addition adds the data of the extra dimensions together. Using the previous values of a and b gives:

a := (long) a;
==>a

a += 
==> [[5,10,15],[20,25,30]]

Assignment reduction looks like a sum over i of inside(A = B[i]) on the correct number of dimensions. The following examples show a few updating operator reductions:

a = 
==> [[1,2,3],[4,5,6]]

long s;
==>s
s += b;
==>84

// ... bitwise conjunction of an array, ...
long s = 1;
==>1
s &= b;
==>0

long s = 1;
==>1
s &= [1, 1, 1, 1];
==>1

// ... logical conjunction of an array, ...
long s = 1;
==>1
s &= (b>0);
==>1

Shape's For loop construction is identical to that of C. The three expressions in parentheses following For give the initial settings, test logic, and loop counter changing, respectively. The code block for the loop can be one statement or a sequence of statements; if the block is a sequence of statements, it is enclosed in curly braces. For instance:

int i;
int a[10];
for (i=0; i< 10; i += 1)
      a[i] = sin(i);					// single statement -- no curly braces

---

Caution: Because the increment operator ++ is not yet implemented, use the construction i += 1 instead of i ++ in loop iterations, as shown above. Using the ++ operator will produce a “Not Yet” error message.

---

Shape's While loop construction is identical to that of C. The loop iterates while the conditional expression evaluates to true, or non-zero. For instance, the For loop of the previous example could be rewritten as:

int i;
int a[10];
i = 0
while (i < 10) {
      a[i] = sin(i);
      i += 1;
      }

Shape's continue and break statements are identical to those of C. The continue statement causes execution in a For or While loop to branch to the next iteration of the loop. The break statement causes execution in a loop to branch out of the loop to the next higher loop level or to exit from a singly-nested loop.

The copy function implements a copy on write (COW) functionality for its single argument. Its action lies between that of define (:=) and assign (=) in that it creates a pointer to its argument only if no writes are done to that pointer. However, when the first write to the returned pointer occurs, the copy function copies the data values of the source. This late binding of copying is efficient for routines that access input port data; it prevents Shape programs from writing over input data, but delays making a copy until a write is attempted.

During the read call on an input port, for instance, this looks like:

val := read(iport_Pressure);

slice := val[0];      // uses only the original data
val[0] = slice + 1    // makes a copy of the data before storing 
                      // the incremented values in val

Shape's scatter and gather functions extract data from one array and copy it to another array. The extracted data need not be arranged in a regular pattern, as is required of subshape, below. However, the values are copied rather than simply assigned a pointer, as they would be with subshape. Thus, scatter and gather are more expensive than subshape.

scatter takes three arguments: the destination (dest), index, and source arrays. scatter's functionality implements the mathematical operation:

dest (index) = source

which copies each value from source into the dest position specified by index. Source and dest must have the same type.

The shapes of index, source, and dest must conform, with the last dimension of index equalling the rank of dest and the remaining dimensions of index equalling their respective dimensions in source. For instance, if source is 2 x 3 and dest is 4 x 1 x 6, a valid index would have shape 2 x 3 x 3 and might be [[0,0,0],[0,0,2],[0,0,4]],[[2,0,0],[2,0,1],[2,0,2]]].

With a source of [[1,2,3],[4,5,6]], the dest would be [[[1,x,2,x,3,x]],[[x,x,x,x,x,x]],[[4,5,6,x,x,x]],[[x,x,x,x,x,x]]]

where x denotes the previous value from dest.

gather is a function that returns a gathered array, with two arguments, index and source, interpreted according to the mathematical operation source(index).

gather returns the array of selected values in the same shape as index.

The shape function returns a dimension vector giving the shape of its input argument. For instance, a 128 x 256 lattice with three channels of data (dims = (128,256), nDataVar = 3) would yield an array of shape [256,128,3].

The shape function is commonly used to discover the rank of an array. An array's rank is its number of dimensions—essentially, the shape of the shape. The correct syntax is:

int rank = shape(shape(val))[0];

Writing only

int rank = shape(shape(val)); 

would fail, because the returned shape would be a vector of length 1 rather than a scalar rank. The zero-ordered slice extracts the scalar from its vector position.

The allocate function allocates an array of the given shape and type (such as long or float, as given in the example below) and fills it with values according to the fill_type. The basic syntax is:

allocate(base_type_example, shape, fill_type)

The fill_type must be one of:

fill_none		leave uninitialized
fill_zero		fill with zeros
fill_index		fill with uniform coordinates (with integer indices)
fill_NaN		fill with IEEE NaN symbols allocate(1, [3, 1], fill_index) ==> [[0],[1],[2]] allocate(1, [3, 3, 2], fill_index) ==> [[[0,0],[0,1],[0,2]],[[1,0],[1,1],[1,2]], [[2,0],[2,1],[2,2]]]

The type of the first argument is used to fix the type of the allocated array. You may use a known array or value, use a casted value, such as (byte)1, or use an explicitly typed number, such as 1L for long or 1.0L for double.

Slice extracts a multidimensional slice from an array. It has two syntactical forms. The first one is x[y], where y is a scalar that selects the yth subarray of x, exactly as in C. When you use this form, the sliced array has rank one less than the source. For example, take a 2D array:

A = [[1,2,3], [2,4,6], [4,8,12], [8,16,24]];

Then A[0] = [1, 2, 3], a three-length vector derived from A in the ordinary C manner.

The second form of slice is A[y:z], where y and z are scalars. In this form an array section, or subarray, of A is extracted. The subarray has the same rank as A, but contains only slices x through y. For example, given A, the statement A[0:1] extracts two vectors from the original array, and the shape of the array is 2 x 3. The rank is 2.

In C and Shape, you can write A[0][0] to get the first element of A. In Shape, however, A[0:2][0:1] is different from A[0:2, 0:1]. The respective shapes are 2 x 3 and 3 x 2, because A[0:2][0:1] is the same as A[0:1].

A[0:2][0:1]; 
==> [[1,2,3],[2,4,6]]

The subshape function takes three or four arguments and returns a reference to a subarray (or subsection) of its input array. It does not copy any data. The syntax is:

subshape (start, end, source)

or

subshape (start, end, stride, source)

where start, end, and stride are vectors of size shape(source) that signal the indices of the beginning and end of the array subsection and the strides between successive elements in each dimension. The default stride is 1. For example, with a 10 x 10 source, you can extract the central 2 x 2 square with subshape([4,4],[5,5], source)and extract every other row with subshape([0,0],[10,11],[1,2], source).

An ending index greater than the size of source is legal only if the actual indices used in the computation do not exceed the array bounds. In this example, rows 0, 2, 4, 6, 8, 10 would be extracted, but row 11 would not.

Subshape does not copy data; it returns a reference to the selected subarray.

The stacking operator concatenates arrays of compatible shape to yield a new array of rank one higher. The stacking syntax is:

[expr, expr, ...]

The shape of the stacked array is equal to the shape of the stacked components, with an added component in the slowest varying dimension. That component is the number of stacked arrays. For instance, let:

a:= [1,2,3];
b:= [4,5,6];
c:= [a,b];
==> [[1,2,3],[4,5,6]]

In this case, both a and b have shape [3], while c has shape [2,3]. You can change the stacking dimension with inside.

The send_indices function takes an index permutation vector and a lattice. The permutation controls where each coordinate ends up. As a special case, if permutation indices agree, then a diagonal is taken in those coordinates. For example:

send_indices([1, 0], [[1, 2], [3, 4]]); 

==> [[1,3],[2,4]]

The above example is a transpose of the 2 x 2 matrix because dimensions 0 and 1 were swapped by the [1,0] index vector.

send_indices([0, 0], [[1, 2], [3, 4]]); 
==> [1,4]

The above example is a diagonal of the 2 x 2 matrix because dimensions 0 and 1 were simultaneously selected by the [0,0] index vector.

Min and max take one or more arguments. With two or more, min does an element-wise minimum over all its arguments. With one argument, it performs a reduction by one coordinate. For example, the first statement takes the pointwise minimum of three vectors, while the second finds the minimum element of one vector:

min([1, 2, 3], [4, -2, 6], [7, 8, 9]); 
==> [1, -2, 3]

min([1, 2, -2, 3]); 
==> -2

The dotproduct operator +.* may be used to form the dot product between vectors and/or arrays. This is matrix or tensor multiplication.

[1, 2, 3] +.* [4, 5, 0]; 
==> 14    

[[1, 2], [3, 4]] +.* [5, 6]; 
==> [17, 39]

[5, 6] +.* [[1, 2], [3, 4]]; 
==> [23, 34]

[[1, 2], [3, 4]] +.*[[5, 9], [10, 13]];

The form A+.*B is identical to the function dot_product(A, B). dot_product has an optional third argument, which directs some number of leading coordinates not to be involved in the product, but, rather, to indicate that several matrix multiplications of lower rank are to be performed. For instance, if A and B are [3, 3, 3] dimensional arrays, then dot_product(A, B) has shape [3, 3, 3, 3], while dot_product(A, B, 1) has shape [3, 3, 3]. The former is a single, 3D tensor product, while the latter consists of three 2D matrix products.

Bitproduct resembles as dotproduct, except that it substitutes bit-wise “or” and “and” functions for addition and multiplication. The bitproduct operator is |.&.

The conditional evaluation operator ?: is similar to that of C. When working with scalar values, its operation is identical to that of C, so that

x ? a : b

evaluates to a if x is true (or non-zero) and to b if x is false (or zero). The operator goes beyond the C interpretation in that it can accept arrays as well. In this case, the arrays x, a, and b must be compatibly shaped. For instance, all three could have the same shape, or either a or b could be a scalar.

The array operation of x ? a : b creates an array the size of x but with values chosen from a or b, depending on the values of x. Scalars a and b are promoted to constant-filled arrays the shape of x, but no additional storage is allocated.

The argument to the inside form is evaluated with different indexing rules than normal. The four array operations — indexing, concatenation (stacking), promotion, and reduction — start from the opposite end of the shape vector. For instance, A[0] selects the first slice of A in the slowest varying dimension, while inside(A[0]) selects the first slice of A in the fastest varying dimension. The former is a blocked selection, while the latter is an interleaved selection. For example:

v := [1, 2]; w := [3, 4];
[v,w];
==> [[1,2],[3,4]]

inside([v, w]); 
==> [[1,3],[2,4]]

m := [[1, 2], [3, 4]]; 
inside(m[0]); 
==> [1, 3]

v := [0, 0]; inside(v += m); 
==> [4, 6]

inside(m + [5, 6]); 
==> [[6,7],[8,9]]

The outside argument evaluates its argument with the default indexing rules. For example:

v := [1, 2]; w := [3, 4];
outside([v, w]); 
==> [[1,2],[3,4]]

m := [[1, 2], [3, 4]]; 
outside(m[0]); 
==> [1, 2]

v := [0, 0]; outside(v += m); 
==> [3, 7]

outside(m + [5, 6]); 
==>

The insideout argument evaluates its argument with the opposite of the current indexing rules. Thus, insideout(inside(expr)); and outside(expr); are equivalent.

The list function is used to concatenate two or more arrays in Shape. This can be useful when passing several arguments to a user function, or when assembling arguments for use in a map or apply call. The syntax for this function is:

list(array [, array] ...)

list uses parentheses (), not square brackets []. It can build arbitrarily complex, heterogenous structures. list(1,2,3) is not equal to [1,2,3]. For example, to create and then concatenate two scalars and a two-vector:

x := 1;
==>x

y := 2;
==>y

z := [3,4];
==>z

list(x,y,z);
==>(1 2 [3 4])

The two functions list_first and list_rest decompose lists, extracting the first and all but the first list elements, respectively. For instance, if a is:

(1, 2, 3), then 
list_first(a);
==> 1
list_rest(a);
==> (2,3)

For perimeter coordinates, the Shape array structure is a list of vectors, one for each coordinate dimension of the lattice. For instance, 3D data with perimeter coordinates has three vectors in a list: the first vector represents the X dimension, and the second and third represent the Y and Z dimensions, respectively.

You can access the list of vectors with the list processing commands, list_first and list_rest, which return the first element of a list and the remainder of the list, respectively. For instance, to access the X, Y, and Z vectors of a perimeter lattice, you could use:

X_vector := list_first(Perim_Data_coord);
Y_vector := list_first(list_rest(Perim_Data_coord));
Z_vector := list_first(list_rest(list_rest(Perim_Data_coord)));

On output, such a list is interpreted as perimeter coordinates for a lattice. You can construct a list using the list function and the nil token. You will need either to write LatFunction routines to handle all coordinate types or else restrict inputs to a known type, using the Module Builder.

The functions map and apply are used to run a Shape function on a set of inputs. The syntax for these functions is:

map(func, list...)
apply(func, list...)

The effects of the calls are different in that map runs the named function on each item in the list of inputs, whereas apply runs the named function on the concatenated list as a single input:

map(sin, list(0, 1, 2, 3));
==>(0 0.841471 0.909297 0.14112)

This is equivalent to concatenating several calls to sin.

sin(0);
==>0

sin(1);
==>0.841471

sin(2);
==>0.909297

sin(3);
==>0.14112

When the list has several arrays in it, the sin function works on each input:

map(sin, list([1, 2, 3], [4, 5], [1.1]));
==>([0.841471, 0.909297, 0.14112],
   [-0.756802, -0.958924],[0.8912007])

This is equivalent to concatenating several calls to sin.

sin([1, 2, 3]);
==>[0.841471 0.909297 0.14112]

sin([4, 5]);
==>[-0.756802 -0.958924]

sin([1.1]);
==>[0.891207]

The apply function treats the list as the list of inputs to a single call of the named function.

apply(min, list(3, 4));
==>3

This is equivalent to the call:

min(3, 4);
==>3

but is different from the concatenation of calls:

min(3);
==>3

min(4);
==>4

The functions pair_p and null_p are Boolean predicate functions, each of which indicates the list status of its argument. Thus, pair_p returns true (non-zero) if its argument is a list of at least two elements, while null_p returns true if its argument is the empty list of no elements.