Metadata-Version: 2.4
Name: resolution-defect
Version: 0.1.0
Summary: Resolution-defect calculus for diagnosing, accelerating, and controlling numerical processes.
Author-email: Dmitry Serikoff <dmitry.serikoff@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dimaq12/resolution-defect
Project-URL: Repository, https://github.com/dimaq12/resolution-defect
Project-URL: Issues, https://github.com/dimaq12/resolution-defect/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Provides-Extra: viz
Requires-Dist: matplotlib>=3.6; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# Resolution Defect

**Resolution Defect** is a small Python library for measuring what a computation
reveals when you run it at three scales:

```text
P_n, P_2n, P_4n

D1    = P_n  - P_2n
D2    = P_2n - P_4n
alpha = log2(||D1|| / ||D2||)
```

That one measurement turns convergence error into a usable signal. It can detect
hidden order, estimate convergence factors, drive Richardson acceleration,
classify active coordinates, recover spectral information, and act as a control
layer around solvers or spectral pipelines.

The package is intentionally independent: it depends only on NumPy and SciPy.
It is compatible with SFT-style workflows through plain arrays, spectra and
pseudoinverse kernels, but it does **not** import `sft`.

## Why This Exists

Most numerical checks ask: "How close am I to the answer?"

Resolution-defect calculus asks a more portable question:

> What changes when the same process is run at `n`, `2n`, and `4n`?

This makes diagnostics possible even when the exact answer is unknown. Any
process with a scale parameter can be wrapped:

- PDE/ODE solvers
- semigroup approximations
- fixed-point iterations
- gradient descent and linear solvers
- power iteration
- spectral predictions
- adaptive sorting or refinement processes
- SFT spectrum refinement pipelines

## Installation

From PyPI:

```bash
pip install resolution-defect
```

From source:

```bash
git clone git@github.com:dimaq12/resolution-defect.git
cd resolution-defect
pip install -e ".[dev]"
```

## Quick Start

```python
import resolution_defect as rd


def solver(n: int):
    return 1.0 + 3.0 / n + 0.5 / n**2


study = rd.ProcessDefect(solver, base_n=32)
result = study.measure()

print(result.alpha)      # leading defect exponent
print(result.norm1)      # ||P_n - P_2n||

accelerated = study.richardson(level=1)
print(accelerated)
```

## Core Primitives

```python
rd.defect_pair(Pn, P2n)
rd.defect_triple(Pn, P2n, P4n)
rd.exponent_from_states(Pn, P2n, P4n)
rd.second_defect(Pn, P2n, P4n)
```

`defect_triple` returns:

```python
result.D1
result.D2
result.second
result.norm1
result.norm2
result.second_norm
result.alpha
result.stable
```

## Universal Process API

Wrap any computation as `runner(n) -> state`:

```python
study = rd.ProcessDefect(lambda n: solver(n), base_n=64)

measured = study.measure()
scan = study.scan([16, 32, 64, 128])
fixed = study.richardson(alpha=measured.alpha)
```

This is the main abstraction of the library. It does not care whether `state`
is a scalar, vector, matrix, tensor, spectrum, field, or application-specific
array.

## Richardson Annihilation

If the leading defect behaves like `n^-alpha`, it can be cancelled:

```python
rd.richardson_integer([Pn, P2n], level=1)
rd.richardson_integer([Pn, P2n, P4n], level=2)
rd.richardson_fractional([Pn, P2n], alpha=0.73)
```

The integer levels use the classic Romberg/Richardson hierarchy. Fractional
annihilation is useful when the measured exponent is not an integer.

## Iterative Algorithms

For a convergent iteration `x_k -> x*`, the defect exponent estimates the hidden
linear convergence factor:

```python
alg = rd.AlgorithmDefect(lambda n: iterate(n), base_n=32)
rho = alg.spectral_radius()
```

The estimator is:

```text
rho(J) ~= 2^(-alpha / n0)
```

This gives a black-box convergence diagnostic for fixed-point iterations,
gradient descent, Gauss-Seidel, power iteration and related processes.

## Semigroup Methods

Resolution Defect includes rational approximations for `exp(-tA)`:

```python
import resolution_defect as rd
from resolution_defect import ops

A = ops.heat_1d(32)
Pn = rd.semigroup(A, t=0.5, n=64, method="BE")
```

Available methods:

- `BE`: Backward Euler, `(I + tA/n)^(-n)`
- `FE`: Forward Euler, `(I - tA/n)^n`
- `CN`: Crank-Nicolson / Pade(1,1)

## Defect Spectroscopy

For Backward Euler modes, the defect exponent follows a universal curve
`F(z, n)`, where `z = t*lambda/n`. Precompute the curve once and invert it:

```python
curve = rd.FCurve.precompute(n=256)

alpha_k = 1.25
lambda_k = curve.lambda_from_alpha(alpha_k, t=0.5, n=256)
```

Vectorized recovery:

```python
lambdas = rd.recover_spectrum_from_defect(alphas, t=0.5, n=256)
```

The informative regime is the transition band: low `z` is nearly flat
(`alpha ~= 1`), while very high `z` can underflow.

## Zone Control

The first defect is a velocity signal. The second defect is an acceleration
signal:

```python
zones = rd.partition_by_defect(Pn, P2n, P4n)
print(zones.counts)
```

Zones:

- `deep_frozen`: already stable, keep it
- `settling`: close to final, local correction is likely enough
- `active`: still changing, needs global work

This is useful for adaptive refinement, active-set methods, sorting processes,
mesh updates and selective recomputation.

## SFT-Compatible Bridge

Resolution Defect does not depend on SFT. The bridge layer operates on arrays:

```python
from resolution_defect.sft_bridge import correct_spectral_prediction

correction = correct_spectral_prediction(
    predicted=lam_sft,
    measured=lam_refined,
    W_pinv=fam.W_pinv,
    k=current_k,
)

k_next = correction.corrected_k
```

The division of labor is clean:

```text
SFT               -> predicts spectra and exposes W_pinv
Resolution Defect -> measures residual defect and maps it to corrections
```

## Examples

```bash
python examples/basic_process.py
python examples/semigroup_heat.py
python examples/sft_compatible_bridge.py
```

## Package Layout

```text
resolution_defect/
  core.py          # D1, D2, alpha, norms
  process.py       # ProcessDefect
  richardson.py    # integer/fractional annihilation
  algorithm.py     # rho(J) from defect
  semigroup.py     # BE/FE/CN products
  spectroscopy.py  # FCurve and lambda recovery
  zones.py         # frozen/settling/active partition
  ops.py           # test operator generators
  regularity.py    # spectral test data helpers
  sft_bridge.py    # array-only compatibility helpers
```

## Development

```bash
pip install -e ".[dev]"
pytest
```

## Status

This is an early release extracted from a larger research codebase. The core API
is intentionally small and array-first. Research demos, plotting dashboards and
large experimental stands are not included in the package; they belong in
examples, papers or downstream integrations.

## License

MIT. Copyright (c) 2026 Dmitry Serikoff (dimaq12).

The license is permissive: use, copy, modify, merge, publish, distribute,
sublicense and sell are allowed. The copyright notice and permission notice
must be preserved in substantial copies of the software.
