API — nefi.diagnostics¶
Generated by scripts/gen_api_docs.py — do not edit by hand. Index
nefi.diagnostics¶
Ill-posedness and optimization-geometry diagnostics.
nefi.diagnostics.filtering¶
The filtering view of a parameterized update (NeTMY §4.4, Lemma 2, App. D.6).
class RealizedUpdate(delta: torch.Tensor, raw_grad: torch.Tensor, delta_ratio: float, grad_ratio: float, damping: float, alignment: float, optimizer: str, lr: float, progress: f...¶
Realized first-step field update vs the raw field-space gradient (NeTMY App. E.5).
to_dict(self) -> dict[str, Any]
def effective_bandwidth(field: torch.nn.Module, progress: float = 1.0) -> float | None¶
Effective bandwidth B_β of the field's annealed encoding (NeTMY Eq. 36–37).
def filter_kernel_row(problem: Any, pixel: int | Sequence[int] | str = 'center', shape: Sequence[int] | None = None, *, field: str | None = None, progress: float = 1.0, module: t...¶
One row of the parameterization filter G_θ = J_θ J_θᵀ (NeTMY Lemma 2, Eq. 32–34).
def kernel_spread(row: torch.Tensor, level: float = 0.5, pixel: int | Sequence[int] | str | None = None, connected: bool = True) -> float¶
Width of a filter-kernel row G_θ e_i in pixels (half-maximum width of its main lobe).
def realized_update(problem: Any, curriculum_stage: Stage | int | None = None, *, shape: Sequence[int] | None = None, optimizer: str | None = None, lr: float | None = None, pro...¶
|Δx| after one optimizer step vs the raw gradient |∇_x L| (NeTMY App. E.5, Fig. 10).
nefi.diagnostics.landscape¶
Loss-landscape diagnostics in field space (what a free-pixel solver sees).
class EnergyBarrier(t: torch.Tensor, loss: torch.Tensor, components: dict[str, torch.Tensor] = <factory>, height: float = 0.0, t_max: float = 0.0, monotone: bool = True)¶
Loss profile along x(t) = (1 − t) x_a + t x_b (NeTMY Fig. 4b).
to_dict(self) -> dict[str, Any]
class Iter0Gradient(grad: torch.Tensor, grads: dict[str, torch.Tensor], ratio: float, peak_index: tuple[int, ...], peak_radius: float, center_mass: float, field: str, init: str...¶
The field-space gradient at initialization and its center-bias signature (NeTMY (P2)).
to_dict(self) -> dict[str, Any]
def ansatz_objective(problem: Any, ansatz: Callable[[torch.Tensor, torch.Tensor], Any], *, shape: Sequence[int] | None = None, terms: Any = None, progress: float = 1.0, physical...¶
The problem's loss as a differentiable function of a low-dimensional ansatz.
def center_mass_ratio(x: torch.Tensor, radius_fraction: float = 0.15, axes: Sequence[int] | None = None) -> float¶
Fraction of the total mass Σ|x| inside a central disk (NeTMY Fig. 4c).
def energy_barrier(problem: Any, fields_a: Any, fields_b: Any, n: int = 21, *, shape: Sequence[int] | None = None, terms: Any = None, progress: float = 1.0, rtol: float = 1e-0...¶
Losses along the straight line between two field states (NeTMY Fig. 4b).
def field_gradient(problem: Any, fields: Any = None, shape: Sequence[int] | None = None, *, progress: float = 1.0, terms: Any = None, stage: Any = None) -> dict[str, torch.Ten...¶
Raw field-space gradient ∇_x L at given field values.
def interpolate_fields(a: Fields, b: Fields, t: float) -> Fields¶
(1 − t) a + t b for the fields present in both (others taken from a).
def iter0_gradient(problem: Any, init: str = 'uniform', *, shape: Sequence[int] | None = None, value: float | Mapping[str, float] | None = None, field: str | None = None, term...¶
Field-space gradient at initialization plus its center/outer ratio (NeTMY (P2)+(P3)).
def uniform_center_mass(shape: Sequence[int], radius_fraction: float = 0.15, axes: Sequence[int] | None = None) -> float¶
:func:center_mass_ratio of a spatially uniform field (the no-bias baseline).
def uniform_fields(problem: Any, shape: Sequence[int] | None = None, value: float | Mapping[str, float] | None = None, progress: float = 0.0) -> Fields¶
Spatially constant fields, by default at the mean of the current (iteration-0) values.
nefi.diagnostics.plots¶
Plot helpers for diagnostics and results (matplotlib is optional).
def new_figure(nrows: int = 1, ncols: int = 1, figsize: tuple[float, float] | None = None)¶
A pyplot-free figure and its axes array (squeeze=False).
def plot_energy_barrier(barriers: Any, ax=None, title: str = 'loss along x(t)')¶
Loss profile(s) along the interpolation path (NeTMY Fig. 4b).
def plot_filter_kernels(rows: Mapping[str, torch.Tensor] | torch.Tensor, ax=None, normalize: bool = True, title: str = 'filter-kernel rows G_θ e_i')¶
Overlay 1-D filter-kernel rows (or show one 2-D row) — NeTMY Lemma 2.
def plot_history(history: Any, ax=None, keys: Sequence[str] | None = None, logy: bool = True, title: str = 'loss history')¶
Loss curves from Result.history (or a Result) with stage boundaries.
def plot_report(report: Any)¶
Multi-panel figure for a :class:~nefi.diagnostics.DiagnosticsReport.
def plot_result(result: Any, gt: Mapping[str, torch.Tensor] | None = None, measurement: Any = None)¶
Overview figure: every field (vs ground truth), prediction vs measurement, loss history.
def plot_sensitivity(sens: torch.Tensor, ax=None, title: str = 'sensitivity ‖∂F/∂x_i‖')¶
Sensitivity map (Jacobian column norms, NeTMY Eq. 23).
def plot_singular_values(sv: Any, ax=None, title: str = 'singular values of dF/dx')¶
Semilog plot of singular-value decay (NeFTY Prop. 2).
def save_figure(fig: Any, path: str | Path, dpi: int = 120) -> Path¶
Save a figure (creating parent directories) and return the path.
def show_field(t: Any, ax=None, title: str | None = None, cmap: str = 'viridis', **plot_kw)¶
Draw a field-shaped tensor: line (1-D), image with colorbar (2-D), mid-slice (3-D).
nefi.diagnostics.report¶
Diagnostic reports: the data-fit paradox check and a one-call :func:diagnose bundle.
class DiagnosticsReport(name: str, field: str, shape: tuple[int, ...], sensitivity: torch.Tensor | None = None, sensitivity_ratio: float | None = None, iter0: Iter0Gradient | None ...¶
Bundle of ill-posedness / optimization-geometry diagnostics for one problem.
save(self, directory: str | Path) -> dict[str, Path]— Writediagnostics.md,diagnostics.jsonanddiagnostics_tensors.pt.summary(self) -> dict[str, Any]— Flat dict of the scalar findings.to_dict(self) -> dict[str, Any]— JSON-serializable dict (scalars, small lists, timings, errors).to_markdown(self) -> str— Markdown report: findings table with the paper reference numbers and readings.
def data_fit_paradox(result: Any, problem: Any, gt: Mapping[str, torch.Tensor] | torch.Tensor | None = None, field_metrics: Mapping[str, Callable] | Sequence[str] | None = None,...¶
Measurement-space fit next to field-space accuracy (NeFTY §5.2, App. G.2, Tab. 7).
def diagnose(problem: Any, gt: Mapping[str, torch.Tensor] | torch.Tensor | None = None, result: Any = None, *, shape: Sequence[int] | None = None, include: Sequence[str]...¶
Run the cheap diagnostics on a problem and bundle them into a :class:DiagnosticsReport.
nefi.diagnostics.sensitivity¶
Forward sensitivity: per-pixel Jacobian column norms of the operator (NeTMY Eq. 23, (P2)).
def center_to_outer_ratio(x: torch.Tensor, center_radius: float = 0.2, ring: tuple[float, float] = (0.8, 1.0), axes: Sequence[int] | None = None) -> float¶
Ratio of the mean magnitude in a central disk to the mean magnitude in an outer ring.
def sensitivity_map(problem: Any, field: str | None = None, shape: Sequence[int] | None = None, n_probes: int = 32, exact: bool = False, *, fields: Any = None, progress: float ...¶
Per-pixel Jacobian column norms ‖∂F/∂x_i‖ of the operator (NeTMY Eq. 23).
nefi.diagnostics.spectrum¶
Spectral diagnostics: singular values of the linearized operator and Hessian conditioning.
def hessian_condition_number(fn: Callable[[torch.Tensor], torch.Tensor], params: Any) -> float¶
Condition number |λ|_max / |λ|_min of the Hessian of a scalar function (NeTMY Fig. 5).
def hessian_spectrum(fn: Callable[[torch.Tensor], torch.Tensor], params: Any) -> tuple[torch.Tensor, torch.Tensor]¶
Eigenvalues (ascending) and the symmetrized Hessian of fn at params.
def lanczos_eigs(matvec: Callable[[torch.Tensor], torch.Tensor], v0: torch.Tensor, k: int, n_iter: int, return_vectors: bool = False) -> tuple[torch.Tensor, torch.Tensor | N...¶
Largest eigenvalues of a symmetric PSD operator by Lanczos with full reorthogonalization.
def singular_values(problem: Any, k: int = 10, n_iter: int = 30, shape: Sequence[int] | None = None, *, field: str | None = None, fields: Any = None, progress: float = 1.0, use...¶
Top-k singular values of the linearized forward operator dF/dx (NeFTY Prop. 2).