resolution-defect 0.1.0

Resolution-defect calculus for diagnosing, accelerating, and controlling numerical processes.

Resolution Defect

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

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:

pip install resolution-defect

From source:

git clone [e-mail]:dimaq12/resolution-defect.git
cd resolution-defect
pip install -e ".[dev]"

Quick Start

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

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:

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:

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:

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:

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

The estimator is:

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):

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:

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:

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:

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:

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:

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

Examples

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

Package Layout

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

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.