Powder Diffraction with Tako Script

tako.xrd is a deterministic geometry operation. It does not use an energy calculator, electronic charge, spin state, or selected MLIP. The same call can return one of two schemas: periodic reciprocal-lattice sticks or a finite-cluster Debye curve. The scattering theory and approximation hierarchy are documented in Powder X-ray Diffraction; visible controls belong in Simulate a Powder Diffraction Pattern.

Calculate a periodic pattern

const crystal = await tako.input("input/crystal.extxyz");

const result = await tako.xrd(crystal, {
  radiation: "CuKa1",
  mode: "periodic",
  twoThetaMinDegrees: 5,
  twoThetaMaxDegrees: 90,
  twoThetaStepDegrees: 0.02,
  scaledIntensities: true,
  symmetryRefinement: true,
  debyeDampingAngstrom2: 0.04,
});

if (result.mode !== "periodic") {
  throw new Error("Periodic XRD silently fell back to Debye; verify cell and PBC");
}
await tako.output("output/periodic-xrd.json", result);

twoThetaStepDegrees is normalized and echoed but does not sample the periodic calculation. The branch returns discrete sticks. debyeDampingAngstrom2 is inert. Symmetry refinement uses a fixed internal tolerance and returns no standardized structure, space group, or success flag.

The selected radiation is one stored wavelength. Generic CuKa and MoKa do not create weighted doublets. Use CuKa1/CuKa2 or MoKa1/MoKa2 explicitly when line separation matters.

Calculate a finite Debye curve

const cluster = await tako.input("input/cluster.xyz");

const result = await tako.xrd(cluster, {
  radiation: "CuKa",
  mode: "debye",
  twoThetaMinDegrees: 5,
  twoThetaMaxDegrees: 90,
  twoThetaStepDegrees: 0.05,
  debyeDampingAngstrom2: 0.04,
  scaledIntensities: false,
  symmetryRefinement: false,
});

if (result.mode !== "debye") {
  throw new Error(`Unexpected XRD mode: ${result.mode}`);
}
await tako.output("output/debye-xrd.json", result);

Debye mode ignores scaledIntensities and symmetryRefinement. The returned intensities are raw values from the implemented Iwasa/Debye model, while the viewer normalizes display height independently. Damping is a reciprocal-space exponential attenuation, not peak broadening.

The finite calculation uses ordinary Cartesian pair distances, no minimum-image convention and no periodic replicas. Current nonzero Waasmaier form factors exist only for C, N, O, P, S, Cl, Ni, Cu, Pd, Ag, Pt, and Au. H and unsupported elements silently contribute zero (Known Limitations). Validate the element set before dispatch:

const supported = new Set([
  "C", "N", "O", "P", "S", "Cl",
  "Ni", "Cu", "Pd", "Ag", "Pt", "Au",
]);
const missing = [...new Set(
  cluster.atoms
    .map((atom) => atom.element)
    .filter((element) => !supported.has(element))
)];
if (missing.length) {
  throw new Error(`Debye form factors are zero for: ${missing.join(", ")}`);
}

Branch on the actual mode

The operation selects Debye when mode is "debye", or when the structure reaches the worker without both a cell and non-none PBC. A requested periodic call can therefore resolve successfully as Debye. The returned mode, not the request, is authoritative.

const pattern = await tako.xrd(structure, options);

if (pattern.mode === "periodic") {
  for (const peak of pattern.peaks) {
    // peak.two_theta_degrees, peak.d_spacing_angstrom,
    // peak.intensity, peak.families[]
  }
} else if (pattern.mode === "debye") {
  for (const point of pattern.points) {
    // point.two_theta_degrees, point.intensity
  }
} else {
  throw new Error(`Unknown XRD result mode: ${pattern.mode}`);
}

Do not access both peaks and points without narrowing mode; each array is absent in the other branch.

Understand range normalization and grid limits

Finite minimum and maximum values are accepted. When maximum is not greater than minimum, normalization repairs the interval. A nonpositive step falls back to 0.02°, and WASM clamps the effective step to at least 0.001°.

Debye point count is

$$M=\left\lfloor\frac{2\theta_{\max}-2\theta_{\min}}{\Delta(2\theta)}\right\rfloor+1,$$

capped at 20,000. The minimum is included; the maximum is not guaranteed. When capped, the result can end far below two_theta_range[1], although the metadata continues to report that requested/repaired maximum. Inspect the last point:

if (result.mode === "debye") {
  const last = result.points.at(-1)?.two_theta_degrees;
  if (last == null || last < result.two_theta_range[1] - result.two_theta_step_degrees) {
    throw new Error("Debye grid did not cover the reported angular range");
  }
}

Keep the Debye minimum nonnegative. Negative angles map to negative scattering coordinate and reject in the lower implementation.

Read periodic peaks

Each periodic peak has angle in degrees, $d$ spacing in ångström, a relative intensity, and one or more families. Each family has integer hkl and an enumerated multiplicity. Reflections within $10^{-5}$ degrees are merged; the first reflection supplies the retained angle and spacing while intensities and multiplicities accumulate.

With scaledIntensities: true, the strongest retained peak is 100. With false, values remain arbitrary theoretical units including form factor, multiplicity, and Lorentz-polarization weighting. Neither state is an absolute count calibration.

The result echoes symmetry_refinement: true when requested even if symmetry dataset creation silently failed and exact input geometry was used.

Read Debye points

Each point has angle in degrees and an unnormalized intensity. The result does not preserve the damping value, Iwasa alpha/method, supported-element report, atom/pair count, $q$ coordinate, or actual final requested-grid status. Keep the input options with the result.

Debye preparation stores $N(N+1)/2$ pair distances and each point traverses those pair groups. Cost is approximately $O(MN^2)$. Reduce the angular range or increase the step before using a very large cluster.

Preserve the artifact boundary

The returned object is the scientific result. The interactive calculation workspace additionally creates result.json, xrd.json, and log.txt; xrd.json duplicates the whole returned XRD object. Those workspace files are not nested result fields and are not automatically created by every Script output context.

The runtime emits a complete partial-result event only after calculation. It does not stream usable partial peaks/points. A rejection or cancellation exposes no checkpoint or resumable pair/reflection cache.

Compare patterns

Keep wavelength and branch fixed. Compare periodic peak positions first, then relative intensities. For Debye curves, keep cluster construction, element coverage, angle grid, and damping fixed. Preserve unscaled JSON before applying display normalization.

Tako does not return an instrument profile, background, zero shift, occupancy/disorder, anomalous scattering, texture, crystallite-size/strain broadening, absorption, or refinement uncertainty. Apply those in a declared downstream model; do not treat the viewer polyline as a simulated experimental trace.

The exhaustive settings, radiation values, types, units, and branch-specific availability conditions are generated in tako.xrd Settings.