vibe-sketcherDocumentation

vibesketcher.document.diffraction

Calculated X-ray powder patterns of periodic structures (#207).

A kinematic powder pattern from a validated three-dimensional cell: every reflection with d >= lambda / (2 sin theta_max) is generated from the reciprocal lattice (rows b_i with a_i . b_j = delta_ij, so 1/d = |h b1 + k b2 + l b3|), and its structure factor is

F(hkl) = sum_j occ_j f0_j(s) exp(-B_j s^2) exp(2 pi i (h x_j + k y_j + l z_j)),

with s = sin(theta)/lambda = 1/(2d), neutral-atom form factors f0 from the Waasmaier-Kirfel parametrisation (D. Waasmaier and A. Kirfel, Acta Cryst. A51, 416 (1995), doi:10.1107/S0108767394013292) and the isotropic Debye-Waller factor with B = 8 pi^2 U_iso (International Tables for Crystallography Vol. C (2006), Sections 6.1.1 and 6.1.1.3). Reflections that coincide in d and abs(F)^2 are merged into one family whose multiplicity is the number of hkl counted over the full sphere, so no point group has to be assumed. The integrated intensity is

I = m abs(F)^2 Lp(theta), Lp = (1 + K cos^2 2theta) / ((1 + K) sin^2 theta cos theta),

the Bragg-Brentano Lorentz-polarisation factor for an unpolarised beam (K = 1) or with a crystal monochromator at 2theta_M (K = cos^2 2theta_M); International Tables Vol. C, Section 6.2. Preferred orientation is optional. It uses the March-Dollase function (A. March, Z. Kristallogr. 81, 285 (1932); W. A. Dollase, J. Appl. Cryst. 19, 267 (1986), doi:10.1107/S0021889886089458):

P(alpha) = (r^2 cos^2 alpha + sin^2 alpha / r)^(-3/2),

where alpha is the angle between a reflection’s scattering vector and the stated preferred-orientation direction, a reciprocal-lattice vector (hkl)* of the same cell, normal to the platelets or along the needles. r = 1 is a random powder, r < 1 plates lying in the sample surface and r > 1 needles. The function averages to 1 over the sphere, so the total intensity is kept. The members of one family can make different angles with the direction, so a family’s intensity is m abs(F)^2 Lp <P>, with <P> the mean over its members, and <P> is reported with the family. It describes symmetric reflection with cylindrical texture about the sample normal; it is not a texture analysis. Anomalous dispersion (f', f''), absorption, extinction and microabsorption are not modelled and every result says so.

Anisotropic displacement parameters are refused, not reduced to U_iso; an element without tabulated coefficients is refused, never dropped. This is a planning aid for comparing a model with a measurement, not a refinement: agreement of a profile does not prove a structure unique.

Module Attributes

WAVELENGTHS

MAX_REFLECTIONS

reflections generated before merging, and profile points.

Functions

calculate(structure[, settings])

The calculated powder pattern of a document's periodic structure.

calculate_from_cif(text[, settings, block, ...])

The calculated powder pattern of a CIF block, with its occupancies and U_iso/B_iso.

calculate_pattern(lattice, scatterers, settings)

Reflections (and an optional profile) of a 3D cell; see the module docstring.

cif_scatterers(text, settings, *[, block, ...])

Lattice, expanded scatterers and a record from a CIF, keeping partial occupancies.

form_factor(element, s)

Waasmaier-Kirfel f0 at s = sin(theta)/lambda (1/angstrom); unknown elements refused.

lorentz_polarisation(two_theta_deg, ...)

Bragg-Brentano Lp (International Tables Vol.

march_dollase(cos_alpha, r)

The March-Dollase weight (Dollase 1986): (r^2 cos^2 + sin^2 / r)^(-3/2).

parse_settings(data)

Validated settings from JSON (raises pydantic.ValidationError or ValueError).

profile_curve(reflections, settings)

Peaks of unit area times their intensity on a regular 2theta grid (no background).

reflections_csv(result)

The reflection list as CSV with a provenance header.

scatterers_of(structure, settings)

The structure's sites with occupancies and B (overrides by site ID, then element).

structure_digest(structure)

The digest a calculated pattern records: the structure without its provenance.

Classes

PatternSettings(*[, radiation, wavelength, ...])

Every choice of a calculated powder pattern; nothing is inferred.

PreferredOrientation(*[, model])

March-Dollase preferred orientation along a reciprocal-lattice direction.

Profile(*[, shape, fwhm_deg, caglioti, eta, ...])

A peak shape for a continuous calculated curve (drawing and overlays only).

Scatterer(label, element, fractional, ...)

One atom of the cell: identity, fractional position, occupancy and B (angstrom^2).

vibesketcher.document.diffraction.WAVELENGTHS: dict[str, float] = {'CuKa1': 1.5405929, 'MoKa1': 0.7093171}

G. Hoelzer et al., Phys. Rev. A 56, 4554 (1997), as tabulated in International Tables Vol. C, Table 4.2.2.1.

Type:

Named characteristic lines (angstrom)

vibesketcher.document.diffraction.MAX_REFLECTIONS = 200000

reflections generated before merging, and profile points.

Type:

Bounded work

class vibesketcher.document.diffraction.Profile(*, shape='pseudo_voigt', fwhm_deg=None, caglioti=None, eta=0.5, step_deg=0.02)[source]

Bases: BaseModel

A peak shape for a continuous calculated curve (drawing and overlays only).

Parameters:
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

shape: Literal['gaussian', 'lorentzian', 'pseudo_voigt']
fwhm_deg: float | None

Constant full width at half maximum (degrees 2theta), or Caglioti U, V, W.

caglioti: tuple[float, float, float] | None
eta: float

Lorentzian fraction of a pseudo-Voigt.

step_deg: float
class vibesketcher.document.diffraction.PreferredOrientation(*, model='march_dollase', hkl, r)[source]

Bases: BaseModel

March-Dollase preferred orientation along a reciprocal-lattice direction.

Parameters:
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model: Literal['march_dollase']
hkl: tuple[int, int, int]

the platelet normal or the needle axis. Only its direction counts.

Type:

The direction (hkl)* in the stated cell’s reciprocal basis

r: float

1 random, below 1 platelets, above 1 needles.

Type:

March parameter

vibesketcher.document.diffraction.march_dollase(cos_alpha, r)[source]

The March-Dollase weight (Dollase 1986): (r^2 cos^2 + sin^2 / r)^(-3/2).

Parameters:
  • cos_alpha (ndarray)

  • r (float)

Return type:

ndarray

class vibesketcher.document.diffraction.PatternSettings(*, radiation='xray', wavelength='CuKa1', two_theta_min=5.0, two_theta_max=90.0, b_iso=<factory>, u_iso=<factory>, default_b_iso=0.0, occupancy=<factory>, monochromator_two_theta=None, preferred_orientation=None, profile=None)[source]

Bases: BaseModel

Every choice of a calculated powder pattern; nothing is inferred.

Parameters:
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

radiation: Literal['xray']
wavelength: float | Literal['CuKa1', 'MoKa1']

A named line (CuKa1, MoKa1) or a wavelength in angstrom.

two_theta_min: float
two_theta_max: float
b_iso: dict[str, float]

Isotropic displacement parameters by site ID, CIF label or element (angstrom^2).

u_iso: dict[str, float]
default_b_iso: float

Used for a site with no stated B or U (0 = static lattice, recorded).

occupancy: dict[str, float]

Occupancy overrides by site ID, CIF label or element.

monochromator_two_theta: float | None

2theta of a crystal monochromator (degrees); none for an unpolarised beam.

preferred_orientation: PreferredOrientation | None

a random powder).

Type:

Optional March-Dollase preferred orientation (none

profile: Profile | None
wavelength_angstrom()[source]
Return type:

float

class vibesketcher.document.diffraction.Scatterer(label, element, fractional, occupancy, b_iso, b_from)[source]

Bases: object

One atom of the cell: identity, fractional position, occupancy and B (angstrom^2).

Parameters:
label: str
element: str
fractional: tuple[float, float, float]
occupancy: float
b_iso: float
b_from: str
vibesketcher.document.diffraction.form_factor(element, s)[source]

Waasmaier-Kirfel f0 at s = sin(theta)/lambda (1/angstrom); unknown elements refused.

Parameters:
  • element (str)

  • s (ndarray)

Return type:

ndarray

vibesketcher.document.diffraction.lorentz_polarisation(two_theta_deg, monochromator_deg)[source]

Bragg-Brentano Lp (International Tables Vol. C, Section 6.2).

Parameters:
  • two_theta_deg (ndarray)

  • monochromator_deg (float | None)

Return type:

ndarray

vibesketcher.document.diffraction.scatterers_of(structure, settings)[source]

The structure’s sites with occupancies and B (overrides by site ID, then element).

Parameters:
Return type:

list[Scatterer]

vibesketcher.document.diffraction.calculate_pattern(lattice, scatterers, settings)[source]

Reflections (and an optional profile) of a 3D cell; see the module docstring.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.diffraction.profile_curve(reflections, settings)[source]

Peaks of unit area times their intensity on a regular 2theta grid (no background).

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.diffraction.calculate(structure, settings=None)[source]

The calculated powder pattern of a document’s periodic structure.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.diffraction.structure_digest(structure)[source]

The digest a calculated pattern records: the structure without its provenance.

Parameters:

structure (PeriodicStructure)

Return type:

str

vibesketcher.document.diffraction.cif_scatterers(text, settings, *, block=None, setting=None, merge_tolerance=0.01)[source]

Lattice, expanded scatterers and a record from a CIF, keeping partial occupancies.

Mixed and partially occupied sites keep their stated occupancy (they are what the pattern needs); U_iso or B_iso come from _atom_site_U_iso_or_equiv / _atom_site_B_iso_or_equiv. A site whose ADP type is Uani/Bani or which appears in an _atom_site_aniso loop is refused.

Parameters:
Return type:

tuple[ndarray, list[Scatterer], dict[str, Any]]

vibesketcher.document.diffraction.calculate_from_cif(text, settings=None, *, block=None, setting=None)[source]

The calculated powder pattern of a CIF block, with its occupancies and U_iso/B_iso.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.diffraction.parse_settings(data)[source]

Validated settings from JSON (raises pydantic.ValidationError or ValueError).

Parameters:

data (dict[str, Any] | None)

Return type:

PatternSettings

vibesketcher.document.diffraction.reflections_csv(result)[source]

The reflection list as CSV with a provenance header.

Parameters:

result (dict[str, Any])

Return type:

str