[hrushikesh-s]

Summary

Include a summary of major changes in bullet points:

• Adds Debye-Waller factors as an option of all phonon makers. With create_debye_waller=True, a last job computes the XRD, neutron and TEM patterns with the anisotropic Debye-Waller factors at each temperature, and once without them.
• The factors use the thermal displacement matrices U and the primitive cell stored by the phonon flow (Breaking: Leave out the acoustic modes at Gamma in the thermal displacement matrices #1590), so U always matches its sites. The q-point mesh, temperatures and frequency cutoff of U are set as for any phonon flow. Only the phonopy makers of VASP and aims compute U by default. The other makers need create_thermal_displacements=True.
• If the mesh has imaginary modes, no U is stored and the job stops with a clear message, unless imaginary_modes_thermal_displacements is set (Breaking: Leave out the acoustic modes at Gamma in the thermal displacement matrices #1590).
• New compute_debye_waller job and DebyeWallerDocument schema. The patterns go to the data store. A Debye-Waller section in docs/user/codes/vasp.md.
• Tests: an EMT run for Cu checks the XRD, ND and TEM intensities against the Debye-Waller factors. A mocked VASP run for NaCl uses the NAC.
• The tutorial is in Add a tutorial for the Debye-Waller workflow #1592. Part of Tracking: atomate2 PRs from Anubhav Jain's group #1591.
• The physics and the first implementation are from Ruby Keesey (@rkeesey).

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.

• Needs pymatgen 2026.10.24 or newer, the first release with the anisotropic Debye-Waller factors of Add anisotropic Debye-Waller factors to XRDCalculator, NDCalculator and TEMCalculator pymatgen#4715. The new debye-waller extra installs it, so the other workflows keep the current pymatgen lower bound.

• CI installs the extra in a separate step, since the strict extras pin an older pymatgen. A new matrix entry runs only the Debye-Waller tests.

TODO (if any)

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

• Once an emmet-core release has Store imaginary_modes and structure in ThermalDisplacementData emmet#1536, raise the emmet-core lower bound and allow the Debye-Waller job for the emmet phonon document, which the pheasy and hiPhive makers return.

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.

[JaGeo]

Could you check the frequency_cutoff and convergence with q points?

11 years ago, I did some relevant tests: https://doi.org/10.1039/c5ce01219h

EDIT:
I now reread the description that phonopy is not used in this context.
I would be interested in a comparison between this method and phonopy's with frequency_cutoff.

[JaGeo]

Also, there is a bit of a disconnect now. The phonon workflow already has an option to compute thermal displacement parameters and can save it as well

atomate2/src/atomate2/common/schemas/phonons.py

Line 137 in 60e6234

class ThermalDisplacementData(BaseModel):

[hrushikesh-s]

Could you check the frequency_cutoff and convergence with q points?

11 years ago, I did some relevant tests: https://doi.org/10.1039/c5ce01219h

EDIT: I now reread the description that phonopy is not used in this context. I would be interested in a comparison between this method and phonopy's with frequency_cutoff.

@JaGeo, yes, I am still running the benchmarking and comparison tests for this workflow from @rkeesey.
I will post the results here once they are ready and are properly checked from my end.

Also, there is a bit of a disconnect now. The phonon workflow already has an option to compute thermal displacement parameters and can save it as well

Yes, let me look into this as well...

[hrushikesh-s]

Could you check the frequency_cutoff and convergence with q points?

11 years ago, I did some relevant tests: https://doi.org/10.1039/c5ce01219h

EDIT: I now reread the description that phonopy is not used in this context. I would be interested in a comparison between this method and phonopy's with frequency_cutoff.

With a cutoff of 0 THz on the default q-point mesh, the acoustic modes at Gamma made U far too large or crashed phonopy, and U converges only as 1/N with the mesh number N. I fixed this for all phonon workflows in #1590, with a benchmark on 51 materials, and #1580 now takes U directly from the phonon flow, so there is no second implementation and no separate frequency_cutoff. Does this make sense?

[hrushikesh-s]

The tutorial in #1592 now also uses this option, and its rerun gives the same results for the six materials.

[rkeesey]

@hrushikesh-s Phonopy's default TDM matrices use Cartesian coordinates, and the CIF convention is only applied when specifically requested (the YAML files with the TDMs in the phonon database include both conventions). Would it be beneficial to implement a method of DWF calculation using Cartesian coordinates as well?

[hrushikesh-s]

@hrushikesh-s Phonopy's default TDM matrices use Cartesian coordinates, and the CIF convention is only applied when specifically requested (the YAML files with the TDMs in the phonon database include both conventions). Would it be beneficial to implement a method of DWF calculation using Cartesian coordinates as well?

@rkeesey, thanks! The Debye-Waller job already starts from phonopy’s Cartesian U, and its output stores both conventions. It converts U to the CIF convention only because pymatgen’s XRD, ND, and TEM calculators read the U11_cif to U12_cif site properties. Both are the same tensor in different bases, so the factors match exp(-2π² gᵀUg) from the Cartesian U to machine precision, which I checked on a triclinic cell.

[hrushikesh-s]

Or would you rather have it as an option of the phonon makers? Then the phonopy, pheasy, and hiPhive makers, and every new phonon maker, would each need the option in their own make(). Until a pymatgen release has materialsproject/pymatgen#4715, all phonon flows would also depend on it. Or is there something else that you suggest to do instead?

I had this in mind. However, the options would be part of the initialisation. I would anyhow recommend that we wait with merging until a new pymatgen release exists.

@JaGeo, materialsproject/pymatgen#4715 is now merged.

[ZKC19940412]

When reviewing this PR, I noticed the Debye-Waller document embeds a full copy of the phonon document's thermal displacement data: from_phonon_doc stores data.model_dump() here (L170), and the EMT test (tests/forcefields/flows/test_debye_waller.py L63-65) asserts the two copies are identical. Can you confirm the dual copy in storage is intended by design? If so, a short note in the field description would preempt the
question for future users.

[hrushikesh-s]

When reviewing this PR, I noticed the Debye-Waller document embeds a full copy of the phonon document's thermal displacement data: from_phonon_doc stores data.model_dump() here (L170), and the EMT test (tests/forcefields/flows/test_debye_waller.py L63-65) asserts the two copies are identical. Can you confirm the dual copy in storage is intended by design? If so, a short note in the field description would preempt the question for future users.

Yes, the copy is on purpose. The patterns are listed per temperature of this data, and the Debye-Waller document has no other temperatures, so it needs the copy to be read on its own. I have added this to the field description. Does that look fine?

[hrushikesh-s]

@JaGeo, #1590 is merged, so this PR now has only the Debye-Waller changes and is up to date with main. It is ready for review.

[JaGeo]

I guess one can use this with any of the harmonic phonon approaches right?

[hrushikesh-s]

Yes, create_debye_waller is an option of the base phonon maker, so the phonopy, pheasy, and hiPhive makers all have it.

The pheasy and hiPhive flows build emmet’s phonon document, though, which does not store the primitive cell of the matrices yet. So for them, the compute_debye_waller job fails until materialsproject/emmet#1536 is released....

[JaGeo]

If this is true, i don't understand the sentence about the T renormalization

[hrushikesh-s]

The sentence only means that $U$ at every temperature comes from the same harmonic phonons, so the change of the phonon frequencies with temperature is not included. That holds for all harmonic phonon makers. I have reworded it that way in the docs. Does it read better now?