Skip to content

Choosing and inspecting resolutions

Download the executed notebook · Build and environment record

A finite module is a diagram of vector spaces and maps, and we can describe it by choosing generators and recording the relations they satisfy. Those relations can have relations of their own. A projective resolution keeps following this process, so that each stage explains the kernel left by the preceding one. Here we will work through a small example far enough to see why that extra stage is needed, then inspect what TamerOp stores and draws.

We use rational coefficients and a directly supplied finite diagram. You need familiarity with vector spaces, matrices and finite posets; the installation instructions give the packages used below. OP.Advanced supplies the constructors and inspection operations needed for this example. The same resolution views accept OP.resolve(enc) when enc came from a filtration or another encoding construction.

All the algebra takes place in the category of modules on the supplied finite poset. An encoding may recover a module on a larger parameter space, but that fact alone does not identify the two categories' derived groups. The category discussion explains the hypotheses needed for such comparisons.

import TamerOp as OP
import CairoMakie
const OA = OP.Advanced
field = OP.CoreModules.QQField()
K = OP.CoreModules.coeff_type(field);

A module on a diamond

The order is $1<2<4$ and $1<3<4$, with 2 and 3 incomparable. Let $M$ have the one-dimensional space $K=\mathbb Q$ at vertex 1 and zero elsewhere. Its structure maps along the four covers are zero. This is already a finite module, so its encoding can assign each vertex to itself.

P = OA.FinitePoset(Bool[1 1 1 1; 0 1 0 1; 0 0 1 1; 0 0 0 1])
dims = [1, 0, 0, 0]
M = OA.PModule{K}(P, dims,
    Dict((u,v) => zeros(K, dims[v], dims[u]) for (u,v) in OA.cover_edges(P)); field)
classifier = OP.Encoding.EncodingMap(P, P, [1,2,3,4])
enc = OP.EncodingResult(P, M, classifier)
@assert OA.check_module(M).valid
OP.visualize(M; kind=:module_inspector, vertex=1)
A diamond-shaped finite order with a one-dimensional space at its bottom vertex and zero-dimensional spaces at its other three vertices.
The module has a line only at vertex 1. The diamond positions describe the finite order, not extra parameter coordinates.

Write $P_i$ for the module supported on the principal upset of vertex $i$: it has a copy of $K$ at every vertex $v\geq i$, with identity maps between nonzero spaces. A map $P_i\to N$ is determined by the image of $1$ at vertex $i$, because the structure maps of $N$ determine its images everywhere above $i$. Thus $\operatorname{Hom}(P_i,N)\cong N_i$. Since exactness of finite modules can be checked at each vertex, this also explains why $P_i$ is projective: maps out of it lift through surjective module maps.

The map $P_1\to M$ keeps the line at 1 and sends every other space to zero. Its kernel has lines at 2, 3 and 4, with both maps to 4 equal to the identity. We need a generator at 2 and another at 3 to cover that kernel. At 4 their images agree, leaving the relation $(1,-1)$ between them. That last relation generates a copy of $P_4$, so the process ends with

\[0\longrightarrow P_4\xrightarrow{d_2}P_2\oplus P_3 \xrightarrow{d_1}P_1\longrightarrow M\longrightarrow0.\]

At vertex 4 the resolution is zero to K to K squared to K to zero, with maps the column (1,-1) and the row (1,1); at the other vertices the nonzero map is an identity.

The diagram chooses bases in which the two coefficients of $d_2$ are 1 and $-1$. At vertex 4 its image is exactly the kernel of $d_1$; at the other vertices exactness follows from the displayed identity maps. This is a hand calculation of the resolution, including its maps. A relation among earlier generators is often called a syzygy; here we can point to the vector that produces one.

Counting the principal projectives in each degree gives the following prediction. These counts are minimal because, at each step, a generator is introduced only where the preceding kernel cannot be generated from lower vertices.

DegreeVertex 1Vertex 2Vertex 3Vertex 4
01000
10110
20001
resolution = OP.resolve(enc; opts=OA.ResolutionOptions(maxlen=2))
table = OA.visual_spec(resolution)
@assert OA.visual_metadata(table).counts == [1 0 0 0; 0 1 1 0; 0 0 0 1]
OA.visual_metadata(table).verification
(minimality = :not_checked, completion = :not_checked, checks = NamedTuple[])

The default table counts the stored summands. To check whether those counts come from a complete minimal resolution, request verify=true. The verification checks that consecutive maps compose to zero, that each kernel equals the preceding image, that the covers use minimal generators, and that the final kernel vanishes. Here the verified counts are the Betti numbers: the multiplicities of the principal projectives in the minimal resolution of this finite module.

verified = OA.visual_spec(resolution; verify=true)
@assert OA.visual_metadata(verified).verification.minimality == :minimal
@assert OA.visual_metadata(verified).verification.completion == :complete
OP.visualize(verified)
A verified degree-by-vertex Betti table with one generator at vertex 1, two relations at vertices 2 and 3, and one syzygy at vertex 4.
The verified multiplicities agree with the hand calculation: P₁ in degree 0, P₂ and P₃ in degree 1, and P₄ in degree 2.

Follow a selected relation into its map

The first summand in degree 1 is supported on a principal upset. Selecting it highlights its source column in $d_1$; the rows describe summands in degree 0. At vertex 4 both degree 1 summands are active, so the stalk map has two columns, just as in the hand calculation.

Setting support_sheets=true draws the summands of the selected term in separate panels. This lets us distinguish the two copies that meet at vertex 4. Their horizontal separation is a drawing choice; the panels still describe summands in the resolution, rather than a decomposition of $M$.

OP.visualize(resolution; kind=:resolution, degree=1, summand=1,
    vertex=4, support_sheets=true, verify=true)
Two separately labelled degree-one principal-upset supports, their common differential into degree zero, and its active matrix at vertex 4.
At vertex 4 both principal upsets contribute a column to d₁. The separate support panels show where each column is active.

The degree 2 summand records the relation between those two generators. Its stored basis may use a different normalization from our hand calculation, so we check the content of the relation: both coefficients are nonzero and applying $d_1$ to the resulting column gives zero.

syzygy = OA.visual_spec(resolution; kind=:resolution, degree=2,
    summand=1, vertex=4, verify=true)
D2 = OA.visual_metadata(syzygy).coefficient_matrix
@assert size(D2) == (2,1) && all(!iszero, D2)
D1 = OA.visual_metadata(OA.visual_spec(resolution; kind=:resolution, degree=1)).coefficient_matrix
@assert all(iszero, D1*D2)
OP.visualize(syzygy)
The syzygy at the top of the diamond maps to the two degree-one summands through a two-by-one matrix with opposite nonzero coefficients.
The two entries of d₂ give a relation between the degree 1 generators; applying d₁ makes their contributions cancel.

Compare the two generators and their relation

Choose either degree 1 summand to see its principal support and the column it contributes to $d_1$. Both are active at vertex 4. The degree 2 selection then gives the relation between them: its two nonzero coefficients cancel after applying $d_1$. Keeping the stalk at vertex 4 makes that cancellation visible while we move between the terms.

Compare the generators and their relation

A cutoff is not a vanishing theorem

If we stop at maxlen=0, we retain the projective cover $P_1\to M$ and leave its nonzero kernel unresolved. The cover is minimal, but this prefix does not determine how many later terms there are. Its table therefore contains only degree 0, and verification marks the resolution as truncated.

prefix = OP.resolve(enc; opts=OA.ResolutionOptions(maxlen=0))
prefix_view = OA.visual_spec(prefix; verify=true)
@assert size(OA.visual_metadata(prefix_view).counts) == (1,4)
@assert OA.visual_metadata(prefix_view).verification.completion == :truncated
OP.visualize(prefix_view)
A single stored degree-zero row explicitly labelled as a truncated resolution prefix, without zero-filled higher degrees.
Only degree 0 was requested. Its nonzero terminal kernel is recorded as truncation, leaving the higher multiplicities unknown.

Grades are extra mathematical data

The table above needs only the finite order and the summand labels. A picture in a plane needs coordinates as well. Supply grades, one coordinate pair for each vertex, whose coordinatewise order agrees with the poset. For this example the four corners of a square give such an order embedding: $u\leq v$ holds exactly when both coordinates of $u$ are at most the corresponding coordinates of $v$.

A dot in the next view records a finite vertex and its multiplicity in the selected resolution degree. Several summands at the same grade are counted together. These remain multiplicities in the finite category; supplying coordinates alone does not establish that they are the Betti numbers of an ambient multigraded free resolution. The category discussion describes why the distinction matters.

grades = [(0,0), (1,0), (0,1), (1,1)]
OP.visualize(resolution; kind=:betti_degrees, degree=1, grades, verify=true)
Two degree-one dots at grades (1,0) and (0,1), each labelled with its finite vertex and multiplicity one.
The two degree 1 summands occur at (1,0) and (0,1), using the supplied order embedding of the diamond.

Reversing the list of grades exchanges bottom and top. It therefore fails the order condition, which the request validator reports below. A layout for drawing a Hasse diagram serves another purpose: it places comparable vertices so that arrows are readable, without promising to recover a given coordinatewise parameter order.

invalid = OA.check_visual_request(resolution; kind=:betti_degrees, grades=reverse(grades))
@assert !invalid.valid
invalid.issues
1-element Vector{String}:
 "ArgumentError: grades must be a" ⋯ 57 bytes ⋯ "ut coordinates are not grades."

The injective direction

There is a dual construction using principal downsets. Write $I_i$ for the module with a line at every vertex $v\leq i$ and identity maps on that support. A map $N\to I_i$ is determined by a linear functional on $N_i$, so $\operatorname{Hom}(N,I_i)\cong N_i^*$. Over a field this functor preserves exact sequences, which makes $I_i$ injective.

Put a line at vertex 4 and zero elsewhere. Its injective resolution embeds it in $I_4$, then uses $I_2\oplus I_3$ and finally $I_1$ to account for the successive cokernels:

\[0\longrightarrow N\longrightarrow I_4\longrightarrow I_2\oplus I_3 \longrightarrow I_1\longrightarrow0.\]

The multiplicities in a minimal injective resolution are called Bass numbers. The arrows run toward increasing resolution degree, so selecting a summand in a positive degree marks its target row in the incoming differential.

dual_dims = [0,0,0,1]
N = OA.PModule{K}(P, dual_dims,
    Dict((u,v) => zeros(K, dual_dims[v], dual_dims[u]) for (u,v) in OA.cover_edges(P)); field)
dual_enc = OP.EncodingResult(P, N, classifier)
injective = OP.resolve(dual_enc; kind=:injective, opts=OA.ResolutionOptions(maxlen=2))
bass = OA.visual_spec(injective; verify=true)
@assert OA.visual_metadata(bass).counts == [0 0 0 1; 0 1 1 0; 1 0 0 0]
OP.visualize(injective; kind=:resolution, degree=1, summand=1, vertex=1, verify=true)
The injective direction of the diamond example, with a selected degree-one cogenerator and its row in the incoming differential.
The injective resolution follows principal downsets. Selecting a degree 1 summand highlights a row in the map arriving there.

Inspect a presentation before minimizing it

A projective presentation describes a module as a cokernel: the generators are identified modulo the image of the relation map. A fringe presentation uses a different construction, taking the image of a map from upsets to downsets. Keeping that distinction in view prevents the same matrix from being given two incompatible interpretations.

Here both the generator and relation terms have summands labelled 1 and 2 on a chain. In the displayed relation map, columns are relations and rows are generators. The lower left entry must vanish because there is no nonzero map from the first principal upset to the second. The lower right entry is allowed by the order and happens to be zero in this example. The viewer marks the forced zero with a dagger.

UpsetPresentation stores the transpose of this displayed matrix; the figure labels the source columns and target rows after making that conversion.

Q = OA.FinitePoset(Bool[1 1; 0 1])
U = [OA.principal_upset(Q,1), OA.principal_upset(Q,2)]
A = K[1 2; 0 0]
presentation = OP.IndicatorTypes.UpsetPresentation{K}(Q, U, U, copy(transpose(A)), nothing)
OP.visualize(presentation; degree=1, summand=2, vertex=2, grades=[(0,0),(1,1)])
A finite projective cokernel presentation, with actual summand labels and a dagger separating the order-forced lower-left zero from the permitted lower-right zero.
The dagger identifies an entry forced to vanish by the order. The other zero is part of the supplied relation matrix.

We can change the bases without changing the presented module. Let $S$ change the relation coordinates and $T$ change the generator coordinates. If the new matrix is $B$, following a vector through the two descriptions gives $AS=TB$, or $B=T^{-1}AS$.

The viewer checks that the supplied changes are invertible and respect the summand grades, then checks this equation. It displays the supplied change without modifying the stored presentation. For a resolution, the same check concerns one selected differential; a change to the whole resolution must transform the adjacent maps and augmentation too.

S = K[1 1; 0 1]
T = K[1 0; 0 1]
changed = OA.visual_spec(presentation; degree=1, vertex=2,
    basis_change=(; source=S, target=T))
@assert OA.visual_metadata(changed).basis_change.matrix == K[1 3; 0 0]
@assert OA.visual_metadata(changed).represented_dimension == 1
OP.visualize(changed)
The original and transformed presentation matrices accompanied by the supplied graded basis changes and the verified equation A S equals T B.
Changing the relation basis replaces A by B while AS = TB. At vertex 2 the cokernel still has dimension one.
Optional: prepare the relation views

We use the stored resolution for each selection and keep the support, coefficient matrix and stalk differential. The surrounding calculation establishes completeness and minimality; these views let us inspect the generators and relation themselves.

relation_labels = ["First degree 1 generator", "Second degree 1 generator", "Degree 2 relation"]
relation_selections = [(1,1), (1,2), (2,1)]
relation_views = []
for (label, (degree, summand)) in zip(relation_labels, relation_selections)
    answer = OA.visual_spec(resolution; kind=:resolution, degree, summand, vertex=4, verify=true)
    @assert answer.metadata.verification.completion == :complete
    @assert size(answer.metadata.stalk_matrix) == (degree == 1 ? (1,2) : (2,1))
    coefficients = OP.visual_panel(answer; panel=3)
    @assert !any(coefficients.metadata.structural_zero_mask)
    rows, columns = size(coefficients.metadata.matrix)
    coefficients = OA.VisualizationSpec(coefficients.kind;
        title=coefficients.title,
        subtitle="P_$degree → P_$(degree-1)\nRows: target; columns: source.\nPrincipal upset bases; rational coefficients\n$rows × $columns",
        layers=coefficients.layers, panels=coefficients.panels,
        axes=coefficients.axes, legend=coefficients.legend,
        interaction=coefficients.interaction, metadata=coefficients.metadata)
    push!(relation_views, OP.compose_visuals((
        support=OP.visual_panel(answer; panel=2),
        coefficients=coefficients,
        at_vertex=OP.visual_panel(answer; panel=4));
        columns=3, title=label, subtitle="Resolution of the bottom simple over Q; stalk selected at vertex 4."))
end
@assert all(iszero, D1 * D2)
prepared_relations = NamedTuple{Tuple(Symbol.(relation_labels))}(Tuple(relation_views))
resolution_directory = joinpath("tamerop_outputs", "resolutions")
mkpath(resolution_directory)
OP.save_visual_session(joinpath(resolution_directory, "relations.html"), prepared_relations;
    selected=Symbol(first(relation_labels)), size=(1560,650),
    title="Follow a generator into the relation it satisfies",
    caption="The two degree 1 generators meet at vertex 4. The degree 2 column lies in the kernel of d1. Columns are source coordinates and rows are target coordinates over Q.");

The same views accept OP.IndicatorResolutions.upset_resolution(M) and downset_resolution(M) when their principal summands are recorded. They cannot assign a single birth label to an arbitrary upset that has several minimal vertices. With exact coefficients the equations above are checked exactly; RealField instead uses the field's declared tolerances for numerical rank and equality decisions.

For a large example, matrix_limit restricts the rows and columns drawn while keeping the full selected matrix in the specification. Support panels use the row limit and retain any explicitly selected summand. The figure states how much is shown, so a cropped picture can still be interpreted as part of a larger computation.

A resolution now gives us a way to turn module maps into a complex of vector spaces. The derived computation guide uses precisely this diamond to compute Ext classes and their products. The visualization reference gives the selection and verification contracts, and the shared export workflow explains how to save a view.