feat(detection): faithful L1Potts solver, hardening, tests, docs

Rewrite the L1Potts implementation to match Algorithm 1 of
Storath, Weinmann & Unser (2017) explicitly. The forward DP is identical
to the paper; backtracking uses explicit parent pointers (uint8 matrix +
prev-argmin vector) instead of the paper's in-place float64 subtraction
trick. Mathematically equivalent, ~8x less memory.

Hardening: reject non-numeric dtypes, NaN/Inf in signal or weights,
empty signal, and predict-before-fit; clear ValueError/RuntimeError
messages instead of cryptic IndexError/AttributeError. Defensive copies
of signal and weights shield the solver from caller mutation.

Tests (tests/test_l1potts.py, 71 cases):
- functional-value parity with Pelt+CostL1 over 5 random seeds
- replication-equivalence for integer weights, including weight ratios
  up to 10000:1
- positive homogeneity over 7 orders of magnitude in alpha
- reversal symmetry of the functional
- multi-pen independence on a single fit
- edge cases: n=1, K=1, n=2, shape (N,1), pen=+inf, pen=NaN, empty
  signal, complex/object/bool dtypes, list/tuple/read-only inputs
- SyntaxWarning regression net via subprocess + compile()

Docs: user-guide page (docs/user-guide/detection/l1potts.md) with usage
example and reference, code-reference autodoc stub, mkdocs nav entries.
Export L1Potts at top level (rpt.L1Potts).

Performance: on N=5000 noisy 1D signal, ~20x faster than
Pelt(model="l1", min_size=1, jump=1) with identical functional value.

Implementation prepared with assistance from Claude (Anthropic) acting
as a coding agent. The algorithm is the cited authors'; the agent's
contributions were the parent-pointer backtracking variant, input
hardening, and the test suite.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mstorath

docs/code-reference/detection/l1potts-reference.md

@@ -0,0 +1,5 @@
+# L1Potts
+
+::: ruptures.detection.l1potts.L1Potts
+    rendering:
+        show_root_heading: true

docs/user-guide/detection/l1potts.md

@@ -0,0 +1,61 @@
+# Penalized L1 Potts segmentation (`L1Potts`)
+
+## Description
+
+The method is implemented in [`L1Potts`][ruptures.detection.l1potts.L1Potts].
+It computes the global minimizer of the **L1 Potts functional** for piecewise constant 1D signals:
+
+$$
+\min_{u \in \mathbb{R}^N} \;\; \gamma \sum_{i=1}^{N-1} \mathbb{1}(u_i \neq u_{i+1}) \;+\; \sum_{i=1}^{N} w_i \, |f_i - u_i|
+$$
+
+where $f$ is the observed signal, $w$ are non-negative per-sample weights, and $\gamma > 0$ is the jump penalty.
+
+The L1 fit makes the estimator robust to heavy-tailed noise and outliers, in contrast to the L2 Potts model used by other ruptures detectors (`Pelt(model="l2")`, `Dynp(model="l2")`).
+
+The implementation is **Algorithm 1 of [[Storath2017]](#Storath2017)**, which solves the problem exactly in $\mathcal{O}(KN)$ time, where $N$ is the number of samples and $K$ the number of distinct values in the signal. The algorithm is much faster than `Pelt(model="l1")` (a 20–30× speedup is typical on a few-thousand-sample noisy signal). It uses a Viterbi-type dynamic program over (level, sample) pairs, where the candidate levels are the unique observed values — the optimal segment level is always one of them, since the weighted L1 median lies in the data.
+
+`L1Potts` accepts only 1D signals. Penalty-only mode (`predict(pen=...)`) is the only supported prediction mode; `n_bkps` and `epsilon` are not.
+
+
+## Usage
+
+```python
+import numpy as np
+import matplotlib.pylab as plt
+import ruptures as rpt
+
+# creation of data with heavy-tailed (Laplace) noise
+n, sigma = 500, 1.0
+n_bkps = 3
+signal, bkps = rpt.pw_constant(n, 1, n_bkps, noise_std=sigma)
+signal = signal.ravel() + np.random.default_rng(0).laplace(scale=sigma, size=n)
+
+# change point detection
+algo = rpt.L1Potts().fit(signal)
+my_bkps = algo.predict(pen=3.0)
+
+# show results
+rpt.show.display(signal, bkps, my_bkps, figsize=(10, 6))
+plt.show()
+```
+
+To downweight known outlier samples, pass per-sample weights to `fit`:
+
+```python
+weights = np.ones(n)
+weights[outlier_indices] = 1e-3  # near-zero weight effectively ignores those samples
+my_bkps = rpt.L1Potts().fit(signal, weights=weights).predict(pen=3.0)
+```
+
+`fit_predict` is also available:
+
+```python
+my_bkps = rpt.L1Potts().fit_predict(signal, pen=3.0, weights=weights)
+```
+
+
+## References
+
+<a id="Storath2017">[Storath2017]</a>
+Storath, M., Weinmann, A., & Unser, M. (2017). Jump-penalized least absolute values estimation of scalar or circle-valued signals. *Information and Inference: A Journal of the IMA*. Preprint: <https://bigwww.epfl.ch/preprints/storath1602p.pdf>

mkdocs.yml

@@ -49,6 +49,7 @@ nav:
       - 'Binary segmentation': user-guide/detection/binseg.md
       - 'Bottom-up segmentation': user-guide/detection/bottomup.md
       - 'Window sliding segmentation': user-guide/detection/window.md
+      - 'L1 Potts': user-guide/detection/l1potts.md
     - Cost functions:
       - 'CostL1': user-guide/costs/costl1.md
       - 'CostL2': user-guide/costs/costl2.md
@@ -92,6 +93,7 @@ nav:
           - Binseg: code-reference/detection/binseg-reference.md
           - BottomUp: code-reference/detection/bottomup-reference.md
           - Window: code-reference/detection/window-reference.md
+          - L1Potts: code-reference/detection/l1potts-reference.md
       - Cost functions:
           - 'CostL1': code-reference/costs/costl1-reference.md
           - 'CostL2': code-reference/costs/costl2-reference.md

src/ruptures/__init__.py

@@ -1,7 +1,7 @@
 """Offline change point detection for Python."""
 
 from .datasets import pw_constant, pw_linear, pw_normal, pw_wavy
-from .detection import Binseg, BottomUp, Dynp, KernelCPD, Pelt, Window
+from .detection import Binseg, BottomUp, Dynp, KernelCPD, L1Potts, Pelt, Window
 from .exceptions import NotEnoughPoints
 from .show import display
 

src/ruptures/detection/__init__.py

@@ -4,5 +4,6 @@
 from .bottomup import BottomUp
 from .dynp import Dynp
 from .kernelcpd import KernelCPD
+from .l1potts import L1Potts
 from .pelt import Pelt
 from .window import Window