[hrushikesh-s]

Summary

Include a summary of major changes in bullet points:

• Adds a tutorial for the Debye-Waller workflow of Add Debye-Waller factors as an option of the phonon makers #1580, which needs Add Debye-Waller factors as an option of the phonon makers #1580.
• Part A runs the workflows. Part B draws all tables and figures from two stored results files (36 KB and 84 KB), so CI runs it in a few seconds.
• Six materials (Cu, W, Si, NaCl, MgO, ZnO) with MACE-OMAT-0-medium, with MACE-Field Born charges for the polar ones. At 300 K, U_iso differs from experiment by 6.8% on average for MACE and by 8.2% for the force constants of the Materials Project's Harmonic Phonon Database (PBEsol).
• Shows the anisotropic U of ZnO, the drop of the XRD intensities with temperature, a Wilson fit that recovers B = 8π²U_iso, the electron diffraction spots of Si and the convergence of U with the q-point mesh.
• Compares five potentials on 15 materials. For the six stable materials at 300 K, MACE-OMAT-0 is closest to DFT (MAE 6.3e-4 Ų), and the PBE potentials give U 20% to 27% larger than the PBEsol reference.
• For materials with imaginary modes, compares the two estimates of Breaking: Leave out the acoustic modes at Gamma in the thermal displacement matrices #1590, "exclude" and "absolute". They differ by 4.6% in the median and by up to 67 times for single sites, so U of such materials is only a rough estimate.
• Linked from docs/user/codes/vasp.md and tutorials/tutorials.md. Part of Tracking: atomate2 PRs from Anubhav Jain's group #1591.

Additional dependencies introduced (if any)

• List all new dependencies needed and justify why. While adding dependencies that bring
  significantly useful functionality is perfectly fine, adding ones that add trivial
  functionality, e.g., to use one single easily implementable function, is frowned upon.
  Justify why that dependency is needed. Especially frowned upon are circular dependencies.

• None. Part A needs the MACE-Field fork and pymatgen 2026.10.24 or newer, as listed in the notebook. Part B needs only atomate2.

TODO (if any)

If this is a work-in-progress, write something about what else needs to be done.

• Add more materials with measured displacement parameters to the comparison, and more stable materials to the comparison of the potentials.

Checklist

Work-in-progress pull requests are encouraged, but please put [WIP] in the pull request
title.

Before a pull request can be merged, the following items must be checked:

• Code is in the standard Python style.
  The easiest way to handle this is to run the following in the correct sequence on
  your local machine. Start with running ruff and ruff format on your new code. This will
  automatically reformat your code to PEP8 conventions and fix many linting issues.
• Doc strings have been added in the Numpy docstring format.
  Run ruff on your code.
• Type annotations are highly encouraged. Run mypy to
  type check your code.
• Tests have been added for any new functionality or bug fixes.
• All linting and tests pass.

Note that the CI system will run all the above checks. But it will be much more
efficient if you already fix most errors prior to submitting the PR. It is highly
recommended that you use the pre-commit hook provided in the repository. Simply run
pre-commit install and a check will be run prior to allowing commits.

[hrushikesh-s]

Also, code structure-wise, I spotted that from_phonon_doc rebuilds the primitive cell via Phonopy(...) (src/atomate2/common/schemas/debye_waller.py, L150-156) and then assigns the stored U matrices to its sites by index (L160-166). Rebuilding leaves room for a site-order mismatch with the cell the matrices were computed on (e.g. across phonopy versions or symprec choices), which would silently produce wrong patterns. It will be much cleaner and has no room for mismatch error if we store the primitive structure (or its species sequence) in the phonon document / ThermalDisplacementData and use it directly here, or at least assert the rebuilt cell matches it.

Rebuilding the cell could indeed give a different site order, so ThermalDisplacementData now stores phonopy’s primitive cell next to the matrices (#1590), and from_phonon_doc uses it directly instead of rebuilding it. With the rebuild gone, from_phonon_doc and compute_debye_waller also no longer take symprec. Does that look fine?

[hrushikesh-s]

The pheasy and hiPhive flows build emmet’s phonon document, which drops this cell, so I opened materialsproject/emmet#1536 to add it. Once it is released, #1580 will raise the emmet-core lower bound so that the Debye-Waller job also runs for these flows. Does that look fine?