Skip to content

DRAFT: Diffraction model with intragranular misorientation #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MACarlsen wants to merge 12 commits into
base: main
Choose a base branch
from
Open

DRAFT: Diffraction model with intragranular misorientation #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
537f235
Add files via upload
MACarlsen May 12, 2026
c146b78
Update README.rst
MACarlsen May 12, 2026
5a7cd07
getting comfortable
MACarlsen May 14, 2026
27135c6
used xfab wrong
MACarlsen May 14, 2026
e75db8a
polefigures completed
MACarlsen May 14, 2026
2495d87
almost done with detector splatting
MACarlsen May 14, 2026
78b9ad9
first working version of detector-space splatting
MACarlsen May 14, 2026
f723098
tested normalization and sense-of-rotation
MACarlsen May 15, 2026
7750f86
exception for no cif file
MACarlsen May 15, 2026
33fc3cb
doctrings and moving functions
MACarlsen May 16, 2026
c692df0
hotfix
MACarlsen May 16, 2026
c0aabd0
xfab uses warren's upper triangular B matrices...
MACarlsen May 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
300 changes: 2 additions & 298 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,299 +1,3 @@
.. image:: https://github.com/FABLE-3DXRD/xrd_simulator/blob/main/docs/source/images/logo.png?raw=true
.. image:: https://github.com/MACarlsen/xrd_simulator_gs/blob/main/docs/_static/gaussian_splatting_diffraction_patterns.png

.. image:: https://img.shields.io/pypi/pyversions/xrd-simulator.svg?
:target: https://pypi.org/project/xrd-simulator/

.. image:: https://github.com/FABLE-3DXRD/xrd_simulator/actions/workflows/python-package-run-tests-linux-py313.yml/badge.svg?
:target: https://github.com/FABLE-3DXRD/xrd_simulator/actions/workflows/python-package-run-tests-linux-py313.yml/badge.svg

.. image:: https://github.com/FABLE-3DXRD/xrd_simulator/actions/workflows/pages/pages-build-deployment/badge.svg?
:target: https://github.com/FABLE-3DXRD/xrd_simulator/actions/workflows/pages/pages-build-deployment/

.. image:: https://badge.fury.io/py/xrd-simulator.svg?
:target: https://pypi.org/project/xrd-simulator/

.. image:: https://anaconda.org/conda-forge/vsc-install/badges/platforms.svg?
:target: https://anaconda.org/conda-forge/xrd_simulator/

.. image:: https://anaconda.org/conda-forge/xrd_simulator/badges/latest_release_relative_date.svg?
:target: https://anaconda.org/conda-forge/xrd_simulator/

===================================================================================================
Simulate X-ray Diffraction from Polycrystals in 3D.
===================================================================================================
.. image:: https://img.shields.io/badge/stability-alpha-f4d03f.svg?
:target: https://github.com/FABLE-3DXRD/xrd_simulator/


The **X**-**R** ay **D** iffraction **SIMULATOR** package defines polycrystals as a mesh of tetrahedral single crystals
and simulates diffraction as collected by a 2D discretized detector array while the sample is rocked
around an arbitrary rotation axis. The full journal paper associated to the release of this code can be found here:

*xrd_simulator: 3D X-ray diffraction simulation software supporting 3D polycrystalline microstructure morphology descriptions
Henningsson, A. & Hall, S. A. (2023). J. Appl. Cryst. 56, 282-292.*
`https://doi.org/10.1107/S1600576722011001`_

``xrd_simulator`` was originally developed with the hope to answer questions about measurement optimization in
scanning x-ray diffraction experiments. However, ``xrd_simulator`` can simulate a wide range of experimental
diffraction setups. The essential idea is that the sample and beam topology can be arbitrarily specified,
and their interaction simulated as the sample is rocked. This means that standard "non-powder" experiments
such as `scanning-3dxrd`_ and full-field `3dxrd`_ (or HEDM if you like) can be simulated as well as more advanced
measurement sequences such as helical scans for instance. It is also possible to simulate `powder like`_
scenarios using orientation density functions as input.

===================================================================================================
Introduction
===================================================================================================
Before reading all the boring documentation (`which is hosted here`_) let's dive into some end to end
examples to get us started on a good flavour.

The ``xrd_simulator`` is built around four python objects which reflect a diffraction experiment:

* A **beam** of x-rays (using the ``xrd_simulator.beam`` module)
* A 2D area **detector** (using the ``xrd_simulator.detector`` module)
* A 3D **polycrystal** sample (using the ``xrd_simulator.polycrystal`` module)
* A rigid body sample **motion** (using the ``xrd_simulator.motion`` module)

Once these objects are defined it is possible to let the **detector** collect scattering of the **polycrystal**
as the sample undergoes the prescribed rigid body **motion** while being illuminated by the xray **beam**.

Let's go ahead and build ourselves some x-rays:

.. code:: python

import numpy as np
from xrd_simulator.beam import Beam

# The beam of xrays is represented as a convex polyhedron
# We specify the vertices in a numpy array.
beam_vertices = np.array(
[
[-1e6, -500.0, -500.0],
[-1e6, 500.0, -500.0],
[-1e6, 500.0, 500.0],
[-1e6, -500.0, 500.0],
[1e6, -500.0, -500.0],
[1e6, 500.0, -500.0],
[1e6, 500.0, 500.0],
[1e6, -500.0, 500.0],
]
)

beam = Beam(
beam_vertices,
xray_propagation_direction=np.array([1.0, 0.0, 0.0]),
wavelength=0.28523,
polarization_vector=np.array([0.0, 1.0, 0.0]),
)

We will also need to define a detector:

.. code:: python

from xrd_simulator.detector import Detector

# The detector plane is defined by it's corner coordinates det_corner_0,det_corner_1,det_corner_2
detector = Detector(
det_corner_0=np.array([142938.3, -38400.0, -38400.0]),
det_corner_1=np.array([142938.3, 38400.0, -38400.0]),
det_corner_2=np.array([142938.3, -38400.0, 38400.0]),
pixel_size=(55.0, 55.0),
gaussian_sigma=1.0,
max_gaussian_kernel_radius=5,
)

Next we go ahead and produce a sample, to do this we need to first define a mesh that
describes the topology of the sample, in this example we make the sample shaped as a ball:

.. code:: python

from xrd_simulator.mesh import TetraMesh

# xrd_simulator supports several ways to generate a mesh, here we
# generate meshed solid sphere using a level set.
mesh = TetraMesh.generate_mesh_from_levelset(
level_set=lambda x: np.linalg.norm(x) - 768.0,
bounding_radius=769.0,
max_cell_circumradius=550.0,
)

Every element in the sample is composed of some material, or "phase", we define the present phases
in a list of ``xrd_simulator.phase.Phase`` objects, in this example only a single phase is present:

.. code:: python

from xrd_simulator.phase import Phase

quartz = Phase(
unit_cell=[4.926, 4.926, 5.4189, 90.0, 90.0, 120.0],
sgname="P3221", # (Quartz)
path_to_cif_file=None, # phases can be defined from crystalographic information files
)

The polycrystal sample can now be created. In this example the crystal elements have random orientations
and the strain is uniformly zero in the sample:

.. code:: python

from scipy.spatial.transform import Rotation as R
from xrd_simulator.polycrystal import Polycrystal

orientation = R.random(mesh.number_of_elements).as_matrix()
# element_phase_map assigns each mesh element to a phase (0 = first phase)
element_phase_map = np.zeros(mesh.number_of_elements, dtype=int)
polycrystal = Polycrystal(
mesh,
orientation,
strain=np.zeros((3, 3)),
phases=quartz,
element_phase_map=element_phase_map,
)

We may save the polycrystal to disc by using the builtin ``save()`` command as

.. code:: python

polycrystal.save('my_polycrystal', save_mesh_as_xdmf=True)

We can visualize the sample by loading the .xdmf file into your favorite 3D rendering program.
In `paraview`_ the sampled colored by one of its Euler angles looks like this:

.. image:: https://github.com/FABLE-3DXRD/xrd_simulator/blob/main/docs/source/images/example_polycrystal_readme.png?raw=true
:align: center

We can now define some motion of the sample over which to integrate the diffraction signal:

.. code:: python

from xrd_simulator.motion import RigidBodyMotion

motion = RigidBodyMotion(
rotation_axis=np.array([0, 1 / np.sqrt(2), -1 / np.sqrt(2)]),
rotation_angle=np.radians(0.1),
translation=np.array([123, -153.3, 3.42]),
)

Now that we have an experimental setup we may collect diffraction by letting the beam and detector
interact with the sample:

.. code:: python

peaks_dict = polycrystal.diffract(beam, motion, detector=detector)
diffraction_pattern, peaks_dict = detector.render(
peaks_dict, frames_to_render=0, method="micro"
)

The resulting rendered detector frame will look something like the below. Note that the positions of the diffraction spots may vary as the crystal orientations were randomly generated!:

.. code:: python

import matplotlib.pyplot as plt

fig, ax = plt.subplots(1, 1, figsize=(12, 12))
# render returns (frames, height, width), take first frame
pattern = (
diffraction_pattern[0].cpu().numpy()
if hasattr(diffraction_pattern, "cpu")
else diffraction_pattern[0]
)
ax.imshow(pattern, cmap="gray", vmax=5000)
plt.show()

.. image:: https://github.com/FABLE-3DXRD/xrd_simulator/blob/main/docs/source/images/diffraction_pattern.png?raw=true
:align: center
:width: 95%

To compute several frames simply change the motion and collect the diffraction again. The sample may be moved before
each computation using the same or another motion.

.. code:: python

polycrystal.transform(motion, time=1.0)
peaks_dict = polycrystal.diffract(beam, motion, detector=detector)

Many more options for experimental setups and intensity rendering exist, have fun experimenting!
The above example code can be found as a `single .py file here.`_

======================================
Installation
======================================

Anaconda installation (Linux and Macos)
=============================================
``xrd_simulator`` is distributed on the `conda-forge channel`_ and the preferred way to install
the xrd_simulator package is via `Anaconda`_::

conda install -c conda-forge xrd_simulator
conda create -n xrd_simulator
conda activate xrd_simulator

This is meant to work across OS-systems and requires an `Anaconda`_ installation.

(The conda-forge feedstock of ``xrd_simulator`` `can be found here.`_)

Anaconda installation (Windows)
======================================
``xrd_simulator`` can be installed on Windows via Anaconda. The package now uses `meshpy`_ which provides
better cross-platform support than the previous pygalmesh dependency.

Pip Installation
======================================
Pip installation is possible. The package uses `meshpy`_ which generally installs cleanly via pip::

pip install xrd-simulator

Source installation
===============================
Naturally one may also install from the sources::

git clone https://github.com/FABLE-3DXRD/xrd_simulator.git
cd xrd_simulator
python setup.py install

This will use `meshpy`_ which generally has better cross-platform support than pygalmesh.

Credits
===============================
``xrd_simulator`` makes good use of xfab and meshpy for tetrahedral mesh generation.
The source code of related repos can be found here:

* `https://github.com/FABLE-3DXRD/xfab`_
* `meshpy`_

Citation
===============================
If you feel that ``xrd_simulator`` was helpful in your research we would love for you to cite us.

*xrd_simulator: 3D X-ray diffraction simulation software supporting 3D polycrystalline microstructure morphology descriptions
Henningsson, A. & Hall, S. A. (2023). J. Appl. Cryst. 56, 282-292.*
`https://doi.org/10.1107/S1600576722011001`_

.. _https://doi.org/10.1107/S1600576722011001: https://doi.org/10.1107/S1600576722011001

.. _https://github.com/FABLE-3DXRD/xfab: https://github.com/FABLE-3DXRD/xfab

.. _https://github.com/marmakoide/miniball: https://github.com/marmakoide/miniball

.. _Anaconda: https://www.anaconda.com/products/individual

.. _meshpy: https://github.com/inducer/meshpy

.. _https://github.com/inducer/meshpy: https://github.com/inducer/meshpy

.. _scanning-3dxrd: https://doi.org/10.1107/S1600576720001016

.. _3dxrd: https://en.wikipedia.org/wiki/3DXRD

.. _powder like: https://en.wikipedia.org/wiki/Powder_diffraction

.. _which is hosted here: https://FABLE-3DXRD.github.io/xrd_simulator/

.. _which is hosted here: https://FABLE-3DXRD.github.io/xrd_simulator/

.. _single .py file here.: https://github.com/FABLE-3DXRD/xrd_simulator/blob/main/docs/source/examples/readme_tutorial.py

.. _paraview: https://www.paraview.org/

.. _can be found here.: https://github.com/conda-forge/xrd_simulator-feedstock

.. _conda-forge channel: https://anaconda.org/conda-forge/xrd_simulator
The future is now!
Binary file added docs/_static/gaussian_splatting_diffraction_patterns.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
67 changes: 67 additions & 0 deletions xrd_simulator/detector.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
import numpy as np
import numpy.typing as npt
import torch
from torch import Tensor
import torch.nn.functional as F
from scipy.special import j1

Expand Down Expand Up @@ -176,6 +177,8 @@ def __init__(
self.lorentz_factor = use_lorentz
self.polarization_factor = use_polarization
self.structure_factor = use_structure_factor
self.shape = self.pixel_coordinates.shape[:2]


def save(self, path: str) -> None:
"""Save detector to disk.
Expand Down Expand Up @@ -397,6 +400,70 @@ def contains(self, zd: torch.Tensor, yd: torch.Tensor) -> torch.Tensor:
"""
return (zd >= 0) & (zd <= self.zmax) & (yd >= 0) & (yd <= self.ymax)


def render_gaussian_splats(
self,
uv_corrds: Tensor,
scale_factors: Tensor,
concentration_tensors: Tensor,
patch_size: int = 16,
splat_max_size: float = 50.0 # Todo, come pu with good rule here.
# d times max misorientation + max grainsize
):
""" Basic 2D Gaussian rasterizer. Each gaussian has the expression:

.. math:: f = s \exp(-[u-u_0, v-v_0] S [u-u_0, v-v_0]^T).

Parameters
----------
uv_corrds : Tensor
Centroid pixel coordinates, shape ``(N, 2)``
scale_factors : Tensor
Intensity scale factors, shape ``(N,)``
concentration_tensors : Tensor
Shape concentration tensors, shape ``(N, 2, 2)``
patch_size : int
For evaluation the detector is split into patches of shize `patch_size` by `patch_size`.
splat_max_size : float
Maximum size of a gaussian splat.

Returns
-------
detector_image : Tensor
Detector image, shape ``self.shape``.
"""

shape = self.shape
u, v = torch.meshgrid(torch.arange(shape[0]), torch.arange(shape[1]))
f = torch.zeros(shape)

patch_size = 16
n_patches_dim1 = (shape[0]-1)//patch_size+1
n_patches_dim2 = (shape[1]-1)//patch_size+1

for patch_index_1 in range(n_patches_dim1):
for patch_index_2 in range(n_patches_dim2):

patch_slice = (slice(patch_size*patch_index_1, patch_size*(patch_index_1+1)),
slice(patch_size*patch_index_2, patch_size*(patch_index_2+1)),)

patch_mean_u = patch_size*(patch_index_1+0.5)
patch_mean_v = patch_size*(patch_index_2+0.5)

include_index = (uv_corrds[:, 0]-patch_mean_u)**2 + (uv_corrds[:, 1]-patch_mean_v)**2 < splat_max_size**2
if not torch.any(include_index):
continue


local_coords = torch.stack([u[patch_slice][None, :, :] - uv_corrds[include_index, 0, None, None],
v[patch_slice][None, :, :] - uv_corrds[include_index, 1, None, None],
], axis=1)

f[patch_slice] += torch.sum(scale_factors[include_index, None, None]\
* torch.exp(- torch.einsum('xiuv,xij,xjuv->xuv' ,local_coords, concentration_tensors[include_index, :, :], local_coords)), axis=0)

return f

# ------------------------------------------------------------------
# 3. Geometry & coordinate helpers
# ------------------------------------------------------------------
Expand Down
Loading
Loading