Structures

SICMUtils supports a variety of structured object types, such as

The explicit constructor for a structured object is a procedure whose name is what we call objects of that type. For example, we make explicit vectors with the procedure named vector, and explicit lists with the procedure named list. For example:

There is no natural way to notate a matrix, except by giving its rows (or columns). To make a matrix with three rows and five columns:

A power series may be constructed from an explicit set of coefficients. For example:

is the power series whose first five coefficients are the first five positive integers and all of the rest of the coefficients are zero.

Although each datatype has its own specialized procedures, there are a variety of generic procedures for selecting the components from structured objects. To get the n-th component from a linear data structure, v, such as a vector or a list, one may in general use the generic selector, ref (or nth, the native Clojure operation that we recommend you prefer):

All structured objects are accessed by zero-based indexing, as is the custom in Clojure programs and in relativity. For example, to get the third element (index = 2) of a vector or a list we can use:

If M is a matrix, then the component in the i-th row and j-th column can be obtained by (ref M i j) (or (get-in M [i j]). For the matrix given above:

Other structured objects are more magical:

The magic is due to Clojure’s beautiful Sequence API. All native collections can be turned into generic sequences. SICMUtils containers all implement this interface, and respond appropriately to seq.

The number of components of a structured object can be found with the count function:

Besides the extensional constructors, most structured-object datatypes can be intentionally constructed by giving a procedure whose values are the components of the object. These generate procedures are:

For example, one may make a 6 component vector each of whose components is pi times the index of that component, as follows:

Or a 3x5 matrix whose components are

Also, it is commonly useful to deal with a structured object in an elementwise fashion. We provide special combinators for many structured datatypes that allow one to make a new structure, of the same type and size of the given ones, where the components of the new structure are the result of applying the given procedure to the corresponding components of the given structures.

Thus, vector addition is equivalent to (vector:elementwise +).

We identify the Clojure vector data type with mathematical n-dimensional vectors. These are interpreted as up tuples when a distinction between up tuples and down tuples is made.

We inherit from Clojure the vector constructor, as well as the literal [x y z] form of construction. Select elements with nth. count returns the length of a vector. We also get the type predicate vector?.

In the documentation that follows, <v> will stand for a vector-valued expression. Operations on vectors typically return an up structure, which is equivalent but explicit about its variance.

Simple arithmetic on vectors is componentwise:

There are a variety of products defined on vectors.

Cross product only makes sense for 3-dimensional vectors.

The product of two vectors makes an outer product structure:

(v:make-basis-unit <n> <i>)

Makes the n-dimensional basis unit vector with zero in all components except for the i-th component, which is one.

Sometimes it is advantageous to distinguish down tuples and up tuples. If the elements of up tuples are interpreted to be the components of vectors in a particular coordinate system, the elements of the down tuples may be thought of as the components of the dual vectors in that coordinate system. The union of the up tuple and the down tuple data types is the data type we call "structures."

Structures may be recursive and they need not be uniform. Thus it is possible to have an up structure with three components: the first is a number, the second is an up structure with two numerical components, and the third is a down structure with two numerical components. Such a structure has size (or length) 3, but it has five dimensions.

In SICMUtils, Clojure vectors are interpreted as up tuples, and the down tuples are distinguished. The predicate structure? is true of any down or up tuple, but the two can be distinguished by the predicates up? and down?.

In the following, <s> stands for any structure-valued expression; <up> and <down> will be used if necessary to make the distinction.

The generic kind operation distinguishes the types:

We reserve the right to change this implementation to distinguish Clojure vectors from up tuples. Thus, we provide (identity) conversions between vectors and up tuples.

Constructors are provided for these types, analogous to list and vector:

The dimension of a structure is the number of entries, adding up the numbers of entries from substructures. The dimension of any structure can be determined by

Processes that need to traverse a structure need to know the number of components at the top level. This is the length of the structure:

The i-th component (zero-based) can be accessed by:

For example:

As usual, the generic ref procedure or the native get-in can recursively access substructure:

Given a structure <s> we can make a new structure of the same type with <x> substituted for the <n>-th component of the given structure using assoc:

We can construct an entirely new structure of length <n> whose components are the values of a procedure using s:generate:

The up/down argument may be either ::structure/up or ::structure/down.

The following generic arithmetic operations are defined for structures.

(zero? <s>) ;;⇒ <boolean>

is true if all of the components of the structure are zero.

(zero-like <s>) ;;⇒ <s>

produces a new structure with the same shape as the given structure but with all components being zero-like the corresponding component in the given structure.

produce new structures which are the result of applying the generic procedure elementwise to the given structure.

is true only when the corresponding components are =.

These are componentwise addition and subtraction.

magically does what you want: If the structures are compatible for contraction the product is the contraction (the sum of the products of the corresponding components.) If the structures are not compatible for contraction the product is the structure of the shape and length of <s2> whose components are the products of <s1> with the corresponding components of <s2>.

Structures are compatible for contraction if they are of the same length, of opposite type, and if their corresponding elements are compatible for contraction (or if either paired-up element is not a structure).

It is not obvious why this is what you want, but try it, you’ll like it!

For example, the following are compatible for contraction:

Two up tuples are not compatible for contraction. Their product is an outer product:

This product is not generally associative or commutative. It is commutative for structures that contract, and it is associative for structures that represent linear transformations.

To yield additional flavor, the definition of square for structures is inconsistent with the definition of product. (It’s defined as the dot-product of the structures.)

It is possible to square an up tuple or a down tuple. The result is the sum of the squares of the components. This makes it convenient to write such things as (/ (square p) (* 2 m)), but it is sometimes confusing.

Some structures, such as the ones that represent inertia tensors, must be inverted. (The m above may be an inertia tensor!)

Division is arranged to make this work, when possible. The details are too hairy to explain in this short document. We probably need to write a book about this!