multimodars 0.3.1__tar.gz → 0.3.2__tar.gz

multimodars-0.3.2/.readthedocs.yaml

@@ -0,0 +1,19 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    rust: "latest"
+  jobs:
+    post_create_environment:
+      - "$READTHEDOCS_VIRTUALENV_PATH/bin/pip install maturin sphinx sphinx-rtd-theme sphinx-autodoc-typehints myst-nb plotly furo"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .

{multimodars-0.3.1 → multimodars-0.3.2}/CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.2] - 2026-05-05
+
+### Added
+- Benchmark suite (`benchmarks/`) with two scripts: `benchmark_bruteforce_stepsize.py`
+  (step-size scaling, `from_file_full`) and `benchmark_cpu_scaling.py` (core-count
+  scaling, `from_array_single`). Results saved to `benchmarks/results/`.
+- Benchmark documentation page (`docs/benchmark.rst`) with result figures and table,
+  linked in the ReadTheDocs table of contents.
+
+### Changed
+- `paper/paper.md` Performance section updated with quantified benchmark results and
+  corrected parallelisation description.
+
+### Performance
+- Intra-pullback alignment (`search_range`) now parallelises over candidate rotation
+  angles via `par_iter` instead of the point-rotation loop. The inner cost-function
+  loop is now sequential. This provides enough rayon tasks per frame step to saturate
+  all cores: bruteforce scales 6.5× and optimised 4.2× from 2 to 16 cores (previously
+  ~1.4× for both). Combined algorithmic + parallelisation gain reaches **38.5×** vs.
+  brute-force at 2 cores.
+
 ## [0.3.1] - 2026-05-04
 
 ### Added

{multimodars-0.3.1 → multimodars-0.3.2}/Cargo.lock

@@ -753,7 +753,7 @@ dependencies = [
 
 [[package]]
 name = "multimodars"
-version = "0.3.1"
+version = "0.3.2"
 dependencies = [
  "anyhow",
  "approx",

{multimodars-0.3.1 → multimodars-0.3.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "multimodars"
-version = "0.3.1"
+version = "0.3.2"
 edition = "2021"
 license = "MIT"
 readme = "README.md"

{multimodars-0.3.1 → multimodars-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multimodars
-Version: 0.3.1
+Version: 0.3.2
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
@@ -79,7 +79,7 @@ For building from source or the full developer setup (tests, linting, docs), see
 
 ## Quick Example
 
-Download [examples.zip](https://github.com/yungselm/multimoda-rs/releases/latest/download/examples.zip) (SHA256: `d11ebc7607f43ab4571fb51c9ac9178caac57774cf5d97f4f068ace4eb070fee`) from the latest release and extract it to your working directory.
+Checkout our **[Documentation](https://multimod-rs.readthedocs.io/en/latest)** for in-depth explanations of the functionality and preloaded notebooks including 3D plots. Otherwise clone the repo to follow along the different examples:
 
 ```python
 import multimodars as mm
@@ -133,7 +133,7 @@ aligned_pair, cl_resampled = mm.align_three_point(
 
 ## Documentation
 
-Full documentation — installation, step-by-step tutorials, interactive Jupyter notebooks, and API reference — is available at **[multimoda-rs.readthedocs.io](https://multimoda-rs.readthedocs.io)**.
+Full documentation — installation, step-by-step tutorials, interactive (preloaded) Jupyter notebooks, and API reference — is available at **[multimoda-rs.readthedocs.io](https://multimoda-rs.readthedocs.io)**.
 
 ## License
 

{multimodars-0.3.1 → multimodars-0.3.2}/README.md

@@ -55,7 +55,7 @@ For building from source or the full developer setup (tests, linting, docs), see
 
 ## Quick Example
 
-Download [examples.zip](https://github.com/yungselm/multimoda-rs/releases/latest/download/examples.zip) (SHA256: `d11ebc7607f43ab4571fb51c9ac9178caac57774cf5d97f4f068ace4eb070fee`) from the latest release and extract it to your working directory.
+Checkout our **[Documentation](https://multimod-rs.readthedocs.io/en/latest)** for in-depth explanations of the functionality and preloaded notebooks including 3D plots. Otherwise clone the repo to follow along the different examples:
 
 ```python
 import multimodars as mm
@@ -109,7 +109,7 @@ aligned_pair, cl_resampled = mm.align_three_point(
 
 ## Documentation
 
-Full documentation — installation, step-by-step tutorials, interactive Jupyter notebooks, and API reference — is available at **[multimoda-rs.readthedocs.io](https://multimoda-rs.readthedocs.io)**.
+Full documentation — installation, step-by-step tutorials, interactive (preloaded) Jupyter notebooks, and API reference — is available at **[multimoda-rs.readthedocs.io](https://multimoda-rs.readthedocs.io)**.
 
 ## License
 

{multimodars-0.3.1 → multimodars-0.3.2}/ROADMAP.MD

@@ -1,5 +1,9 @@
 # Python package that has one purpose: Combining any intravascular image modality with CCTA meshes.
 
+# Optimizations
+- [] Optimize the ray intersection algorithm
+- [] Better parallelization strategy for frames alignment by processing in batches (frames only have to be aligned relative to each other not sequentially)
+
 # Centerline alignment module
 (- [] Create Centerline directly from mesh) (v1.0.0)
 
@@ -16,9 +20,6 @@
 - [] helper function to automatically export only certain points on mesh (e.g. RCA or LCA)
 - [] function to combine anomalous section only with the distal part
 
-# Miscellaneous
-- [x] Improve print statements in the whole package
-
 # Prepublish checklist (JOSS review feedback — open until resolved):
 
 ## Dependencies / packaging
@@ -40,7 +41,7 @@
   so regressions are caught automatically.
 
 ## Performance claim
-- [] Provide reproducible code + sample data for the performance claim in the paper (lines 102-104):
+- [x] Provide reproducible code + sample data for the performance claim in the paper (lines 102-104):
   "Empirical performance on a 16-core CPU: an OCT pullback with 280 frames and a rotation search range
   of ±3° (final accuracy 0.01°) saw alignment time reduced from 150 s to 18 s with the optimized
   multiscale search."

multimodars-0.3.2/benchmarks/BENCHMARK_PLAN.md

@@ -0,0 +1,143 @@
+# Benchmark Plan: multimoda-rs Alignment Performance
+
+## Overview
+
+Two benchmarks to characterise the alignment performance of `multimodars`.
+
+| # | What | Function | Dataset |
+|---|------|----------|---------|
+| 1 | Bruteforce vs. optimised at varying step sizes | `from_file_full` | IVUS rest/stress |
+| 2 | CPU-core scaling (parallelism) | `from_array_single` | OCT (280 frames) |
+
+Results land in `benchmarks/results/`.
+
+---
+
+## Benchmark 1 — Bruteforce vs. Optimised: Step-Size Scaling
+
+### Goal
+
+Quantify how bruteforce and optimised alignment scale as `step_rotation_deg` decreases
+(i.e. as the rotation-search grid becomes finer).
+
+### Setup
+
+| Parameter | Value |
+|-----------|-------|
+| Function | `from_file_full` |
+| Dataset | `examples/data/ivus_rest` / `examples/data/ivus_stress` (IVUS) |
+| `range_rotation_deg` | 90.0° (±90° → 180° total sweep) |
+| `write_obj` | `False` — avoids disk-I/O noise |
+| `smooth` | `False` |
+| `postprocessing` | `False` |
+| `interpolation_steps` | `0` |
+| Repetitions per condition | 3 (median wall time reported) |
+
+### Independent variable
+
+`step_rotation_deg` ∈ {5.0, 2.5, 1.0, 0.5, 0.1} degrees.
+
+Corresponding number of rotation steps n = 180 / step (using the full ±90° range):
+
+| step (°) | n\_steps |
+|----------|---------|
+| 5.0      | 36      |
+| 2.5      | 72      |
+| 1.0      | 180     |
+| 0.5      | 360     |
+| 0.1      | 1 800   |
+
+### Expected behaviour
+
+- **Bruteforce**: exhaustively scores every rotation angle for every frame pair →
+  wall time grows linearly with n\_steps (O(n)).
+- **Optimised**: coarse-to-fine hierarchical search → sub-linear in n\_steps,
+  asymptotically O(log n).
+
+The plot axes are logarithmic so the two complexity classes appear as straight lines
+with clearly different slopes.
+
+### Output
+
+`benchmarks/results/bruteforce_stepsize.png` — log-log line plot:
+
+- x-axis (bottom): number of rotation steps; (top): step size in degrees
+- y-axis: median wall time (seconds)
+- Line 1: bruteforce (red ○–) + O(n) reference dashed line
+- Line 2: optimised (blue ■ --)
+- Right y-axis: speedup factor (bruteforce / optimised)
+
+---
+
+## Benchmark 2 — CPU-Core Scaling
+
+### Goal
+
+Measure how parallelism scales from 1 → 16 CPU cores for both alignment modes,
+using a large OCT pullback (280 frames) to stress the frame-level parallelism
+in the rayon thread pool.
+
+### Note on function choice
+
+The OCT example data (`examples/data/oct_single/`) ships as
+`oct_contours_raw.csv` + `oct_ref.csv`, which do not follow the AIVUS-CAA
+file-naming convention expected by `from_file_single`.  The benchmark therefore
+uses `from_array_single` (as demonstrated in the docs notebook), which accepts
+raw numpy arrays directly.  The algorithm under test is identical.
+
+### Setup
+
+| Parameter | Value |
+|-----------|-------|
+| Function | `from_array_single` |
+| Dataset | `examples/data/oct_single/` (280 frames, OCT) |
+| `step_rotation_deg` | 0.01° (from docs/notebooks) |
+| `range_rotation_deg` | 6.0° (from docs/notebooks) |
+| `image_center` | (5.0, 5.0) (from docs/notebooks) |
+| `n_points` | 40 (from docs/notebooks) |
+| `smooth` | `False` |
+| `write_obj` | `False` |
+| Repetitions per condition | 3 (median wall time reported) |
+
+### Independent variable
+
+`RAYON_NUM_THREADS` ∈ {1, 2, 4, 8, 12, 16}
+
+**Important**: rayon's global thread pool is initialised once per process from
+the `RAYON_NUM_THREADS` environment variable.  To guarantee a fresh pool at each
+thread count, every (n\_cores × bruteforce × repeat) combination is executed in
+a **separate subprocess** with the variable set before any import of `multimodars`.
+
+### Expected behaviour
+
+- **Optimised**: near-linear speedup up to ~8 cores, then diminishing returns
+  (Amdahl's law — serial fraction of the pipeline limits gains beyond that).
+- **Bruteforce**: also benefits from rayon frame-level parallelism, but expected
+  to saturate earlier because the per-step work is less cache-friendly.
+
+### Output
+
+`benchmarks/results/cpu_scaling.png` — two-panel figure:
+
+- Left panel: wall time (s) vs. CPU cores, two lines (bruteforce, optimised)
+- Right panel: speedup relative to 1 core vs. CPU cores +
+  ideal linear-speedup reference; same two lines
+
+---
+
+## Running the Benchmarks
+
+```bash
+# From project root
+python benchmarks/benchmark_bruteforce_stepsize.py
+python benchmarks/benchmark_cpu_scaling.py
+```
+
+Estimated runtimes (rough, machine-dependent):
+
+| Benchmark | Estimate |
+|-----------|----------|
+| Benchmark 1 (all step sizes × 2 modes × 3 reps) | 5–30 min |
+| Benchmark 2 (6 core counts × 2 modes × 3 reps in subprocesses) | 20–60 min |
+
+Results are saved as PNG files in `benchmarks/results/`.

multimodars-0.3.2/benchmarks/benchmark_bruteforce_stepsize.py

@@ -0,0 +1,196 @@
+"""Benchmark 1: bruteforce vs. optimised alignment at varying step sizes.
+
+Tests from_file_full on the bundled IVUS rest/stress example data with
+step_rotation_deg in {5.0, 2.5, 1.0, 0.5, 0.1} degrees.
+
+write_obj / smooth / postprocessing are all disabled so only the alignment
+algorithm itself is timed.
+
+Output: benchmarks/results/bruteforce_stepsize.png
+"""
+
+import statistics
+import time
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+
+import multimodars as mm
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+_ROOT = Path(__file__).parent.parent
+DATA_ROOT = _ROOT / "examples" / "data"
+INPUT_AB = str(DATA_ROOT / "ivus_rest")
+INPUT_CD = str(DATA_ROOT / "ivus_stress")
+RESULTS_DIR = Path(__file__).parent / "results"
+
+STEP_SIZES: list[float] = [5.0, 2.5, 1.0, 0.5, 0.1, 0.05]
+RANGE_DEG: float = 90.0
+REPEATS: int = 3
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _n_steps(step: float) -> float:
+    return (RANGE_DEG * 2) / step
+
+
+def _run_once(step: float, bruteforce: bool) -> float:
+    t0 = time.perf_counter()
+    mm.from_file_full(
+        input_path_ab=INPUT_AB,
+        input_path_cd=INPUT_CD,
+        step_rotation_deg=step,
+        range_rotation_deg=RANGE_DEG,
+        write_obj=False,
+        smooth=False,
+        postprocessing=False,
+        bruteforce=bruteforce,
+        interpolation_steps=0,
+    )
+    return time.perf_counter() - t0
+
+
+# ---------------------------------------------------------------------------
+# Benchmark
+# ---------------------------------------------------------------------------
+
+
+def run_benchmark() -> dict[str, list[float]]:
+    results: dict[str, list[float]] = {"bruteforce": [], "optimised": []}
+
+    for step in STEP_SIZES:
+        print(f"step={step:4.1f}°  bruteforce=True  ", end="", flush=True)
+        times_bf = [_run_once(step, bruteforce=True) for _ in range(REPEATS)]
+        med_bf = statistics.median(times_bf)
+        results["bruteforce"].append(med_bf)
+        print(f"{med_bf:.2f} s")
+
+        print(f"step={step:4.1f}°  bruteforce=False ", end="", flush=True)
+        times_opt = [_run_once(step, bruteforce=False) for _ in range(REPEATS)]
+        med_opt = statistics.median(times_opt)
+        results["optimised"].append(med_opt)
+        speedup = med_bf / med_opt if med_opt > 0 else float("inf")
+        print(f"{med_opt:.2f} s  (speedup {speedup:.1f}x)")
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Plotting
+# ---------------------------------------------------------------------------
+
+
+def plot_results(results: dict[str, list[float]]) -> None:
+    RESULTS_DIR.mkdir(parents=True, exist_ok=True)
+
+    n_steps_list = [_n_steps(s) for s in STEP_SIZES]
+    bf_times = results["bruteforce"]
+    opt_times = results["optimised"]
+    speedups = [bf / opt for bf, opt in zip(bf_times, opt_times)]
+
+    fig, (ax_main, ax_speedup) = plt.subplots(
+        1, 2, figsize=(14, 5), constrained_layout=True
+    )
+
+    # --- Left panel: wall time ---
+    ax_main.plot(
+        n_steps_list,
+        bf_times,
+        "o-",
+        color="tab:red",
+        linewidth=2,
+        markersize=7,
+        label="Bruteforce",
+    )
+    ax_main.plot(
+        n_steps_list,
+        opt_times,
+        "s--",
+        color="tab:blue",
+        linewidth=2,
+        markersize=7,
+        label="Optimised",
+    )
+
+    # O(n) reference anchored at the first bruteforce point
+    ref_n, ref_t = n_steps_list[0], bf_times[0]
+    linear_ref = [ref_t * (n / ref_n) for n in n_steps_list]
+    ax_main.plot(
+        n_steps_list,
+        linear_ref,
+        ":",
+        color="tab:red",
+        linewidth=1.5,
+        alpha=0.55,
+        label="O(n) reference",
+    )
+
+    ax_main.set_xscale("log")
+    ax_main.set_yscale("log")
+    ax_main.set_xlabel("Number of rotation steps  (2 × range / step)", fontsize=12)
+    ax_main.set_ylabel("Median wall time  (s)", fontsize=12)
+    ax_main.set_title(
+        "Bruteforce vs. Optimised — Step-Size Scaling\n"
+        "from_file_full · IVUS rest/stress · range = 90°",
+        fontsize=11,
+    )
+    ax_main.legend(fontsize=11)
+    ax_main.grid(True, which="both", alpha=0.3)
+
+    # Secondary x-axis with step-size labels
+    ax_top = ax_main.twiny()
+    ax_top.set_xscale("log")
+    ax_top.set_xlim(ax_main.get_xlim())
+    ax_top.set_xticks(n_steps_list)
+    ax_top.set_xticklabels([f"{s}°" for s in STEP_SIZES])
+    ax_top.set_xlabel("Step size  (degrees)", fontsize=12)
+
+    # --- Right panel: speedup factor ---
+    ax_speedup.plot(
+        n_steps_list,
+        speedups,
+        "D-",
+        color="tab:green",
+        linewidth=2,
+        markersize=7,
+    )
+    ax_speedup.axhline(1.0, color="gray", linewidth=1, linestyle=":")
+    ax_speedup.set_xscale("log")
+    ax_speedup.set_xlabel("Number of rotation steps  (2 × range / step)", fontsize=12)
+    ax_speedup.set_ylabel("Speedup  (bruteforce / optimised)", fontsize=12)
+    ax_speedup.set_title(
+        "Speedup of Optimised over Bruteforce\n"
+        "from_file_full · IVUS rest/stress · range = 90°",
+        fontsize=11,
+    )
+    ax_speedup.grid(True, which="both", alpha=0.3)
+
+    ax_top2 = ax_speedup.twiny()
+    ax_top2.set_xscale("log")
+    ax_top2.set_xlim(ax_speedup.get_xlim())
+    ax_top2.set_xticks(n_steps_list)
+    ax_top2.set_xticklabels([f"{s}°" for s in STEP_SIZES])
+    ax_top2.set_xlabel("Step size  (degrees)", fontsize=12)
+
+    out = RESULTS_DIR / "bruteforce_stepsize.png"
+    fig.savefig(out, dpi=150)
+    print(f"\nPlot saved → {out}")
+    plt.show()
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    print("=== Benchmark 1: Bruteforce vs. Optimised — Step-Size Scaling ===\n")
+    results = run_benchmark()
+    print("\nPlotting results …")
+    plot_results(results)