Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
594b06f
feat: add provisional many-body minimax solver and envelope gradient …
Oct 4, 2026
c4685b7
docs: record owner MIT decision for the ellcech source in provenance …
Oct 4, 2026
225111e
feat: add pairwise-aligned public many-body API (tangency_simplex, ta…
Oct 4, 2026
5012023
feat: harden the many-body engine (Newton guard, general constant off…
Oct 4, 2026
dc39c2e
fix many-body solver review findings
Oct 4, 2026
565547a
refactor: name the many-body API after the Čech filtration (cech, Cec…
Oct 4, 2026
5a799d5
fix: stabilize many-body Newton and FW convergence
Oct 4, 2026
c878998
refactor: keep Cech stabilization controls private
Oct 4, 2026
6d0e6fe
fix: reject non-SPD quadratic blocks in the public Čech API
Oct 4, 2026
9c17323
fix: consistent stabilisation in singleton and FW-gap paths; allow ze…
Oct 4, 2026
ce78b37
fix: global gap recheck after Newton, re-evaluate exhausted FW, stabi…
Oct 4, 2026
c1bb4f6
fix: require a positive Newton tolerance
Oct 4, 2026
a340bd6
docs: state the quasi-Newton approximation under mu-dependent conditi…
Oct 4, 2026
a8736e3
fix: make many-body minimax convergence robust
Oct 5, 2026
920566d
fix: preserve the caller FW iteration budget
Oct 5, 2026
d460012
fix: enforce dual gap for direct SLSQP
Oct 5, 2026
8917630
fix: preserve active set after scale clipping
Oct 5, 2026
6a76478
fix: restore plain Frank-Wolfe steps, keep the SLSQP fallback
Oct 5, 2026
13b88e1
fix: remove automatic solver fallbacks; non-convergence raises
Oct 5, 2026
357fb01
docs: name the dual step pairwise Frank-Wolfe; declare comparator tol…
Oct 5, 2026
0d60fb0
fix: bound packed normalization roundoff by the largest row
Oct 5, 2026
4301950
feat: default fw+brentq+newton; relative duality-gap convergence test
Oct 5, 2026
3bf2406
test: pin the relative-gap contract; comparator tolerance relative to…
Oct 5, 2026
a401b9c
fix: bound Cech normalization roundoff by computed terms
Oct 5, 2026
e5a5e91
fix: scale regularized FW gap by actual dual value
Oct 5, 2026
99a0dfa
fix: derive the negative-alpha allowance from the support rows only
Oct 5, 2026
536592a
fix: certify the roundoff estimate, unify the convergence contract, d…
Oct 5, 2026
ff87d40
feat: traceable composite default route (auto) with per-stage diagnos…
Oct 5, 2026
db5ea80
fix: propagate solver statuses to public diagnostics; document result…
Oct 5, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,14 @@ This section documents the reasons for each entry in the `stubtest-allowlist.txt

**Reason:** This entry is necessary because the `MethodName` type alias is defined as a `typing.Literal` in the implementation, but it is simplified to `str` in the corresponding stub file (`.pyi`). This simplification is intentional to avoid duplicating the literal values in the stub, which would make it harder to maintain. (An equivalent entry for the `ellphi.solver` re-export was needed with older mypy versions but is reported as unused since mypy 1.20.)

* `ellphi._minimax_python.MethodName`

**Reason:** The stub declares the same seven-value `typing.Literal` alias as the implementation, but stubtest cannot verify multi-value `Literal` aliases: it expands the stub alias into a union of single-value literals and reports the runtime alias as "not a Union". Simplifying the stub to `str` does not avoid the report either, so the entry keeps the precise stub type.

* `ellphi.cech.MethodName`

**Reason:** The stub declares the precise eight-value `typing.Literal` alias, including the public `"auto"` route, but stubtest cannot verify multi-value `Literal` aliases and reports the runtime alias as "not a Union". The precise alias is retained for type checking.

#### Managing the Allowlist

When adding a new entry to the `stubtest-allowlist.txt` file, you must also update the "Allowlist Justification" section in this document to include a clear and concise explanation for why the entry is needed. This ensures that the allowlist remains transparent and easy to manage.
Expand Down
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,13 @@ Starting from an ordinary point cloud, it estimates local covariance, inflates *
- **N-Dimensional Support**: Works with n-dimensional ellipsoids, allowing for analysis in higher-dimensional spaces.
- **Visualization**: Comes with helper functions to quickly visualize ellipse clouds using Matplotlib.

For simplex-level anisotropic filtrations, `ellphi.cech(coefs)` computes the
Čech time for several ellipsoids, while `ellphi.cech_grad(coefs)` also returns
the gradient with respect to the packed coefficients. The default `method="auto"`
tries the robust many-body route and records the selected method, convergence
status, gap, iteration count, and any fallback stages in the result's `info`
field.

## Installation

Install from PyPI:
Expand Down
111 changes: 111 additions & 0 deletions docs/guide/cech_filtration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
# Čech filtration

The public `ellphi.cech` API computes the anisotropic Čech filtration value for
a simplex of packed ellipsoid coefficient vectors. For
`f_i(x)` describing the growing ellipsoids
`E_i(t) = {f_i <= t^2}`, `cech(coefs)` returns the Čech filtration time
`t`, where

`t^2 = alpha(sigma) = min_x max_i f_i(x)`

is the least squared scale at which all bodies share a common point.

The result fields are ordered as
`(t, point, mu, support, active_set, info)`. The gradient result fields are
ordered as `(t, point, mu, dt_dcoef, support, active_set, info)`.

- `t`: the Čech filtration time, with `t^2 = alpha(sigma)`.
- `point`: the common intersection point `x*` at the critical scale.
- `mu`: the Lagrange multipliers, or dual weights on the simplex.
- `support`: the thresholded weight support
`{i : mu_i > weight_tol}`.
- `active_set`: the tight-constraint set at the returned point,
`I = {i : t^2 - f_i(point) <= active_tol * max(1, t^2)}`; if `alpha` is
clipped at zero, the actual clipping shift `t^2 - alpha` is added to this
threshold.
- `info`: a `CechInfo` record containing `requested_method`, `method_used`,
`converged`, the final `gap`, the selected stage's `n_iter`, and its
`stages` tuple. Each `CechStage` records `method`, `converged`, `status`,
`gap`, and `n_iter`.

The public `cech` and `cech_grad` signatures intentionally do not expose
matrix stabilization controls such as `regularization`,
`condition_number_limit`, or `max_conditioning_steps`. Stabilized solves are
available only through the private `ellphi._minimax_python` engine for
research use, and the public coefficient-space gradient carries no guarantee
for those stabilized solves.

At the critical scale the intersection is the single point `x*`. The active
ellipsoid boundaries pass through `x*` and satisfy
`sum_i mu_i grad f_i(x*) = 0`, so their normals are positively dependent;
the boundaries are not tangent to each other. Pairwise tangency is only the
`k = 2` special case: for `k = 2` the Čech time equals the tangency time
computed by `tangency()`, and `cech()` agrees with it.

Up to numerical tolerance, `support` is a subset of `active_set`; under
strict complementarity (ND1), they coincide. For three unit balls centred at
`(0, 0)`, `(2, 0)`, and `(0, 2)`, the point is `(1, 1)`, support has
two indices, and `active_set` has three.

Every solver method uses the same accepted-result gap contract:
`gap <= tol * max(1, abs(dual value))`. Thus `tol` is an all-method relative
duality-gap tolerance, not a pairwise-FW-only control or a Newton residual
tolerance. The Frank-Wolfe description below refers only to the first stage
of the default route.

Failure diagnostics depend on the route. A named method runs one stage and
raises `RuntimeError` with that stage's method, status, iteration count, final
gap, `tol`, and relative-gap scale. The `auto` route lists both attempted
stages, including each method, status, final gap, and iteration or evaluation
count; it does not collapse them into a single named-method diagnostic.

## Default route

The default `method="auto"` is a declared two-stage route. Stage 1 runs
`fw+brentq+newton` with the caller's `tol`, `max_iter`, and `newton_tol`. If it
does not converge, stage 2 runs the gap-enforced dual-weight solver
`scipy-slsqp` from uniform weights with the same `tol`. `info.stages` records
both stages when the fallback is used, including the first stage's status and
final gap. The selected stage is reported by `info.method_used`, and the
requested route remains visible in `info.requested_method`.

The route never reports a non-converged result as success. If both stages fail,
`cech` raises `RuntimeError` with each stage's status, final gap, and iteration
or evaluation count. A named method runs only that method and raises on
failure; named methods never fall back.

Each Frank-Wolfe step in stage 1 selects the best vertex (largest constraint
value) and the worst active vertex (smallest constraint value), then swaps mass
along `e_s - e_v` with step at most `mu[v]`. Its gap tolerance is relative to
`max(1, |dual value|)`.

The private engine's internal field named `active_set` is the weight support
(historical ellcech naming) and is not part of the public API.

If `unpack_conic` returns `(A_i, b_i, c_i)`, the center is
`xbar_i = -A_i^{-1} b_i` and the completed-square constant is
`delta_i = c_i - b_i^T A_i^{-1} b_i`. The public API passes this computed
`delta_i` to the many-body engine, including when it is small, so
general independent constants are supported.

A packed row encodes its constant as
`c_i = xbar_i^T A_i xbar_i + delta_i`. For `|xbar_i|^2 >> 1`, the computed
`delta_i` can lose precision in the centered quadratic term and its
subtraction from `c_i`. The implementation reports a per-row rounding
estimate based on the solve residual and the dot-product/subtraction
dimension; this is an estimate, not a rigorous bound. Callers needing exact
normalization at large translations should center their data first. Packed
input requires `d >= 2`; d=1 packed conics are not supported and raise
`ValueError`.

The many-body engine uses the completed-square offsets above. Thus
`cech_grad(coefs)` returns `dt_dcoef`, the gradient for arbitrary
independent packed-coordinate perturbations, including the constant component.
For the upper-triangular packed basis
`[x_i**2, 2*x_i*x_j (i < j), 2*x_i, 1]`, the formula is
`mu_i * basis(point) / (2*t)`. It assumes a non-degenerate input, at least
two indices in `active_set`, multipliers supported on `active_set`, and an
exact weighted linear solve. Convergence or a small residual alone is not a
derivative certificate, and the gradient is undefined at `t == 0`.
For far-translated inputs, the uncentred packed basis used by this derivative
can be poorly conditioned.
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ nav:
- User Guide:
- TDA Workflow: guide/tda_workflow.md
- Differentiable Tangency: guide/differentiable.md
- Čech Filtration: guide/cech_filtration.md
- Notebook Examples: guide/notebooks.md
- API Reference:
- Overview: reference/index.md
Expand Down
Loading
Loading