Auto Preconditioner

Research toolkit for comparing classical and learned preconditioners for dense linear systems. The motivating application is the complex impedance system of a split-ring resonator (SRR) array.

What is included

• matrix families with controlled structure and conditioning;
• Jacobi, dense LU, circulant, and SVD preconditioners;
• GMRES, LGMRES, and BiCGSTAB adapters with consistent result records;
• reproducible benchmark orchestration through ExperimentSuite;
• ridge and CNN approximations of the inverse operator;
• two bundled SRR datasets with matrix sizes 36 and 450;
• held-out-frequency benchmarks and resonance-region analysis.

The CNN model predicts coefficients of a low-rank correction rather than a full inverse:

[ P(A) = P_{\mathrm{Jacobi}}(A) + \Delta_{\mathrm{CNN}}(A). ]

The correction basis is learned from training inverses with SVD. A final one-dimensional line search minimizes (\lVert P(A)A-I\rVert_F).

Installation

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[ml,dev]"

Python 3.11 or newer is required. PyTorch is optional unless CNNApprox is used.

Quick start

from preconditioner import ExperimentSuite

suite = ExperimentSuite()
result = suite.benchmark_sizes(
    sizes=(16, 32, 64),
    samples_per_size=3,
    matrix_families=("SPD", "Toeplitz"),
    preconditioners=("None", "Diagonal", "Circulant"),
    solvers=("GMRES",),
)

for row in result.summaries:
    print(row)

Run a small SRR benchmark:

python -m benchmarks.real_data \
  --dataset small \
  --frequency-count 12

Run the CNN demo with held-out frequencies:

python -m experiments.cnn_frequency_demo \
  --dataset large \
  --frequency-count 24 \
  --training-count 16 \
  --test-count 8

Generated CSV, JSON, plots, and checkpoints belong under artifacts/, which is ignored by Git.

Repository layout

preconditioner/
  core/       numerical primitives
  learning/   ridge and CNN inverse approximators
  real_data/  SRR loading and impedance construction
  research/   benchmark runner, plots, and ExperimentSuite
benchmarks/   command-line performance benchmarks
experiments/  reproducible research experiments
preconditioner/real_data/datasets/  bundled small and large SRR datasets
notebooks/    output-free walkthroughs
docs/         methodology and experiment notes
tests/        unit and integration tests

The arrays stored as params["freqs"] are angular frequencies (\omega) in rad/s, despite the historical key name.

Validation

ruff check preconditioner benchmarks experiments examples tests
pytest

See docs/cnn_frequency_demo.md, docs/real_data_benchmark.md, and docs/resonance_analysis.md for experiment details.