nefi 0.1.2

Neural-Field Inversion recovers hidden physical fields from a single measurement and a differentiable model of the instrument.
The physics is enforced exactly, a coordinate neural field represents the unknown, and no training data is needed.

Documentation · Get started · Gallery · Interactive 3-D · Papers

Why nefi

• The physics stays exact. Every candidate field passes through a differentiable model of your instrument, whether FFT optics, PDE solvers with exact adjoints, wave propagation or scattering, so the answer is always consistent with the physics rather than a soft penalty away from it.
• No training data. The unknown is optimized for the measurement at hand with a coarse-to-fine, frequency-annealed schedule. There is nothing to collect, nothing to amortize and nothing to go stale.
• It adapts itself. Noise level, budget, learning rate, regularization strength and even the representation can be chosen automatically, and gauge freedoms that the data cannot resolve are detected and fixed.
• The representation is the prior. Neural fields, grids, level sets, layered media and coordinate warps are interchangeable, and the library measures which one matches your operator.
• It tells you how far to trust the result. Noise-floor verdicts, ill-posedness diagnostics, a benchmark protocol with confidence intervals and an inverse-crime guard, and refinements that are refused when the data do not support them.

Quickstart

pip install nefi                             # torch, numpy, scipy, pyyaml, tqdm ("nefi[viz]": + matplotlib)
nefi run toy1d                               # generate → invert → evaluate → runs/toy1d-<hash>/
nefi bench toy1d --methods neural,grid --n 4 --seeds 0,1
nefi diagnose toy1d                          # sensitivity, iter-0 gradient, filter rows, spectrum

import nefi
from nefi.instances.toy1d import make_problem

problem, gt, meas = make_problem(n=128, seed=0)      # 1-D deblurring, seconds on a CPU
result = nefi.invert(problem)                        # neural field + annealed two-stage curriculum
print(nefi.metrics.psnr(result.fields["x"], gt["x"]))

Bring your own problem — any measurement process you can write in PyTorch, no subclassing:

import torch
import nefi

k = torch.tensor([1.0, 4.0, 6.0, 4.0, 1.0])
k = (k[:, None] * k[None]) / 256

def forward(x):                                   # your physics: a blurred, saturating camera
    blurred = torch.nn.functional.conv2d(x[None, None], k[None, None], padding=2)[0, 0]
    return torch.tanh(1.5 * blurred)

x_true = torch.zeros(64, 64); x_true[20:44, 16:40] = 1.0
y = forward(x_true) + 0.01 * torch.randn(64, 64)  # your data

problem = nefi.from_forward(forward, y, shape=(64, 64),
                            prior="nonnegative + piecewise_constant")   # what you know
result = nefi.invert(problem)
print(nefi.quick_report(result, problem, gt=x_true))   # did the fit reach the noise floor?

from_forward chooses the representation, initialization, noise level, loss weights, learning rate and curriculum; every decision is logged and overridable (guide).

Gallery

_{Twelve of the registered systems as ground truth · measurement · reconstruction, from one gallery run on a CPU. Browse the gallery →}

What's inside

Instances

The registered problems, each runnable end to end with nefi run <name> --smoke and documented on its own page.

Interactive 3-D

_{Ground truth · smooth · edge-refined, one camera, IoU and Dice computed in the browser — a self-contained HTML file written by nefi.viz.save_volume_viewer. Rotate it live →}

Reproducing the papers

configs/nv_relaxometry_paper.yaml and configs/thermal_tomography_paper.yaml hold the papers' settings table by table. The server runbook lists the exact commands for the headline tables, their GPU cost and the caveats to check first, and the paper → code map traces every equation to the code.

nefi bench configs/nv_relaxometry_paper.yaml --methods netmy,f1,grid,grid_f1 \
     --classes all --by-class --n 64 --seeds 0,1,2 --device cuda        # NeTMY Tab. 1
nefi run configs/thermal_tomography_paper.yaml --device cuda             # one NeFTY specimen

Development

git clone https://github.com/CAB-Lab-Princeton/NEFI.git && cd NEFI
pip install -e ".[dev]"      # + pytest, ruff, mypy, scikit-image, matplotlib, typer, rich
make test                    # fast CPU suite; make lint, make smoke

The latest development version installs with pip install git+https://github.com/CAB-Lab-Princeton/NEFI.git; see CONTRIBUTING.md.

Documentation

Get started · Tutorials · Guides · Gallery · Physics · Instances · Research · API · CLI · Contributing · Changelog

Every page is also readable as markdown under docs/.

Citation

If you use nefi, please cite the papers it implements:

@article{zhao2026netmy,
  title   = {Neural Fields for {NV}-Center Inverse Sensing},
  author  = {Zhao, Zhixuan and Zhong, Tao and Hu, Yixun and de Leon, Nathalie P. and
             Allen-Blanchette, Christine},
  journal = {arXiv preprint arXiv:2605.13988},
  year    = {2026}
}

@article{zhong2026nefty,
  title   = {Neural Field Thermal Tomography: A Differentiable Physics Framework for
             Non-Destructive Evaluation},
  author  = {Zhong, Tao and Hu, Yixun and Zheng, Dongzhe and Sood, Aditya and
             Allen-Blanchette, Christine},
  journal = {arXiv preprint arXiv:2603.11045},
  year    = {2026}
}

License

MIT © 2026 CAB Lab, Princeton University. See LICENSE.

Acknowledgements

nefi is developed and maintained by the CAB Lab at Princeton University. It grew out of the lab's series of papers on neural-field inversion, of which NeTMY and NeFTY are the first two, and we thank the authors of both.