NEBULA3D

NEBULA3D (Neutron Elastic Background Utility for Local Analysis and 3D-ΔPDF) is a Python package and browser console that cleans 3D reciprocal-space diffuse-scattering volumes, neutron or X-ray, into real-space 3D-ΔPDF maps, with an AI agent that assesses and tunes the reduction with you.

Try it in the browser: https://drthyang.github.io/nebula3d/ runs the whole pipeline client-side; nothing is uploaded.

NEBULA Pilot on the built-in synthetic demo volume (simulated data, not measured), with a local model. A time-lapse: the waits for the model are sped up.

What it does

• The reduction, stage by stage: powder-ring removal, Bragg and satellite punch, backfill, radial background correction (the flatten stage), the 3D-ΔPDF transform and a back-FFT consistency check (the pipeline).
• Aware of the crystal: the stages keep the symmetry the input declares, non-orthogonal cells are fine, and the UB can be checked and refined from where the Bragg peaks sit.
• Powder rings told from diffuse: a shell is subtracted only if it rises in nearly every direction in 3D, so the crystal's own diffuse stays (powder rings).
• One console, two run modes: the static web app runs the pipeline in your browser; nebula3d-web serves the same console natively, with no size limit.
• Mantid files in and out: it loads NeXus Viewer and Mantid exports, and writes volumes that Mantid's LoadMD opens.

Quick start

Open https://drthyang.github.io/nebula3d/, load the built-in demo volume (Use demo) or your own .nxs/.h5, and press Run pipeline.

To run it natively, from a clone (Python 3.10+ and Node.js):

pip install -e ".[web]"
make web-install && make ui     # build the console once
nebula3d-web                    # serves http://127.0.0.1:8000

More, including the batch scripts: QUICKSTART.md.

NEBULA Pilot

An agent docked beside every page. Connect a local model (Ollama, LM Studio) or a cloud one (OpenAI, Gemini, Anthropic): it measures cuts, judges each stage, runs and tunes the pipeline, and shows you the figures it reads. Every number comes from deterministic metrics, and each answer is checked against the tools' results before you read it. Its tools, guardrails and evals: docs/pilot.md.

Status

Beta: the latest release is 0.3.0, and main carries the 0.4.0 work (CHANGELOG.md). CI runs the Python tests on 3.10–3.13 with ruff and mypy, and the console's tests and builds, including replays of the agent's evals (docs/development.md).

Documentation

• Quickstart: run the console, in the browser or natively.
• The console: its views, run modes and architecture.
• NEBULA Pilot: the agent's tools, guardrails and evals.
• Running the pipeline: input data, the scripts, each stage, the Python API; also command recipes.
• Algorithms: powder rings, Bragg cleanup, 3D-ΔPDF, UB refinement.
• Development: install from source, checks, CI.
• All documentation · Changelog

License and provenance

Copyright (C) 2026 Tsung-han Yang.

This project is licensed under the GNU Affero General Public License v3.0 or later.

This is an independent personal software project. It is not affiliated with, sponsored by, endorsed by, funded by, developed for, or owned by any employer, institution, laboratory, university, government agency, funding organization, facility, or other organization.

Commercial, closed-source, proprietary, or alternative licensing may be available only by separate written permission from the copyright holder.

See PROVENANCE.md for the project provenance statement.