Special Complex Functions

create_simplicial_complex(labels::Vector{String},
                          simplices::Vector{Vector{Int}};
                          p::Int=2)

Initialize a Lefschetz complex from a simplicial complex. The complex is over the rationals if p=0, and over GF(p) if p>0.

The vector labels contains a label for every vertex, while simplices contains all the highest-dimensional simplices necessary to define the simplicial complex. Every simplex is represented as a vector of Int, with entries corresponding to the vertex indices.

create_simplicial_complex(labels::Vector{String},
                          simplices::Vector{Vector{String}};
                          p::Int=2)

Initialize a Lefschetz complex from a simplicial complex. The complex is over the rationals if p=0, and over GF(p) if p>0.

The vector labels contains a label for every vertex, while simplices contains all the highest-dimensional simplices necessary to define the simplicial complex.

create_simplicial_rectangle(nx::Int, ny::Int; p::Int=2)

Create a simplicial complex covering a rectangle in the plane. The complex is over the rationals if p=0, and over GF(p) if p>0.

The rectangle is given by the subset [0,nx] x [0,ny] of the plane. Each unit square is represented by four triangles, which meet in the center point of the square. Labels have the following meaning:

• The label XXXYYYb corresponds to the point (XXX, YYY).
• The label XXXYYYc corresponds to (XXX + 1/2, YYY + 1/2).

The number of characters in XXX and YYY matches the number of digits of the larger number of nx and ny. The function returns the following objects:

• A simplicial complex sc::LefschetzComplex.
• A vector coords::Vector{Vector{Float64}} of vertex coordinates.

create_simplicial_delaunay(boxw::Real, boxh::Real, pdist::Real, attmpt::Int;
                           p::Int=2)

Create a planar Delaunay triangulation inside a box. The complex is over the rationals if p=0, and over GF(p) if p>0.

The function selects a random sample of points inside the rectangular box [0,boxw] x [0,boxh], while trying to maintain a minimum distance of pdist between the points. The argument attmpt specifies the number of attempts when trying to add points. A standard value is 20, and larger values tend to fill holes better, but at the expense of runtime. From the random sample, the function then creates a Delaunay triangulation, and returns the following objects:

• A simplicial complex sc::LefschetzComplex.
• A vector coords::Vector{Vector{Float64}} of vertex coordinates.

Note that the function does not provide a full triangulation of the given rectangle. Close to the boundary there will be gaps.

create_simplicial_delaunay(boxw::Real, boxh::Real, npoints::Int;
                           p::Int=2)

Create a planar Delaunay triangulation inside a box. The complex is over the rationals if p=0, and over GF(p) if p>0.

The function selects a random sample of npoints points inside the rectangular box [0,boxw] x [0,boxh]. From the random sample, the function then creates a Delaunay triangulation, and returns the following objects:

• A simplicial complex sc::LefschetzComplex.
• A vector coords::Vector{Vector{Float64}} of vertex coordinates.

Note that the function does not provide a full triangulation of the given rectangle. Close to the boundary there will be gaps.

sc = simplicial_torus(p::Int)

Create a triangulation of the two-dimensional torus.

The function returns a simplicial complex which represents a two-dimensional torus. The argument p specifies the characteristic of the underlying field. This triangulation is taken from Figure 6.4 in Munkres' book on Algebraic Topology. The boundary vertices are labeled as letters as in the book, the five center vertices are labeled by 1 through 5.

Examples

julia> println(homology(simplicial_torus(0)))
[1, 2, 1]

julia> println(homology(simplicial_torus(2)))
[1, 2, 1]

julia> println(homology(simplicial_torus(3)))
[1, 2, 1]

sc = simplicial_klein_bottle(p::Int)

Create a triangulation of the two-dimensional Klein bottle.

The function returns a simplicial complex which represents the two-dimensional Klein bottle. The argument p specifies the characteristic of the underlying field. This triangulation is taken from Figure 6.6 in Munkres' book on Algebraic Topology. The boundary vertices are labeled as letters as in the book, the five center vertices are labeled by 1 through 5.

Examples

julia> println(homology(simplicial_klein_bottle(0)))
[1, 1, 0]

julia> println(homology(simplicial_klein_bottle(2)))
[1, 2, 1]

julia> println(homology(simplicial_klein_bottle(3)))
[1, 1, 0]

sc = simplicial_projective_plane(p::Int)

Create a triangulation of the projective plane.

The function returns a simplicial complex which represents the projective plane. The argument p specifies the characteristic of the underlying field. This triangulation is taken from Figure 6.6 in Munkres' book on Algebraic Topology. The boundary vertices are labeled as letters as in the book, the five center vertices are labeled by 1 through 5.

Examples

julia> println(homology(simplicial_projective_plane(0)))
[1, 0, 0]

julia> println(homology(simplicial_projective_plane(2)))
[1, 1, 1]

julia> println(homology(simplicial_projective_plane(3)))
[1, 0, 0]

sc = simplicial_torsion_space(n::Int, p::Int)

Create a triangulation of a space with 1-dimensional torsion.

The function returns a simplicial complex which has the following integer homology groups:

• In dimension 0 it is the group of integers.
• In dimension 1 it is the integers modulo n.
• In dimension 2 it is the trivial group.

In other words, the simplicial complex has nontrivial torsion in dimension 1. It is a triangulation of an n-gon, in which all boundary edges are oriented counterclockwise, and all of these edges are identified. The parameter p specifies the characteristic of the underlying field.

Examples

julia> println(homology(simplicial_torsion_space(6,2)))
[1, 1, 1]

julia> println(homology(simplicial_torsion_space(6,3)))
[1, 1, 1]

julia> println(homology(simplicial_torsion_space(6,5)))
[1, 0, 0]

create_cubical_complex(cubes::Vector{String}; p::Int=2)

Initialize a Lefschetz complex from a cubical complex. The complex is over the rationals if p=0, and over GF(p) if p>0.

The vector cubes contains a list of all the highest-dimensional cubes necessary to define the cubical complex. Every cube is represented as a string as follows:

• d integers, which correspond to the coordinates of a point in d-dimensional Euclidean space
• a point .
• d integers 0 or 1, which give the interval length in the respective dimension

The first d integers all have to occupy the same number of characters. In addition, if the occupied space is L characters for each coordinate, the coordinates only can take values from 0 to 10^L - 2. This is due to the fact that the boundary operator will add one to certain coordinates, and they still need to be representable withing the same L digits.

For example, the string 030600.101 corresponds to the point (3,6,0) in three dimensions. The dimensions are 1, 0, and 1, and therefore this string corresponds to the cube [3,4] x [6] x [0,1]. The same cube could have also been represented by 360.101 or by 003006000.101.

Example

julia> cubes = ["00.11", "01.01", "02.10", "11.10", "11.01", "22.00"];

julia> lc = create_cubical_complex(cubes);

julia> lc.ncells
17

julia> homology(lc)
3-element Vector{Int64}:
 2
 1
 0

create_cubical_rectangle(nx::Int, ny::Int;
                         p::Int=2, randomize::Real=0.0)

Create a cubical complex covering a rectangle in the plane. The complex is over the rationals if p=0, and over GF(p) if p>0.

The rectangle is given by the subset [0,nx] x [0,ny] of the plane, and each unit square gives a two-dimensional cube in the resulting cubical complex. The function returns the following objects:

• A cubical complex cc::LefschetzComplex
• A vector coords::Vector{Vector{Float64}} of vertex coordinates

If the optional parameter randomize is assigned a positive real fraction r less that 0.5, then the actual coordinates will be randomized. They are chosen uniformly from discs of radius r centered at each vertex.

create_cubical_box(nx::Int, ny::Int, nz::Int;
                   p::Int=2, randomize::Real=0.0)

Create a cubical complex covering a box in space. The complex is over the rationals if p=0, and over GF(p) if p>0.

The box is given by the subset [0,nx] x [0,ny] x [0,nz] of space, and each unit cube gives a three-dimensional cube in the resulting cubical complex. The function returns the following objects:

• A cubical complex cc::LefschetzComplex
• A vector coords::Vector{Vector{Float64}} of vertex coordinates

If the optional parameter randomize is assigned a positive real fraction r less that 0.5, then the actual coordinates will be randomized. They are chosen uniformly from balls of radius r centered at each vertex.

cube_field_size(cube::String)

Determine the field sizes of a given cube label.

The function returns the dimension of the ambient space in the first output parameter pointdim, and the length of the individual coordinate fields in the second return variable pointlen.

Example

julia> cube_field_size("011654003020.0110")
(4, 3)

cube_information(cube::String)

Compute a cube's coordinate information.

The function returns an integer vector with the cubes coordinate information. The return vector intinfo contains in its components the following data:

• 1:pointdim: Coordinates of the anchor point
• 1+pointdim:2*pointdim: Interval length in each dimension
• 1+2*pointdim: Dimension of the cube

Note that pointdim equals the dimension of the points specifying the cube.

Example

julia> cube_information("011654003.011")
7-element Vector{Int64}:
  11
 654
   3
   0
   1
   1
   2

cube_label(pointdim::Int, pointlen::Int, pointinfo::Vector{Int})

Create a label from a cube's coordinate information.

The dimension of the ambient Eucliden space is pointdim, while the field length for each coordinate is pointlen. The vector pointinfo has to be of length at least two times pointdim. The first pointdim entries contain the coordinates of the anchor point, while the next pointdim entries are either 0 or 1 depending on the size of the interval. For example, if poindim = 3 and pointinfo = [1,2,3,1,0,1], then we represent the cube in three-dimensional space given by [1,2] x [2] x [3 4].

Example

julia> cube_label(3,2,[10,23,5,1,1,0])
"102305.110"

get_cubical_coords(cc::LefschetzComplex)

Compute the vertex coordinates for a cubical complex.

The variable cc has to contain a cubical complex, and the function returns a vector of coordinates for the vertices of the complex, that can then be used for plotting. ```

convert_cells(lc::LefschetzComplex, cl::Vector{Int})

Convert cell list cl in the Lefschetz complex lc from index form to label form.

convert_cells(lc::LefschetzComplex, cl::Vector{String})

Convert cell list cl in the Lefschetz complex lc from label form to index form.

convert_cellsubsets(lc::LefschetzComplex, clsub::Vector{Vector{Int}})

Convert CellSubsets clsub in the Lefschetz complex lc from index form to label form.

convert_cellsubsets(lc::LefschetzComplex, clsub::Vector{Vector{String}})

Convert CellSubsets clsub in the Lefschetz complex lc from label form to index form.

cellsubset_bounding_box(lc, coords, csubset)

Compute the bounding box for a cell subset.

For the Lefschetz complex lc::LefschetzComplex, whose vertices have the coordinates given in coords::Vector{<:Vector{<:Real}}, this function computes the smallest enclosing box for the closure of the cell subset given in csubset::Cells. The function returns the coordinates bmin and bmax of the minimal and maximal corners of the box, respectively.

cellsubset_distance(lc, coords, csubset, dpoint)

Compute the distance of a cell subset from a point.

For the Lefschetz complex lc::LefschetzComplex, whose vertices have the coordinates given in coords::Vector{<:Vector{<:Real}}, this function computes the smallest distance of the vertices in the closure of the cell subset given in csubset::Cells from the point given in dpoint::Vector{<:Real}.

cellsubset_planar_area(lc, coords, csubset)

Compute the area of a planar cell subset.

For the Lefschetz complex lc::LefschetzComplex, whose vertices have the coordinates given in coords::Vector{<:Vector{<:Real}}, this function computes the area of the cell subset given in csubset::Cells. The function assumes that the complex is two-dimensional and that the maximal 2-cells in the cell subset are all polygonal with straight boundary edges. If these conditions are not met an error is raised.

locate_planar_cellsubsets(lc, coords, csubsets, rmin, rmax)

Locate cell subsets relative to a planar rectangle.

For the Lefschetz complex lc::LefschetzComplex, whose vertices have the coordinates given in coords::Vector{<:Vector{<:Real}}, and the cell subsets in csubsets::CellSubsets this function extracts the indices of all cell subset closures which lie in the interior, or intersect the boundary of the rectangle specified by the minimal and maximal corners rmin::Vector{<:Real} and rmax::Vector{<:Real}, respectively. The function returns

• indexI::Vector{Int}: indices of cell subset closures inside the rectangle,
• indexB::Vector{Int}: indices of cell subset closures which intersect the rectangle boundary.

locate_planar_cellsubsets(lc, coords, csubsets, c, r)

Locate cell subsets relative to a planar circle.

For the Lefschetz complex lc::LefschetzComplex, whose vertices have the coordinates given in coords::Vector{<:Vector{<:Real}}, and the cell subsets in csubsets::CellSubsets this function extracts the indices of all cell subset closures which lie in the interior, or intersect the boundary of the circle specified by the center point c::Vector{<:Real} and radius r::Real. The function returns

• indexI::Vector{Int}: indices of cell subset closures inside the circle,
• indexB::Vector{Int}: indices of cell subset closures which intersect the circle.

cellsubset_location_rectangle(lc, coords, csubset, rmin, rmax)

Determine the location of a cell subset relative to a rectangle.

For the Lefschetz complex lc::LefschetzComplex, whose vertices have the coordinates given in coords::Vector{<:Vector{<:Real}}, this function determines the location of the closure of the cellsubset given in csubset::Cells relative to the rectangle specified by the minimal and maximal corners rmin::Vector{<:Real} and rmax::Vector{<:Real}, respectively. The function returns

• 1 if the set lies in the interior of the rectangle,
• 2 of the set intersects the rectangle boundary, and
• 3 if the set lies in the exterior of the rectangle.

cellsubset_location_circle(lc, coords, csubset, c, r)

Determine the location of a cell subset relative to a circle.

For the Lefschetz complex lc::LefschetzComplex, whose vertices have the coordinates given in coords::Vector{<:Vector{<:Real}}, this function determines the location of the closure of the cellsubset given in csubset::Cells relative to the circle specified by the center point c::Vector{<:Real} and the radius r::Real. The function returns

• 1 if the set lies in the interior of the circle,
• 2 of the set intersects the circle, and
• 3 if the set lies in the exterior of the circle.

convert_planar_coordinates(coords::Vector{<:Vector{<:Real}},
                           p0::Vector{<:Real},
                           p1::Vector{<:Real})

Convert a given collection of planar coordinates.

The vector coords contains pairs of coordinates, which are then transformed to fit into the box with vertices p0 = (p0x,p0y) and p1 = (p1x,p1y). It is assumed that p0 denotes the lower left box corner, while p1 is the upper right corner. The function shifts and scales the coordinates in such a way that every side of the box contains at least one point. Upon completion, it returns a new coordinate vector coordsNew.

More precisely, if the x-coordinates are spanning the interval [xmin,xmax] and the y-coordinates span [ymin,ymax], then the point (x,y) is transformed to (xn,yn) with:

• xn = p0x + (p1x-p0x) * (x-cxmin) / (cxmax-cxmin)
• yn = p0y + (p1y-p0y) * (y-cymin) / (cymax-cymin)

convert_spatial_coordinates(coords::Vector{<:Vector{<:Real}},
                            p0::Vector{<:Real},
                            p1::Vector{<:Real})

Convert a given collection of spatial coordinates.

The vector coords contains triples of coordinates, which are then transformed to fit into the box with vertices p0 = (p0x,p0y,p0z) and p1 = (p1x,p1y,p1z). It is assumed that each coordinate of p0 is strictly smaller than the corresponding coordinate of p1. The function shifts and scales the coordinates in such a way that every side of the box contains at least one point. Upon completion, it returns a new coordinate vector coordsNew.

More precisely, if the x-coordinates are spanning the interval [xmin,xmax], the y-coordinates span [ymin,ymax], and the z-coordinates span [zmin,zmax], then the point (x,y,z) is transformed to (xn,yn,zn) with:

• xn = p0x + (p1x-p0x) * (x-cxmin) / (cxmax-cxmin)
• yn = p0y + (p1y-p0y) * (y-cymin) / (cymax-cymin)
• zn = p0z + (p1z-p0z) * (z-czmin) / (czmax-czmin)

signed_distance_rectangle(p, rmin, rmax)

Compute the signed distance from a point to a rectangle.

The point in question is given as p::Vector{<:Real}. The rectangle has to be parallel to the coordinate axes and is given via its lower left corner rmin::Vector{<:Real} and its upper right corner rmax::Vector{<:Real}. The function returns the signed distance, which is negative inside the rectangle, and positive outside.

signed_distance_circle(p, c, r)

Compute the signed distance from a point to a circle.

The point is specified as p::Vector{<:Real}, while the circle is given by its center point c::Vector{<:Real} and radius r::Real. The function returns the signed distance, which is negative inside the circle, and positive outside.

segment_intersects_rectangle(p1, p2, rmin, rmax)

Determine whether a line segment intersects a rectangle boundary.

The endpoints of the line segment are specified in the form p1,p2::Vector{<:Real}. The rectangle is parallel to the coordinate axes and is given via its lower left corner rmin::Vector{<:Real} and its upper right corner rmax::Vector{<:Real}. The function returns true if the line segment intersects the rectangle boundary, otherwise false.

segment_intersects_circle(p1, p2, c, r)

Determine whether a line segment intersects a circle.

The endpoints of the line segment are specified in the form p1,p2::Vector{<:Real}, while the circle is given by its center point c::Vector{<:Real} and radius r::Real. The function returns true if the line segment intersects the circle, otherwise it returns false.