Examples#
Independent, executable examples in the Sphinx-Gallery format: a leading reStructuredText description, executable Python, and commented narrative sections. They run on a CPU without reference-data downloads or EMsoft, and are grouped by the de-ebsd layer they exercise – simulation builds master patterns from a crystal, indexing matches measured patterns back to orientations.
The small direction grids, electron counts and scans keep the examples practical to execute; they are teaching settings, not evidence of converged experimental accuracy. Each example selects its backend explicitly.
Run a script from the repository root:
uv run python examples/simulation/cif_to_detector.py
Build the gallery (including downloadable notebooks):
uv sync --group docs --group notebook
uv run python -m sphinx -b html -W --keep-going docs docs/_build/html
Open docs/_build/html/index.html to view the results. In a plain Python
process, figures are constructed but no browser is opened automatically.
Use the generated notebook or gallery to interact with the plots, or call
figure.save_html("my_figure.html") on a figure returned by .show().
Sphinx-Gallery captures the final expression in each code block through the
figure’s _repr_html_ method. In Jupyter, that same expression displays the
native anyplotlib widget. Camera controls work in exported HTML; Python
callbacks and editable setup widgets require a running notebook kernel.
The standalone cif_to_master_pattern.ipynb notebook covers the same ground
as the CIF example in notebook form. Download Si.cif beside a downloaded CIF
example notebook, or run it from the repository root. CIF lengths are in
angstroms; de-ebsd converts them to nanometres.
Master-pattern simulation#
The forward chain: crystal -> structure factors -> reflections -> Bloch-wave dynamical solve -> master pattern -> detector projection, with every intermediate object inspectable. Start with the CIF-to-detector workflow, then explore energy-resolved Monte Carlo statistics and numerical convergence.
compare_emsoft.py compares against kikuchipy’s bundled nickel reference
using its stored crystal, Bethe settings, reflection cutoff and Monte Carlo
depth profile. It reports correlations and normalized residuals for both
hemispheres and a detector projection, and displays both 3D spheres. The
reference is 8-bit, so the example does not claim bitwise intensity parity.
An unquantized local EMsoft file can be selected by editing reference_path.
From a CIF to a dynamical master pattern and detector images
Native Monte Carlo and energy-resolved EBSD simulation
Orientation indexing#
The inverse problem: recover the orientation that produced a measured pattern. Both examples index a synthetic two-grain scan projected from a de-ebsd master pattern, so the answer is known and the error can be quoted – a closed round trip that validates the conventions and the workflow, not experimental accuracy.
dictionary_indexing.py is the brute-force baseline: project the master at
every orientation of a fundamental-zone sample and take the best normalized
cross-correlation. spherical_indexing.py replaces that library with a
spherical-harmonic cross-correlation over all of SO(3), whose cost does not
depend on the crystal symmetry. Both end in gradient refinement, which is what
takes a coarse grid hit to sub-degree accuracy.
Dictionary indexing: a synthetic scan, indexed and refined
Spherical indexing: cross-correlation over all of SO(3)