rustures finds points where the statistical behaviour of a sequence changes: its mean, distribution, trend, autoregressive dynamics, or kernel representation. The search algorithms and built-in cost functions run in Rust while the public API stays in Python.

The project is inspired by the excellent ruptures ecosystem, but it is an independent implementation rather than a complete drop-in replacement.

[!IMPORTANT] rustures is currently pre-alpha. The API is usable and heavily tested, but public APIs and compatibility guarantees may still change between releases.

Why rustures?

• A native core without a Python loop in the hot path. Built-in costs and detectors execute in optimized Rust.
• Exact and approximate search strategies. Use fixed-K dynamic programming, penalized optimal partitioning, kernel CPD, or faster greedy detectors.
• Memory is part of the API. Dynp and full-Gram kernel backends reject oversized jobs before allocating their main tables.
• Kernel CPD without mandatory quadratic storage. The default fused backend is exact and does not materialize a full Gram matrix.
• Custom Python costs when the built-ins are not enough. Dynp and Pelt accept scalar callbacks and optional endpoint-batched callbacks.
• Multivariate input is first-class. Most costs accept an (n_samples, n_features) NumPy array; scalar signals may remain one-dimensional.
• Python-safe failure boundaries. Invalid data, allocation limits, numerical failures, and unwinding Rust panics become catchable Python exceptions.
• Reproducible validation. Deterministic generators, metrics, exhaustive small oracles, parity fixtures, and raw benchmark artifacts live in the repository.

Quick start

import rustures as rpt

# Deterministic piecewise-constant data and its true breakpoints.
signal, truth = rpt.pw_constant(
    n_samples=600,
    n_features=2,
    n_bkps=3,
    noise_std=0.7,
    seed=42,
)

# Penalized exact segmentation.
prediction = rpt.Pelt(
    model="l2",
    min_size=10,
    jump=1,
).fit_predict(signal, pen=12.0)

precision, recall = rpt.precision_recall(truth, prediction, margin=10)

print("truth:     ", truth)
print("prediction:", prediction)
print(f"precision={precision:.3f}, recall={recall:.3f}")

Breakpoints use the half-open interval convention and always include the terminal sample. A result such as [120, 360, 600] represents segments [0, 120), [120, 360), and [360, 600).

Choosing an algorithm

Fixed number of changes

algo = rpt.Dynp(model="normal", min_size=8, jump=2).fit(signal)

print("workspace bytes:", algo.estimated_memory_bytes(n_bkps=3))
breakpoints = algo.predict(n_bkps=3)

Dynp defaults to a 512 MiB prediction-workspace limit. Override it explicitly when you know the process budget:

algo = rpt.Dynp(
    model="l2",
    jump=1,
    max_memory_bytes=256 * 1024 * 1024,
).fit(signal)

# Raises MemoryError before allocating DP states if the limit would be exceeded.
breakpoints = algo.predict(n_bkps=32)

Kernel change-point detection

kernel_algo = rpt.KernelCPD(
    kernel="rbf",
    gamma_policy="sampled",
    gamma_samples=10_000,
    seed=42,
    backend="fused",
    min_size=5,
    jump=1,
)

breakpoints = kernel_algo.fit_predict(signal, n_bkps=3)

Available kernels are "linear", "rbf", and "cosine".

The full backend has its own 512 MiB default limit through max_gram_bytes.

Cost models

The following model strings work with the general-purpose detectors:

Standalone cost objects expose fit, error(start, end), and sum_of_costs:

cost = rpt.CostL2().fit(signal)
segment_cost = cost.error(100, 220)
partition_cost = cost.sum_of_costs([100, 220, len(signal)])

Custom Python costs

Dynp and Pelt accept any object with this protocol:

class CustomCost:
    min_size: int

    def fit(self, signal): ...
    def error(self, start: int, end: int) -> float: ...

    # Optional: calculate several segments ending at the same endpoint.
    def error_many(self, starts, ends): ...

For example, a Bernoulli negative log-likelihood cost can be written as:

import numpy as np
import rustures as rpt


class BernoulliCost:
    min_size = 1

    def fit(self, signal):
        values = np.asarray(signal, dtype=np.float64).reshape(-1)
        if not np.all((values == 0.0) | (values == 1.0)):
            raise ValueError("BernoulliCost expects only 0 and 1")
        self.values = values
        self.prefix = np.r_[0.0, np.cumsum(values)]
        return self

    def error(self, start, end):
        length = end - start
        ones = self.prefix[end] - self.prefix[start]
        p = ones / length
        if p == 0.0 or p == 1.0:
            return 0.0
        return -(ones * np.log(p) + (length - ones) * np.log1p(-p))


binary_signal = np.r_[np.zeros(80), np.ones(60), np.zeros(90)]

breakpoints = rpt.Dynp(
    custom_cost=BernoulliCost(),
    min_size=10,
    jump=1,
).fit_predict(binary_signal, n_bkps=2)

error_many avoids one Python call per segment candidate. The adapter retains only one endpoint batch, so it does not silently build an O(n²) Python cost table. Exceptions raised by a custom cost preserve their Python type, message, and traceback. Custom Pelt uses the exact unpruned path because arbitrary user costs do not automatically satisfy the PELT pruning inequality.

Included utilities

Deterministic signal generators:

• pw_constant
• pw_linear
• pw_normal
• pw_wavy

Evaluation metrics:

• hausdorff
• precision_recall
• rand_index

All generators require an explicit seed and return (signal, breakpoints).

Performance snapshot

The latest local comparison used Windows 11 x86-64, Python 3.11, a release abi3 wheel, N=400, min_size=5, jump=5, and the median of five alternating runs. Times include a fresh Dynp.fit_predict call.

These are machine- and workload-specific results, not universal guarantees. Raw data is available in artifacts/validation/phase9-final-regression-benchmark.json, and the benchmark driver is benchmarks/benchmark_phase7_costs.py.

Correctness and safety

The repository currently checks correctness through several independent layers:

• exhaustive enumeration for small fixed-K and penalized problems;
• black-box parity fixtures generated from pinned ruptures behaviour;
• full-Gram, streaming, fused, scalar, and AVX2 backend parity tests;
• deterministic tie-breaking tests;
• finite-input, overflow, singular, collinear, constant, and large-offset cases;
• 2,528 Linear/AR fast-path comparisons against scalar SVD Dynp and Pelt;
• Python exception and Rust panic-boundary process-survival tests.

The AVX2 path uses runtime CPU detection. CPUs without AVX2 automatically use the scalar implementation instead of failing at import time.

Installation

Current compatibility

• Python 3.10 or newer is declared through abi3-py310.
• NumPy 1.23 or newer is required.
• Binary wheels are published for Linux x86-64 and ARM64, Windows x86-64, and macOS Intel and Apple Silicon.
• The current wheels target GIL-enabled CPython. They do not target 32-bit Python, PyPy, free-threaded CPython, or native Windows ARM64.

Install a published wheel from PyPI:

python -m pip install rustures

Build from source

Prerequisites: Python 3.10+, Rust 1.83+, and a working native compiler toolchain.

git clone https://github.com/denrew88/rustures.git
cd rustures

python -m venv .venv

Activate the environment:

Windows PowerShell:  .venv\Scripts\Activate.ps1
Linux/macOS:         source .venv/bin/activate

Build and install an editable release extension:

python -m pip install --upgrade pip
python -m pip install "maturin>=1.14,<2.0" "numpy>=1.23"
python -m maturin develop --release

Or create a wheel:

python -m maturin build --release

The wheel is written to target/wheels/.

Development

# Rust unit, oracle, and parity tests
cargo test

# Formatting and linting
cargo fmt -- --check
cargo clippy --all-targets --all-features -- -D warnings

# Python wheel tests after installing a built wheel
python -m pip install pytest
python -m pytest tests/python/test_wheel.py -q

# Longer Linear/AR regression matrix
cargo test --release --test regression_mass -- --ignored --nocapture

Tutorial notebooks are available in English and Korean.

Project status

Implemented today:

• Dynp, Pelt, Binseg, BottomUp, Window, KernelCPD, and L1Potts
• eight general-purpose cost models
• linear, RBF, and cosine kernels with three exact backends
• custom Python costs for Dynp and Pelt
• multivariate signal handling, metrics, and deterministic datasets
• typed Python errors, panic isolation, memory preflight, and type hints

Major work still planned:

• approximate low-rank kernel backends;
• broader profiling across CPU architectures and feature dimensions;
• additional interpreter and architecture coverage as the API matures.

License

Licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.

The Rust dependencies compiled into the wheel, their selected license options, copyright notices, and full license texts are recorded in THIRD-PARTY-LICENSES. The report is generated from Cargo.lock for the verified Windows x86-64 target with:

cargo install --locked --features cli cargo-about
cargo about generate --locked --fail -c about.toml -o THIRD-PARTY-LICENSES about.hbs