Refactor/benchmarks (#65)

* Refactors benchmarks for CI performance suite

Consolidates and optimizes benchmarks into a CI performance suite for faster and more comprehensive regression detection.

- Replaces `small_scale_triangulation.rs` with `ci_performance_suite.rs`
- Adds 5D triangulation benchmarks
- Modifies benchmark jobs to use the CI performance suite
- Removes allocation counting from `ci_performance_suite` benchmarks
- Adds new benchmarks for memory scaling and triangulation vs hull memory usage

* Refactors and expands benchmark suite

Significantly expands and refactors the benchmark suite to include comprehensive performance measurements across dimensions 2D-5D.

Introduces microbenchmarks for core algorithms like Bowyer-Watson triangulation, neighbor assignment, and duplicate cell removal.  Adds memory usage and validation benchmarks to assess allocation patterns and correctness.

Updates point generation to be more consistent and reproducible using a util module.  Provides targeted benchmarks for incremental construction, measuring vertex addition performance.

These enhancements provide deeper insights into performance bottlenecks and scaling behavior across different dimensions.

* Refactors and expands benchmark suite

Improves the benchmark suite by refactoring random point generation, enhancing CI performance benchmarks, and adding memory analysis capabilities.
This change standardizes point generation using a central utility function, improving consistency and maintainability.

* Refactors baseline generation workflow

Streamlines the baseline generation workflow by relocating the baseline results file to the artifact directory directly within the generation script. This change simplifies artifact preparation and cleanup, ensuring consistency and reducing redundancy in file handling.

Additionally, updates Ruff configuration and usage across the project for improved code quality and formatting.

* Improves changelog title formatting with edge cases

Adds tests to cover edge cases in changelog title formatting, specifically focusing on line wrapping with very short length
limits. It also fixes a bench command to include the workspace.

These tests ensure the commit link is split correctly across multiple lines and bolding is omitted when the line length is insufficient.

* Improves test reliability and documentation

Updates a test to mock JSON loading more effectively, preventing potential issues with file access during testing.

Refines documentation in WARP.md to improve clarity and consistency, including:
- Updates clippy command with more pedantic lints
- Clarifies cspell usage and terminology
- Removes redundant documentation validation step
- Clarifies run_all_examples.sh execution
- Adds more specialized tests

These changes enhance code quality, testability, and documentation accuracy, promoting better development practices.

* Improves CI performance and changelog utils

Enhances CI workflow by recommending branch strategies to avoid unnecessary performance testing.

Refines changelog title formatting to handle long titles and ensure proper markdown escaping.

Updates WARP guidance to clarify the use of automated tools and code validation procedures.

Author: acgetchell

.github/workflows/benchmarks.yml

@@ -346,7 +346,7 @@ jobs:
           echo "   Baseline origin: ${BASELINE_ORIGIN:-unknown}"
 
           # This will exit with code 1 if significant regressions are found
-          echo "   Using full comparison mode against ${BASELINE_ORIGIN:-unknown} baseline"
+          echo "   Using CI performance suite against ${BASELINE_ORIGIN:-unknown} baseline"
           BASELINE_PATH="baseline-artifact/baseline_results.txt"
           if uv run benchmark-utils --help >/dev/null 2>&1; then
             uv run benchmark-utils compare --baseline "$BASELINE_PATH"

.github/workflows/generate-baseline.yml

@@ -77,12 +77,12 @@ jobs:
         run: |
           echo "🚀 Generating performance baseline for tag $TAG_NAME"
 
-          # Run baseline generation using Python CLI tool
+          # Run baseline generation using Python CLI tool with CI performance suite
           uv run benchmark-utils generate-baseline \
             || uv run python -m scripts.benchmark_utils generate-baseline
 
           # Verify baseline was created
-          if [ ! -f "benches/baseline_results.txt" ]; then
+          if [ ! -f "baseline-artifact/baseline_results.txt" ]; then
             echo "❌ Baseline generation failed - no baseline file created"
             exit 1
           fi
@@ -91,9 +91,9 @@ jobs:
 
           # Show baseline summary
           echo "📊 Baseline summary:"
-          head -n 10 benches/baseline_results.txt
+          head -n 10 baseline-artifact/baseline_results.txt
           echo "..."
-          benchmark_count=$(grep -c "^===" benches/baseline_results.txt || echo "0")
+          benchmark_count=$(grep -c "^===" baseline-artifact/baseline_results.txt || echo "0")
           echo "Total benchmarks: $benchmark_count"
 
       - name: Prepare baseline artifact
@@ -102,14 +102,9 @@ jobs:
           SAFE_COMMIT_SHA: ${{ github.sha }}
           SAFE_RUN_ID: ${{ github.run_id }}
         run: |
-          # Create artifact directory
-          mkdir -p baseline-artifact
-
-          # Copy baseline file with tag-specific name
-          cp benches/baseline_results.txt "baseline-artifact/baseline-$TAG_NAME.txt"
-
-          # Also copy as generic name for easy download
-          cp benches/baseline_results.txt "baseline-artifact/baseline_results.txt"
+          # The baseline file is already in baseline-artifact/ from the script
+          # Just copy it with tag-specific name
+          cp baseline-artifact/baseline_results.txt "baseline-artifact/baseline-$TAG_NAME.txt"
 
           # Create metadata file
           cat > "baseline-artifact/metadata.json" <<EOF
@@ -148,7 +143,7 @@ jobs:
         if: ${{ success() }}
         run: |
           # Remove temporary baseline file from working directory
-          rm -f benches/baseline_results.txt
+          rm -f baseline-artifact/baseline_results.txt
           echo "✅ Cleaned up temporary baseline file"
 
       - name: Display next steps

CHANGELOG.md

@@ -9,11 +9,122 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
 ## [Unreleased](https://github.com/acgetchell/delaunay/compare/v0.4.1...HEAD)
 
+### Merged Pull Requests
+
+- Docs/release v0.4.2 [`#60`](https://github.com/acgetchell/delaunay/pull/60)
+- Test/benchmarking [`#59`](https://github.com/acgetchell/delaunay/pull/59)
+- Fix/squashed commit body parsing [`#58`](https://github.com/acgetchell/delaunay/pull/58)
+
 ### Changed
 
-- **Enhances changelog generation and release process** [`3a57f53`](https://github.com/acgetchell/delaunay/commit/3a57f53b62a9888bf55d7cc021d9d00865b671ca)
+- **Documentation updates for upcoming v0.4.2** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+  Updates README to the `scripts/` directory detailing the purpose, usage, and dependencies of each utility script.
+
+  Updates WARP.md to focus on AI guidance
+
+  Also adds minor spell check fixes.
+
+- **Refactors examples and enhances testing structure** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+  Refactors the example directory and enhances the testing framework to improve code organization and maintainability.
+
+- **Moves the \`test\_alloc\_api.rs\` and \`test\_circumsphere.rs\` examples to the \`tests/\` directory and renames them to \`allocation\_api.rs\` and**
+
+  **\`circumsphere\_debug\_tools.rs\`, respectively, to reflect their role as debugging and testing utilities.**
+  [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+- **Updates documentation to reflect these changes.** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+- **Refactors examples and updates documentation** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+  Renames `implicit_conversion.rs` to `into_from_conversions.rs` and updates its content to better reflect the use of `Into`/`From` traits for coordinate
+  conversions.
+
+  This change improves clarity and modernizes the example to align with current Rust best practices. Also updates documentation across multiple files to reflect
+  the rename and new example.
+
+- **Improves benchmark comparisons and tooling** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+  Refactors the benchmark comparison process to use the baseline artifact directly instead of copying it to a temporary location.
+
+  This change avoids unnecessary file operations and simplifies the workflow.
+  It also introduces average regression calculation for more accurate performance analysis, taking individual benchmark variations into account.
+  Adds new pytest-based tests for the benchmark comparison tool to improve reliability.
+
+  Cleans up temporary baseline files after artifact generation to prevent clutter and potential conflicts.
+  Updates the WARP.md documentation to reflect recent changes and adds guidance on shell script formatting.
+  Also updates the all examples script to improve error handling and example discovery.
+
+- **Changes benchmarks to use geometric mean** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+  Enhances benchmark reporting with geometric mean for time changes and commit SHA resolution from metadata.
+
+  Adds Clippy configuration and improves Rust code quality checks.
+
+  Refactors example running to improve discovery and handling of Cargo examples, including timeout support.
+
+  Updates WARP.md with more detailed instructions on code quality and style conventions, including formatting, linting, spell checking, and JSON validation.
+
+- **Improves benchmark comparison and example handling** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+  Enhances benchmark comparison by normalizing time units, using geometric mean for averaging changes, and guarding against non-positive ratios.
+
+  Adds robustness to example script by checking for example directory and adding timeout and kill signals.
+
+  Also includes minor fixes to metadata handling and test assertions.
+
+- **Modifies benchmark workflows to correctly identify baseline results files and set environment variables accordingly.**
+
+  [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
 
-- **Automates performance regression testing** [`d57a6fd`](https://github.com/acgetchell/delaunay/commit/d57a6fd6aee01ec5c65940d8177896bcb191e06b)
+- **Enhances example execution script to handle timeouts with or without \`timeout\` command, ensuring consistent behavior across environments.**
+
+  [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+- **Updates shell script formatting guidelines in WARP.md to enforce tab indentation.** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+- **Updates example script and documentation** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+  Updates the example script to support time units in `EXAMPLE_TIMEOUT`.
+
+  Removes the unnecessary creation of the results directory in the example script.
+
+  Clarifies shell script formatting requirements in the documentation.
+
+  Adds tracking issues for future improvements.
+
+  Fixes #61
+
+- **Refactors benchmarks for CI performance suite** [`4863dfe`](https://github.com/acgetchell/delaunay/commit/4863dfe9ae9fabef838da214e5eb35f4c74b7d12)
+
+- **Refactors and expands benchmark suite** [`43e55a9`](https://github.com/acgetchell/delaunay/commit/43e55a9e90239de0ee030d5de38fc8fdfec17c51)
+
+- **Refactors and expands benchmark suite** [`f77e441`](https://github.com/acgetchell/delaunay/commit/f77e441ec19f4184983eca21f85bbca6ce554932)
+
+### Removed
+
+- **Removes outdated examples and clarifies the purpose of remaining examples in the README.**
+
+  [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+### Fixed
+
+- **Fixes benchmark and regression reports,** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+  Refactors benchmark scripts to improve baseline commit SHA resolution and report top regressions.
+
+  Adds timeout functionality to example scripts, including support for `gtimeout` on macOS, and introduces an `EXAMPLE_TIMEOUT` environment variable.
+
+  Updates tests and documentation accordingly.
+
+- **Fixes benchmark and example scripts** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+  Refactors benchmark artifact handling and example execution for better reliability and clarity.
+
+- **Corrects an issue in circumsphere tests, boundary detections.** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
+
+- **Fix pesky shell script linting** [`f10aba3`](https://github.com/acgetchell/delaunay/commit/f10aba3)
 
 ## [v0.4.1](https://github.com/acgetchell/delaunay/compare/v0.4.0...v0.4.1) - 2025-08-30
 
@@ -50,15 +161,15 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
   Also includes minor improvements to benchmark comparison and documentation.
 
-- **Pins `tarpaulin` version in code coverage workflow and adds a cache restore key for
+- **Pins \`tarpaulin\` version in code coverage workflow and adds a cache restore key for improved caching.**
 
-  improved caching.** [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
+  [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
 
-- **Adds common directories to `.cspell.json` to prevent spellcheck errors in those
+- **Adds common directories to \`.cspell.json\` to prevent spellcheck errors in those directories.**
 
-  directories.** [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
+  [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
 
-- **Enhances the `tag-from-changelog.sh` script to support hyperlink changelog syntax.** [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
+- **Enhances the \`tag-from-changelog.sh\` script to support hyperlink changelog syntax.** [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
 
 - **Adds DOI badge to README** [`a5f0f51`](https://github.com/acgetchell/delaunay/commit/a5f0f51dae0174cdf541f7e556e13441caa2a850)
 
@@ -142,10 +253,6 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
   Addresses several issues and introduces enhancements across benchmark infrastructure and related scripts, resulting in improved robustness and functionality.
 
-- **Updates `generate_baseline.sh` to collect git commit info even when git isn't available
-
-  and fixes an issue that prevented benchmarks from running in dev mode.** [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
-
 - **Updates WARP.md to find and execute shellcheck and shfmt.** [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
 
 - **Improves benchmark and CI scripts** [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
@@ -171,13 +278,18 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
 - **Corrects environment variable assignment in benchmark workflows for proper behavior.** [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
 
-- **Improves the error handling, unit handling, and overall stability of benchmark parsing
+- **Improves the error handling, unit handling, and overall stability of benchmark parsing scripts.**
+
+  [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
+
+- **Updates \`generate\_baseline.sh\` to collect git commit info even when git isn't available and fixes an issue that prevented benchmarks from running in**
 
-  scripts.** [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
+  **dev mode.**
+  [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
 
-- **Improves hardware comparison logic to reduce false positives and uses PowerShell for
+- **Improves hardware comparison logic to reduce false positives and uses PowerShell for hardware detection on Windows.**
 
-  hardware detection on Windows.** [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
+  [`5fb31b1`](https://github.com/acgetchell/delaunay/commit/5fb31b1)
 
 ## [v0.4.0](https://github.com/acgetchell/delaunay/compare/v0.3.5...v0.4.0) - 2025-08-22
 
@@ -218,13 +330,13 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
   correctness and performance of the new functionality.
 
-- **Implements a pure incremental Delaunay triangulation algorithm, removing the supercell
+- **Implements a pure incremental Delaunay triangulation algorithm, removing the supercell approach and improving performance scaling.**
 
-  approach and improving performance scaling.** [`2e31533`](https://github.com/acgetchell/delaunay/commit/2e31533)
+  [`2e31533`](https://github.com/acgetchell/delaunay/commit/2e31533)
 
-- **Adds reusable buffers to the Bowyer-Watson algorithm, reducing memory allocation
+- **Adds reusable buffers to the Bowyer-Watson algorithm, reducing memory allocation overhead.**
 
-  overhead.** [`2e31533`](https://github.com/acgetchell/delaunay/commit/2e31533)
+  [`2e31533`](https://github.com/acgetchell/delaunay/commit/2e31533)
 
 - **Introduces robust geometric predicates to handle degenerate cases more effectively.** [`2e31533`](https://github.com/acgetchell/delaunay/commit/2e31533)
 
@@ -295,9 +407,9 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
   This commit introduces several key changes:
 
-- **Optimizes validation methods with early termination and pre-computed mappings, leading
+- **Optimizes validation methods with early termination and pre-computed mappings, leading to faster validation.**
 
-  to faster validation.** [`2e31533`](https://github.com/acgetchell/delaunay/commit/2e31533)
+  [`2e31533`](https://github.com/acgetchell/delaunay/commit/2e31533)
 
 - **Uses arc-swap crate for lock-free atomic cache updates.** [`2e31533`](https://github.com/acgetchell/delaunay/commit/2e31533)
 
@@ -360,7 +472,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
   This change addresses potential issues with floating-point precision and error handling, leading to more robust and reliable Delaunay triangulations.
 
-  Also includes formatting and linter fixes, and updates CI workflow to include rustfmt and clippy checks to maintain code quality and consistency. Adds
+  Also includes formatting and linter fixes, and updates CI workflow to include rustfmt and clippy checks to maintain code quality and consistency.  Adds
   perturbation test and enhances failure handling in degenerate cases.
 
 - **Improves numerical stability and robustness** [`2e31533`](https://github.com/acgetchell/delaunay/commit/2e31533)

CONTRIBUTING.md

@@ -11,6 +11,7 @@ to experienced developers looking to contribute significant features.
 - [Development Environment Setup](#development-environment-setup)
 - [Project Structure](#project-structure)
 - [Development Workflow](#development-workflow)
+- [CI Performance Testing](#ci-performance-testing)
 - [Code Style and Standards](#code-style-and-standards)
 - [Testing](#testing)
 - [Documentation](#documentation)
@@ -229,6 +230,55 @@ The project follows a standard Rust library structure with additional tooling fo
 
 For detailed code organization patterns and module structure, see [code organization documentation][code-organization].
 
+## CI Performance Testing
+
+### ⚠️ **Important: Rust Code Changes Trigger Lengthy Baseline Comparisons**
+
+**Any changes to Rust code will automatically trigger performance regression testing in CI, which can take 30-45 minutes to complete.**
+
+The benchmark workflow runs on changes to:
+
+- `src/**` - Any core library code
+- `benches/**` - Benchmark code  
+- `Cargo.toml` or `Cargo.lock` - Dependencies
+
+### **Branch Strategy Recommendation**
+
+To avoid triggering lengthy baseline comparisons unnecessarily:
+
+✅ **Recommended**: Keep documentation and Python utility updates in **separate branches/PRs** from Rust code changes
+
+❌ **Avoid**: Mixing documentation updates with Rust code changes in the same commit/PR
+
+### **Examples**
+
+**Good workflow:**
+
+```bash
+# Branch 1: Documentation updates only
+git checkout -b docs/update-readme
+# Edit README.md, CONTRIBUTING.md, etc.
+git commit -m "docs: update contributing guidelines"
+# → No benchmarks triggered, fast CI
+
+# Branch 2: Rust code changes (separate PR)
+git checkout -b feat/improve-algorithm 
+# Edit src/core/triangulation.rs
+git commit -m "feat: optimize triangulation algorithm"
+# → Benchmarks triggered, but isolated to code changes
+```
+
+**Avoid:**
+
+```bash
+# Mixed changes (triggers benchmarks for trivial doc fixes)
+git add README.md src/core/triangulation.rs
+git commit -m "feat: algorithm improvement + doc updates"
+# → 45-minute benchmark run for a simple doc fix
+```
+
+This strategy helps maintain fast feedback loops for documentation work while ensuring proper performance regression testing for code changes.
+
 ## Development Workflow
 
 ### 1. Issue-Driven Development

Cargo.lock

@@ -37,6 +37,7 @@ uuid = { version = "1.18.0", features = ["v4", "serde"] }
 
 [dev-dependencies]
 criterion = { version = "0.7", features = ["html_reports"] }
+pastey = "0.1"
 
 [features]
 count-allocations = ["allocation-counter"]
@@ -57,8 +58,17 @@ harness = false
 name = "assign_neighbors_performance"
 harness = false
 
+
+[[bench]]
+name = "memory_scaling"
+harness = false
+
+[[bench]]
+name = "triangulation_vs_hull_memory"
+harness = false
+
 [[bench]]
-name = "small_scale_triangulation"
+name = "ci_performance_suite"
 harness = false
 
 [lints.rust]