TDA4j

Circular coordinates (de Silva-Morozov-Vejdemo-Johansson) for one persistent H¹ class of points' own Vietoris-Rips complex -- see homology.CircularCoordinates.compute's own doc for r/cocycleIndex/prime's exact meaning and the full construction, and h1Bars above for how to find a valid r. Throws IllegalArgumentException for an invalid r/cocycleIndex/prime, or NoIntegerCocycleException (a RuntimeException, so it crosses MATLAB's Java bridge the same way IllegalArgumentException already does) if the chosen class has no exact integer lift at prime -- see that exception's own doc for what to do about it (usually: retry with a larger prime).

Cubical persistence of a dense n-dimensional grid (an image or voxel volume): a flat, row-major array of per-pixel/voxel values plus an explicit shape -- the same convention CubicalImage.fromFlatArray uses (last axis fastest-varying, so shape=(rows,cols)/a flattened Array[Array[Double]] matches an ordinary 2D image). computeFromImage below is a double[][]-typed 2D convenience wrapper over this, MATLAB's own natural matrix shape for the common image case.

There is no "complex" option here -- a cubical grid is a different SHAPE of input entirely (no metric space, no point coordinates), not a different value for an existing option, so it gets its own entry point rather than a new "complex" value on computeFromPoints/computeFromDistanceMatrix. Recognized options:

• "engine": "naive" (default), "chunks", "cohomology", or "fast-cubical" -- "ripser" is never offered here: PackedRipserCohomologyContext is specialized to Simplex[Int] Vietoris-Rips complexes and has no notion of a cubical complex at all. "fast-cubical" (homology.FastCubicalHomologyContext, Le Breton- Szustakowski-Piraud's dual-graph union-find, extended past 2D by a hybrid with chunks for the residual middle dimensions) is refused only for a degenerate 1-axis "image" (ambient dimension < 2) -- see CLAUDE.md's Cubical complexes section and .claude/DESIGN-fast-engines-hybrid-middle-dimensions.md.
• "maxDimension": integer, default is the grid's own ambient dimension (i.e. "give me everything"). Unlike complex=vr/"cech" above, a cubical grid's own top dimension is ALREADY naturally bounded by its ambient dimension (an image's own dimensionality) and is never artificially cut short the way an unbounded VR/Cech complex is -- so this option is purely an opt-in performance cap for a caller who only wants low-dimensional homology, not a correctness necessity.
• "sublevel": "true" (default) or "false" -- sublevel-set (ascending intensity) filtration, GUDHI/DIPHA/ Perseus's own convention, or superlevel-set ("false" -- the standard "sublevel of -f is superlevel of f" trick, see CubicalImage.scala's own doc). Reported birth/death values under sublevel=false are in NEGATED-intensity units, not raw pixel values -- documented, expected behavior of this trick, not a bug.
• "field"/"prime"/"epsilon": same as computeFromPoints above.

Vietoris-Rips persistence from a precomputed pairwise-distance matrix (square, symmetric, zero diagonal -- expected but not checked beyond squareness, matching ExplicitMetricSpace's own contract). Use this when your dissimilarity measure isn't Euclidean distance on the rows you'd otherwise pass to computeFromPoints. complex=alpha is not available here -- alpha complexes need real coordinates.

Step 2 (distance-matrix input) -- see computeFromPointsAndLandmarks's own doc; identical recipe, just from a precomputed pairwise-distance matrix instead of point coordinates.

2D convenience over computeFromCubicalImage: pixels(i)(j) as a dense grid, shape (pixels.length, pixels(0).length) -- MATLAB's own natural matrix type, so the common 2D image case needs no explicit shape/flattening. See computeFromCubicalImage for recognized options; this delegates to it directly.

Vietoris-Rips or alpha-complex persistence from a point cloud (one row per point, Euclidean distance). This is the only entry point that supports complex=alpha, since alpha complexes need actual coordinates, not just pairwise distances.

Step 2 (point-cloud input) of the two-step witness recipe: compute the witness complex barcode for an EXPLICIT, caller-supplied landmark set (0-based ambient indices into points) -- typically LandmarkSelectionResult.landmarks() from step 1, but any hand-picked or reused set works too; this method never re-selects landmarks itself. Always computes complex=witness (there is nothing else it could compute) -- "complex" is accepted as an option ONLY when its value is "witness", so a caller migrating from the one-shot computeFromPoints who still types that flag out of habit isn't silently ignored, but a genuine mismatch (e.g. a stray "complex","vr") IS caught. Recognizes "witnessVariant", "nu", "engine", "maxDimension", "maxFiltrationValue", "field", "prime", "epsilon" -- see computeFromPoints's own doc for what each means; NOT "numLandmarks"/"landmarkSelector"/ "landmarkSeed", since landmarks are supplied directly here, not selected.

landmarks must be non-empty, every entry in [0, points.length), and free of duplicates -- checked eagerly with an actionable message (an out-of-range index equal to points.length specifically hints at a 1-based-indexing mistake, MATLAB's own default convention).

Dowker complex persistence from a general relation R: L x W -> [0, Infinity] (relation(x)(w), one row per L-side point, one column per witness w) -- NOT a point cloud or a distance matrix, so this is a separate entry point rather than a "complex" value on computeFromPoints/computeFromDistanceMatrix (see streams.DowkerGeometry's own doc for why: R need not be square, symmetric, or derived from any metric at all). relation values must be non-negative; +Infinity is the correct way to encode "never related" (see streams.DowkerGeometry.fromBoolean for lifting a classical boolean relation).

Recognizes:

• "engine": "naive" (default) or "cohomology" only -- the Dowker complex is not a flag complex in general (a witness for a whole simplex need not witness any of its edges, see streams.DowkerGeometry's own doc), so "ripser"/"chunks" are refused, exactly like complex=witness with witnessVariant=general.
• "maxDimension": integer, default 2 -- same "top homological degree reported" meaning as computeFromPoints's own option; both engines here need the internal "+1" build-and-drop dance since the Dowker complex's own top dimension is not naturally bounded (up to relation.length - 1, same status as complex=cech/complex=witness with witnessVariant=general).
• "maxFiltrationValue": double, default +Infinity (NOT a minimumEnclosingRadius-style truncation -- an arbitrary relation gives no cone argument to truncate against, same reasoning as complex=witness/witnessVariant=general's own default).
• "dual": "true" or "false" (default) -- when true, computes the W-side complex (vertices = one per COLUMN of relation, witnessed by rows) instead of the L-side complex, via streams.DowkerGeometry.dual (the transposed relation). The functorial Dowker duality theorem guarantees the two sides' barcodes agree exactly once zero-persistence bars are dropped -- see .claude/WORKLOG-dowker-complex.md -- so this is the direct way to get the OTHER side's representatives (e.g. when L is small but W's own representatives are what a caller actually wants) without transposing relation by hand.
• "field", "prime", "epsilon": same as computeFromPoints.

See coveringRadiusFromPoints's own doc; identical, just from a precomputed pairwise-distance matrix.

The covering radius R = max_x min_{l in landmarks} d(x,l) of an ARBITRARY landmark set -- not necessarily one selectLandmarksFrom* chose (e.g. a hand-picked or externally-computed set) -- for the same 2R threshold recipe LandmarkSelectionResult.coveringRadius() supports for a selectLandmarksFrom*-chosen set. Same landmark validation as computeFromPointsAndLandmarks.

The (birth, death) range of every persistent H¹ class of points' own Vietoris-Rips complex, as an N-by-2 array (column 0 birth, column 1 death, +Inf for an essential bar), sorted by persistence descending -- row i here is exactly circularCoordinates's own cocycleIndex = i. There is no way to pick a meaningful r for circularCoordinates without first knowing a target bar's own range, so this is the intended first call for a MATLAB caller, not merely a diagnostic -- see homology.CircularCoordinates.h1Bars's own doc.

Step 1 (distance-matrix input) -- see selectLandmarksFromPoints's own doc; identical recipe, just from a precomputed pairwise-distance matrix instead of point coordinates.

Step 1 (point-cloud input) of the two-step witness recipe: pick landmarks via "landmarkSelector" ("maxmin" default or "random", seeded by "landmarkSeed") and read back the covering radius R -- without yet building any complex. Recognizes ONLY "numLandmarks" (REQUIRED), "landmarkSelector", and "landmarkSeed" -- a STRICTER allowlist than computeFromPoints's own (see landmarkSelectionKeys's own doc for why). Pass LandmarkSelectionResult.landmarks() straight into computeFromPointsAndLandmarks for step 2, or into coveringRadiusFromPoints if you want R for a DIFFERENT (e.g. hand-edited) landmark set.