# Benchmark Summary

This page summarizes the public benchmark tables that are regenerated by the
scripts in this repository. The full command list is in
{doc}`benchmark_reproduction`.

The current tables should be read as implementation evidence, not as a final
claim about the fastest persistent-homology software. GUDHI is used as the main
external reference because the PH-roadmap benchmark paper compares many
packages and makes GUDHI a useful calibrated baseline:
[Otter et al., 2017](https://arxiv.org/abs/1506.08903).

## What Is Compared

The synthetic table compares two MorseFrames paths on the same generated
simplicial complexes:

- ordinary full-complex persistence on the filtration;
- Morse persistence after building a Morse sequence and the corresponding
  reference/reduction input.

That table is generated in core validation mode with the C++ backend active.
If `morseframes.cpp_backend_available()` is false when the command is run, the
numbers measure the pure-Python fallback instead and should not replace the
tracked native-backed table.

The native GUDHI-view tables compare three in-process paths on the same
`Gudhi::Simplex_tree` input:

- `Direct`: MorseFrames through a read-only `Simplex_tree` view;
- `Import`: copy the GUDHI tree into the compact owning MorseFrames complex,
  then run MorseFrames;
- `GUDHI`: GUDHI persistent cohomology on the original `Simplex_tree`.

`Direct` is the relevant integration direction. `Import` is useful as a
diagnostic, but it includes a copy that we would not want in an upstream GUDHI
entry point.

## How To Read The Ratios

For `Std/Morse`, values above `1` mean the Morse pipeline is faster than the
ordinary full-complex reducer for that row.

For `GUDHI/Direct`, values above `1` mean the direct MorseFrames view is faster
end-to-end than GUDHI persistence on the same `Simplex_tree`. Values below `1`
mean GUDHI is faster.

For `GUDHI/Reducer`, values above `1` mean the Morse reducer kernel is faster
than GUDHI persistence after the Morse input has already been built. This ratio
does not include view construction, sequence construction, or reference-input
construction.

## Current Reading

The native-backed synthetic scale table now shows `Std/Morse > 1` on the
reported lower-star, plateau, and Rips rows. The clearest stress-test behavior
is on the denser Rips examples, where ordinary reduction becomes more expensive
and the strategy choice matters strongly.

The native GUDHI-view tables are more nuanced. On the reported default and
larger lean runs, the direct `f-max`, `f-min`, and same-level paths are faster
than GUDHI end-to-end on the tested rows, while `plateau-greedy` remains more
mixed. The import path is still much slower because copying the
`Simplex_tree` dominates. The reducer kernel itself is faster than GUDHI
persistence on all reported native rows, but much of the remaining engineering
work is in pre-reducer construction costs.

The stage-profile table makes that bottleneck explicit. In the quick native
profile, roughly three quarters of direct-path time is spent before the reducer
starts: read-only view construction plus Morse frame construction. That is why
the next optimization work should focus on the view, sequence construction, and
reference-input construction rather than only the annotation reducer.

## Compact Tables

<!-- benchmark-summary-tables:start -->

The tables below are short, rendered summaries of the current public benchmark
fragments. This block is generated by `tools/render_benchmark_summary.py`.
The full LaTeX fragments remain the source for reproducible benchmark tables in
this software repository; they are not manuscript source.

### Synthetic Scale

| Family | Strategy | Cases | Avg. simplices | Critical % | Morse time | Std/Morse |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| lower-star | `f-max` | 3 | 317.7 | 18.8 | 59.3 us | 1.97 (1.91-1.99) |
| lower-star | `f-min` | 3 | 317.7 | 18.8 | 86.7 us | 1.34 (1.29-1.35) |
| lower-star | `saturated` | 3 | 317.7 | 18.8 | 112.9 us | 1.08 (1.03-1.09) |
| lower-star | same-level | 3 | 317.7 | 36.2 | 86.7 us | 1.32 (1.26-1.37) |
| plateau | `f-max` | 3 | 317.7 | 22.1 | 66.0 us | 1.82 (1.62-1.88) |
| plateau | `f-min` | 3 | 317.7 | 22.1 | 99.8 us | 1.15 (1.09-1.18) |
| plateau | `saturated` | 3 | 317.7 | 22.1 | 99.7 us | 1.16 (1.11-1.21) |
| plateau | same-level | 3 | 317.7 | 38.5 | 87.2 us | 1.30 (1.26-1.34) |
| Rips | `f-max` | 3 | 2,770.3 | 67.3 | 970.3 us | 4.13 (3.97-4.61) |
| Rips | `f-min` | 3 | 2,770.3 | 67.3 | 1,146.1 us | 3.65 (3.41-3.86) |
| Rips | `saturated` | 3 | 2,770.3 | 67.3 | 1,361.1 us | 2.91 (2.84-3.20) |
| Rips | same-level | 3 | 2,770.3 | 94.2 | 820.0 us | 5.32 (4.69-5.64) |

### Native GUDHI View

This compact table reports the best `GUDHI/Direct` strategy for each default
30-repeat native case.

| Case | Simplices | Best direct strategy | Direct | GUDHI | GUDHI/Direct | GUDHI/Reducer |
| --- | ---: | --- | ---: | ---: | ---: | ---: |
| `flag-120-r018` | 2,081 | same-level | 0.65 ms | 0.88 ms | 1.32 (1.31-1.36) | 4.40 (4.26-4.49) |
| `flag-160-r016` | 2,957 | same-level | 0.99 ms | 1.35 ms | 1.36 (1.33-1.44) | 4.33 (4.22-4.65) |
| `grid-32x32-plateau` | 5,891 | `f-max` | 1.35 ms | 2.68 ms | 1.91 (1.84-1.99) | 7.41 (7.24-7.59) |
| `grid-48x48-plateau` | 13,443 | `f-max` | 2.31 ms | 5.07 ms | 2.28 (2.13-2.34) | 116.89 (110.65-120.28) |

### Direct-Path Stage Split

| Stage group | Share | Interpretation |
| --- | ---: | --- |
| Read-only view construction | 38.2% | Simplex extraction, boundary lookup, coboundaries, and order arrays. |
| Morse frame construction | 37.9% | Morse sequence plus reference/reduction-input construction. |
| Reducer kernel | 24.3% | Annotation reduction after the Morse input has been built. |
| All pre-reducer work | 75.7% | Current native-adapter bottleneck before the reducer starts. |

<!-- benchmark-summary-tables:end -->

## Public Artifacts

The main table fragments are tracked in the repository:

- [`docs/synthetic_scale_table.tex`](https://github.com/lnajman/morseframes/blob/main/docs/synthetic_scale_table.tex)
- [`docs/native_gudhi_view_default_r30_table.tex`](https://github.com/lnajman/morseframes/blob/main/docs/native_gudhi_view_default_r30_table.tex)
- [`docs/native_gudhi_large_lean_r30_table.tex`](https://github.com/lnajman/morseframes/blob/main/docs/native_gudhi_large_lean_r30_table.tex)
- [`docs/native_gudhi_stage_profile_quick_table.tex`](https://github.com/lnajman/morseframes/blob/main/docs/native_gudhi_stage_profile_quick_table.tex)
- [`docs/profile_metric_fair_validation_table.tex`](https://github.com/lnajman/morseframes/blob/main/docs/profile_metric_fair_validation_table.tex)
- [`docs/profile_selector_decision_summary_table.tex`](https://github.com/lnajman/morseframes/blob/main/docs/profile_selector_decision_summary_table.tex)
- [`docs/selector_feature_diagnostic_table.tex`](https://github.com/lnajman/morseframes/blob/main/docs/selector_feature_diagnostic_table.tex)

Raw CSVs, manuscript prose fragments, manuscript PDFs, and private discussion
notes are intentionally kept out of the public package repository.