Module `ateams.arithmetic`

Functions

def ComputePersistencePairs(boundary, filtration, homology, breaks)

Computes the persistence pairs of the complex corresponding to the provided boundary matrix and filtration.

Args

boundary : np.array: Flattened boundary matrix given by Complex.matrices.full.
filtration : np.array: Permutation on the order of the columns of the boundary matrix. Here, we assume that only cells of dimension homology are being permuted. Shuffling the order of cells of different dimensions will result in incorrect computations.
homology : int: Homology group we're interested in; corresponds to the dimension of permuted cells.
breaks : np.array: Index ranges for cells by dimension, given by Complex.breaks.

Returns

A list of [birth, death] pairs.

def ReducedKernelSample(coboundary, zeros, faces, columns, p, verbose)

Uses the SpaSM sparse Gaussian elimination strategy to sample uniformly from the kernel of the submatrix of the coboundary matrix.

Args

coboundary: Memory-contiguous one-dimensional coboundary array, like that of the Cubical Complex object.
zeros: Memory-contiguous array of row indices that will be included in the coboundary submatrix.
faces: The number of faces per plaquette.
columns: Integer representing the number of columns in the coboundary submatrix; should be the total number of faces in the complex.
p: Characteristic of the field $\mathbb Z/p\mathbb Z$ .

Returns

A C++ std::vector with spin assignments.

def SubReducedKernelSample(coboundary, zeroRows, zeroColumns, p, verbose)

Uses the SpaSM sparse Gaussian elimination strategy to sample uniformly from the kernel of the submatrix of the coboundary matrix.

Args

coboundary: Memory-contiguous one-dimensional coboundary array, like that of the Cubical Complex object.
zeros: Memory-contiguous array of row indices that will be included in the coboundary submatrix.
p: Characteristic of the field $\mathbb Z/p\mathbb Z$ .

Returns

A C++ std::vector with spin assignments.

Classes

class Twist (...)

Implements the twist_reduce algorithm from Chen and Kerber (2011) and PHAT (2017). Implemented as a class so we minimally re-compute boundary matrix things; we also move away from NumPy integers and toward C-style ones for compatibility.

Args

characteristic : char: Characteristic of the finite field $\mathbb Z/p\mathbb Z$ .
boundary : np.ndarray: The full flattened boundary matrix. Given a complex C (e.g. Cubical), C.matrices.full.
breaks : np.ndarray: Indices at which cells of a new dimension begin in boundary. Given a complex C (e.g. Cubical), C.breaks.
cellCount : int: Total number of cells in the complex. Given a model M (e.g. SwendsenWang), M.cellCount.
dimension : int: Dimension of percolation. Given a model M (e.g. SwendsenWang), M.dimension.
__DEBUG : bool: Do we want to run in debug mode? This shows standard error stream output from the matrix reducers.

For example,

from ateams.complexes import Cubical
from ateams.arithmetic import Twist
import numpy as np

# Create a lattice; set the cell count, dimension, field characteristic.
C = Cubical().fromCorners([3,3])
cellCount = len(C.flattened)
dimension = 1
field = 3

# Create the Twist object.
Twister = Twist(field, C.matrices.full, C.breaks, cellCount, dimension)

# Construct a filtration and compute the percolation events.
filtration = np.arange(cellCount)
essential = Twist.LinearComputePercolationEvents(filtration)

In this case, essential should be {0, 17, 35, 21}, and the times $17$ and $21$ are the essential $1$ -dimensional cycles.

Methods

def LinearComputeBasis(self)

Computes bases for the dimensionth homology group.

Returns

A Basis (equivalently, a BoundaryMatrix) of sparse vectors that form the basis for the dimensionth homology group.

def LinearComputeCobasis(self)

Computes a basis for the dimensionth cohomology group, relative to the basis chosen by Twist.LinearComputeBasis().

Returns

A Basis (equivalently, a BoundaryMatrix) of sparse vectors that form the basis for the dimensionth homology group.

def LinearComputePercolationEvents(self, filtration)

NOTE: Twist.RankComputePercolationEvents() is recommended for general use.

Given a filtration — i.e. a reordering of the columns of the full boundary matrix — gives times at which essential cycles of dimension dimension were created. Performs arithmetic using flattened addition and multiplication tables stored in vector<char>s.

Args

filtration : np.ndarray: An array of column indices.

Returns

A set containing indices at which essential cycles appear.

def RankComputePercolationEvents(self, filtration, stop=0)

Given a filtration — i.e. a reordering of the columns of the full boundary matrix — gives times at which giant cycles of dimension dimension were created.

Args

filtration : np.ndarray: An array of column indices.
stop : int=0: The rank at which we stop searching. For example, if we're computing persistence on a 4-torus and stop is 3, then we find only the time at which the third giant cycle was born. If stop is 0 (or falsy), then find all the birth times.

Returns

A set containing indices at which essential cycles appear.