diffBloch¶

Coverage Python PyTorch NumPy Pydantic Ruff mypy License: MIT

Differentiable Bloch wave structure refinement for 3D electron diffraction.

This codebase is entirely open-source, and we welcome user contributions as well as questions.

Overview¶

diffBloch is a crystallographic refinement software for 3D ED. To perform a refinement both an initial structural model and experimental data are required. The initial unrefined atomic structure in the form of a ‘cif’ (crystallographic information file) can be obtained from previous experiments if the structure is known or via structure solution. Experimental data in the form of diffraction frames are collected while the crystal is tilted/rocked through reciprocal space and reduced upstream by one of PETS2 or DIALS, into the.cif_pets data format.

diffBloch performs the refinement as two complementary values: a crystal structure, consisting of atomic coordinates, occupancies and thermal displacement parameters, and a settled Plan, consisting of crystallographic metadata such as thickness or orientation. Together they feed the refinement engine, which runs a repeatable Bloch wave simulation, compares calculated and observed intensities, and iteratively minimizes the objective by updating selected trainable parameters. The guides below unpack that path from experiment inputs through preprocessing, refinement, reproducibility, observability, and runnable examples.

Guide	Contents
Workflow	Refinement pipeline from input files to refined structure.
Inputs and outputs	Files required for a refinement and files produced by diffBloch.
Hyperparameter selection	Simulation, preprocessing, and refinement hyperparameters and their defaults.
Convergence testing	Convergence of calculated intensities with respect to `g_max`, `sg_max`, and rocking-curve sampling.
Preprocessing	Crystal-orientation and thickness determination before structural refinement.
Bloch wave simulation	Theory and equations used to calculate dynamical diffraction intensities.
Refinement	Structural parameter optimization against experimental intensities.
Devices and scaling	CPU and GPU execution, memory controls, and refinement profiling.
Reproducibility	Records identifying the inputs and preprocessing used for a refinement.
Examples	Runnable experiments included with diffBloch.
Publications and references	Publications using diffBloch and the sources the codebase draws on.

Quickstart¶

Command line¶

The command-line interface (CLI) runs diffBloch from a terminal. This is the standard way to run a complete experiment.

uv installs the required Python packages and runs diffBloch inside the project environment. Git LFS downloads the larger experimental-data files stored in the repository.

From the repository directory:

git lfs install
git lfs pull
uv sync --dev

Each diffBloch command takes the path to an experiment directory containing experiment.yaml, the starting CIF, and the .cif_pets data:

uv run diffbloch refine <experiment_dir>

Citation¶

If diffBloch is used in research, please cite it as:

@misc{diffBloch,
  author  = {Doherty, Tiarnan and Malik, Shreshth and Colmey, Benjamin and Maitland, Iain, and Midgley, Paul},
  title   = {diffBloch},
  version = {0.2.0},
  year = {2026},
  url     = {https://github.com/Differentiable-Electron-Crystallography/diffBloch}
}

diffBloch¶

Overview¶

Quickstart¶

Command line¶

Citation¶

Subscribe¶