Python API Reference

This page is generated from the public morseframes Python module. The documentation build uses the pure-Python fallback, so the optional C++ extension does not need to be compiled on Read the Docs.

Python interface for MorseFrames.

This module intentionally mirrors the C++ core in include/morseframes. When the nanobind extension is available, finalized complexes and Morse sequences carry stateful C++ objects; otherwise the same API falls back to the pure-Python implementation.

class morseframes.AdaptivePersistenceResult(diagram: 'PersistenceDiagram', method: 'str', sequence: 'MorseSequence', num_simplices: 'int', num_critical_simplices: 'int', critical_ratio: 'float', max_critical_ratio: 'float', sequence_seconds: 'float', persistence_seconds: 'float', total_seconds: 'float', fallback_reason: 'str | None' = None, candidate_profiles: 'tuple[MorseReferenceProfile, ...]' = (), candidate_benchmarks: 'tuple[PersistenceBenchmark, ...]' = (), selection_metric: 'str | None' = None, selection_mode: 'str | None' = None)

Bases: object

Parameters:

  • diagram (PersistenceDiagram)

  • method (str)

  • sequence (MorseSequence)

  • num_simplices (int)

  • num_critical_simplices (int)

  • critical_ratio (float)

  • max_critical_ratio (float)

  • sequence_seconds (float)

  • persistence_seconds (float)

  • total_seconds (float)

  • fallback_reason (str | None)

  • candidate_profiles (tuple[MorseReferenceProfile, ...])

  • candidate_benchmarks (tuple[PersistenceBenchmark, ...])

  • selection_metric (str | None)

  • selection_mode (str | None)

candidate_benchmarks: tuple[PersistenceBenchmark, ...] = ()
candidate_profiles: tuple[MorseReferenceProfile, ...] = ()
critical_ratio: float
diagram: PersistenceDiagram
essential_barcode()
Return type:

tuple[tuple[int, float], …]

fallback_reason: str | None = None
finite_barcode(*, include_zero=False)
Parameters:

include_zero (bool)

Return type:

tuple[tuple[int, float, float], …]

max_critical_ratio: float
method: str
num_critical_simplices: int
num_simplices: int
persistence_seconds: float
selection_metric: str | None = None
selection_mode: str | None = None
sequence: MorseSequence
sequence_seconds: float
total_seconds: float
class morseframes.CoreductionDirectionBenchmark(direction: 'str', num_simplices: 'int', num_levels: 'int', num_critical_simplices: 'int', frame_seconds: 'float', morse_reduction_seconds: 'float', reducer_setup_seconds: 'float', reducer_compute_seconds: 'float', morse_seconds: 'float', standard_seconds: 'float', repeats: 'int', finite_interval_count: 'int', essential_interval_count: 'int', reducer_working_set_size: 'int', reducer_initial_total_annotation_size: 'int', reducer_boundary_annotation_xors: 'int', reducer_boundary_annotation_total_input_size: 'int', reducer_boundary_annotation_total_output_size: 'int', reducer_pivot_eliminations: 'int', reducer_xor_applied: 'int', reducer_xor_total_input_size: 'int', reducer_xor_total_output_size: 'int', metrics: 'dict[str, object]' = <factory>)

Bases: object

Parameters:

  • direction (str)

  • num_simplices (int)

  • num_levels (int)

  • num_critical_simplices (int)

  • frame_seconds (float)

  • morse_reduction_seconds (float)

  • reducer_setup_seconds (float)

  • reducer_compute_seconds (float)

  • morse_seconds (float)

  • standard_seconds (float)

  • repeats (int)

  • finite_interval_count (int)

  • essential_interval_count (int)

  • reducer_working_set_size (int)

  • reducer_initial_total_annotation_size (int)

  • reducer_boundary_annotation_xors (int)

  • reducer_boundary_annotation_total_input_size (int)

  • reducer_boundary_annotation_total_output_size (int)

  • reducer_pivot_eliminations (int)

  • reducer_xor_applied (int)

  • reducer_xor_total_input_size (int)

  • reducer_xor_total_output_size (int)

  • metrics (dict[str, object])

property critical_ratio: float
direction: str
essential_interval_count: int
finite_interval_count: int
frame_seconds: float
metrics: dict[str, object]
morse_reduction_seconds: float
morse_seconds: float
num_critical_simplices: int
num_levels: int
num_simplices: int
reducer_boundary_annotation_total_input_size: int
reducer_boundary_annotation_total_output_size: int
reducer_boundary_annotation_xors: int
reducer_compute_seconds: float
reducer_initial_total_annotation_size: int
reducer_pivot_eliminations: int
reducer_setup_seconds: float
reducer_working_set_size: int
reducer_xor_applied: int
reducer_xor_total_input_size: int
reducer_xor_total_output_size: int
repeats: int
property speedup: float
standard_seconds: float
class morseframes.EssentialInterval(birth: 'int', dimension: 'int', birth_value: 'float')

Bases: object

Parameters:

  • birth (int)

  • dimension (int)

  • birth_value (float)

birth: int
birth_value: float
dimension: int
class morseframes.EssentialIntervalSimplices(birth: 'Simplex', dimension: 'int', birth_value: 'float')

Bases: object

Parameters:

  • birth (tuple[int, ...])

  • dimension (int)

  • birth_value (float)

birth: tuple[int, ...]
birth_value: float
dimension: int
class morseframes.FilteredComplex

Bases: object

Finite filtered abstract simplicial complex.

Simplices are inserted explicitly. finalize checks closure under faces, validates filtration monotonicity, assigns simplex ids, and builds boundary and coboundary incidence.

add_simplex(vertices, filtration)
Parameters:

  • vertices (Sequence[int])

  • filtration (float)

Return type:

FilteredComplex

as_simplices()
Return type:

tuple[tuple[int, …], …]

boundary(simplex_id)
Parameters:

simplex_id (int)

Return type:

tuple[int, …]

boundary_simplices(simplex_or_vertices)
Parameters:

simplex_or_vertices (int | Sequence[int])

Return type:

tuple[tuple[int, …], …]

coboundary(simplex_id)
Parameters:

simplex_id (int)

Return type:

tuple[int, …]

coboundary_simplices(simplex_or_vertices)
Parameters:

simplex_or_vertices (int | Sequence[int])

Return type:

tuple[tuple[int, …], …]

contains(vertices)
Parameters:

vertices (Sequence[int])

Return type:

bool

cpp_backend_active()
Return type:

bool

dimension(simplex_id)
Parameters:

simplex_id (int)

Return type:

int

filtration(simplex_id)
Parameters:

simplex_id (int)

Return type:

float

filtration_list()
Return type:

tuple[tuple[tuple[int, …], float], …]

filtration_of(vertices)
Parameters:

vertices (Sequence[int])

Return type:

float

property filtration_order: tuple[int, ...]
finalize()
Return type:

FilteredComplex

find_simplex(vertices)
Parameters:

vertices (Sequence[int])

Return type:

int | None

classmethod from_facets(facets, *, simplex_filtration=0.0, finalize=True)
Parameters:

  • facets (Iterable[Sequence[int]])

  • simplex_filtration (float | Mapping[tuple[int, ...], float] | Callable[[tuple[int, ...]], float])

  • finalize (bool)

Return type:

FilteredComplex

classmethod from_graph(edges, *, vertices=None, vertex_filtration=0.0, edge_filtration=None, finalize=True)
Parameters:

  • edges (Iterable[Sequence[int]])

  • vertices (Iterable[int] | None)

  • vertex_filtration (float | Mapping[int, float] | Sequence[float] | Callable[[int], float])

  • edge_filtration (float | Mapping[tuple[int, int], float] | Callable[[tuple[int, int]], float] | None)

  • finalize (bool)

Return type:

FilteredComplex

classmethod from_gudhi_simplex_tree(simplex_tree, *, finalize=True)
Parameters:

  • simplex_tree (object)

  • finalize (bool)

Return type:

FilteredComplex

classmethod from_lower_star(facets, vertex_values, *, dimension_offset=0.0, finalize=True)
Parameters:

  • facets (Iterable[Sequence[int]])

  • vertex_values (float | Mapping[int, float] | Sequence[float] | Callable[[int], float])

  • dimension_offset (float)

  • finalize (bool)

Return type:

FilteredComplex

classmethod from_rips_distance_matrix(distances, *, max_edge_length=inf, max_dimension=1, vertex_filtration=0.0, finalize=True)
Parameters:

  • distances (Sequence[Sequence[float]])

  • max_edge_length (float)

  • max_dimension (int)

  • vertex_filtration (float | Mapping[int, float] | Sequence[float] | Callable[[int], float])

  • finalize (bool)

Return type:

FilteredComplex

classmethod from_simplices(simplices, *, finalize=True)
Parameters:

  • simplices (Iterable[tuple[Sequence[int], float]])

  • finalize (bool)

Return type:

FilteredComplex

insert(vertices, filtration)
Parameters:

  • vertices (Sequence[int])

  • filtration (float)

Return type:

FilteredComplex

level(simplex_id)
Parameters:

simplex_id (int)

Return type:

int

property level_values: tuple[float, ...]
property num_levels: int
require_simplex_id(vertices)
Parameters:

vertices (Sequence[int])

Return type:

int

simplex(simplex_id)
Parameters:

simplex_id (int)

Return type:

SimplexRecord

simplex_id(vertices)
Parameters:

vertices (Sequence[int])

Return type:

int | None

simplex_list()
Return type:

tuple[tuple[int, …], …]

simplex_records()
Return type:

tuple[SimplexRecord, …]

simplices()
Return type:

Iterator[SimplexRecord]

simplices_of_level(level)
Parameters:

level (int)

Return type:

tuple[int, …]

property size: int
to_cpp()
Return type:

object

vertices(simplex_id)
Parameters:

simplex_id (int)

Return type:

tuple[int, …]

morseframes.FilteredComplexBuilder

alias of SimplexTreeBuilder

class morseframes.MorseComplex(critical_simplices: 'tuple[int, ...]', boundaries: 'dict[int, Annotation]', simplex_to_critical: 'dict[int, int]')

Bases: object

Parameters:

  • critical_simplices (tuple[int, ...])

  • boundaries (dict[int, tuple[int, ...]])

  • simplex_to_critical (dict[int, int])

as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[tuple[int, …], …]

boundaries: dict[int, tuple[int, ...]]
boundaries_as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

dict[tuple[int, …], tuple[tuple[int, …], …]]

boundary(critical_id)
Parameters:

critical_id (int)

Return type:

tuple[int, …]

boundary_as_simplices(complex_, critical_id)
Parameters:
Return type:

tuple[tuple[int, …], …]

critical_simplices: tuple[int, ...]
simplex_to_critical: dict[int, int]
class morseframes.MorseCoreferenceFrame(sequence: 'MorseSequence', _coreferences: 'tuple[Annotation, ...] | None' = None, _cpp_coreferences: 'object | None' = None, _cpp_frame: 'object | None' = None)

Bases: object

Parameters:

  • sequence (MorseSequence)

  • _coreferences (tuple[tuple[int, ...], ...] | None)

  • _cpp_coreferences (object | None)

  • _cpp_frame (object | None)

coreference_complex(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[tuple[tuple[int, …], …], …]

property coreferences: tuple[tuple[int, ...], ...]
coreferences_as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[tuple[tuple[int, …], …], …]

cpp_coreference_map_active()
Return type:

bool

sequence: MorseSequence
class morseframes.MorseReferenceFrame(sequence: 'MorseSequence', _references: 'tuple[Annotation, ...] | None' = None, _cpp_references: 'object | None' = None, _cpp_frame: 'object | None' = None)

Bases: object

Parameters:

  • sequence (MorseSequence)

  • _references (tuple[tuple[int, ...], ...] | None)

  • _cpp_references (object | None)

  • _cpp_frame (object | None)

cpp_reference_map_active()
Return type:

bool

reference_complex(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[tuple[tuple[int, …], …], …]

property references: tuple[tuple[int, ...], ...]
references_as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[tuple[tuple[int, …], …], …]

sequence: MorseSequence
class morseframes.MorseReferenceProfile(num_simplices: 'int', num_levels: 'int', num_critical_simplices: 'int', num_regular_pairs: 'int', sequence_algorithm: 'str', frame_mode: 'str', reference_final_live_nonempty_annotations: 'int', reference_final_live_total_annotation_size: 'int', reference_peak_live_nonempty_annotations: 'int', reference_peak_live_total_annotation_size: 'int', reference_released_annotations: 'int', reference_released_total_annotation_size: 'int', reducer_working_set_size: 'int', reducer_initial_nonempty_annotations: 'int', reducer_initial_total_annotation_size: 'int', reducer_initial_max_annotation_size: 'int', reducer_initial_inverse_list_entries: 'int', reducer_boundary_plan_face_scans: 'int', reducer_boundary_annotation_candidate_criticals: 'int', reducer_boundary_annotation_zero_skipped_criticals: 'int', reducer_boundary_annotation_zero_skipped_faces: 'int', reducer_boundary_annotation_xors: 'int', reducer_boundary_annotation_total_input_size: 'int', reducer_boundary_annotation_total_output_size: 'int', reducer_boundary_annotation_max_size: 'int', reducer_boundary_annotation_max_output_size: 'int', estimated_reducer_work: 'int', profile_seconds: 'float', metrics: 'dict[str, object]' = <factory>)

Bases: object

Parameters:

  • num_simplices (int)

  • num_levels (int)

  • num_critical_simplices (int)

  • num_regular_pairs (int)

  • sequence_algorithm (str)

  • frame_mode (str)

  • reference_final_live_nonempty_annotations (int)

  • reference_final_live_total_annotation_size (int)

  • reference_peak_live_nonempty_annotations (int)

  • reference_peak_live_total_annotation_size (int)

  • reference_released_annotations (int)

  • reference_released_total_annotation_size (int)

  • reducer_working_set_size (int)

  • reducer_initial_nonempty_annotations (int)

  • reducer_initial_total_annotation_size (int)

  • reducer_initial_max_annotation_size (int)

  • reducer_initial_inverse_list_entries (int)

  • reducer_boundary_plan_face_scans (int)

  • reducer_boundary_annotation_candidate_criticals (int)

  • reducer_boundary_annotation_zero_skipped_criticals (int)

  • reducer_boundary_annotation_zero_skipped_faces (int)

  • reducer_boundary_annotation_xors (int)

  • reducer_boundary_annotation_total_input_size (int)

  • reducer_boundary_annotation_total_output_size (int)

  • reducer_boundary_annotation_max_size (int)

  • reducer_boundary_annotation_max_output_size (int)

  • estimated_reducer_work (int)

  • profile_seconds (float)

  • metrics (dict[str, object])

property boundary_annotation_work: int
property critical_ratio: float
estimated_reducer_work: int
frame_mode: str
metrics: dict[str, object]
num_critical_simplices: int
num_levels: int
num_regular_pairs: int
num_simplices: int
profile_seconds: float
reducer_boundary_annotation_candidate_criticals: int
reducer_boundary_annotation_max_output_size: int
reducer_boundary_annotation_max_size: int
reducer_boundary_annotation_total_input_size: int
reducer_boundary_annotation_total_output_size: int
reducer_boundary_annotation_xors: int
reducer_boundary_annotation_zero_skipped_criticals: int
reducer_boundary_annotation_zero_skipped_faces: int
reducer_boundary_plan_face_scans: int
reducer_initial_inverse_list_entries: int
reducer_initial_max_annotation_size: int
reducer_initial_nonempty_annotations: int
reducer_initial_total_annotation_size: int
reducer_working_set_size: int
reference_final_live_nonempty_annotations: int
reference_final_live_total_annotation_size: int
reference_peak_live_nonempty_annotations: int
reference_peak_live_total_annotation_size: int
reference_released_annotations: int
reference_released_total_annotation_size: int
sequence_algorithm: str
class morseframes.MorseSequence(steps: 'tuple[MorseStep, ...]', critical_simplices: 'tuple[int, ...]', critical_index_of_simplex: 'tuple[int, ...]', paired_with: 'tuple[int | None, ...]', algorithm: 'str' = 'saturated', _cpp_payload: 'dict[str, object] | None' = None, _cpp_sequence: 'object | None' = None, _complex_signature: 'tuple[tuple[Simplex, float], ...] | None' = None)

Bases: object

Parameters:

  • steps (tuple[MorseStep, ...])

  • critical_simplices (tuple[int, ...])

  • critical_index_of_simplex (tuple[int, ...])

  • paired_with (tuple[int | None, ...])

  • algorithm (str)

  • _cpp_payload (dict[str, object] | None)

  • _cpp_sequence (object | None)

  • _complex_signature (tuple[tuple[tuple[int, ...], float], ...] | None)

algorithm: str = 'saturated'
as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[MorseStepSimplices, …]

cpp_backend_active()
Return type:

bool

critical_index(simplex_id)
Parameters:

simplex_id (int)

Return type:

int

critical_index_of_simplex: tuple[int, ...]
critical_simplices: tuple[int, ...]
critical_simplices_as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[tuple[int, …], …]

is_critical(simplex_id)
Parameters:

simplex_id (int)

Return type:

bool

paired_with: tuple[int | None, ...]
paired_with_as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[tuple[int, …] | None, …]

pairs_as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[tuple[tuple[int, …], tuple[int, …]], …]

steps: tuple[MorseStep, ...]
steps_as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[MorseStepSimplices, …]

class morseframes.MorseStep(type: 'str', sigma: 'int', tau: 'int | None', level: 'int')

Bases: object

Parameters:

  • type (str)

  • sigma (int)

  • tau (int | None)

  • level (int)

level: int
sigma: int
tau: int | None
type: str
class morseframes.MorseStepSimplices(type: 'str', sigma: 'Simplex', tau: 'Simplex | None', level: 'int')

Bases: object

Parameters:

  • type (str)

  • sigma (tuple[int, ...])

  • tau (tuple[int, ...] | None)

  • level (int)

level: int
sigma: tuple[int, ...]
tau: tuple[int, ...] | None
type: str
class morseframes.PersistenceBenchmark(num_simplices: 'int', num_levels: 'int', num_critical_simplices: 'int', sequence_algorithm: 'str', frame_mode: 'str', reference_final_live_nonempty_annotations: 'int', reference_final_live_total_annotation_size: 'int', reference_peak_live_nonempty_annotations: 'int', reference_peak_live_total_annotation_size: 'int', reference_released_annotations: 'int', reference_released_total_annotation_size: 'int', reducer_working_set_size: 'int', reducer_initial_nonempty_annotations: 'int', reducer_initial_total_annotation_size: 'int', reducer_initial_max_annotation_size: 'int', reducer_initial_inverse_list_entries: 'int', reducer_boundary_plan_face_scans: 'int', reducer_boundary_annotation_candidate_criticals: 'int', reducer_boundary_annotation_zero_skipped_criticals: 'int', reducer_boundary_annotation_zero_skipped_faces: 'int', reducer_boundary_annotation_xors: 'int', reducer_boundary_annotation_total_input_size: 'int', reducer_boundary_annotation_total_output_size: 'int', reducer_boundary_annotation_max_size: 'int', reducer_boundary_annotation_max_output_size: 'int', reducer_pivot_eliminations: 'int', reducer_remove_candidate_scans: 'int', reducer_remove_applied: 'int', reducer_remove_total_annotation_size: 'int', reducer_remove_max_annotation_size: 'int', reducer_xor_candidate_scans: 'int', reducer_xor_applied: 'int', reducer_xor_changed_labels: 'int', reducer_xor_total_input_size: 'int', reducer_xor_total_output_size: 'int', reducer_xor_max_input_size: 'int', reducer_xor_max_output_size: 'int', reducer_xor_inserted_labels: 'int', reducer_xor_removed_labels: 'int', reducer_inverse_list_appends: 'int', sequence_seconds: 'float', reference_seconds: 'float', morse_reduction_seconds: 'float', reducer_setup_seconds: 'float', reducer_compute_seconds: 'float', morse_seconds: 'float', standard_seconds: 'float', repeats: 'int', finite_interval_count: 'int', essential_interval_count: 'int', barcodes_materialized: 'bool', validation_mode: 'str', finite_barcode: 'tuple[tuple[int, float, float], ...]', essential_barcode: 'tuple[tuple[int, float], ...]')

Bases: object

Parameters:

  • num_simplices (int)

  • num_levels (int)

  • num_critical_simplices (int)

  • sequence_algorithm (str)

  • frame_mode (str)

  • reference_final_live_nonempty_annotations (int)

  • reference_final_live_total_annotation_size (int)

  • reference_peak_live_nonempty_annotations (int)

  • reference_peak_live_total_annotation_size (int)

  • reference_released_annotations (int)

  • reference_released_total_annotation_size (int)

  • reducer_working_set_size (int)

  • reducer_initial_nonempty_annotations (int)

  • reducer_initial_total_annotation_size (int)

  • reducer_initial_max_annotation_size (int)

  • reducer_initial_inverse_list_entries (int)

  • reducer_boundary_plan_face_scans (int)

  • reducer_boundary_annotation_candidate_criticals (int)

  • reducer_boundary_annotation_zero_skipped_criticals (int)

  • reducer_boundary_annotation_zero_skipped_faces (int)

  • reducer_boundary_annotation_xors (int)

  • reducer_boundary_annotation_total_input_size (int)

  • reducer_boundary_annotation_total_output_size (int)

  • reducer_boundary_annotation_max_size (int)

  • reducer_boundary_annotation_max_output_size (int)

  • reducer_pivot_eliminations (int)

  • reducer_remove_candidate_scans (int)

  • reducer_remove_applied (int)

  • reducer_remove_total_annotation_size (int)

  • reducer_remove_max_annotation_size (int)

  • reducer_xor_candidate_scans (int)

  • reducer_xor_applied (int)

  • reducer_xor_changed_labels (int)

  • reducer_xor_total_input_size (int)

  • reducer_xor_total_output_size (int)

  • reducer_xor_max_input_size (int)

  • reducer_xor_max_output_size (int)

  • reducer_xor_inserted_labels (int)

  • reducer_xor_removed_labels (int)

  • reducer_inverse_list_appends (int)

  • sequence_seconds (float)

  • reference_seconds (float)

  • morse_reduction_seconds (float)

  • reducer_setup_seconds (float)

  • reducer_compute_seconds (float)

  • morse_seconds (float)

  • standard_seconds (float)

  • repeats (int)

  • finite_interval_count (int)

  • essential_interval_count (int)

  • barcodes_materialized (bool)

  • validation_mode (str)

  • finite_barcode (tuple[tuple[int, float, float], ...])

  • essential_barcode (tuple[tuple[int, float], ...])

barcodes_materialized: bool
essential_barcode: tuple[tuple[int, float], ...]
essential_interval_count: int
finite_barcode: tuple[tuple[int, float, float], ...]
finite_interval_count: int
frame_mode: str
morse_reduction_seconds: float
morse_seconds: float
num_critical_simplices: int
num_levels: int
num_simplices: int
reducer_boundary_annotation_candidate_criticals: int
reducer_boundary_annotation_max_output_size: int
reducer_boundary_annotation_max_size: int
reducer_boundary_annotation_total_input_size: int
reducer_boundary_annotation_total_output_size: int
reducer_boundary_annotation_xors: int
reducer_boundary_annotation_zero_skipped_criticals: int
reducer_boundary_annotation_zero_skipped_faces: int
reducer_boundary_plan_face_scans: int
reducer_compute_seconds: float
reducer_initial_inverse_list_entries: int
reducer_initial_max_annotation_size: int
reducer_initial_nonempty_annotations: int
reducer_initial_total_annotation_size: int
reducer_inverse_list_appends: int
reducer_pivot_eliminations: int
reducer_remove_applied: int
reducer_remove_candidate_scans: int
reducer_remove_max_annotation_size: int
reducer_remove_total_annotation_size: int
reducer_setup_seconds: float
reducer_working_set_size: int
reducer_xor_applied: int
reducer_xor_candidate_scans: int
reducer_xor_changed_labels: int
reducer_xor_inserted_labels: int
reducer_xor_max_input_size: int
reducer_xor_max_output_size: int
reducer_xor_removed_labels: int
reducer_xor_total_input_size: int
reducer_xor_total_output_size: int
reference_final_live_nonempty_annotations: int
reference_final_live_total_annotation_size: int
reference_peak_live_nonempty_annotations: int
reference_peak_live_total_annotation_size: int
reference_released_annotations: int
reference_released_total_annotation_size: int
reference_seconds: float
repeats: int
sequence_algorithm: str
sequence_seconds: float
property speedup: float
standard_seconds: float
validation_mode: str
class morseframes.PersistenceDiagram(finite_pairs: 'tuple[PersistencePair, ...]', essential: 'tuple[EssentialInterval, ...]')

Bases: object

Parameters:
essential: tuple[EssentialInterval, ...]
essential_as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[EssentialIntervalSimplices, …]

essential_barcode()
Return type:

tuple[tuple[int, float], …]

finite_barcode(*, include_zero=False)
Parameters:

include_zero (bool)

Return type:

tuple[tuple[int, float, float], …]

finite_pairs: tuple[PersistencePair, ...]
finite_pairs_as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

tuple[PersistencePairSimplices, …]

intervals_as_simplices(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

dict[str, tuple[PersistencePairSimplices, …] | tuple[EssentialIntervalSimplices, …]]

class morseframes.PersistencePair(birth: 'int', death: 'int', dimension: 'int', birth_value: 'float', death_value: 'float')

Bases: object

Parameters:

  • birth (int)

  • death (int)

  • dimension (int)

  • birth_value (float)

  • death_value (float)

birth: int
birth_value: float
death: int
death_value: float
dimension: int
class morseframes.PersistencePairSimplices(birth: 'Simplex', death: 'Simplex', dimension: 'int', birth_value: 'float', death_value: 'float')

Bases: object

Parameters:

  • birth (tuple[int, ...])

  • death (tuple[int, ...])

  • dimension (int)

  • birth_value (float)

  • death_value (float)

birth: tuple[int, ...]
birth_value: float
death: tuple[int, ...]
death_value: float
dimension: int
morseframes.SameLevelReductionDirectionBenchmark

alias of CoreductionDirectionBenchmark

class morseframes.SimplexRecord(id: 'int', vertices: 'Simplex', dimension: 'int', level: 'int', filtration: 'float', boundary: 'tuple[int, ...]', coboundary: 'tuple[int, ...]')

Bases: object

Parameters:

  • id (int)

  • vertices (tuple[int, ...])

  • dimension (int)

  • level (int)

  • filtration (float)

  • boundary (tuple[int, ...])

  • coboundary (tuple[int, ...])

boundary: tuple[int, ...]
coboundary: tuple[int, ...]
dimension: int
filtration: float
id: int
level: int
vertices: tuple[int, ...]
class morseframes.SimplexTreeBuilder(*, merge='min', use_cpp=True)

Bases: object

Mutable construction helper that finalizes into a FilteredComplex.

The builder is intentionally a front-end only: it deduplicates incremental insertions and offers simplex-tree-style membership queries, then releases to the compact filtered complex used by the Morse and persistence kernels.

Parameters:

  • merge (str)

  • use_cpp (bool)

add_simplex(vertices, filtration=0.0, *, include_faces=True)
Parameters:

  • vertices (Sequence[int])

  • filtration (float)

  • include_faces (bool)

Return type:

SimplexTreeBuilder

clear()
Return type:

None

contains(vertices)
Parameters:

vertices (Sequence[int])

Return type:

bool

filtration(vertices)
Parameters:

vertices (Sequence[int])

Return type:

float

finalize(*, clear=True)
Parameters:

clear (bool)

Return type:

FilteredComplex

find_simplex(vertices)
Parameters:

vertices (Sequence[int])

Return type:

bool

classmethod from_facets(facets, *, simplex_filtration=0.0, merge='min')
Parameters:

  • facets (Iterable[Sequence[int]])

  • simplex_filtration (float | Mapping[tuple[int, ...], float] | Callable[[tuple[int, ...]], float])

  • merge (str)

Return type:

SimplexTreeBuilder

classmethod from_lower_star(facets, vertex_values, *, dimension_offset=0.0, merge='min')
Parameters:

  • facets (Iterable[Sequence[int]])

  • vertex_values (float | Mapping[int, float] | Sequence[float] | Callable[[int], float])

  • dimension_offset (float)

  • merge (str)

Return type:

SimplexTreeBuilder

get_filtration()
Return type:

tuple[tuple[tuple[int, …], float], …]

insert(vertices, filtration=0.0, *, include_faces=True)
Parameters:

  • vertices (Sequence[int])

  • filtration (float)

  • include_faces (bool)

Return type:

SimplexTreeBuilder

insert_facet(facet, *, simplex_filtration=0.0)
Parameters:

  • facet (Sequence[int])

  • simplex_filtration (float | Mapping[tuple[int, ...], float] | Callable[[tuple[int, ...]], float])

Return type:

SimplexTreeBuilder

insert_lower_star_facet(facet, vertex_values, *, dimension_offset=0.0)
Parameters:

  • facet (Sequence[int])

  • vertex_values (float | Mapping[int, float] | Sequence[float] | Callable[[int], float])

  • dimension_offset (float)

Return type:

SimplexTreeBuilder

insert_simplex(vertices, filtration=0.0, *, include_faces=True)
Parameters:

  • vertices (Sequence[int])

  • filtration (float)

  • include_faces (bool)

Return type:

SimplexTreeBuilder

insert_simplex_only(vertices, filtration=0.0)
Parameters:

  • vertices (Sequence[int])

  • filtration (float)

Return type:

SimplexTreeBuilder

property max_dimension: int
num_simplices()
Return type:

int

num_vertices()
Return type:

int

simplex_filtration(vertices)
Parameters:

vertices (Sequence[int])

Return type:

float

simplices()
Return type:

tuple[tuple[tuple[int, …], float], …]

property size: int
to_filtered_complex(*, finalize=True, clear=False)
Parameters:

  • finalize (bool)

  • clear (bool)

Return type:

FilteredComplex

to_gudhi_simplex_tree()
Return type:

object

morseframes.annotation_as_simplices(complex_, sequence, annotation)
Parameters:
Return type:

tuple[tuple[int, …], …]

morseframes.assert_matches_gudhi(complex_, *, include_zero=False)
Parameters:
Return type:

None

morseframes.assert_matches_standard(complex_, *, include_zero=False)
Parameters:
Return type:

None

morseframes.benchmark_coreduction_directions(complex_, *, repeats=3)
Parameters:
Return type:

tuple[CoreductionDirectionBenchmark, …]

morseframes.benchmark_persistence(complex_, *, repeats=3, sequence_algorithm='saturated', frame_mode='fused', materialize_barcodes=True)
Parameters:

  • complex_ (FilteredComplex)

  • repeats (int)

  • sequence_algorithm (str)

  • frame_mode (str)

  • materialize_barcodes (bool)

Return type:

PersistenceBenchmark

morseframes.benchmark_same_level_reduction_directions(complex_, *, repeats=3)

Benchmark reference/coreference directions for same-level reduction.

Parameters:
Return type:

tuple[CoreductionDirectionBenchmark, …]

morseframes.benchmark_sequence_algorithms(complex_, *, algorithms=('saturated', 'f-max', 'f-min', 'same-level-reduction', 'flooding-max', 'flooding-min', 'flooding-minmax', 'flooding-maxmin', 'plateau-greedy'), repeats=1, frame_mode='fused', materialize_barcodes=False)

Benchmark a portfolio of Morse sequence constructors on one complex.

Parameters:

  • complex_ (FilteredComplex)

  • algorithms (Iterable[str] | str | None)

  • repeats (int)

  • frame_mode (str)

  • materialize_barcodes (bool)

Return type:

tuple[PersistenceBenchmark, …]

morseframes.compute_coreference_complex(complex_, sequence=None, coreferences=None, *, algorithm='same-level-reduction')
Parameters:
Return type:

tuple[tuple[tuple[int, …], …], …]

morseframes.compute_coreference_map(complex_, sequence=None, *, algorithm='saturated')
Parameters:
Return type:

tuple[tuple[int, …], …]

morseframes.compute_coreference_map_modp(complex_, sequence=None, *, modulus, algorithm='saturated')

Compute the Morse coreference map over the prime field F_modulus.

Parameters:
Return type:

tuple[tuple[tuple[int, int], …], …]

morseframes.compute_morse_complex(complex_, sequence=None, references=None, *, algorithm='saturated')
Parameters:
Return type:

MorseComplex

morseframes.compute_morse_coreference_persistence(complex_, sequence=None, coreferences=None, *, algorithm='same-level-reduction', modulus=2)
Parameters:

  • complex_ (FilteredComplex)

  • sequence (MorseSequence | None)

  • coreferences (Sequence[tuple[int, ...]] | Sequence[tuple[tuple[int, int], ...]] | None)

  • algorithm (str)

  • modulus (int)

Return type:

PersistenceDiagram

morseframes.compute_morse_coreference_persistence_modp(complex_, sequence=None, coreferences=None, *, modulus, algorithm='same-level-reduction')

Compute Morse coreference persistence over the prime field F_modulus.

Parameters:

  • complex_ (FilteredComplex)

  • sequence (MorseSequence | None)

  • coreferences (Sequence[tuple[tuple[int, int], ...]] | None)

  • modulus (int)

  • algorithm (str)

Return type:

PersistenceDiagram

morseframes.compute_morse_persistence(complex_, sequence=None, references=None, *, algorithm='saturated', modulus=2)
Parameters:

  • complex_ (FilteredComplex)

  • sequence (MorseSequence | None)

  • references (Sequence[tuple[int, ...]] | Sequence[tuple[tuple[int, int], ...]] | None)

  • algorithm (str)

  • modulus (int)

Return type:

PersistenceDiagram

morseframes.compute_morse_persistence_modp(complex_, sequence=None, references=None, *, modulus, algorithm='saturated')

Compute Morse persistence over the prime field F_modulus.

Parameters:

  • complex_ (FilteredComplex)

  • sequence (MorseSequence | None)

  • references (Sequence[tuple[tuple[int, int], ...]] | None)

  • modulus (int)

  • algorithm (str)

Return type:

PersistenceDiagram

morseframes.compute_morse_sequence(complex_, *, algorithm='saturated')
Parameters:
Return type:

MorseSequence

morseframes.compute_morse_sequence_and_coreference_map(complex_, *, algorithm='same-level-reduction')
Parameters:
Return type:

MorseCoreferenceFrame

morseframes.compute_morse_sequence_and_reference_map(complex_, *, algorithm='saturated')
Parameters:
Return type:

MorseReferenceFrame

morseframes.compute_persistence_adaptive(complex_, *, max_critical_ratio=0.4, sequence_algorithm='saturated', candidate_algorithms=None, selection_repeats=1, selection_metric='estimated_reducer_work', selection_mode='profile', frame_mode='fused')
Parameters:

  • complex_ (FilteredComplex)

  • max_critical_ratio (float)

  • sequence_algorithm (str)

  • candidate_algorithms (Iterable[str] | str | None)

  • selection_repeats (int)

  • selection_metric (str)

  • selection_mode (str)

  • frame_mode (str)

Return type:

AdaptivePersistenceResult

morseframes.compute_persistence_portfolio(complex_, *, algorithms=('saturated', 'f-max', 'f-min', 'same-level-reduction', 'flooding-max', 'flooding-min', 'flooding-minmax', 'flooding-maxmin', 'plateau-greedy'), repeats=1, frame_mode='fused', selection_metric='morse_seconds', include_standard=True, max_critical_ratio=1.0)
Parameters:

  • complex_ (FilteredComplex)

  • algorithms (Iterable[str] | str | None)

  • repeats (int)

  • frame_mode (str)

  • selection_metric (str)

  • include_standard (bool)

  • max_critical_ratio (float)

Return type:

AdaptivePersistenceResult

morseframes.compute_persistence_profile_portfolio(complex_, *, algorithms=('saturated', 'f-max', 'f-min', 'same-level-reduction', 'flooding-max', 'flooding-min', 'flooding-minmax', 'flooding-maxmin', 'plateau-greedy'), repeats=1, selection_metric='estimated_reducer_work', max_critical_ratio=1.0)
Parameters:

  • complex_ (FilteredComplex)

  • algorithms (Iterable[str] | str | None)

  • repeats (int)

  • selection_metric (str)

  • max_critical_ratio (float)

Return type:

AdaptivePersistenceResult

morseframes.compute_reference_complex(complex_, sequence=None, references=None, *, algorithm='saturated')
Parameters:
Return type:

tuple[tuple[tuple[int, …], …], …]

morseframes.compute_reference_map(complex_, sequence=None, *, algorithm='saturated')
Parameters:
Return type:

tuple[tuple[int, …], …]

morseframes.compute_reference_map_modp(complex_, sequence=None, *, modulus, algorithm='saturated')

Compute the Morse reference map over the prime field F_modulus.

Parameters:
Return type:

tuple[tuple[tuple[int, int], …], …]

morseframes.compute_standard_persistence(complex_, *, modulus=2)

Compute ordinary persistence over the prime field F_modulus.

The existing C++ path is used for the default Z2 case. Odd prime fields currently use the pure-Python oriented-boundary reducer. Composite moduli are rejected because the barcode API assumes a field.

Parameters:
Return type:

PersistenceDiagram

morseframes.compute_standard_persistence_modp(complex_, modulus)

Compute ordinary persistence over the prime field F_modulus.

Parameters:
Return type:

PersistenceDiagram

morseframes.coreference_map_as_simplices(complex_, sequence=None, coreferences=None, *, algorithm='same-level-reduction')
Parameters:
Return type:

tuple[tuple[tuple[int, …], …], …]

morseframes.cpp_backend_active(complex_)
Parameters:

complex_ (FilteredComplex)

Return type:

bool

morseframes.cpp_backend_available()
Return type:

bool

morseframes.cpp_compute_coreference_map(cpp_complex, cpp_sequence)
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object)

Return type:

tuple[tuple[int, …], …]

morseframes.cpp_compute_coreference_map_modp(cpp_complex, cpp_sequence, modulus)
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object)

  • modulus (int)

Return type:

tuple[tuple[tuple[int, int], …], …]

morseframes.cpp_compute_coreference_map_object(cpp_complex, cpp_sequence)
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object)

Return type:

object

morseframes.cpp_compute_morse_coreference_persistence(cpp_complex, cpp_sequence=None, *, algorithm='same-level-reduction')
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object | None)

  • algorithm (str)

Return type:

PersistenceDiagram

morseframes.cpp_compute_morse_coreference_persistence_modp(cpp_complex, cpp_sequence=None, *, algorithm='same-level-reduction', modulus)
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object | None)

  • algorithm (str)

  • modulus (int)

Return type:

PersistenceDiagram

morseframes.cpp_compute_morse_persistence(cpp_complex, cpp_sequence=None, *, algorithm='saturated')
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object | None)

  • algorithm (str)

Return type:

PersistenceDiagram

morseframes.cpp_compute_morse_persistence_modp(cpp_complex, cpp_sequence=None, *, algorithm='saturated', modulus)
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object | None)

  • algorithm (str)

  • modulus (int)

Return type:

PersistenceDiagram

morseframes.cpp_compute_morse_sequence(cpp_complex, *, algorithm='saturated')
Parameters:

  • cpp_complex (object)

  • algorithm (str)

Return type:

object

morseframes.cpp_compute_morse_sequence_and_coreference_map_object(cpp_complex, *, algorithm='same-level-reduction')
Parameters:

  • cpp_complex (object)

  • algorithm (str)

Return type:

object

morseframes.cpp_compute_morse_sequence_and_reference_map_object(cpp_complex, *, algorithm='saturated')
Parameters:

  • cpp_complex (object)

  • algorithm (str)

Return type:

object

morseframes.cpp_compute_reference_map(cpp_complex, cpp_sequence)
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object)

Return type:

tuple[tuple[int, …], …]

morseframes.cpp_compute_reference_map_modp(cpp_complex, cpp_sequence, modulus)
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object)

  • modulus (int)

Return type:

tuple[tuple[tuple[int, int], …], …]

morseframes.cpp_compute_reference_map_object(cpp_complex, cpp_sequence)
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object)

Return type:

object

morseframes.cpp_compute_standard_persistence(cpp_complex)
Parameters:

cpp_complex (object)

Return type:

PersistenceDiagram

morseframes.cpp_compute_standard_persistence_modp(cpp_complex, modulus)
Parameters:

  • cpp_complex (object)

  • modulus (int)

Return type:

PersistenceDiagram

morseframes.cpp_filtered_complex_from_simplices(simplices, *, finalize=True)
Parameters:

  • simplices (Iterable[tuple[Sequence[int], float]])

  • finalize (bool)

Return type:

object

morseframes.cpp_profile_morse_reference_frame(cpp_complex, *, algorithm='saturated')
Parameters:

  • cpp_complex (object)

  • algorithm (str)

Return type:

MorseReferenceProfile

morseframes.cpp_reduce_morse_coreference_persistence(cpp_complex, cpp_sequence, coreferences)
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object)

  • coreferences (object)

Return type:

PersistenceDiagram

morseframes.cpp_reduce_morse_persistence(cpp_complex, cpp_sequence, references)
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object)

  • references (Sequence[tuple[int, ...]] | object)

Return type:

PersistenceDiagram

morseframes.cpp_reduce_morse_persistence_with_metrics(cpp_complex, cpp_sequence, references)
Parameters:

  • cpp_complex (object)

  • cpp_sequence (object)

  • references (Sequence[tuple[int, ...]] | object)

Return type:

tuple[PersistenceDiagram, dict[str, object]]

morseframes.cpp_reference_map_to_tuple(cpp_references)
Parameters:

cpp_references (object)

Return type:

tuple[tuple[int, …], …]

morseframes.gudhi_barcode(complex_, *, include_zero=False, modulus=2)

Compute a comparable barcode with an installed/importable GUDHI.

Parameters:
Return type:

tuple[tuple[tuple[int, float, float], …], tuple[tuple[int, float], …]]

morseframes.morse_sequence_as_simplices(complex_, sequence=None, *, algorithm='saturated')
Parameters:
Return type:

tuple[MorseStepSimplices, …]

morseframes.profile_morse_reference_frame(complex_, *, algorithm='saturated')

Profile a Morse-reference frame without running the pivot reduction.

Parameters:
Return type:

MorseReferenceProfile

morseframes.profile_morse_sequence_algorithms(complex_, *, algorithms=('saturated', 'f-max', 'f-min', 'same-level-reduction', 'flooding-max', 'flooding-min', 'flooding-minmax', 'flooding-maxmin', 'plateau-greedy'), repeats=1)

Profile candidate Morse sequence constructors without full reductions.

Parameters:

  • complex_ (FilteredComplex)

  • algorithms (Iterable[str] | str | None)

  • repeats (int)

Return type:

tuple[MorseReferenceProfile, …]

morseframes.reference_map_as_simplices(complex_, sequence=None, references=None, *, algorithm='saturated')
Parameters:
Return type:

tuple[tuple[tuple[int, …], …], …]

morseframes.select_morse_sequence_algorithm(complex_, *, algorithms=('saturated', 'f-max', 'f-min', 'same-level-reduction', 'flooding-max', 'flooding-min', 'flooding-minmax', 'flooding-maxmin', 'plateau-greedy'), repeats=1, frame_mode='fused', selection_metric='morse_seconds', materialize_barcodes=False)

Return the best measured Morse strategy for one complex.

Parameters:

  • complex_ (FilteredComplex)

  • algorithms (Iterable[str] | str | None)

  • repeats (int)

  • frame_mode (str)

  • selection_metric (str)

  • materialize_barcodes (bool)

Return type:

PersistenceBenchmark

morseframes.select_morse_sequence_profile(complex_, *, algorithms=('saturated', 'f-max', 'f-min', 'same-level-reduction', 'flooding-max', 'flooding-min', 'flooding-minmax', 'flooding-maxmin', 'plateau-greedy'), repeats=1, selection_metric='estimated_reducer_work')

Return the best cheap profile among candidate Morse strategies.

Parameters:

  • complex_ (FilteredComplex)

  • algorithms (Iterable[str] | str | None)

  • repeats (int)

  • selection_metric (str)

Return type:

MorseReferenceProfile