Powder diffraction planning¶
The sketcher can calculate an X-ray powder pattern from a periodic structure or a CIF, read a measured pattern with its provenance, and draw the two together for a paper. A calculated pattern is a planning aid. It shows where reflections fall and how strong a model predicts them to be. It is not a refinement. Agreement of a profile with a measurement does not prove that a structure is unique, and it says nothing about instrument uncertainty. Peak finding, indexing, Pawley and Rietveld refinement belong in specialist engines.
Calculated patterns¶
Every reflection with d >= lambda / (2 sin theta_max) is generated from the
reciprocal lattice of the stated cell, with rows b_i such that
a_i . b_j = delta_ij and 1/d = |h b1 + k b2 + l b3|. The 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) and B = 8 pi^2 U_iso. The
integrated intensity of a reflection family is I = m |F|^2 Lp, with the
Bragg-Brentano Lorentz-polarisation factor
Lp = (1 + K cos^2 2theta) / ((1 + K) sin^2 theta cos theta)
where K = 1 for an unpolarised beam and K = cos^2 2theta_M with a crystal
monochromator at 2theta_M. Reflections with equal d and equal |F|^2 form
one family. Its multiplicity m is the number of hkl counted over the full
sphere, so no point group is assumed. Reflections that only overlap in d
stay separate entries. Indices are given in the basis of the stated cell, so
the primitive and conventional cells of the same crystal give the same
pattern with different hkl labels.
The form factors f0 are the neutral-atom parametrisation of Waasmaier and
Kirfel, valid for s up to 6 per angstrom. An element without coefficients
(beyond californium) is refused, never dropped. Ion charges in a CIF type
symbol are ignored and the neutral-atom factor is used. Anomalous dispersion,
absorption, extinction and microabsorption are not modelled. Every result
lists these assumptions.
Preferred orientation¶
preferred_orientation applies the March–Dollase correction (March, 1932;
Dollase, 1986). Each reflection
is weighted by
P(alpha) = (r^2 cos^2 alpha + sin^2 alpha / r)^(-3/2)
where alpha is the angle between the reflection’s scattering vector and
the stated direction. The direction is a reciprocal-lattice vector (hkl)*
of the same cell: the normal of plate-like crystallites, or the axis of
needles. r = 1 is a random powder. r < 1 describes plates lying in the
sample surface, which strengthens the reflections along the normal by r^-3.
r > 1 describes needles. P averages to 1 over the sphere, so the total
intensity is kept.
The members of a family can make different angles with the direction. In
NaCl along (001)*, two members of {200} lie along it and four lie normal
to it. A family’s intensity is therefore m |F|^2 Lp <P>, and each
reflection reports its mean weight <P> as preferred_orientation. The
model assumes symmetric reflection and cylindrical texture about the sample
normal. It is a correction for comparing with a textured measurement, not a
texture analysis.
The result’s assumptions and references name the correction, as does the
overlay figure’s provenance line. The reflection CSV adds a header line and a
preferred_orientation column. Stored patterns keep the setting.
Settings¶
Field |
Meaning |
|---|---|
|
|
|
The 2theta range in degrees (default 5 to 90). |
|
Isotropic displacement parameters in square angstrom, keyed by site ID, CIF label or element. A site may have B or U, not both. |
|
B for sites with no stated value (default 0, a static lattice, which the result records). |
|
Occupancy overrides by site ID, CIF label or element. |
|
2theta of a crystal monochromator in degrees. |
|
|
|
A peak shape for a continuous curve: |
A key in b_iso, u_iso or occupancy that names no site or element is
refused. Anisotropic displacement parameters (u_aniso, b_aniso, a CIF
_atom_site_aniso_ loop or a Uani ADP type) are refused. They are not
reduced to U_iso. Work is bounded: at most 200000 reflections before
merging and 200000 profile points.
The Caglioti width is FWHM^2 = U tan^2 theta + V tan theta + W. A profile is
for display. Its peaks have unit area times the reflection intensity, and the
curve is normalised to a maximum of 100 with no background.
From a CIF¶
A CIF is read with its partial occupancies and _atom_site_U_iso_or_equiv
or _atom_site_B_iso_or_equiv values. The asymmetric unit is expanded with
the file’s symmetry operations, or with the operations of its space-group
symbol, as CIF import does. Unlike CIF import,
partially occupied and mixed sites are kept as they are, because the pattern
needs them. The result records the CIF’s SHA-256 digest, data block and
symmetry source.
Result¶
A result lists each reflection with hkl, multiplicity, d_angstrom,
two_theta_deg, q_inv_angstrom (Q = 2 pi / d), f_squared, lp,
intensity and relative_intensity (strongest = 100). It also gives the
number of systematically absent reflections (extinct), the scatterers with
their occupancy and B and where each B came from, the wavelength and its
source, the assumptions, the references and a source record. For a document
structure, source holds the structure ID and the SHA-256 digest of its
model.
Measured patterns¶
A measured pattern is read from plain text only:
XY: whitespace-separated columns in
.xy,.xye,.dator.txt.CSV: comma- or semicolon-separated columns in
.csv, with an optional row of column names.
The columns are x, intensity and, optionally, the intensity’s standard
uncertainty. Comment lines starting with #, !, ;, ', % or // are
kept as the file’s header. The x axis must be stated as two_theta_deg,
d_angstrom or q_inv_angstrom. It is never guessed from the numbers, and
any other axis is refused. The intensity unit is counts, counts_per_second
or arbitrary.
Vendor and binary formats, such as Bruker RAW and BRML, PANalytical XRDML, Rigaku RAS, Philips UDF and GSAS files, are refused with the reason. Convert them to XY or CSV with the instrument software. This keeps the vendors’ file formats and their licensing out of the sketcher. A file with binary content, non-numeric data rows, a ragged column count, fewer than two points or an x column that is not strictly monotonic is refused.
Each import keeps its provenance: the SHA-256 digest and size of the original bytes, the file name without its directory, the encoding, the format, the stated axis, unit and wavelength, the instrument fields and sample text exactly as given, the header lines, the point count and the x range.
Overlay figures¶
An overlay draws the measured curve, the calculated profile (or sticks when no profile was asked for) and a row of reflection tick marks under the curves. Provenance lines name both sources by their digests, the wavelengths and the instrument fields. The calculated curve is scaled to the measured maximum for display, the factor is printed, and nothing is fitted. The x axis is 2theta, d or Q.
A measured 2theta pattern is compared in 2theta only when its stated wavelength equals the calculated one. It is converted to d or Q only with its stated wavelength. A measured d or Q pattern can be drawn on any axis. Other combinations are refused rather than shifted. Figures are SVG, or PDF and PNG through the publication extra, in the style of the periodic figures. Their text uses the packaged Roboto font, which PDF embeds. The width is given in SVG pixels (1/96 inch) and the file states the same size in points, so a PNG has width × dpi / 96 pixels.
SDK¶
from vibesketcher.document import crystal
from vibesketcher.document.diffraction import PatternSettings, calculate, reflections_csv
from vibesketcher.document.measured_patterns import MeasuredSettings, read_measured
from vibesketcher.render.diffraction import OverlayOptions, overlay_figure
si = crystal.prototype("diamond", identifier="si", cell="conventional")
calculated = calculate(si, PatternSettings(b_iso={"Si": 0.5}, profile={"fwhm_deg": 0.1}))
print(reflections_csv(calculated))
data = b"# example\n20.0 10\n20.1 12\n20.2 11\n"
measured = read_measured(
data,
"si.xy",
MeasuredSettings(axis="two_theta_deg", wavelength_angstrom=1.5405929),
)
svg = overlay_figure(calculated, measured, OverlayOptions(label_reflections=4))
calculate_from_cif(text, settings, block=..., setting=...) calculates from
CIF text, and read_measured_file(path, settings) reads a file from disk.
CLI¶
vibe-sketcher solid powder si.vsk --structure si --b-iso Si=0.5 -o si.csv
vibe-sketcher solid powder --cif nacl.cif --wavelength MoKa1 --json
vibe-sketcher solid powder nacl.vsk --structure nacl --preferred-orientation 0,0,1 --march-r 0.6
vibe-sketcher solid powder-measured run.xy --axis two_theta_deg \
--wavelength 1.5405929 --instrument geometry=Bragg-Brentano
vibe-sketcher solid powder-figure si.vsk --structure si --fwhm 0.1 \
--measured run.xy --measured-axis two_theta_deg \
--measured-wavelength 1.5405929 --label-reflections 4 -o overlay.svg
solid powder prints the reflection table, --json the full result, and
-o writes the reflections as CSV with a provenance header or the result as
JSON. --settings reads all settings from a JSON file, and the options
override it. A refusal exits with status 3.
REST and MCP¶
Route |
Purpose |
|---|---|
|
|
|
|
|
|
|
|
None of these routes changes a document. The MCP tools
calculate_powder_pattern, read_measured_pattern and
powder_overlay_figure call them.
Stored patterns¶
A document can keep measured and calculated patterns in its additive
diffraction_patterns list, so overlays and exports need no re-upload.
vibesketcher.document.diffraction_store provides the SDK:
from vibesketcher.document import diffraction_store as ds
doc, m = ds.store_measured(doc, measured, revision=doc.revision)
doc, c = ds.store_calculated(doc, xrd.calculate(structure), revision=doc.revision)
ds.stored(doc) # summaries, each marked stale or current
svg = ds.overlay(doc, c["id"], m["id"])
ds.comparison(doc, m["id"], c["id"], "d_angstrom")
text = ds.pattern_csv(doc, m["id"]) # points with a provenance header
doc = ds.undo(doc) # or ds.remove(doc, pattern_id)
A measured record keeps the SHA-256 and size of the original bytes, the file name, format and encoding, the stated axis, intensity unit and wavelength, and the instrument fields, sample and header lines as given. It also keeps the points. The bytes themselves are not stored.
A calculated record keeps the result without its profile arrays, the profile curve, and the digest of its periodic structure. Only patterns of the document’s own structures are stored; import a CIF as a structure first.
A calculated record turns stale when its structure changes or is removed. Overlays, comparisons, CSV exports and undo refuse a stale record with
diffraction.stale_pattern.removestill deletes it.Every store is checked against the document revision (
diffraction.revision_conflict). Bounds: 32 patterns, 200,000 points per pattern, 1,000,000 points per document and 20,000 reflections per calculated pattern (diffraction.too_large).Stored overlays follow the wavelength rule above. A comparison only lists the reflections inside the measured range. It computes no fit or agreement factor.
The records travel in the
.vskfile and in the QVF document section. The QVF writers also add a non-critical vendor sectionx_vibesketch.diffraction, because QVF has no diffraction contract.ds.from_qvfreads that section. A single-structure QVF carries only the calculated patterns of that structure.
Not covered yet¶
CLI, REST and MCP routes for the stored patterns are the next slice. Neutron and electron radiation, the Ka2 doublet, anomalous dispersion, absorption corrections, vendor formats and a reviewed QVF diffraction contract are open. Refinement results are not claimed.
References¶
D. Waasmaier and A. Kirfel, Acta Cryst. A51, 416 (1995), doi:10.1107/S0108767394013292. The neutral-atom form factor coefficients.
International Tables for Crystallography, Vol. C (2006), Sections 6.1.1 (form factors and the Debye-Waller factor) and 6.2 (Lorentz-polarisation factor).
G. Hoelzer et al., Phys. Rev. A 56, 4554 (1997). The Cu Ka1 and Mo Ka1 wavelengths.
G. Caglioti, A. Paoletti and F. P. Ricci, Nucl. Instrum. 3, 223 (1958). The width function.
A. March, Z. Kristallogr. 81, 285 (1932). The March function.
W. A. Dollase, J. Appl. Cryst. 19, 267 (1986), doi:10.1107/S0021889886089458. The March–Dollase preferred-orientation correction.