Topp Python API

中文 · Usage · Mathematics

All public objects are imported from topp. topp._core is private and has no compatibility guarantee.

Input type

DiagramLike is a runtime and typing alias exported from topp; it represents a strict real-valued array-like input or a PreparedDiagram. Array-like inputs must convert to a float64 array of shape (n, 2). See Inputs, duplicates, and essential points for strict validation rules.

PreparedDiagram

An immutable preprocessed object returned by prepare_diagram.

• n_points: rows in the valid original input, including diagonal and essential points;

• n_finite_points: finite points strictly above the diagonal;

• len(prepared): equal to n_points.

prepare_diagram(diagram) -> PreparedDiagram

Validates and copies the input, then creates caches used by batch operations. Later input mutations cannot affect the prepared object. Passing an existing PreparedDiagram returns it unchanged.

bottleneck_distance(diagram_a, diagram_b) -> float

Returns the exact Bottleneck distance with L∞ between points and infinite diagonal multiplicity. The result may be np.inf.

wasserstein_distance(diagram_a, diagram_b, *, order=1, internal_p=np.inf) -> float

Supported combinations:

• order=1, internal_p=np.inf: exact W1-L∞;

• order=2, internal_p=2: exact W2-L2.

Other combinations raise NotImplementedError.

bottleneck_distances(query, diagrams, *, out=None) -> np.ndarray

Computes one-to-many exact Bottleneck distances in one native call. Returns a float64 array of shape (m,). A valid out is filled and returned unchanged; it must be writable, aligned, C-contiguous, float64, and correctly sized.

wasserstein_distances(query, diagrams, *, order=1, internal_p=np.inf, out=None) -> np.ndarray

Computes one-to-many Wasserstein distances in one native call and reuses a workspace across the batch. Metric parameters match the pairwise function.

bottleneck_within(diagram_a, diagram_b, threshold) -> bool

Exact decision API. Returns True exactly when the Bottleneck distance is <= threshold. The threshold must be non-negative and not NaN; +inf is valid.

Exceptions

• TypeError: non-real diagrams, invalid scalar types, non-iterable targets, or an invalid out type;

• ValueError: invalid shape, float64 representability, point semantics, scalar value, or out layout;

• NotImplementedError: valid but unsupported Wasserstein parameter combinations;

• MemoryError: native allocation failure.

Threads and the GIL

Native distance calculations and batch loops release the Python GIL. PreparedDiagram is immutable and safe for concurrent reads; callers must synchronize concurrent writes to out.