Skip to content

Source representatives

A source representative expresses a chain or cochain on the cells from which a computation was built. Obtaining it requires three kinds of retained data: the source geometry, the computed coefficients and a map relating the two cell bases. The source cells guide develops examples of cycles, fillings, cocycles and component memberships; the implementation account explains the equations behind their checks.

Retention and ordinary queries

persistence_diagram(data, filtration; source=true) and cubical_persistence(values; source=true) retain source geometry and checked maps by constructing explicit complexes. Choose representatives=true to retain cycle and filling data, or cocycles=true to retain cochain data. These are independent choices: source geometry alone does not supply a selected class representative.

You may also pass a FilteredComplex or SourceCorrespondence directly to persistence_diagram, which retains that supplied source data. A correspondence for ordinary persistence must have one parameter and agree with the requested order; its own coefficient field determines the calculation's field. Ordinary source queries require a splitting retraction: if $i$ sends computed chains to source chains and $p$ sends source chains back, then $pi$ must be the identity. A general map without this retraction remains usable explicitly through lift_source_chain.

Automatic geometry follows the filtered complex input contract. A distance matrix or a supplied cellular boundary matrix does not determine coordinates. Supply a FilteredComplex with geometry for those inputs. Cubical arrays retain exact grades, sublevel or superlevel order and periodic identifications. A one dimensional vertex array is drawn in a plane with its second coordinate zero. Sampling and graph sparsification determine the retained model. A collapse request additionally retains that same model before collapse and a checked correspondence to it.

A cycle and its finite death filling

Advanced.persistence_representative(diagram; dim, kind=:finite, index=1, scale=nothing) selects an original member of the interval list. The scale defaults to birth and must lie both inside the selected interval, with finite death excluded, and inside the recorded construction window.

The result's cycle and bounding_chain fields contain the computed cycle and, for finite death, its filling. When source data were retained, source_cycle is a checked SourceChain at the query scale and source_bounding_chain is checked at death. The boundary of that source filling must equal the source cycle. Without source retention these source fields are nothing; without representative retention the query reports available=false. Descriptive metadata cannot recover coefficients that were not retained.

A cocycle at a chosen scale

A cochain assigns coefficients to cells and evaluates chains by linearity. It is a cocycle when it vanishes on boundaries. The query Advanced.persistence_cocycle(diagram; dim, scale, kind=:finite, index=1) returns source_cochain when a checked source retraction was retained. The cochain is restricted to active source cells and checked against their boundaries.

This query uses the transpose of the retraction $p$, because evaluation on a source chain $s$ is evaluation on $ps$ in the computed complex. The map $i$ alone has the wrong direction. Homology and cohomology reductions choose representatives independently, so matching their interval member indices does not establish a dual pairing, including when intervals have equal endpoints.

Correspondences and chain queries

These operations and types belong to TamerOp.Advanced and are implemented by TamerOp.DataIngestion.

OperationContract
source_correspondence(computed, source=computed; field=PrimeField(2), lift=nothing, retraction=nothing)Accepts two FilteredComplex objects. By default it matches exact source identities and contracts complementary cells at equal appearance grade sets. Explicit maps are converted to sparse matrices over the field and checked.
source_correspondence(data, filtration; field=PrimeField(2), cache=nothing)Retains the constructed geometry and, when collapse is requested, the same model before collapse.
lift_source_chain(c; dim, coefficients, parameter, kind=:cycle)Accepts a coefficient vector indexed by cells in degree dim. Checks activity and the appropriate boundary equations before and after applying the correspondence. :chain permits arbitrary chains; :cocycle requires a retraction.
source_chain_data(chain)Returns support indices, source identities, oriented geometry, grade sets, coefficients (integer residues over prime fields), field, parameter and metadata.
check_source_correspondence(c; throw=false)Checks the complexes, the filtered chain map equations and any splitting equation. Returns SourceValidationSummary.
check_source_chain(chain; throw=false)Checks the source complex and geometry, support activity and the declared cycle or cocycle equation. Returns SourceValidationSummary.
optimize_representative(chain; weights=nothing, max_candidates=100000)Finds minimum weighted support within the nonzero cycle's homology class at its parameter. Refuses to enumerate a boundary image exceeding the candidate budget.

SourceCorrespondence, SourceChain and SourceValidationSummary provide compact show output and structured describe results. Treat retained arrays as read only. Correspondences support QQField() and prime fields; ordinary persistence and finite representative optimization require prime fields.

Supply a map for every retained chain degree, including zero. Rows index the destination cells and columns index the domain cells, each within that degree. Pad absent top degrees explicitly. Coefficients must belong to the chosen exact field or be integers that coerce to it; QQField() also accepts rational coefficients. Automatic source identities must be unique within each dimension. Geometry describes the cells' support and need not give an embedding.

The map and chain operations accept several parameters and multicritical cells, meaning cells with several possible appearance grades. A cell is active when any one of those grades precedes the query parameter in every declared coordinate order. The correspondence relates the supplied cell bases. It does not identify an unrelated module basis, a class on another slice or a point discarded before construction by proximity in a drawing.

Minimizing weighted support

The optimizer considers cycles obtained from the input by adding boundaries in the active finite complex. Weights are finite nonnegative integer, rational or floating values, one for every source cell in the chain degree; the default is one. The objective sums weights only where a coefficient is nonzero. Equal objective values keep the first enumerated candidate.

The result's metadata records the parameter, exact objective, weights, candidate count, original coefficients and a boundary_adjustment witness. The witness certifies that the new cycle differs from the original by a boundary. A zero homology class, inactive support, a noncycle, invalid weights or an exceeded budget raises ArgumentError. The minimum concerns the given weights and parameter; it need not minimize geometric length or persist as a minimum after the active complex changes.

Drawing and saving source results

visualize(chain; view_dims=nothing, max_cells=10000, max_labels=50, labels=true) draws support in degrees zero, one and two over the retained source complex. With more than three source coordinates, supply an explicit projection onto two or three coordinates. Higher chain degrees remain available algebraically but are rejected by this renderer.

The background and selected support each obey max_cells. Metadata retains exact data and reports how many cells were displayed or omitted. The compact source readout lists at most eight records and reports additional omissions. Coefficient labels use the oriented source basis, and the readout gives signed boundaries. Periodic geometry is drawn in a fundamental domain whose boundary identifications remain part of the source complex.

For an ordinary inspection_session(diagram; dim), select an interval and its original member, then request representative=true. Available source cycles are drawn at birth and fillings at death. Static snapshots and live browser views use the same records. Drawing a barcode or selecting a cell does not compute missing representatives or optimize their support.

persistence_diagram_data and the persistence JSON format preserve retained source complexes and maps. Loading checks their equations; automatic contractions are recomputed and compared. The data codec accepts supported metadata values and rejects arbitrary callbacks. Saving intervals alone cannot restore omitted source cells or maps later.

TamerOp.DataIngestion.SourceCorrespondence — Type
SourceCorrespondence

A retained chain map from a computed complex to source cells. A chain map commutes with taking boundaries, so it sends a computed cycle to a source cycle. Construct the correspondence with source_correspondence.

An optional retraction maps source chains back to computed chains and recovers each computed chain after its lift. Its transpose lets a computed cocycle evaluate source chains. Use describe to inspect retained counts, the field and retraction availability, and check_source_correspondence to validate the maps. Treat retained arrays as read only.

TamerOp.DataIngestion.SourceChain — Type
SourceChain

A chain or cochain on retained source cells at one parameter. Obtain it through lift_source_chain or an ordinary persistence representative query. A chain is a linear combination of cells; a cochain assigns values to those cells and evaluates chains by linearity. The kind records whether the object is an arbitrary chain, a cycle with zero boundary, or a cocycle vanishing on active boundaries.

describe gives the degree, parameter, field and support size. source_chain_data returns the nonzero coefficients and corresponding source identities and geometry. visualize draws that retained geometry without computing a new homology basis.

TamerOp.Advanced.SourceValidationSummary — Type
SourceValidationSummary

A validation result for a source correspondence or chain. valid reports whether its required checks passed, and issues lists any failures. Use describe for a structured result containing the validation kind as well.

TamerOp.Advanced.source_correspondence — Function
source_correspondence(computed, source=computed; field=PrimeField(2),
                      lift=nothing, retraction=nothing)

Retain checked maps between FilteredComplex objects. With one object, both maps are identities. With two objects and no explicit maps, match exact source identities and construct a retraction by canceling complementary cells with equal appearance grade sets. The computed cells must form a subcomplex of the source with the same oriented boundaries, and its complement must admit these cancellations.

An explicit lift may instead be any filtered chain map: it commutes with boundaries and respects cell appearances. A supplied retraction must recover each computed chain after lifting it. This certifies an injection on homology but permits additional source classes outside the image. Map rows index destination cells and columns index domain cells within each degree. Supply all retained degrees, including zero, and pad absent top degrees explicitly.

Exact rational and prime fields are supported. The result keeps both complexes; algebraic cancellation can increase the number of nonzero matrix entries. Use describe for counts and retained map information, and lift_source_chain for a cycle or cocycle at one parameter. Several parameters and several appearance grades per cell are supported. A module encoding without a retained cell correspondence does not provide the data needed by this constructor.

source_correspondence(data, filtration; field=PrimeField(2), cache=nothing)

Construct and retain source geometry through filtered_complex. When ingestion collapses cells, retain the same selected model before collapse and check a correspondence to it. Sampling and sparsification remain part of that model; restoring collapsed cells does not restore discarded points or omitted edges.

The result is a SourceCorrespondence, which can be inspected with describe and queried with lift_source_chain. Inputs without automatic geometry require a supplied FilteredComplex with geometry and the required maps.

TamerOp.Advanced.lift_source_chain — Function
lift_source_chain(c; dim, coefficients, parameter, kind=:cycle)

Apply a retained SourceCorrespondence to a coefficient vector indexed by computed cells of degree dim. Check activity and the required cycle or cocycle equation before and after mapping, then return a SourceChain on the source cells at parameter.

With kind=:cocycle, use the transpose of the retained retraction and restrict the result to active source cells. A computed cocycle evaluates a source chain by first mapping that chain back to the computed complex. A lift without a retraction cannot perform this operation. Use kind=:chain for arbitrary chains, including fillings; this mode checks activity without imposing a cycle equation.

Coefficients must be integers, elements of the retained field, or rational numbers over QQField(). Supply one coefficient per computed cell in the chosen degree and a parameter tuple with one entry per filtration coordinate; a scalar is accepted for one parameter. The supplied maps determine the basis correspondence.

TamerOp.Advanced.source_chain_data — Function
source_chain_data(chain)

Return the nonzero coefficients of a source chain together with their cell indices, source identities, oriented geometry and appearance grades. The result also gives the degree, chain kind, parameter, field, construction information and verification or optimization metadata. Over a prime field, coefficients are represented by their canonical integer residues.

Cell indices are positions within the chain degree. Source identities refer to the input model and are retained separately from those positions.

TamerOp.Advanced.check_source_correspondence — Function
check_source_correspondence(c; throw=false)

Check the two filtered complexes and their map equations over the retained field. Each map must commute with taking boundaries and send active cells to active cells. If a retraction is retained, also check retraction * lift == identity in each degree.

Return a SourceValidationSummary containing valid and issues, or raise an ArgumentError on failure when throw=true. The splitting equation makes the lift injective on homology; it does not exclude additional source classes.

TamerOp.Advanced.check_source_chain — Function
check_source_chain(chain; throw=false)

Check the source complex, support activity and the equation required by the chain kind. A cycle must have zero boundary; a cocycle must vanish on every active boundary. An arbitrary :chain, such as a death filling, need not satisfy either equation on its own.

Return a SourceValidationSummary with valid and issues, or raise an ArgumentError on failure when throw=true.

TamerOp.Advanced.optimize_representative — Function
optimize_representative(c; weights=nothing, max_candidates=100000)

Find a cycle of minimum weighted support in the homology class of the nonzero SourceChain c, at its declared parameter and over its prime field. Weights are finite nonnegative real numbers, one per source cell of that degree; the default gives every cell weight one. The objective sums weights at cells with nonzero coefficients, regardless of coefficient magnitude.

Enumerate the active boundary image exactly, refusing the problem before search if the number of candidates exceeds max_candidates. Ties keep the first enumerated chain. The returned source cycle records its weights, objective, candidate count and an explicit chain whose boundary is the difference from the original cycle. This certifies the unchanged nonzero class. The minimum uses the declared cell weights and active complex; it need not minimize Euclidean length or remain minimal at another parameter.

Components and merge histories

component_history(cells) constructs a ComponentHistory from the vertices and edges of a FilteredComplex, its one-skeleton. The history retains original vertex and edge identities and exact births and merges. Each edge with nonzero boundary must have two opposite unit coefficients, giving its endpoints. A loop with zero boundary cannot join two components. Higher cells do not change degree zero homology, so under this incidence condition the component history is independent of the coefficient field.

Start with component_count(history; scale) if you only need a count. components_at(history; scale) returns the partition in rows containing component, node, vertices and sources. Vertex indices are positions in the source vertex list; sources contains the original source identities. component_members(history; scale, component) follows the chosen birth vertex. Its status is :not_born, :alive or :merged. After the selected bar dies, its vertices belong to the returned descendant component, while the bar itself remains ended.

For a source with one parameter, scale uses the original parameter units, including superlevel thresholds. For several parameters, construct the history with slice=(base=(...), direction=(...)). Queries then use the scalar $t$ along base + t * direction. Each direction coordinate must advance strictly in its declared source order; a superlevel coordinate requires a negative direction, and zero direction coordinates are rejected. A multicritical cell enters at the earliest slice parameter reaching any of its appearance grades. No direction normalization or sampling is applied. The resulting history belongs to this line, rather than assigning a universal merge tree to the multiparameter filtration.

All events at the query scale are included. The older birth survives a merge, with the smaller source vertex index breaking equal birth ties. Edges at the same grade are processed in source order. This gives a reproducible binary forest for a simultaneous event without assigning different times to its merges. Births that die at the same parameter remain in the forest. component_intervals(h; include_ephemeral=true) includes their empty intervals in its returned rows; an ordinary barcode omits them.

The detailed operations belong to Advanced, with implementation in OrdinaryPersistence:

OperationResult
component_history_summary(h)Counts and conventions without listing memberships; also available through describe.
component_intervals(h; include_ephemeral=false)Rows containing a source birth vertex label, birth, death, immediate absorbing label and source identity. Essential death is nothing, relative to the retained source. Superlevel endpoints keep original units.
component_merges(h)The merge node, exact scale, joining edge and source identity, both children and the survivor and absorbed labels. Leaf nodes are vertex indices; merge nodes follow them.
component_parameter(h, scale)The corresponding original parameter tuple.
check_component_history(h; throw=false)Checks the source and forest, including reconstruction of exact events. This performs a full validation.

persistence_diagram(h; field=PrimeField(2)) produces the ordinary degree zero diagram. Metadata retains birth vertex labels for finite and essential intervals. Those labels belong to the history and need not be the representatives chosen by an independent reduction. Keep the history for membership queries: the generated diagram contains intervals and labels without copying the source correspondence.

Conversely, component_history(diagram) requires retained source data and checks equality of degree zero interval multisets. Equal intervals do not identify individual basis representatives. A SourceCorrespondence input requires a checked retraction and complexes satisfying the graph incidence condition on both sides. It compares their degree zero interval multisets and obtains memberships from the original source. These correspondence and diagram methods accept one parameter; for a slice of a multiparameter source, pass the retained original FilteredComplex directly.

A reduced FilteredComplex supplied alone describes its retained cells and cannot recover removed vertices. An unrelated encoding or unsupported reduced basis likewise cannot provide source membership solely through equal endpoints or positions in a picture.

Static and linked component views

visualize(h; scale) shows the degree zero intervals, source components and merge forest. component selects a source birth vertex. event selects a merge node, moves to its exact scale and by default selects the absorbed birth label. Source geometry uses two or three coordinates; give an explicit view_dims projection for more coordinates.

Superlevel charts show increasing progress as -parameter, while controls and exact records keep the original parameter units. Connectivity comes from source incidences, including periodic identifications. If distinct exact values round to the same drawing coordinate, the readout reports this while retaining the exact selection and membership.

max_cells=10000 bounds the source drawing. max_branches=100 separately bounds interval rows and displayed forest nodes, prioritizing selected records and reporting omissions. No extra merge replaces an omitted node. max_labels=30 limits labels and the compact membership readout. show_ephemeral=false hides empty bars by default. These drawing limits leave the full partition and exact selection in snapshot metadata unchanged.

inspection_session(h; scale, ...) creates a ComponentInspectionSession; render it with visualize(session; backend=:wglmakie). The browser links bars, source vertices in a planar view and forest nodes to exact scale, component and event controls. Three dimensional source geometry remains rotatable; selection is available through bars, the forest and controls. Previous and next buttons visit source event scales. Hover reads already prepared identities.

Advanced.select_inspection! changes scale, component or event. Changing the scale or component clears the selected event unless one is explicitly supplied, and invalid changes preserve the previous snapshot. Independent rendered views share selection and release their own listeners when disconnected. Closing the session releases its input and listeners and retains the final static snapshot. The live inspection guide explains this shared session behavior.

Construction sorts edge events and stores a forest of linear size. Counting components traverses the forest without listing their vertices; full membership queries and visualization snapshots construct the source vertex partition. Drawing limits do not reduce that algebraic query. Treat retained source and history arrays as read only.

TamerOp.component_history — Function
component_history(source::FilteredComplex; slice=nothing)
component_history(source::SourceCorrespondence)
component_history(diagram::PersistenceDiagram)

Compute H0 component births and merges from the retained source one-skeleton. Each nonzero edge boundary must have two opposite unit coefficients; loops with zero boundary do not merge components. Higher cells do not change H0. The calculation is field independent for this cellular contract.

One-parameter sources use their original parameter (including superlevels). For multiparameter sources supply slice=(base=..., direction=...), with every direction strictly positive in the declared oriented order. A cell with several critical grades enters at the minimum of their slice-entry times. Slice queries use its affine parameter t. No normalization or sampling is hidden.

Vertices precede edges at tied events; the older component survives, with ties broken by source vertex index. Membership at an event includes all cells at that event. Zero-length bars remain in the forest and are omitted from its ordinary diagram. Source-correspondence inputs require a verified retraction and the same graph-incidence contract on both complexes. Storage is linear in vertices/edges; memberships are materialized only when requested. A diagram input must retain source correspondence. Its H0 interval multiset is checked against the original source; repeated equal bars do not identify individual reduction-basis representatives.

TamerOp.component_count — Function

component_count(h; scale) counts actual components after all events at scale, without materializing memberships.

TamerOp.components_at — Function

components_at(h; scale) materializes the partition of active source vertices, with persistent elder labels and original source identities.

TamerOp.component_members — Function
component_members(h; scale, component)

Follow the source birth vertex labelled component. Return its current actual component and original vertex IDs. status=:merged explicitly follows its descendant after the selected bar dies; it does not assert that the bar survives. Before birth the membership is empty. All events at the queried scale are included.

TamerOp.OrdinaryPersistence.ComponentHistory — Type
ComponentHistory

A merge forest for one specified one-parameter filtration or oriented affine slice of a FilteredComplex. Construct with component_history. The forest retains original vertex/edge indices and exact event parameters, including simultaneous and zero-length births. Elder ties use the source vertex index; this is a reproducible choice, not a canonical identity of tied classes.

Use component_count for a cheap count, components_at or component_members for requested memberships, and component_intervals/component_merges for bars and events. Retained inputs/arrays must be treated as read-only.

TamerOp.Advanced.component_intervals — Function

component_intervals(h; include_ephemeral=false) returns bars labelled by their source birth vertex. Death is nothing for essential bars; superlevel endpoints use original units.

TamerOp.Advanced.component_merges — Function

component_merges(h) lists actual merge edges, both child nodes, surviving/absorbed birth vertices, and exact scales. Equal scales are simultaneous; their binary display order is a choice.

TamerOp.Advanced.check_component_history — Function

Validation of a supplied merge history, including its source, slice and reconstructed forest. This explicit check rebuilds the history; ordinary count/membership queries do not.

TamerOp.Advanced.ComponentInspectionSession — Type
ComponentInspectionSession

Linked H0 interval, merge-forest and original source membership views, created by inspection_session(component_history(source); ...). Updates select scale, component (a birth-vertex index), or an event (a merge-node index). Selecting an event moves to its exact scale; editing scale clears the selected event. Hover reads prepared metadata. Closing releases inputs and listeners while retaining the final static snapshot. Inputs must remain read-only while in use.

To express a selected image in a finite homology module on source cells, use propagation_source_chain. Supply the ordered target homology basis explicitly. The routine checks that basis but relies on the declared correspondence with module coordinates. See the selected vector source link.