XRDplayground: a Python-based educational tool for interactive learning of powder X-ray diffraction crystallography

One of the barriers to learning crystallography through the powder X-ray diffraction (PXRD) technique is the understanding and visualization of the crystal structure and its effects on the diffraction pattern. To enhance learning through visualization, we present XRDplayground, an open-source software developed in Python that can simultaneously simulate the unit cell and its PXRD pattern. It features a graphical user interface where all the structural parameters of the crystal, such as lattice parameters and atomic positions inside the unit cell, are adjustable via sliders. The PXRD pattern is simulated by taking into consideration the X-ray energy and the crystallite size using Scherer's equation. XRDplayground is an educational tool to make PXRD crystallography more engaging and enhance learning and understanding of the concepts rather than mathematical treatment and/or superficial memorization.

1. Introduction

The powder X-ray diffraction (PXRD) technique is widely used to determine and understand the structure and symmetry of materials through both qualitative and quantitative analyses. These analyses involve interpreting a pattern on the basis of peak positions as a function of the scattering angle (2θ), peak intensities and peak profiles (Dinnebier & Billinge, 2008). Most of the time, beginners in this technique are only aware that the pattern is somehow related to the structure and symmetry of matter. Students often encounter difficulties in understanding the formal mathematical description of the Fourier transform and the abstract concept of reciprocal space, even for single crystals. Moreover, the peak overlapping in PXRD further complicates the understanding of these concepts. This overlapping makes PXRD somewhat less tangible than single-crystal X-ray diffraction, which always depends on a specific direction under diffraction conditions.

Over the years, many different strategies, methodologies and tools have been developed to teach crystallography and PXRD (Flor et al., 2024), some of them dedicated to high school students (Schimpf et al., 2023; Murray et al., 2024). These include strategies (Gražulis et al., 2015; Luft et al., 2010; Pett, 2010), benchtop single-crystal X-ray diffractometers (Giorgi & Berchadsky, 2022), historical overviews (Mascarenhas, 2020), symmetry and Bravais lattices (Graw & Stalke, 2022; Hanson, 2010; Nespolo & Souvignier, 2010), puzzles (Schimpf et al., 2023), motifs and lattices in a web-based tools (Bardella et al., 2017), online educational materials for PXRD crystallography (Toby, 2010; Kantardjieff, 2010), macromolecular crystallography (Faust et al., 2008, 2010), and a collection of scholarly scripts dealing with the mathematics and physics of peak profile functions and intensities in PXRD (Dinnebier & Scardi, 2021, 2023). A review of tools, website links and equipment that can be used when teaching crystallography can be found in the supplementary information of From geology to biology: an interdisciplinary course in crystal growth presented by Arkhipov et al. (2022). All these references are designed to perform specific tasks on specific platforms in specific areas of science.

XRDplayground, presented here, is an open-source software developed in Python, designed with a graphical user interface (GUI) to build and manipulate a unit cell and allow the observation of its PXRD pattern. As the visualization of the unit cell and its XRD pattern has become more prevalent and expected, XRDplayground serves as a valuable tool for educating beginners on the technique. The software capabilities extend beyond visualization, including sliders to control the lattice parameters, chemical composition, number of atoms and their respective positions (fractional coordinates x/a, y/b, z/c), crystallite size (using the isotropic Scherrer model), and the X-ray energy, the latter considering corrections due to anomalous scattering effects.

The Python programming language has been widely used in scientific programming and plotting. Usually, Python tools for PXRD are associated with data treatment, such as GSAS-II (Toby & Von Dreele, 2013, 2014; O'Donnell et al., 2018) and SrRietveld (Tian et al., 2013), or require reading crystal structures from CIFs, e.g. Dans_Diffraction (https://www.iucr.org/resources/other-directories/software/dans_diffraction). XRDplayground was created to teach PXRD in the multidisciplinary school Escola Ricardo Rodrigues de Luz Síncrotron (https://pages.cnpem.br/er2ls/) from the Brazilian Synchrotron Light Laboratory. The school has taken place every July since 2017 and is dedicated to Brazilian graduate and undergraduate students, post-docs, and young professionals. Students can come from any background (physics, chemistry, biology, soil, materials, environmental science and engineering). For such an audience, the main goal of XRDplayground is to show the different types of structures and the effect of the symmetry of the unit cell on PXRD without the necessity of an input file (users are free to build a fictitious or a real crystal model). It can be useful to the crystallographic community in teaching, education and training, enabling learners to interact and explore the possibilities of symmetries and their changes.

The software is introduced here, along with its boundary conditions and control parameters, which are accessible via sliders. We then present several concepts for discussion and teaching. These include multiplicity, lattice strain (macrostrain), lattice-type transformations for primitive (P), body-centered (I), one face-centered (A, B or C) and face-centered (F) lattices, and their consequences, such as systematic absences and resonant diffraction. Many of the ideas introduced here can be adapted to any class focused on the theme of PXRD.

2. Installation requirements

The software is open source and can be downloaded for free from the CNPEM Repository on GitHub (https://github.com/cnpem/XRDplayground/). It is distributed under the Apache 2.0 License, which permits users to modify and share as needed. It requires Python to be installed on the machine along with some additional libraries listed below. It is highly recommended to create a virtual environment (e.g. using Conda) to run it. The configuration shown below was tested and worked for both Linux (using the Micromamba package manager from https://github.com/mamba-org/mamba) and Windows (using the Miniconda package manager from https://repo.anaconda.com/miniconda/) machines. The libraries used were downloaded from the conda-forge repository (https://conda-forge.org/). The dependencies used are shown in Table 1. An installation tutorial for Windows is provided in the supplementary information.

Table 1
Latest tested dependencies necessary for running XRDplayground

Dependency	Version	Sites and references
Python	3.12.5	https://www.python.org/
Matplotlib	3.9.2	Hunter (2007)
NumPy	2.0.1	Harris et al. (2020)
xrayutilities	1.7.8	Kriegner et al. (2013)
PyQt	5.15.9	https://pypi.org/project/PyQt5/
qtawesome	1.3.1	https://pypi.org/project/QtAwesome/

3. Graphical user interface

A screenshot of the GUI is shown in Fig. 1. The interface is simple and does not require any special computing knowledge, allowing users to systematically explore the relationship between a real-space structure and the corresponding PXRD pattern. It is divided into four groups: (A) a graph that displays the PXRD pattern; (B) a 3D drawing of the unit cell; (C) a sliders and buttons to control lattice parameters, X-ray wavelength and crystal size; and (D) controls for the information concerning the position, type and number of atoms inside the unit cell.

Figure 1 Screenshot of XRDplayground. (A) Simulated XRD pattern (CsCl in black); (A1) freeze and unfreeze curves; (A2) show/hide hkl peaks. (B) Representation of the unit cell and (B1) show/hide elements of the unit cell. (C) Controls for (C1) lattice parameters, (C2) energy and (C3) crystallite size sliders. (D) Controls for (D1) atom type, (D2) adding and removing atoms, and (D3)–(D4) positioning atoms in the unit cell.

The controls for the diffraction pattern graph include zoom in and out; auto-scale; maximum intensity scale; and three options (red, blue and green) for freezing the pattern at the current slider and atom conditions, for chemical element, and for position. These buttons allow the user to compare different simulations. Another button allows loading of experimental data from a file (in the format 2θ versus intensity) for comparison with the simulation. For this purpose, controls for applying a scale factor to multiply the loaded data (or the frozen curves) are also available (A1). In the upper right corner (A2), there is a button that turns on and off an arrow showing the position of a peak in the diffraction pattern, chosen by its Miller indexes which, in turn, are controlled by the three edit boxes beside it. The on/off button also shows or hides the atomic planes corresponding to the Miller indexes in the 3D drawing of the unit cell (B). Parameters related to the extent of the simulation, such as the initial and final 2θ values, the 2θ step, and maximum h, k and l values for calculating the peaks, can be selected using the `settings' button, also located in the upper right corner (A2).

The controls for the 3D drawing of the unit cell (B1) include zoom in and out and three buttons that turn on and off the visualization of the unit cell faces, edges and atoms; the fourth button expands the visualization of the atoms to eight unit cells. Additionally, the projection of the unit cell can be rotated by clicking and dragging with the pointing device on the 3D drawing.

At the bottom left of the window (C1), there are controls for the six parameters related to the lattice: a, b, c, α (the angle between the b and c vectors), β (angle between the a and c vectors) and γ (angle between the a and b vectors). When these parameters are changed – which can be done using sliders or by entering values in the edit boxes – both the XRD pattern and the unit cell are updated according to the new values. At the bottom center, there is a control for the X-ray beam energy (C2) – and equivalently the beam wavelength – which also updates the diffraction pattern, considering the change in the atomic scattering factor due to absorption effects. The last control in this section is the crystallite size (C3), which uses the isotropic Scherrer formula to change the peak widths. All the sliders result in an interactive simulation of the cell and the XRD patterns.

At the bottom right (D), there is a control for the atoms within the unit cell. At the top left of this window, there is, by default, an initial atom in an input box (D1) that depends on the loaded initial structure. The atom type can be changed by editing the text in the box, as long as the text matches a chemical symbol. This atom is also, by default, placed at the fractional coordinate (x/a, y/b, z/c) = (0, 0, 0). The only controls for this atom are its color, which can be changed via the button next to its chemical symbol, and its size, which can be changed in the adjacent edit text box. At the top right of this window, there are two buttons that can add or remove atoms in the unit cell (D2). When an atom is added, a control box for it appears (D3) and, by default, the atom is placed at the center of the unit cell: fractional position (0.5, 0.5, 0.5). Each atom has controls for its own chemical symbol, unique color and fractional position, which can be changed using sliders or by entering a value into the respective edit box. After another atom has been added, their controls will be stacked up to three atoms, and additional atoms will be placed in another tab, accessible via the tab selection on the left (D4).

When the program is opened, it will randomly load the atom positions and lattice parameters of a real material taken from its pool of structures. There are, for now, 16 structures in this pool, which are listed in Appendix A. However, the user can change any of the parameters or add and remove atoms from the unit cell. Some initialization options can be changed from the default file created when running the program for the first time.

3.1. Example

As a proof of concept for the software, an example data plot with a reference structure and the simulated XRD pattern from XRDplayground is shown in Fig. 2. The reference is BaTiO₃ (PDF 04-002-3207), simulated in blue dots considering Cu Kα energy with a Caglioti function. The XRDplayground-simulated pattern is shown in black. A scale factor of 30 and particle size of 1000 Å were needed to achieve the agreement shown between the patterns. All structural and wavelength parameters used in XRDplayground are given in Table 2. Sufficient agreement from the whole pattern is observed. The peaks beyond 100° for 2θ are high-hkl peaks that were not included in the XRDplayground simulation.

Table 2
Simulated parameters used in XRDplayground to compare with BaTiO₃ (PDF 04-002-3207) shown in Fig. 2

Ba fractional coordinate	(0, 0, 0)
Ti fractional coordinate	(1/2, 1/2, 1/2)
O fractional coordinate	(1/2, 0, 0)
O fractional coordinate	(0, 1/2, 0)
O fractional coordinate	(0, 0, 1/2)
Energy	8.05 keV
Crystallite size	1000 Å
a = b	4.019 Å
c	3.985 Å
Scale factor	30

Figure 2 Plot of the simulated data from XRDplayground using the parameters from Table 2 and the BaTiO3 data (PDF 04-002-3207).

4. Limitations of the software

As an interactive learning tool, the main idea of XRDplayground is to provide users with a novel way to visualize the effect of each parameter on the final PXRD pattern. Complex structures with many atoms in the unit cell and very large lattice parameters are always interesting to visualize and, often, to compare with some experimental patterns. XRDplayground calculates the PXRD pattern including the peak position, full width at half-maximum and intensity of each peak on the basis of a general equation only with free parameters as in the triclinic lattice P1 with the atoms in site symmetry x, y, z. It can take a long time to calculate the scattering of crystals of very large lattice parameters up to high hkl indexes and update the diffraction pattern before the `callback' function of the slider is called again. In this sense, one of the main limitations is the ability to calculate all these intensities very quickly. To make the calculation faster, the maximum hkl indexes are limited, by default, to ±4, which allows for the calculation of more than 700 peaks. Additionally, there are limitations on the number of atoms in the unit cell; by default, the limit is set to ten atoms, also due to the time-consuming procedure of calculating the intensity of the peaks. Another limitation concerns the energy/wavelength sliders. Every time they are changed, each hkl peak must be checked to see if it lies within the 2θ range. Moreover, the atomic scattering factor must be recalculated for each 2θ value, delaying the update of the diffraction pattern. Another limiting factor is the 2θ range; high angles imply high hkl values, and sometimes peaks such as hkl = 500, which by default are not calculated, do not appear in the diffraction pattern, even when their 2θ value is within the range. If the user wants to include higher-hkl peaks in the calculation of the PXRD pattern, the maximum values of h, k and l can be changed using the settings button located at A2 (see Fig. 1). At any time, the user can search for the 2θ position of any hkl peak in the main graph – even for hkl peaks not calculated due to the maximum value of ±4 – which can help decide if the limiting value should be adjusted.

Finally, we did not include the possibility to change the atomic displacement of the atoms, which is related to atomic motion and possible static displacive disorder. In other words, for the calculations, we consider that each atom remains at its crystallographic site.

The default values of XRDplayground can be changed by editing the text file it creates the first time it is run or by changing the default values within the configuration buttons that are placed in the program. As the maximum hkl, 2θ range and number of atoms increases, and the 2θ step decreases, the update in the PXRD pattern becomes slower due to the number of calculations. This causes the program to lose its original purpose, which is to fluidly visualize the variations in the diffraction pattern with changes in the unit cell.

5. Conclusions

XPDplayground illustrates various aspects of the influence of the lattice on the XRD pattern, serving as a versatile tool with interactive graphics that can enhance discussions and the teaching of diffraction concepts. Further, students can observe firsthand how lattice parameters, chemical composition, crystallite size and X-ray wavelength are embodied and convoluted in the PXRD pattern. This direct observation significantly improves the likelihood of students retaining the concepts of structure and symmetry, as they witness these elements change in real time with the movement of sliders. Consequently, this tool facilitates the learning of symmetry effects on diffraction patterns, enabling students to grasp these concepts before evaluating whether the model is reasonable.

APPENDIX A

Pool of structures

In Table 3, we list the pool of structures from which one is picked by chance and loaded when the program starts.

Table 3
Material, crystalline structure, lattice parameters and atomic positions for the structures loaded in the program

Material	Crystal system	Lattice parameters a, b, c (Å)	Angles α, β, γ (°)	Atomic positions
LaB6	SC: PDF 04-004-8705	a = b = c = 4.155	α = β = γ = 90	La: (0, 0, 0)
				B: (0.1996, 1/2, 1/2), (1/2, 1/2, 0.8004), (1/2, 1/2, 0.1996), (1/2, 0.1996, 1/2), (1/2, 0.8004, 1/2), (0.8004, 1/2, 1/2)
Si	FCC	a = b = c = 5.43	α = β = γ = 90	Si: (0, 0, 0), (1/2, 1/2, 0), (0, 1/2, 1/2), (1/2, 0, 1/2), (1/4, 1/4, 1/4), (3/4, 3/4, 1/4), (3/4, 1/4, 3/4), (1/4, 3/4, 3/4)
Diamond	FCC	a = b = c = 5.63	α = β = γ = 90	C: (0, 0, 0), (1/2, 1/2, 0), (0, 1/2, 1/2), (1/2, 0, 1/2), (1/4, 1/4, 1/4), (3/4, 3/4, 1/4), (3/4, 1/4, 3/4), (1/4, 3/4, 3/4)
NaCl	FCC: PDF 04-002-1178	a = b = c = 5.64	α = β = γ = 90	Na: (0, 0, 0), (1/2, 1/2, 0), (0, 1/2, 1/2), (1/2, 0, 1/2)
				Cl: (1/2, 1/2, 1/2), (1/2, 0, 0), (0, 1/2, 0), (0, 0, 1/2)
CsCl	SC: PDF 04-007-8791	a = b = c = 4.11	α = β = γ = 90	Cs: (0, 0, 0)
				Cl: (1/2, 1/2, 1/2)
Cu	FCC: PDF 00-004-0836	a = b = c = 3.60	α = β = γ = 90	Cu: (0, 0, 0), (1/2, 1/2, 0), (0, 1/2, 1/2), (1/2, 0, 1/2)
α-Fe	BCC: PDF 00-006-0696	a = b = c = 2.87	α = β = γ = 90	Fe: (0, 0, 0), (1/2, 1/2, 1/2)
Rutile	Tetragonal: PDF 00-021-1276	a = b = 4.592, c = 2.957	α = β = γ = 90	Ti: (0, 0, 0), (1/2, 1/2, 1/2)
				O: (0.305, 0.305, 0), (0.695, 0.695, 0), (0.805, 0.895, 1/2), (0.195, 0.195, 1/2)
Zn	Hexagonal: PDF 01-090-3171	a = b = 2.66, c = 4.94	α = β = 90, γ = 120	Zn: (0, 0, 0), (1/3, 2/3, 1/2)
Mg	Hexagonal: PDF 00-035-0821	a = b = 3.21, c = 5.21	α = β = 90, γ = 120	Mg: (0, 0, 0), (1/3, 2/3, 1/2)
Graphite	Hexagonal: PDF 00-056-0159	a = b = 2.46, c = 6.71	α = β = 90, γ = 120	C: (0, 0, 0), (2/3, 1/3, 1/2), (0, 0, 1/2), (1/3, 2/3, 0)
Quartz	Hexagonal: PDF 00-046-1045	a = b = 4.914, c = 5.406	α = β = 90, γ = 120	Si: (0, 0, 0), (0.5277, 0.4723, 0.0004), (0.0554, 0.5277, 0.3334)
				O: (0.9437, 0.2658, 0.1215), (0.2619, 0.1502, 0.4549), (0.3775, 0.584, 0.4545), (0.7935, 0.416, 0.5453), (0.6779, 0.7342, 0.8783), (0.1117, 0.8498, 0.2119)
BaTiO3 cubic	Cubic: PDF 01-090-5787	a = b = c = 4.01	α = β = γ = 90	Ba: (0, 0, 0)
				Ti: (1/2, 1/2, 1/2)
				O: (1/2, 1/2, 0), (0, 1/2, 1/2), (1/2, 0, 1/2)
BaTiO3 tetragonal	Tetragonal: PDF 01-090-2462	a = b = 3.99, c = 4.03	α = β = γ = 90	Ba: (0, 0, 0)
				Ti: (1/2, 1/2, 0.51)
				O: (1/2, 1/2, 0.02), (0, 1/2, 0.51), (1/2, 0, 0.51)
BaTiO3 orthorhombic	Orthorhombic: PDF 01-090-2459	a = 3.99, b = 5.67, c = 5.69	α = β = γ = 90	Ba: (0, 0, 0), (0, 1/2, 1/2)
				Ti: (1/2, 0, 0.51), (1/2, 1/2, 0.01)
				O: (0, 0, 0.48), (0, 1/2, 0.98), (1/2, 0.255, 0.233), (1/2, 0.745, 0.233), (1/2, 0.755, 0.733), (1/2, 0.245,0.733)
CuO	Monoclinic: PDF 01-073-6023	a = 4.69, b = 3.42, c = 5.13	α = γ = 90, β = 99.54	Cu: (0, 0, 0), (1/2, 1/2, 0), (0, 1/2, 1/2), (1/2, 0, 1/2)
				O: (3/4 0.17, 1/4), (1/4, 0.67, 1/4), (3/4, 0.33, 3/4), (1/4, 0.73, 3/4)

APPENDIX B

Future implementation

Here we list some desired future implementations for XRDplayground, which we believe will broaden its applicability in teaching the PXRD technique and enrich discussions on topics not covered in its current version. For the next version, we are planning to:

(1) Add a dropdown menu that allows users to load any structure from the pool of predefined structures, as well as user-defined saved structures.

(2) Add a third option to visualize the unit cell, which includes the atoms located at the edges of the cells (unchecked = normal unit cell; checked = eight unit cells; tris­tate = include atoms on the opposite face).

(3) Include the `site occupancy factor' as one of the atom properties.

(4) Allow erasing of specific atoms instead of just the last one.

(5) Allow easy selection of common wavelengths from bench sources, such as Cu Kα, Mo Kα and Ag Kα.

(6) Include space group symmetry and all site symmetry rules. This would make it possible to read .cif files and use the sliders to modify the structure when applicable. It would also allow users to include many more atoms in a unit cell due to site multiplicity and work with more complex structures.

(7) Include the option to control atomic displacement parameters to simulate structural disorder.

(8) Include the option to create or import small molecules and treat them as rigid bodies, enabling users to shift and/or rotate them to observe the effects of these transformations on the PXRD pattern.

(9) Allow users to explore the effects of varying parameters that describe the preferred orientation, as well as the theoretical shape of the crystallites, on the appearance of the simulated PXRD pattern.

If there are any other implementations that the reader would like to see in the next version, please contact the authors.