crystod.xrd

crystod.xrd#

Public powder-diffraction API of CrystOD (the crystod-xrd domain).

Powder X-ray diffraction patterns of a crystal structure, the Python form of crystod-xrd: the Bragg peaks of a pymatgen Structure for a chosen radiation (a K-alpha doublet such as CuKa with the Ka1 + Ka2 lines in the 2:1 ratio, or a single line such as MoKa1), their broadening into a continuous pattern, and the text-table and figure writers the command uses.

Computing patterns

load_structure() – a POSCAR as a pymatgen Structure.
compute_xrd_pattern() – the Bragg peaks for one radiation, as an XRDPattern of Peak records (h k l, multiplicity, d, 2theta, intensity, line).

Broadening and output

smear_pattern() – the peaks broadened with a Lorentzian or Gaussian profile of unit area, as (two_theta, intensity) arrays.
write_peak_table() – the comma-separated table crystod-xrd writes.
plot_xrd_pattern() – the PDF (or PNG, SVG) with tick marks at the peak positions.

Tables

WAVELENGTHS – the line wavelengths (RIETAN-FP manual).
KALPHA_DOUBLETS – the doublet compositions.
XRAY_TYPES, PEAK_PROFILES – the names --xraytype and --peak-profile accept.

Usage:

from crystod import xrd
from crystod.examples import example_path

structure = xrd.load_structure(str(example_path("221_PPOSCAR_ScF3")))
pattern = xrd.compute_xrd_pattern(structure, "CuKa", (10, 120))
for peak in pattern.peaks[:3]:
    print(peak.hkl, round(peak.two_theta, 3), round(peak.intensity, 2), peak.line)
two_theta, intensity = xrd.smear_pattern(pattern, "lorentzian", width=0.1)

Attributes resolve lazily (PEP 562): importing this module is instant and pymatgen and matplotlib load only on first use. Functions report bad input as ValueError through this namespace (the implementation module raises SystemExit, as the command line wants).

class crystod.xrd.Peak(hkl, multiplicity, families, d, two_theta, intensity, line)[source]#

Bases: object

One Bragg reflection of a computed pattern.

Variables:

hkl (tuple[int, int, int]) – Miller indices of the first family of planes contributing to the peak.
multiplicity (int) – Multiplicity of that family.
families (tuple[tuple[tuple[int, int, int], int], ...]) – Every ((h, k, l), multiplicity) that pymatgen merged into this peak because the d spacings coincide (cubic (3 0 0) and (2 2 1), for instance); the first entry is hkl.
d (float) – Interplanar spacing in Angstrom.
two_theta (float) – Scattering angle 2theta in degrees.
intensity (float) – Relative intensity, 100 for the strongest reflection of the line it belongs to (50 for the strongest Ka2 reflection of a doublet).
line (str) – The radiation line that produced the peak ("CuKa1").

d: float#

families: tuple[tuple[tuple[int, int, int], int], ...]#

property families_label: str#

every merged family with its multiplicity.

Type:: "(3 0 0) x6 + (2 2 1) x24"

hkl: tuple[int, int, int]#

intensity: float#

line: str#

multiplicity: int#

two_theta: float#

class crystod.xrd.XRDPattern(peaks, xray_type, wavelengths, formula, space_group, two_theta_range, structure_name='', _cache=<factory>)[source]#

Bases: object

A computed powder pattern: the peak list plus what it was computed for.

Variables:

peaks (list[crystod.xrd_pattern.Peak]) – The Bragg peaks in order of increasing 2theta.
xray_type (str) – The radiation name given ("CuKa", "MoKa1", …).
wavelengths (dict[str, float]) – line -> wavelength in Angstrom for every line that contributed (two entries for a doublet).
formula (str) – Reduced chemical formula of the structure.
space_group (str) – International symbol found by spglib through pymatgen.
two_theta_range (tuple[float, float]) – The (min, max) window in degrees the peaks were collected in.
structure_name (str) – The file name the structure was read from, used in output names and plot legends (empty when built from a Structure).

table_lines()[source]#

The peak table as printed by crystod-xrd, one string per line.

Return type:: list[str]

formula: str#

property intensity: ndarray[tuple[Any, ...], dtype[float64]]#: The relative intensities of the peaks.

peaks: list[Peak]#

space_group: str#

structure_name: str = ''#

property two_theta: ndarray[tuple[Any, ...], dtype[float64]]#: The 2theta positions of the peaks, in degrees.

two_theta_range: tuple[float, float]#

wavelengths: dict[str, float]#

xray_type: str#

crystod.xrd.compute_xrd_pattern(structure, xray_type='CuKa', two_theta_range=(10.0, 120.0), *, min_intensity=0.0, symprec=0.01, structure_name='')[source]#

Compute the powder pattern of a structure for one radiation.

This is crystod-xrd -c POSCAR --xraytype TYPE without the files. Each line of the radiation is run through pymatgen’s XRDCalculator (intensities scaled to 100 for the strongest peak); for a doublet the Ka2 peaks are weighted by 1/2 and the two lists are merged in order of 2theta.

Parameters:

structure – A pymatgen.core.Structure (see load_structure()).
xray_type (str) – A K-alpha doublet ("CuKa", the default, "MoKa", …) or a single line ("CuKa1", "CuKb", …); XRAY_TYPES lists them, case-insensitively.
two_theta_range (tuple[float, float]) – (min, max) in degrees; peaks outside are dropped.
min_intensity (float) – Peaks whose scaled intensity is below this percentage are dropped. 0 keeps every reflection (pymatgen’s own default would hide those below 0.1 %).
symprec (float) – Tolerance in Angstrom of the space-group determination used for the printed symbol only; the intensities are computed from the structure as given, without symmetrization.
structure_name (str) – Name recorded in the result for output names and legends (the CLI passes the file name).

Returns:

The XRDPattern.

Raises:

SystemExit – Unknown radiation name (ValueError when called through crystod.xrd).

Return type:

XRDPattern

Example

>>> from crystod import xrd
>>> from crystod.examples import example_path
>>> s = xrd.load_structure(str(example_path("221_PPOSCAR_ScF3")))
>>> pattern = xrd.compute_xrd_pattern(s, "CuKa1", (10, 60))
>>> pattern.space_group, len(pattern.peaks)
('Pm-3m', 6)
>>> peak = pattern.peaks[0]
>>> peak.hkl, round(peak.two_theta, 2), round(peak.intensity, 1)
((1, 0, 0), 21.82, 100.0)

crystod.xrd.load_structure(path)[source]#

Read a POSCAR into a pymatgen Structure.

Parameters:: path (str) – The structure file (VASP POSCAR/CONTCAR format).
Returns:: The pymatgen.core.Structure.
Raises:: SystemExit – The file does not exist or cannot be parsed (ValueError when called through crystod.xrd).

crystod.xrd.plot_xrd_pattern(pattern, path, profile='lorentzian', width=0.1, two_theta_range=None, show=False)[source]#

Draw the broadened pattern with tick marks at the Bragg positions.

Parameters:

pattern (XRDPattern) – The peaks to draw.
path (str) – Output file; the extension selects the format (.pdf, .png, .svg, … as matplotlib supports).
profile (str) – Broadening profile, see smear_pattern().
width (float) – Profile width in degrees, see smear_pattern().
two_theta_range (tuple[float, float] | None) – The window to draw; the pattern’s own by default.
show (bool) – Open an interactive matplotlib window as well.

Returns:

path.

Return type:

str

crystod.xrd.smear_pattern(pattern, profile='lorentzian', width=0.1, npoints=5000, two_theta_range=None)[source]#

Broaden the peaks into a continuous pattern.

Every peak becomes a unit-area profile of the same width scaled by its intensity: a Lorentzian (w/pi) / ((x - x0)^2 + w^2) or a Gaussian exp(-(x - x0)^2 / (2 w^2)) / (w sqrt(2 pi)). The two profiles share the same integrated intensity per peak, so they can be compared directly.

Parameters:

pattern (XRDPattern) – The peaks, from compute_xrd_pattern().
profile (str) – "lorentzian" (default) or "gaussian".
width (float) – The profile parameter w in degrees (Lorentzian half width at half maximum, Gaussian standard deviation); 0.1 by default.
npoints (int) – Number of 2theta samples.
two_theta_range (tuple[float, float] | None) – The window to sample; the pattern’s own by default.

Returns:

(two_theta, intensity) arrays of length npoints.

Raises:

SystemExit – Unknown profile name or non-positive width (ValueError when called through crystod.xrd).

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]]]

crystod.xrd.write_peak_table(pattern, path)[source]#

Write the peak list as a comma-separated text table.

Columns: h, k, l, multiplicity, d, two_theta, intensity, line, families – the last holds every merged family ((3 0 0) x6 + (2 2 1) x24) and is the only non-numeric column besides line. The header lines record the structure, the radiation and the wavelength(s).

Parameters:

pattern (XRDPattern) – The peaks to write.
path (str) – Output file name.

Returns:

path.

Return type:

str

crystod.xrd.WAVELENGTHS#: X-ray wavelengths in Angstrom, from the RIETAN-FP manual (F. Izumi and K. Momma). Keys are the names --xraytype accepts for a single line; the doublets of KALPHA_DOUBLETS are built from these.

crystod.xrd.KALPHA_DOUBLETS#: K-alpha doublets: name -> ((line, weight), (line, weight)). The Ka2 pattern enters with half the weight of Ka1, the 2:1 ratio of the two lines.

crystod.xrd.XRAY_TYPES = ('CuKa', 'AgKa', 'MoKa', 'CoKa', 'FeKa', 'CrKa', 'CuKa1', 'CuKa2', 'CuKb', 'AgKa1', 'AgKa2', 'MoKa1', 'MoKa2', 'CoKa1', 'CoKa2', 'FeKa1', 'FeKa2', 'CrKa1', 'CrKa2')#: Every name --xraytype accepts, doublets first.

crystod.xrd.PEAK_PROFILES = ('lorentzian', 'gaussian')#: The broadening profiles of smear_pattern().

crystod.xrd

Contents

crystod.xrd#