Bottleneck and Wasserstein distance between two persistence diagrams, plus the ground-metric convention they share. Hand-rolled per .claude/WORKLOG-mainstream-feature-gap-analysis.md item 4: pure bipartite matching over diagram points (each also matchable to its own projection onto the diagonal birth = death), not a boundary- matrix optimization like the circular-coordinates/optimal-cycles items -- no relation to Barcode's map/kernel/cokernel algebra, hence its own file/object.
Parameter naming and the ground-metric/aggregation split follow Hera (anigmetov/hera) and GUDHI's own wasserstein_distance, cross-checked against both (not recalled from memory, and independently re-derived below) rather than assumed: groundNorm (GUDHI/Hera's internal_p) is the norm on the birth-death plane used to cost a single matched pair; order (GUDHI/Hera's order/wasserstein_power, called q in Kerber-Morozov-Nigmetov 2017) is the exponent used to aggregate all matched pairs' costs into one number. As order -> Infinity this aggregation becomes a max, i.e. Wasserstein converges to bottleneck -- but wassersteinDistance below only accepts finite order (seeding a Hungarian cost matrix with cost^Infinity is not meaningful); call bottleneckDistance directly for that case, matching how GUDHI/Hera expose them as separate entry points rather than one function with an infinite default.
'''Essential (never-dying) bars''': matched only to other essential bars, never to the diagonal (infinite persistence means infinite distance to the diagonal under any ground norm) and never to a finite bar (infinite vs. finite death is likewise infinitely bad). If the two diagrams have different numbers of essential bars, the distance is Double.PositiveInfinity -- there is no finite matching. When the counts agree, essential bars carry no usable death coordinate (both are "the same" point at infinity, contributing nothing to the cost), so they are matched purely by ascending birth value; this is provably cost-minimal for both the sum-of- powers (Wasserstein) and max (bottleneck) aggregations, by the standard line-matching exchange argument (for any x1 < x2, y1 < y2: max/sum of the sorted pairing (x1,y1),(x2,y2) never exceeds the crossed pairing (x1,y2),(x2,y1)), so it can be resolved directly instead of routed through the general bipartite solvers below. This also keeps Infinity values out of the Hungarian/Hopcroft-Karp cost matrices entirely (an Infinity - Infinity = NaN landmine in the Hungarian potential updates, avoided by construction rather than guarded against).
The ground metric on the birth-death plane used to cost one matched pair of diagram points (GUDHI/Hera's internal_p). LInfinity (the default in both) is the usual TDA convention.
The ground metric on the birth-death plane used to cost one matched pair of diagram points (GUDHI/Hera's internal_p). LInfinity (the default in both) is the usual TDA convention.
Bottleneck distance between two persistence diagrams of a single homological dimension. diagram1/ diagram2 must each be internally homogeneous in .dim (a mismatch usually means an unfiltered multi-dimensional barcode was passed by mistake -- use bottleneckDistanceByDimension for that case); the two diagrams' own dimensions are not required to agree with each other, since asking that question directly (rather than through bottleneckDistanceByDimension) is treated as a deliberate choice, not a mistake to guard against. See the class doc for the essential-bar policy and the ground-metric/aggregation convention.
Bottleneck distance between two persistence diagrams of a single homological dimension. diagram1/ diagram2 must each be internally homogeneous in .dim (a mismatch usually means an unfiltered multi-dimensional barcode was passed by mistake -- use bottleneckDistanceByDimension for that case); the two diagrams' own dimensions are not required to agree with each other, since asking that question directly (rather than through bottleneckDistanceByDimension) is treated as a deliberate choice, not a mistake to guard against. See the class doc for the essential-bar policy and the ground-metric/aggregation convention.
Convenience wrapper: groups two (possibly multi-dimensional) barcodes by .dim and computes bottleneckDistance within each dimension present in either one (a dimension missing from one side is treated as the empty diagram on that side, i.e. every bar on the other side must die to the diagonal, or the comparison is Infinity if any of them is essential).
Convenience wrapper: groups two (possibly multi-dimensional) barcodes by .dim and computes bottleneckDistance within each dimension present in either one (a dimension missing from one side is treated as the empty diagram on that side, i.e. every bar on the other side must die to the diagonal, or the comparison is Infinity if any of them is essential).
Wasserstein distance (order order, default 1.0) between two persistence diagrams of a single homological dimension. Same single-dimension-per-list requirement, essential-bar policy, and ground-metric convention as bottleneckDistance -- see the class doc. order must be finite and >= 1.0; call bottleneckDistance directly for the order = Infinity case.
Wasserstein distance (order order, default 1.0) between two persistence diagrams of a single homological dimension. Same single-dimension-per-list requirement, essential-bar policy, and ground-metric convention as bottleneckDistance -- see the class doc. order must be finite and >= 1.0; call bottleneckDistance directly for the order = Infinity case.