Skip to content

From inputs to computed objects

Download the executed notebook · Build and environment record

Suppose we know how a shape grows, and want to follow its connected components. We can construct a persistence module from that filtration. We might instead know the vector spaces and maps we want from the outset, perhaps by specifying the region where a class is present. Both starting points lead to a finite encoding, which gives us spaces and maps to inspect and use in further calculations.

We will try each route: first with two points, then with a sloped strip in the parameter plane. After recovering a space and a map from each encoding, we will construct the same kind of kernel on both finite modules. This gives us a way to see what the common interface means mathematically.

You need basic vector spaces, matrices and coordinatewise comparison of pairs. Persistence modules introduces those ideas, and finite encodings explains how the finite model represents the original parameters. To run the guide, use Julia 1.12 with TamerOp and CairoMakie in the documented notebook environment. No input files are needed.

What you already haveWhere to beginWhat you obtain
Points, images, graphs, or cells with filtration gradesA supported filtration and its encoding workflowAn encoding of the selected persistence module, with its parameter assignment
Supported geometric upsets and downsets, with a coefficient matrixAn indicator presentationAn encoding of the module specified by that presentation
A finite poset with compatible spaces and mapsA finite PModuleA module already in the finite setting; parameter lookup is unnecessary

If the question is only about a barcode in one parameter, the ordinary persistence guide gives a direct route that need not construct an encoding. Here we want to keep working with the spaces and maps.

Set up the two computations

We use OP for the main workflows and OA for the detailed region, module and morphism constructors. Our vector spaces and matrices will have rational coefficients. CairoMakie supplies the static figures.

import TamerOp as OP
import TamerOp.Advanced as OA
import TamerOp.CoreModules: QQField
import LinearAlgebra: I
import CairoMakie
CairoMakie.activate!(type="png", px_per_unit=1)
field = QQField();

Start from a filtration

Take two points at $(0,0)$ and $(3,4)$, whose distance is 5. Give them function values 0 and 1. A function–Rips filtration uses two increasing parameters: an edge-length threshold $r$ and a function threshold $a$. A vertex is present when its function value is at most $a$; an edge is present when both endpoints are present and their distance is at most $r$.

Thus the second point enters at $a=1$, and the edge connecting the points enters at $r=5$. Here $r$ is an edge-length threshold, not the radius of balls around the points. We retain vertices and edges (max_dim=1), which suffice to determine connected components.

points = OP.PointCloud([[0.0, 0.0], [3.0, 4.0]])
filtration = OP.FunctionRipsFiltration(
    vertex_values=[0.0, 1.0], max_dim=1);
OP.visualize(points; kind=:points_2d, labels=["u", "v"])
The two source points are at (0,0) and (3,4). Their distance is five; their assigned function values, zero and one, determine when the vertices enter the filtration.

The picture places the points in physical space. The filtration parameters $(r,a)$ describe a different plane: $r$ controls which distances are allowed, and $a$ controls which vertex values are allowed.

Before computing, we can predict degree zero homology by counting connected components. Each component contributes one basis vector.

Parameter $(r,a)$Present cellsNumber of components
$(1/2,0)$First vertex1
$(1/2,1)$Both vertices, no edge2
$(5,1)$Both vertices and their edge1

At the last parameter the edge joins the components, so the map from the preceding space has a two dimensional source, a one dimensional target and rank one.

data_encoding = OP.encode(points, filtration; degree=0, field=field)
OP.describe(data_encoding)
(kind = :encoding_result, poset_type = TamerOp.FiniteFringe.ProductOfChainsPoset{2}, module_type = TamerOp.DataIngestion._LazyEncodedModule, encoding_map_type = TamerOp.EncodingCore.CompiledEncoding{TamerOp.EncodingCore.GridEncodingMap{2, Float64, TamerOp.FiniteFringe.ProductOfChainsPoset{2}}, TamerOp.FiniteFringe.ProductOfChainsPoset{2}, Nothing, Nothing, @NamedTuple{encoding_cache::TamerOp.CoreModules.EncodingCache}}, compiled = true, backend = :data, has_cohomology = false, has_presentation = true, module_dims = nothing, materialized = false, provenance = (category = :finite_poset_representations, base_poset = ProductOfChainsPoset(axes=(2, 2), orientation=(1, 1), nvertices=4), field = QQField(), degree = 0, degree_convention = :homological, encoding = (map_type = TamerOp.EncodingCore.CompiledEncoding{TamerOp.EncodingCore.GridEncodingMap{2, Float64, TamerOp.FiniteFringe.ProductOfChainsPoset{2}}, TamerOp.FiniteFringe.ProductOfChainsPoset{2}, Nothing, Nothing, @NamedTuple{encoding_cache::TamerOp.CoreModules.EncodingCache}}, backend = :data), window = (lower = (0.0, 0.0), upper = (5.0, 1.0), coordinates = :oriented, outside_lower = :unrepresented, upper_extension = :constant), orientation = (1, 1), construction = (requested = :function_rips, effective = :function_rips, substitution = :none, projection = :none, grade_scale = :diameter, requested_max_dim = 1, retained_max_dim = 1), discretization = (axes_policy = :encoding, axes_source = :computed_grades, axis_kind = nothing, grade_placement = :critical_grades, sampling = false, quantization = :none, eps = nothing), approximation = (sparsify = :none, input_point_count = 2, retained_vertex_count = 2, radius_cutoff = nothing, collapse = :none, multicritical = :union, onecritical_selector = nothing, onecritical_enforce_boundary = nothing, grade_arithmetic = :float64, neighbor_search = :not_used, construction_substitution = :none), backend = (requested = (ingestion = :data, neighbors = :auto, multicover = :auto, delaunay = :auto), effective = :native, linear_algebra = :operation_specific), ambient_identification = :not_asserted, chain_storage = :cochain_reindexed_homology, reconstruction = :computed_graded_complex))

The returned EncodingResult keeps the finite poset and the assignment from filtration parameters to its labels. It can defer constructing spaces and maps until they are needed; encoding_module requests that finite module.

We inspect the domain $r\geq0$, $a\geq0$. The default grid contains the critical grades where cells enter, so it retains all the changes in this example. A coarser grid can move those births; ingestion choices explains how. Below the first grid grade, a lookup can return 0 to indicate an unrepresented parameter. That value is a label convention, and must be distinguished from a label whose represented vector space is zero.

data_module = OP.encoding_module(data_encoding)
data_classifier = OP.encoding_map(data_encoding)
data_dimensions = OP.dimensions(data_encoding)
parameters = [(1//2, 0//1), (1//2, 1//1), (5//1, 1//1)]
labels = [OA.locate(data_classifier, p) for p in parameters]
@assert all(>(0), labels)
@assert data_dimensions[labels] == [1, 2, 1]
(; parameters, dimensions=data_dimensions[labels])
(parameters = Tuple{Rational{Int64}, Rational{Int64}}[(1//2, 0), (1//2, 1), (5, 1)], dimensions = [1, 2, 1])

A parameter chooses a finite label; that label chooses a space. These labels belong to the returned encoding, so we obtain them by lookup instead of guessing their numeric IDs.

Now recover the merge map. structure_map takes finite labels. The original parameters are comparable in coordinatewise order, which justifies this query as a map in the persistence module.

merge_map = OA.structure_map(data_module;
    source=labels[2], target=labels[3])
@assert merge_map == OP.QQ[1 1]
merge_map
1×2 TamerOp.DataIngestion._StructuralInclusionMap{Rational{BigInt}}:
 1  1

The row $[1\;1]$ sends the two component coordinates $(u,v)$ to $u+v$, because both components become the same connected component. Vectors of the form $(v,-v)$ map to zero and form its one dimensional kernel.

The inspector below shows how this map relates to the selected parameters and their finite labels. In the parameter panel, the first coordinate is $r$ and the second is $a$. The viewing window limits the picture while leaving the encoded module unchanged.

data_window = ([0.0, 0.0], [7.0, 3.0])
OP.visualize(data_encoding; kind=:module_inspector,
    parameter_pair=(parameters[2], parameters[3]), box=data_window)
The function–Rips encoding recovers the merge map from (r,a)=(1/2,1) to (5,1). Two component coordinates map to one by a rank-one row matrix with both entries equal to one. The finite-poset positions are schematic.

The prepared view lets us choose among three maps in this same encoding. In inclusion, the second point enters and the original component maps into a space with two component coordinates. In identity, we stay at $(1/2,1)$, so both coordinates remain unchanged. In merge, the edge enters and the two coordinates map to their sum. Compare the matrix shapes and ranks as you change the selection; the parameter panel shows which pair is being queried.

These are three answers computed by TamerOp over the rational field. The export cell below creates the same collection when you run the notebook.

Explore the three structure maps

Optional: Save the prepared map views

We prepare a visual specification for each comparable pair, then save their drawings and data in one HTML file. You can open that file in a browser or send it to someone who does not have Julia installed.

inclusion_map = OA.structure_map(data_module; source=labels[1], target=labels[2])
identity_map = OA.structure_map(data_module; source=labels[2], target=labels[2])
@assert inclusion_map == reshape(OP.QQ[1, 0], 2, 1)
@assert identity_map == Matrix{OP.QQ}(I, 2, 2)
map_views = (
    inclusion=OA.visual_spec(data_encoding; kind=:module_inspector,
        parameter_pair=(parameters[1], parameters[2]), box=data_window),
    identity=OA.visual_spec(data_encoding; kind=:module_inspector,
        parameter_pair=(parameters[2], parameters[2]), box=data_window),
    merge=OA.visual_spec(data_encoding; kind=:module_inspector,
        parameter_pair=(parameters[2], parameters[3]), box=data_window))
mkpath("tamerop_outputs")
OP.save_visual_session(joinpath("tamerop_outputs", "two_point_maps.html"), map_views;
    selected=:merge, title="Three maps from two points",
    caption="Choose inclusion, identity or merge. The parameters are edge threshold r and function threshold a; the matrices use rational coefficients.");

The rank gives a shorter description of the same map. The rank invariant records this number for each comparable pair of parameters. We can request it from the encoding and return to the actual matrices whenever the numbers leave a question unresolved.

data_ranks = OP.invariant(data_encoding; which=:rank_invariant)
merge_rank = OA.value_at(OP.invariant_value(data_ranks), labels[2], labels[3])
@assert merge_rank == 1
merge_rank
1

Define a module by regions

We can specify a persistence module without supplying a point cloud or a filtration. Consider the closed strip

\[S=\{(x,y)\in\mathbb R^2:0\leq x+y\leq1\}.\]

At a point of $S$, assign the space $\mathbb Q$; elsewhere assign zero. Between comparable points inside $S$, use the identity map. All other prescribed maps are zero. Any point between two comparable points of the strip remains in the strip. This order-convexity condition makes the prescribed maps compose consistently.

This support has sloped boundaries and extends without bound in the direction $(1,-1)$. A finite axis-aligned grid of critical coordinates cannot describe those boundaries exactly throughout the original plane. A finite region encoding can: it distinguishes below the strip, inside it, and above it.

Write $S=U\cap D$, where the upset $U$ satisfies $x+y\geq0$ and the downset $D$ satisfies $x+y\leq1$. Increasing coordinates keeps a point in the upset; decreasing them keeps a point in the downset. make_hpoly(A,b) describes the inequalities $Az\leq b$. Thus the first inequality uses the row $[-1\;-1]$, and the second uses $[1\;1]$.

U = OA.PLUpset(OA.poly_union(
    OA.make_hpoly(OP.QQ[-1 -1], OP.QQ[0])))
D = OA.PLDownset(OA.poly_union(
    OA.make_hpoly(OP.QQ[1 1], OP.QQ[1])))
presentation = OA.PLFringe([U], [D], reshape(OP.QQ[1], 1, 1));

The coefficient $[1]$ defines a map from the upset indicator to the downset indicator. Each indicator assigns the field to its region and zero outside, with identity maps within the region. The image of our map is one dimensional exactly where both regions are present, giving the strip module. Indicator presentations develops this construction.

The sloped regions require the general polyhedral encoder. Rational coefficients in their inequalities keep the boundary geometry exact; the separate field option chooses rational arithmetic for the vector spaces.

strip_encoding = OP.encode(presentation,
    OA.EncodingOptions(backend=:pl, field=field))
strip_module = OP.encoding_module(strip_encoding)
strip_classifier = OP.encoding_map(strip_encoding)
strip_dimensions = OP.dimensions(strip_encoding)
@assert OA.nvertices(OP.encoding_poset(strip_encoding)) == 3
@assert sort(strip_dimensions) == [0, 0, 1]
(; finite_labels=length(strip_dimensions), dimensions=strip_dimensions)
(finite_labels = 3, dimensions = [0, 1, 0])

Three labels describe the whole plane: one below the strip, one inside, and one above. The labels outside the strip represent zero spaces, so queries there still have a specified answer.

Take $s=(0,0)$ and $t=(1/4,1/4)$. Both lie in the strip and $s\leq t$, giving the identity matrix $[1]$. The upper boundary point $(1,0)$ belongs to the strip as well. We also check $(100,-100)$ on the lower boundary, well beyond the window that we will draw.

s, t = (0//1, 0//1), (1//4, 1//4)
qs, qt = [OA.locate(strip_classifier, p) for p in (s, t)]
strip_map = OA.structure_map(strip_module; source=qs, target=qt)
@assert strip_map == reshape(OP.QQ[1], 1, 1)
@assert strip_dimensions[OA.locate(strip_classifier, (1, 0))] == 1
@assert strip_dimensions[OA.locate(strip_classifier, (100, -100))] == 1
strip_map
1×1 Matrix{Rational{BigInt}}:
 1
strip_window = ([-1.0, -1.0], [2.0, 2.0])
OP.visualize(strip_encoding; kind=:module_inspector,
    parameter_pair=(s, t), box=strip_window)
A finite window of the unbounded closed strip 0≤x+y≤1. The selected comparable points lie in its one-dimensional region and have identity structure map. The finite model has three labels; its other two spaces are zero.

In the parameter panel, the sloped region is the support where the module is nonzero. The finite model is a chain with three labels and a one dimensional space at its middle label. Both maps between adjacent labels are zero, because each has a zero space at one end. Our two selected parameters reach the middle label, whose identity is the displayed matrix.

The boundary queries used rational arithmetic. The screen drawing has finite precision and shows only the selected window of the unbounded strip.

Change the target and predict the answer

Move the target to $z=(1,1)$. The pair $s\leq z$ is still comparable, but $z$ lies above the strip. Predict the matrix shape and rank. Then compare the same rank-invariant query used for the filtration.

z = (1, 1)
qz = OA.locate(strip_classifier, z)
leaving_map = OA.structure_map(strip_module; source=qs, target=qz)
strip_ranks = OP.invariant(strip_encoding; which=:rank_invariant)
leaving_rank = OA.value_at(OP.invariant_value(strip_ranks), qs, qz)
@assert size(leaving_map) == (0, 1)
@assert leaving_rank == 0
(; matrix_size=size(leaving_map), rank=leaving_rank)
(matrix_size = (0, 1), rank = 0)
OP.visualize(strip_encoding; kind=:module_inspector,
    parameter_pair=(s, z), box=strip_window)
The comparable pair (0,0)≤(1,1) leaves the closed strip. The defined structure map has a one-dimensional source, zero-dimensional target, matrix shape 0×1, and rank zero.

Consider instead $(0,1)$ and $(1,0)$. Both belong to the strip, but they are incomparable: one coordinate increases while the other decreases. The parameter order therefore prescribes no structure map between them, even though their finite labels agree. For the comparable pair $s\leq z$ above, there is a prescribed map and it happens to be zero. Exploring spaces and maps develops this distinction through parameter queries.

Continue with algebra on either module

We have used each encoding to look up spaces and maps. We can now construct a new module from those same data. Take two copies of a module $M$ and add their vectors at each label:

\[\alpha:M\oplus M\longrightarrow M,\qquad \alpha_p(u,v)=u+v.\]

For any structure map $A$ of $M$, linearity gives $A(u+v)=Au+Av$. Addition therefore commutes with every structure map. A compatible family of maps between two modules is called a module morphism; here its matrix at each label is $[I\;I]$.

The vectors killed by addition are the pairs $(u,-u)$. They form a kernel space at each label, and the structure maps carry such pairs to pairs of the same form. Taken together, these spaces and maps give a kernel module isomorphic to $M$. We can make this construction independently for each of our examples, without requiring their two finite posets to agree.

data_double = OA.direct_sum(data_module, data_module)
data_addition = OA.PMorphism(data_double, data_module,
    [hcat(Matrix{OP.QQ}(I, d, d), Matrix{OP.QQ}(I, d, d))
     for d in data_dimensions])
@assert OA.check_morphism(data_addition).valid
data_kernel, data_inclusion = OA.kernel_with_inclusion(data_addition)
@assert OP.dimensions(data_kernel).stalks == data_dimensions
OP.dimensions(data_kernel)
(vertices = 4, stalks = [1, 1, 2, 1], total = 5, maximum_stalk = 2, edges = 4)

kernel_with_inclusion returns the kernel module and the map that includes it in the doubled module. This inclusion tells us how a computed kernel coordinate becomes a vector in the original coordinates.

At the label with two components, addition takes four coordinates to two. We will check that each column of the inclusion maps to zero under addition, then check that including a kernel vector commutes with moving along the merge map. First display the addition matrix at that label.

p, q = labels[2], labels[3]
addition_at_p = OA.component(data_addition, p)
inclusion_at_p = OA.component(data_inclusion, p)
inclusion_at_q = OA.component(data_inclusion, q)
kernel_merge = OA.structure_map(data_kernel; source=p, target=q)
doubled_merge = OA.structure_map(data_double; source=p, target=q)
@assert addition_at_p * inclusion_at_p == zeros(OP.QQ, 2, 2)
@assert doubled_merge * inclusion_at_p == inclusion_at_q * kernel_merge
addition_at_p
2×4 Matrix{Rational{BigInt}}:
 1  0  1  0
 0  1  0  1

The inclusion has one column for each kernel coordinate. Its four rows give the coordinates in the doubled two-component space.

inclusion_at_p
4×2 Matrix{Rational{BigInt}}:
  0  -1
 -1   0
  0   1
  1   0

The kernel module also has its own merge map from $p$ to $q$:

kernel_merge
1×2 Matrix{Rational{BigInt}}:
 1  1

The equality being checked is the commutative square

\[\begin{array}{ccc} K(p)&\xrightarrow{\ \iota_p\ }&(M\oplus M)(p)\\ {\scriptstyle K(p\leq q)}\downarrow&&\downarrow{\scriptstyle (M\oplus M)(p\leq q)}\\ K(q)&\xrightarrow{\ \iota_q\ }&(M\oplus M)(q). \end{array}\]

In words, include a kernel vector and then move along the filtration, or first move in the kernel module and then include it: both paths give the same vector. The software chooses bases for these kernel spaces, so their inclusion matrices need not use our preferred signs.

Repeat the construction for the strip using the same public operations. Display its kernel inclusion at the selected label inside the strip.

strip_double = OA.direct_sum(strip_module, strip_module)
strip_addition = OA.PMorphism(strip_double, strip_module,
    [hcat(Matrix{OP.QQ}(I, d, d), Matrix{OP.QQ}(I, d, d))
     for d in strip_dimensions])
@assert OA.check_morphism(strip_addition).valid
strip_kernel, strip_inclusion = OA.kernel_with_inclusion(strip_addition)
@assert OP.dimensions(strip_kernel).stalks == strip_dimensions
@assert OA.component(strip_addition, qs) * OA.component(strip_inclusion, qs) == zeros(OP.QQ, 1, 1)
OA.component(strip_inclusion, qs)
2×1 Matrix{Rational{BigInt}}:
 -1
  1

Inside the strip, addition takes two coordinates to one, and their differences form the kernel. Outside, all these spaces are zero. The original classifier now lets us interpret the kernel module at points of the plane as well.

The same construction applies to a supplied PModule. Within each morphism, source and target must use the same finite poset and coefficient field. If two geometric encodings were constructed separately, comparing their modules requires a justified common base; matching numeric labels does not establish one.

Further operations include resolutions and the derived constructions Ext and Tor. These use the category of modules on the actual finite poset, so changing an encoding can change their answers even when the ambient module is recovered. The category guide explains these operations and that dependence.

Continue with spaces and maps

The two points gave us a merge map, while the strip gave us identity and zero maps according to where the selected parameters lay. In each case, the finite encoding kept enough information to construct addition and its kernel, and its parameter assignment let us interpret the result in the original domain.

Exploring spaces and maps continues with more queries and coordinate views. For the construction used to specify the strip, read indicator presentations.