tako.xrd Settings

Page type: Reference · Generated from src/script/takoScriptDocs.ts · Verified 2026-07-11T00:00:00.000Z

On this page

tako.xrd

This page is generated from code-owned Doxygen-style metadata in src/script/takoScriptDocs.ts. Update that file first, then regenerate this page so runtime capability descriptions, docs, and agent guidance stay aligned.

tako.xrd

Computes geometry-only periodic Bragg sticks or a finite Cartesian-pair Debye curve. The actual returned mode can silently differ from a periodic request when cell or PBC is absent.

Signature: await tako.xrd(structure, { radiation, mode, twoThetaMinDegrees, twoThetaMaxDegrees, twoThetaStepDegrees, scaledIntensities, symmetryRefinement, debyeDampingAngstrom2 })

Theory

Periodic XRD applies Bragg diffraction: lattice spacings map to two-theta peak positions for a chosen X-ray wavelength, and structure factors determine relative intensities.
Debye scattering uses ordinary finite Cartesian pair distances without periodic replicas or minimum-image wrapping. Its damping is reciprocal-space attenuation, not peak broadening.
Periodic intensities assume full occupancy, neutral-atom bundled form factors, zero Debye-Waller factors, and one ideal powder Lorentz-polarization model. Debye form factors are nonzero only for a small hardcoded element set.

Usage Notes

Require result.mode === "periodic" when reciprocal-lattice semantics are mandatory; missing cell/PBC silently falls back to Debye.
Keep the radiation line fixed when comparing predicted patterns to experiment or between structures.
scaledIntensities and symmetryRefinement affect periodic mode only. The viewer normalizes display height independently for both modes.
Validate Debye element coverage: only C, N, O, P, S, Cl, Ni, Cu, Pd, Ag, Pt, and Au have nonzero current form factors; H/others contribute zero.

Settings

Setting	Type	Default	Values	Unit	Validation	Description
`radiation`	enum	`CuKa`	`CuKa`, `CuKa1`, `CuKa2`, `CuKb1`, `MoKa`, `MoKa1`, `MoKa2`, `MoKb1`, `CrKa`, `FeKa`, `CoKa`, `AgKa`, `WLa1`, `WLa2`		Unknown values normalize to CuKa in TypeScript; unsupported values reaching WASM reject.	Single stored source wavelength. Generic Ka choices are averages, not synthesized Ka1/Ka2 doublets.
`mode`	enum	`periodic`	`periodic`, `debye`		Unknown values normalize to periodic. Runtime overrides periodic to Debye when cell or non-none PBC is absent.	Requested algorithm. The returned `mode` is authoritative.
`twoThetaMinDegrees`	number	`5`		degrees	Nonfinite values fall back to 5. Negative finite values are accepted, but Debye later rejects negative scattering coordinate.	Lower angular bound. Included exactly in the Debye grid; periodic reflections are filtered against it.
`twoThetaMaxDegrees`	number	`90`		degrees	Nonfinite values fall back to 90. If not greater than minimum, normalization uses 90 when possible or minimum+1.	Reported upper bound. Debye grid may end below it due to nonintegral step or the 20,000-point cap.
`twoThetaStepDegrees`	number	`0.02`		degrees	Nonpositive/nonfinite falls back to 0.02; WASM clamps to at least 0.001.	Debye sampling interval. Periodic mode ignores it but echoes it in metadata.
`scaledIntensities`	boolean	`true`			Boolean default true; ignored in Debye mode.	Periodic only: scale strongest retained merged peak to 100. False remains arbitrary theoretical units, not absolute counts.
`symmetryRefinement`	boolean	`true`			Boolean default true; ignored in Debye mode. Periodic standardization failure silently falls back to exact input.	Periodic only: request spg standardization at fixed 1e-5 internal-bohr tolerance. No standardized structure, space group, or success flag is returned.
`debyeDampingAngstrom2`	number	`0.04`		Å²	Negative/nonfinite values normalize to 0.04 in TypeScript; WASM clamps residual negative input to zero. Ignored in periodic mode.	Debye reciprocal-space exponential attenuation applied once to total intensity; not line broadening or a periodic site Debye-Waller factor.

Example

const crystal = await tako.input("input/powder-candidate.extxyz");
const result = await tako.xrd(crystal, {
  radiation: "CuKa",
  mode: "periodic",
  twoThetaMinDegrees: 5,
  twoThetaMaxDegrees: 80,
  twoThetaStepDegrees: 0.02,
  scaledIntensities: true,
});
await tako.output("output/xrd.json", result);

Result

Discriminated XRD result. Periodic mode returns merged Bragg sticks/families; Debye mode returns sampled finite-pair points. No calculator provenance, settings record, standardized cell, experimental profile, or restart state is returned.

Field	Type	Unit	Availability	Description
`kind`	”xrd”		Every resolved result	Runtime discriminator.
`mode`	”periodic” \| “debye”		Every resolved result	Actual branch. Debye can result from an explicit request or silent missing-cell/PBC fallback.
`radiation`	string		Every resolved result	ASCII radiation enum label such as CuKa1.
`wavelength_angstrom`	number	Å	Every resolved result	Exact stored single-line wavelength used for angle/scattering conversion.
`two_theta_range`	[number, number]	degrees	Every resolved result	Normalized reported range. In capped Debye output it can extend beyond the last actual point.
`two_theta_step_degrees`	number	degrees	Every resolved result	Effective step after minimum 0.001 clamp; metadata-only in periodic mode.
`scaled_intensities`	boolean		Periodic mode only	Requested periodic scaling flag.
`symmetry_refinement`	boolean		Periodic mode only	Requested periodic standardization flag; not evidence that standardization succeeded.
`peaks`	object[]		Periodic mode only; may be empty when no retained reflection lies in range	Merged ideal powder sticks sorted by angle.
`peaks[].two_theta_degrees`	number	degrees	Every periodic peak	Bragg angle of the first reflection retained in the merged peak.
`peaks[].d_spacing_angstrom`	number	Å	Every periodic peak	Interplanar spacing associated with the retained representative reflection.
`peaks[].intensity`	number	relative; 0–100 when scaled, arbitrary otherwise	Every periodic peak	Merged structure-factor × multiplicity × Lorentz-polarization model intensity.
`peaks[].families`	object[]		Every periodic peak	Metric-grouped reflection families merged at the angle.
`peaks[].families[].hkl`	[integer, integer, integer]		Every periodic family	Representative Miller index; grouping is metric-based rather than a returned space-group equivalence proof.
`peaks[].families[].multiplicity`	integer		Every periodic family	Count of enumerated reflections assigned to the family.
`points`	object[]		Debye mode only; nonempty for a valid nonnegative grid	Finite-cluster Debye curve in increasing sampled angle.
`points[].two_theta_degrees`	number	degrees	Every Debye point	Sampled angle. Minimum is included; reported maximum is not guaranteed.
`points[].intensity`	number	raw arbitrary Iwasa/Debye units	Every Debye point	Unscaled pair-sum intensity including angular and damping multipliers. Viewer display normalizes and clamps negatives separately.

Errors and Promise Behavior

Rejects unsupported radiation, invalid/singular periodic lattice or reciprocal metric, missing periodic scattering parameters, or Debye negative scattering coordinate/invalid numerical input.
Requested periodic mode does not reject missing cell/PBC; it resolves through Debye. Require result.mode when branch identity is an invariant.
Periodic symmetry standardization failure is silent and falls back to exact input while symmetry_refinement remains true in output.
Debye form-factor noncoverage is silent: H and unsupported elements contribute zero rather than rejecting.
Cancellation terminates the worker and exposes no partial reflection/pair cache. The complete partialResult event arrives only after branch computation.