API — `nefi.autotune`¶

Generated by scripts/gen_api_docs.py — do not edit by hand. Index

`nefi.autotune`¶

Auto-tuning: detect and fix the common failure modes of a per-measurement inversion.

`nefi.autotune.acquisition`¶

Acquisition / identifiability report: what the measurement can and cannot determine.

`class AcquisitionReport(verdict: str, field: str, shape: tuple[int, ...], n_unknowns: int, n_data: int, data_ratio: float, sigma: float | None, sigma_source: str, amplitude: float ...`¶

Outcome of :func:acquisition_report (str(report) is the explanation).

flagged (property) — True unless the verdict is well-determined.
summary(self) -> str
to_dict(self) -> dict[str, Any]
to_markdown(self) -> str

`def acquisition_report(problem: Any, k: int = 8, *, field: str | None = None, n_probes: int = 16, n_iter: int | None = None, blocks: int = 8, rel_tol: float = 0.1, snr: float = 1....`¶

Classify how well the acquisition determines the unknown, and say what would help.

`nefi.autotune.convergence`¶

Fit-quality driven budget and learning rate: does the fit reach the noise floor, and when?

`class ConvergenceReport(status: str, sigma: float | None, sigma_source: str, probes: list[ProbeRecord], lr_probes: list[ProbeRecord], lr: float, base_lr: float, lr_range_pick: floa...`¶

Outcome of :func:probe_convergence.

chi (property) — Misfit of the largest probe.
fitted_field(self, steps: int | None = None, lr: float | None = None) -> Any — The fitted field of the probe with steps (default: the recommendation) and lr (default: the recommended rate), or None.
summary(self) -> str
to_dict(self) -> dict[str, Any]
to_markdown(self) -> str

`class ProbeRecord(steps: int, lr: float, chi: float | None, rmse: float, data_loss: float, seconds: float, kind: str = 'budget', field_change: float | None = None)`¶

One probe fit: budget, learning rate and the resulting misfit.

to_dict(self) -> dict[str, Any]

`def probe_convergence(problem: Any, *, steps: Sequence[int] = (50, 100, 200), extend: int = 3, max_probe_steps: int | None = None, sigma: float | None = None, curriculum: Curricu...`¶

Short probes with doubling budgets: at the noise floor, converging, or stalled?

`def tune_budget(problem: Any, report: ConvergenceReport | None = None, *, curriculum: Curriculum | None = None, tau: float | None = None, anneal_fraction: float | None = No...`¶

A curriculum with the budget, learning rate, annealing and stopping the probes call for.

`nefi.autotune.gauge`¶

Gauge / null-space detection and repair: transformations of the unknown the data cannot see.

`class DirectionPenalty(direction: Mapping[str, torch.Tensor], target: float = 0.0, scale: float = 1.0, name: str | None = None)`¶

Soft gauge fix along a custom direction: ((⟨x, v⟩ − c₀) / scale)².

coefficient(self, fields: Mapping[str, torch.Tensor]) -> torch.Tensor
forward(self, ctx: Context) -> torch.Tensor

`class Gauge(kind: str, field: str, name: str, invisibility: float, detected: bool, degree: float | None = None, handled_by: str | None = None, fix: str = 'none', note: ...`¶

One probed direction.

to_dict(self) -> dict[str, Any]
unresolved (property)

`class GaugeReport(gauges: list[Gauge], tol: float, probe: dict[str, Any] = <factory>, seconds: float = 0.0, evaluations: int = 0, repairs: list[str] = <factory>)`¶

Outcome of :func:detect_gauges (report.unresolved is what :func:repair_gauges fixes; report.repairs lists what it did).

detected (property)
summary(self) -> str — One line: what the data cannot see and what fixes it.
to_dict(self) -> dict[str, Any]
to_markdown(self) -> str
unresolved (property)

`class LeastSquaresScale(field: str | None = None, homogeneity: float = 1.0)`¶

Scale correction for signed data: α^p = ⟨y, ŷ⟩ / ⟨ŷ, ŷ⟩ over observed entries.

`class MeanAnchor(inner: Head, value: float = 0.0, region: torch.Tensor | None = None)`¶

x = inner(h) − mean_R(inner(h)) + value: fixes an invisible additive constant.

init_bias(self)
init_value (property)
inverse(self, value)
transform(self, raw, others, progress=1.0)

`class SignConvention(field: str | None = None, rule: str = 'max_abs_positive')`¶

Resolve an invisible global sign by a convention applied after the fit.

`def border_region(shape: Sequence[int], width: float = 0.1) -> torch.Tensor`¶

Boolean frame of max(1, round(width · n)) cells along every axis of shape.

`def detect_gauges(problem: Any, *, tol: float = 0.001, candidates: Mapping[str, Any] | None = None, fields: Sequence[str] | None = None, kinds: Sequence[str] = ('constant', '...`¶

Probe the forward model for invariances the data cannot resolve.

`def repair_gauges(problem: Any, report: GaugeReport, *, fixes: Sequence[str] | None = None, mean_prior: float | Mapping[str, float] | None = None, anchor: str | torch.Tensor ...`¶

Return a copy of problem with every unresolved gauge of report fixed.

`def strip_gauge_fixes(problem: Any, names: Sequence[str] | None = None) -> Any`¶

Copy of problem without mean-anchor heads (ZeroMean / :class:MeanAnchor).

`nefi.autotune.orchestrate`¶

One-call auto-tuning: noise → gauges → acquisition → budget / learning rate → regularization → (held-out search), every decision logged and reported.

`class AutotuneReport(problem: str, level: str, seed: int, sigma: float | None, sigma_source: str, decisions: list[Decision], gauges: GaugeReport | None, acquisition: Acquisition...`¶

Everything :func:autotune_problem measured and decided.

save(self, directory: str | Path) -> dict[str, Path] — Write autotune.json and autotune.md to directory.
summary(self) -> str — One paragraph: what was changed and why.
to_dict(self) -> dict[str, Any]
to_markdown(self) -> str

`def autotune_instance(instance: Any, seed: int = 0, level: str = 'standard', *, scene_class: str | None = None, curriculum: Curriculum | None = None, device: str = 'cpu', compare...`¶

Auto-tune a registered instance on one of its own measurements.

`def autotune_problem(problem: Any, *, level: str = 'standard', sigma: float | None = None, curriculum: Curriculum | None = None, problem_factory: Callable[..., Any] | None = Non...`¶

Detect and fix the common failure modes of a per-measurement inversion, in one call.

`def autotuned_method(level: str = 'quick', name: str | None = None, **autotune_kw: Any) -> Any`¶

A :class:~nefi.bench.protocol.Method that auto-tunes every measurement before solving.

`def compare_runs(instance: Any, gt: Mapping[str, Any], problem: Any, curriculum: Curriculum, tuned: Any, tuned_curriculum: Curriculum, seed: int = 0, device: str = 'cpu') ->...`¶

Solve the default and the tuned configuration; metrics, raw PSNR, steps, time, χ.

`def instance_factory(instance: Any, measurement: Any) -> Callable[..., Any]`¶

(**config_overrides) -> problem on a fixed measurement (fresh instance per call).

`nefi.autotune.regularization`¶

Regularization strength by the discrepancy principle (Morozov), with a GradNorm fallback.

`class RegularizationResult(weights: Mapping[str, float] | None = None, **attrs: Any)`¶

{term: tuned base weight} plus the evidence (a dict subclass).

apply(self, problem: Any, curriculum: Curriculum | None = None) -> tuple[Any, Curriculum] — (problem copy with the tuned base weights, curriculum with tuned overrides).
to_dict(self) -> dict[str, Any]
to_markdown(self) -> str

`def regularizer_names(problem: Any, curriculum: Curriculum | None = None) -> list[str]`¶

Non-data loss terms active in some stage (gauge penalties excluded).

`def tune_regularization(problem: Any, names: Sequence[str] | None = None, *, sigma: float | None = None, budget_scale: float = 0.2, tau: float = 1.0, mode: str = 'joint', curriculu...`¶

Regularization weights by the discrepancy principle: final RMSE ≈ τ·σ.

`nefi.autotune.search`¶

Held-out hyper-parameter search: let the measurement itself choose the configuration.

`class Dimension(name: str, kind: str, low: float | None = None, high: float | None = None, choices: tuple[Any, ...] | None = None, default: Any = None)`¶

One search dimension: kind ∈ "log", "linear", "int", "choice".

sample(self, u: float) -> Any — Map u ∈ [0, 1) to a value of the dimension.
to_dict(self) -> dict[str, Any]

`class Trial(index: int, params: dict[str, Any], score: float, val_mse: float | None, train_rmse: float | None, chi: float | None, steps: int, seconds: float, error: str...`¶

One evaluated configuration.

to_dict(self) -> dict[str, Any]

`class TuneReport(best: dict[str, Any], best_score: float, default_score: float, trials: list[Trial], space: dict[str, Dimension], objective: str, curriculum: Curriculum | No...`¶

Outcome of :func:autotune: best configuration, all trials, and its curriculum.

build(self, problem_factory: Callable[..., Any], curriculum: Curriculum | None = None) -> tuple[Any, Curriculum] — (problem, curriculum) of the best configuration (full budget).
improvement (property) — Relative objective improvement of the best trial over the default (trial 0).
table(self) -> str
to_dict(self) -> dict[str, Any]
to_markdown(self) -> str

`def apply_params(problem_factory: Callable[..., Any], params: Mapping[str, Any], curriculum: Curriculum | None = None) -> tuple[Any, Curriculum]`¶

Build (problem, curriculum) for one configuration.

`def as_dimension(name: str, spec: Any) -> Dimension`¶

Dimension from a spec: a :class:Dimension, ("log"|"linear"|"int", lo, hi), a list of choices, or a (lo, hi) pair (log-uniform when both are positive).

`def autotune(problem_factory: Callable[..., Any], *, space: Mapping[str, Any] | None = None, holdout: float = 0.1, budget_scale: float = 0.2, trials: int = 8, seed: int ...`¶

Held-out (or discrepancy) search over a small hyper-parameter space.

`def default_space(problem_factory: Callable[..., Any], problem: Any, curriculum: Curriculum | None = None) -> dict[str, Dimension]`¶

The default search space for a problem built by problem_factory().

API — nefi.autotune¶

nefi.autotune¶

nefi.autotune.acquisition¶

class AcquisitionReport(verdict: str, field: str, shape: tuple[int, ...], n_unknowns: int, n_data: int, data_ratio: float, sigma: float | None, sigma_source: str, amplitude: float ...¶

def acquisition_report(problem: Any, k: int = 8, *, field: str | None = None, n_probes: int = 16, n_iter: int | None = None, blocks: int = 8, rel_tol: float = 0.1, snr: float = 1....¶

nefi.autotune.convergence¶

class ConvergenceReport(status: str, sigma: float | None, sigma_source: str, probes: list[ProbeRecord], lr_probes: list[ProbeRecord], lr: float, base_lr: float, lr_range_pick: floa...¶

class ProbeRecord(steps: int, lr: float, chi: float | None, rmse: float, data_loss: float, seconds: float, kind: str = 'budget', field_change: float | None = None)¶

def probe_convergence(problem: Any, *, steps: Sequence[int] = (50, 100, 200), extend: int = 3, max_probe_steps: int | None = None, sigma: float | None = None, curriculum: Curricu...¶

def tune_budget(problem: Any, report: ConvergenceReport | None = None, *, curriculum: Curriculum | None = None, tau: float | None = None, anneal_fraction: float | None = No...¶

nefi.autotune.gauge¶

class DirectionPenalty(direction: Mapping[str, torch.Tensor], target: float = 0.0, scale: float = 1.0, name: str | None = None)¶

class Gauge(kind: str, field: str, name: str, invisibility: float, detected: bool, degree: float | None = None, handled_by: str | None = None, fix: str = 'none', note: ...¶

class GaugeReport(gauges: list[Gauge], tol: float, probe: dict[str, Any] = <factory>, seconds: float = 0.0, evaluations: int = 0, repairs: list[str] = <factory>)¶

class LeastSquaresScale(field: str | None = None, homogeneity: float = 1.0)¶

class MeanAnchor(inner: Head, value: float = 0.0, region: torch.Tensor | None = None)¶

class SignConvention(field: str | None = None, rule: str = 'max_abs_positive')¶

def border_region(shape: Sequence[int], width: float = 0.1) -> torch.Tensor¶

def detect_gauges(problem: Any, *, tol: float = 0.001, candidates: Mapping[str, Any] | None = None, fields: Sequence[str] | None = None, kinds: Sequence[str] = ('constant', '...¶

def repair_gauges(problem: Any, report: GaugeReport, *, fixes: Sequence[str] | None = None, mean_prior: float | Mapping[str, float] | None = None, anchor: str | torch.Tensor ...¶

def strip_gauge_fixes(problem: Any, names: Sequence[str] | None = None) -> Any¶

nefi.autotune.orchestrate¶

class AutotuneReport(problem: str, level: str, seed: int, sigma: float | None, sigma_source: str, decisions: list[Decision], gauges: GaugeReport | None, acquisition: Acquisition...¶

def autotune_instance(instance: Any, seed: int = 0, level: str = 'standard', *, scene_class: str | None = None, curriculum: Curriculum | None = None, device: str = 'cpu', compare...¶

def autotune_problem(problem: Any, *, level: str = 'standard', sigma: float | None = None, curriculum: Curriculum | None = None, problem_factory: Callable[..., Any] | None = Non...¶

def autotuned_method(level: str = 'quick', name: str | None = None, **autotune_kw: Any) -> Any¶

def compare_runs(instance: Any, gt: Mapping[str, Any], problem: Any, curriculum: Curriculum, tuned: Any, tuned_curriculum: Curriculum, seed: int = 0, device: str = 'cpu') ->...¶

def instance_factory(instance: Any, measurement: Any) -> Callable[..., Any]¶

nefi.autotune.regularization¶

class RegularizationResult(weights: Mapping[str, float] | None = None, **attrs: Any)¶

def regularizer_names(problem: Any, curriculum: Curriculum | None = None) -> list[str]¶

def tune_regularization(problem: Any, names: Sequence[str] | None = None, *, sigma: float | None = None, budget_scale: float = 0.2, tau: float = 1.0, mode: str = 'joint', curriculu...¶

nefi.autotune.search¶

class Dimension(name: str, kind: str, low: float | None = None, high: float | None = None, choices: tuple[Any, ...] | None = None, default: Any = None)¶

class Trial(index: int, params: dict[str, Any], score: float, val_mse: float | None, train_rmse: float | None, chi: float | None, steps: int, seconds: float, error: str...¶

class TuneReport(best: dict[str, Any], best_score: float, default_score: float, trials: list[Trial], space: dict[str, Dimension], objective: str, curriculum: Curriculum | No...¶

def apply_params(problem_factory: Callable[..., Any], params: Mapping[str, Any], curriculum: Curriculum | None = None) -> tuple[Any, Curriculum]¶

def as_dimension(name: str, spec: Any) -> Dimension¶

def autotune(problem_factory: Callable[..., Any], *, space: Mapping[str, Any] | None = None, holdout: float = 0.1, budget_scale: float = 0.2, trials: int = 8, seed: int ...¶

def default_space(problem_factory: Callable[..., Any], problem: Any, curriculum: Curriculum | None = None) -> dict[str, Dimension]¶