Below is an introduction to some running code. This note is written to provide a high level introduction to some obscure code. It is written after getting a good deal of the code working. Earlier notes were written before or during code development.

Topologists have found that a large class of the spaces they study can be decomposed into zones that overlap only on their boundaries and are all topologically equivalent to the closed ball. In n dimensions these balls need no more than n+1 neighbors.

Here we require enough metric properties of the space to make it look locally Euclidean. By some accounts the simplest way of partitioning an n-dimensional manifold is into n-simplexes, called zones here, which are topologically equivalent to a ball. The intersection of two zones is either empty, or consists of a simplex. If the simplex is of n−1 dimensions the simplex is called a facet and the zones are neighbors of each other. A modest number of simplexes are required to retain the topological properties of a space, but in the limit of more and smaller simplexes Regge observed that each simplex can be considered to be a flat space while doing ever less damage to the given metric properties. With small simplexes this simplical complex can approach the metric properties of the manifold. The model must include the neighbor relationship and the lengths of the edges (1-simplexes).

Two inputs to these programs are data structures, top, topology and ds2, the metric.


We approximate an n dimensional manifold with a set of closed n-simplexes, called zones, whose union approximates the manifold. An (n−1)-simplex is a facet and when two distinct zones, A and B, have the same facet as a subset, A and B are neighbors.

There is a long history defining the topology of a space by specifying which simplexes are neighbors of which other simplexes. We define our topology by assuming an abstract enumerated set of vertices, which are 0-simplexes, and specifying each zone of the model by indicating its n+1 vertices within the abstract vertex set. This determines when two zones are neighbors as when their vertex sets differ in just one vertex. Zones {3, 4, 6, 8} and {3, 6, 8, 9} are neighbors for they share the facet {3, 6, 8}.

Such a conglomeration of simplexes is often called a complex, which is a term we use. Some manifolds are oriented, and others, such as the Möbeus strip or Klein bottle, are not. The same dichotomy applies to complexes. This code demands oriented complexes; it would probably be not too much trouble to ease this restriction. Here is a nice oriented simplicial complex.

This code takes a topology data set in our format and returns the boundary of the complex, which is a complex of one fewer dimensions in the same format. It does nothing else but this is a modification of that code, renamed as morphgen to take on the extra task of introducing neighbors to each other as it discovers the mates of facets of the provided zones. morphgen returns the boundary of the complex consisting of the unmated facets. These left over facets come with the hooks that their missing neighbors would have been given and thus allows signaling from the boundary, if any, of the complex.

We use two sorts of coordinate system within the complex and sometimes another outside in case of an embedded complex:

Vertex Numbering

A vexing and confusing issue is how zone logic names its vertices and facets, and how it communicates with its neighbors so that they will not confuse the identities of the vertices of the shared facet. A facet is always opposite a unique vertex and conversely. We take from Euclid the practice of using related names. Actually we number both with numbers from 0 to n, inclusive. Vertex j is opposite facet j. We always choose vertex n as the origin and the basis vectors for the zone are the n edges from vertex n to vertex j, for 0≤j<n. Vectors and tensors in the zone tend to be redundant having indices running from 0 thru n.

Facet coordinates omit one basis vector, and thus one component, compared with either neighbor and either neighbor knows which this omitted vector is. If j < n then facet j of a zone uses all of the zone’s basis vectors except the one running from vertex n to vertex j. Facet n of a zone shares no basis vectors with the zone, but the transformation is still fast, if confusing. The ordering of local vertex numbering is assigned by logic in routine which always chooses to make the ordering the same as the global vertex numbering. Thus as a vector moves from one zone to a neighbor the vector representation is first transformed (cvz2f) by abandoning the basis vector not in the shared facet and adopting the normal to the facet. The coefficient for this facet normal basis is placed at the end of the fbcc vector representation, as vector component n−1. The vector representation elides the position for the abandoned basis vector and the component for the normal goes at the end of the array. Then the message is passed to the neighbor who abandons the shared normal basis element and adopts (cvf2z) its own basis vector, not in the facet. These two transformations together are less work than a general matrix multiply.


It turns out that the distances between pairs of vertices of a zone is necessary and just sufficient to tell zone logic the shape of the zone. Actually the distance squared is even better information for then we can make that negative and describe Minkowski’s space. The natural coordinates within a zone are barycentric which are oblique coordinates which require a metric tensor in just the form used by differential geometry. The metric tensor is constant thruout the zone. morphgen is given an extra argument which is a routine that knows how to compute these squared distances and deliver them to the new zone objects as creates them. Currently the routine is the only argument to morphgen and it derives the information from known embedding information.

When a ray enters a zone across a facet, the zone logic converts the position and direction vectors of the ray from facet coordinates, fbcc, to zone coordinates, zbcc, and considers that it is receding from the first facet and approaching some of the other facets. The sign of the respective zbcc components of the ray’s direction vector provide this information directly. For each facet that the ray is approaching, a simple division determines how soon it would reach that facet. That earliest facet is selected for egress and the new position is computed and converted to the coordinates of that facet and the new neighbor is informed.


Routine constructs an n-complex in an n dimensional Euclidean space as illustrated here and here. The argument embd is an array of Cartesian coordinates, one per vertex. The global vertex number serves to index into embd to retrieve the coordinates of that vertex according to the embedding. More detail here.

Routine jig is specialized for embedding an n-complex in a Euclidean n-space. It provides means for injecting a ray into the complex and catching it as it emerges. With the help of prep it accepts the input and reports the output in the surrounding Cartesian coordinates. Just now it requires the test builder to predict which boundary facet the ray will emerge from.

The input data set top specifies an oriented zone by giving an even permutation of the vertices. Other parts of the computation insist on the vertex lists being in order but accompanied with a boolean stating the orientation.