Lattice dynamics workflow using Pheasy

[hrushikesh-s]

Summary

Include a summary of major changes in bullet points:

• Feature 1 -- Add lattice dynamics workflow using pheasy for harmonic & anharmonic phonon calculations

Additional dependencies introduced (if any)

• pheasy – used to generate symmetry-aware cluster spaces, construct null-space constraints, build displacement/sensing matrices, and fit harmonic force constants from displacement–force data; also used for optional higher-order IFC fitting, phonon renormalization, and force-constant conversion workflows.
• alamode (alm) – used to estimate the number of irreducible force-constant parameters and thereby determine how many displaced supercells are needed for harmonic and anharmonic IFC extraction; also used to estimate higher-order anharmonic parameter counts.
• hiphive – used as a post-processing and recovery backend for force constants: it enforces rotational sum rules on second-order IFCs when imaginary modes are present, reconstructs corrected force constants, and is also used to convert third-order force constants to phono3py format for thermal-conductivity workflows.

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.

[hrushikesh-s]

Hi @JaGeo, does this look okay?

[JaGeo]

@hrushikesh-s thanks!

I think one point we need to discuss is the deprecation of the phonon related schema. Our codes actually depend on the old schema and i think we should handle this carefully.

[hrushikesh-s]

Hi @JaGeo , Thanks for bringing this up, that makes a lot of sense.

I agree that switching directly to the Emmet models could be disruptive since earlier production codes may still rely on the current atomate2 schema. Would it be reasonable to handle this in a phased way?

What I had in mind is:

• In this PR, we transition to using the Emmet models internally
• Keep the existing atomate2.common.schemas.phonons import path for backward compatibility
• Preserve any atomate2-specific helper methods so existing workflows don’t break
• Add a DeprecationWarning with a clear timeline

This way we can move toward the new schema without introducing a breaking change immediately. Does that sound like a reasonable approach to you? If yes, then I can make these edits to the current PR.

[JaGeo]

I do recall a discussion involving @esoteric-ephemera that we wanted to potentially keep both options.
I am in principle okay with a long-term deprecation. I would need to check the emmet models in detail to judge if they would still fully serve our purposes.

[esoteric-ephemera]

I don't remember off hand how much the two schemas differ, can you point me to the fields that are needed in the legacy schema that are missing in the new emmet one @hrushikesh-s?

[hrushikesh-s]

Hi @esoteric-ephemera ,

I compared the legacy atomate2 phonon schema against the new emmet one. The main differences are:

1. The new emmet schema replaces the old PhononBSDOSDoc with a PhononBSDOSTask + built PhononBSDOSDoc split.

2. phonon_bandstructure and phonon_dos are no longer stored as raw pymatgen objects; they use emmet wrapper schemas (PhononBS, PhononDOS).

3. The following legacy stored fields are not present as explicit stored fields in the new emmet schema:

   • free_energies
   • heat_capacities
   • internal_energies
   • entropies
   • temperatures
   • uuids
   • jobdirs

4. In emmet, thermodynamic quantities are computed from the DOS on demand rather than stored as arrays on the main BSDOS doc.

5. has_imaginary_modes is now a computed field rather than a plain stored field.

6. phonopy_settings was renamed to post_process_settings.

7. force_constants changed shape from the legacy wrapped ForceConstants object to a plain nested matrix list.

8. total_dft_energy changed convention: legacy atomate2 stored it per formula unit, while emmet stores it per atom.

9. The new schema also adds fields the legacy one did not have, such as phonon_method, epsilon_electronic, and sum-rule diagnostics (sum_rules_breaking, ASR/CNSR-related computed data).

Aside -- I tried to restore the legacy phonon schema functionality for the phonon, QHA, and Grüneisen workflows, and have fixed the associated test failures. Can you pls take a look and confirm whether these changes align with the goal of continuing to support the legacy schema for these workflows in the short term, with a plan to migrate to the emmet schema later?

[hrushikesh-s]

Also, it's worthwhile to mention that the current PR makes use of my fork of Pheasy repo, and the PR is underway on Pheasy to make it compatible with the current atomate2 style reading of .npy files for disp & force matrices

[JaGeo]

Thanks!

From the timeline: i will likely look at it after Easter (next week earliest). I have to grade and prepare my teaching this week. I would also like to test and explore the changes in detail.