diffBloch

Differentiable Bloch-wave structure refinement for 3D electron diffraction.

📖 Documentation: https://diffbloch.com/ — Usage guide and API reference.

Quickstart

Prerequisite: install uv and Git LFS for the bundled .cif_pets experimental data and plan-checkpoint .npz checkpoints, then sync the project environment from the repository root:

git lfs install
git lfs pull
uv sync --dev

Run CLI commands through uv run unless you have separately installed the diffbloch console script on your shell PATH.

# Run the optimizer and update trainable structural parameters:
uv run diffbloch run refine examples/Colmey_et_al_2026/data/quartz-no-abs

For Developers

We welcome collaborations and interested parties may contribute to the codebase.

Every merge to main re-runs the end to end (e2e) physics anchors. These correspond to rapid tests of the codebase's key functionalities and integration. Specifically, the measured mean R_obs for the example quartz refinement is expected to remain the same upon changes made to the directory. This Fig. tracks the result of this test upon every merge; the shaded band is the pinned tolerance. A flat line inside the band is the desired outcome, evidence the physics is reproducible commit over commit. Gaps are commits with no valid measurement (the committed checkpoint was stale for that commit's recipe, so the fast anchor could not score it).

Citation

If you use diffBloch in your research, please cite it as:

Doherty, T., Malik, S., Colmey, B., Maitland, I. & Midgley, P. (2026). diffBloch, version 0.2.0. https://github.com/Differentiable-Electron-Crystallography/diffBloch