Lattice dynamics workflow using Pheasy by hrushikesh-s · Pull Request #1063 · materialsproject/atomate2

hrushikesh-s · 2024-11-22T03:14:35Z

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.

Modified some parts based on Janine's comments.

…atomate2 into atomate2_jz_pheasy

…lacement method.

…group for crystals.

…tomate2 data schema

esoteric-ephemera · 2026-03-27T19:26:22Z

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 · 2026-03-27T20:15:22Z

Hi @esoteric-ephemera ,

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

The new emmet schema replaces the old PhononBSDOSDoc with a PhononBSDOSTask + built PhononBSDOSDoc split.
phonon_bandstructure and phonon_dos are no longer stored as raw pymatgen objects; they use emmet wrapper schemas (PhononBS, PhononDOS).
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
In emmet, thermodynamic quantities are computed from the DOS on demand rather than stored as arrays on the main BSDOS doc.
has_imaginary_modes is now a computed field rather than a plain stored field.
phonopy_settings was renamed to post_process_settings.
force_constants changed shape from the legacy wrapped ForceConstants object to a plain nested matrix list.
total_dft_energy changed convention: legacy atomate2 stored it per formula unit, while emmet stores it per atom.
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 · 2026-03-27T20:23:51Z

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 · 2026-03-31T04:49:19Z

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.

JaGeo · 2026-04-08T09:58:15Z

    return Response(output={"plus": plus_struct, "minus": minus_struct})


-@job(data=[PhononBSDOSDoc])


With this new workflow, no object needs to be transferred to "data"?

JaGeo · 2026-04-08T10:05:12Z

    )


-@job(data=[PhononBSDOSDoc])


Is this not needed?

Or at least a replacement for this one?

JaGeo · 2026-04-08T10:13:03Z

-from atomate2.common.schemas.phonons import (
-    PhononBSDOSDoc,
-    PhononComputationalSettings,
-    PhononJobDirs,
-    PhononUUIDs,
-    ThermalDisplacementData,
-)


I understood that we keep this for now, yes? Why not keeping the tests as long as we keep the schema?

JaGeo · 2026-04-08T10:17:49Z

@@ -0,0 +1,362 @@
+"""Flow for calculating (an)harmonic FCs and phonon energy renorma. with pheasy."""


Suggested change

"""Flow for calculating (an)harmonic FCs and phonon energy renorma. with pheasy."""

"""Flow for calculating (an)harmonic FCs and phonon energy renormalisation with pheasy."""

JaGeo · 2026-04-08T10:21:48Z

+    if cal_anhar_fcs:
+        # Due to the cutoff radius of the force constants use the unit of Borh in ALM,
+        # we need to convert the cutoff radius from Angstrom to Bohr.
+        with ALM(lattice * 1.89, positions, numbers) as alm:


I assume this is accurate enough for a cutoff but maybe more digits?

JaGeo · 2026-04-08T10:23:53Z

+        force_constants = parse_FORCE_CONSTANTS(filename=new_fc_file)
+        phonon.force_constants = force_constants
+        phonon.symmetrize_force_constants()
+
+        phonon.save(_DEFAULT_FILE_PATHS["phonopy"])
+
+        # get phonon band structure
+        kpath_dict, kpath_concrete = _get_kpath(
+            structure=get_pmg_structure(phonon.primitive),
+            kpath_scheme=kpath_scheme,
+            symprec=symprec,
+        )
+
+        npoints_band = kwargs.get("npoints_band", 101)
+        qpoints, connections = get_band_qpoints_and_path_connections(
+            kpath_concrete, npoints=kwargs.get("npoints_band", 101)
+        )
+
+        # phonon band structures will always be computed
+        phonon.run_band_structure(
+            qpoints, path_connections=connections, with_eigenvectors=True
+        )
+        phonon.write_yaml_band_structure(filename=_DEFAULT_FILE_PATHS["band_structure"])
+        bs_symm_line = get_ph_bs_symm_line(
+            _DEFAULT_FILE_PATHS["band_structure"],
+            labels_dict=kpath_dict,
+            has_nac=born is not None,
+        )


can more code be reused from phonon.py? If we have an update for the plotting, we would need to fix it here as well. Same for the code below.

JaGeo · 2026-04-08T10:25:44Z

+from importlib.util import find_spec
+
+if not find_spec("openff"):
+    raise ImportError(
+        "openff must be installed via conda forge to use with atomate2:\n"
+        "conda install -c conda-force openff"
+    )
+


can you check if this is consistent with how we handle this accross atomate2?

JaGeo · 2026-04-08T10:28:19Z

+    assert_allclose(
+        ph_doc.primitive_matrix,
+        [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
+        rtol=1e-5,
+        atol=1e-10,
+    )
+    assert ph_doc.code == "vasp"
+    assert isinstance(
+        ph_doc.post_process_settings,
+        PhononComputationalSettings,
+    )
+    assert ph_doc.post_process_settings.npoints_band == 101
+    assert ph_doc.post_process_settings.kpath_scheme == "seekpath"
+    assert ph_doc.post_process_settings.kpoint_density_dos == 7000
+
+    assert ph_doc.chemsys == "Si"


I don't see a test that actually checks the new implemented functionality. How do we make sure that the results stay consistent?

JaGeo · 2026-04-08T10:34:27Z

Hi @hrushikesh-s ,

I left a few comments.

My main points:

pheasy functionality must be tested, e.g., by testing some of the phonon results.
could you check that both Grüneisen and QHA workflow still work in practice when they are run with fireworks or jobflow-remote. The data objects are a really important point
should we provide a forcefield implementation for testing?
should we provide a tutorial for pheasy? if we had a forcefield implementation, this would be much easier to do.
conflicts need to be solved :)

esoteric-ephemera · 2026-04-08T17:07:37Z

Hey @hrushikesh-s sorry I missed your messages. These schema changes are very much intentional:

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

This is to explicitly allow for storing these as separate objects. PhononBSDOSTask should go to regular mongo collections, whereas band structures and DOS should go to GridFS

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

There is an opt-in setting for using the new emmet models. The default is still to use the pymatgen models in atomate2 (opt-out).

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

There is no reason to store free_energies, heat_capacities, internal_energies, entropies, and temperatures in the document, since these are computed from a set of temperatures. What if the user wants a different set of temps than the one prescribed in the document?

The uuids and jobdirs are stored in a calc_meta field

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

A model computed field will still be saved in the document if it has been calculated. It is just a way to defer calculating an expensive model field until the user requests it

Regarding the other fields being renamed, the document model explicitly handles the migration internally. You don't have to do anything to coerce the fields. Put a decent amount of work into it to do that since it needed to migrate our existing data seamlessly too

Please revert these changes regarding the schema or communicate what changes you need in the schema to get the workflows to run correctly

hrushikesh-s · 2026-04-08T19:18:38Z

Hi @JaGeo and @esoteric-ephemera, thanks for your detailed comments. I will start working on the comments this Friday and will keep you updated.

JaGeo · 2026-05-03T12:05:14Z

+    # When this code is run on Github tests, it is failing because it is
+    # not able to find the FORCE_CONSTANTS file. This is because the file is
+    # somehow getting generated in some temp directory. Can you fix the bug?


i guess this works now as well

JaGeo · 2026-07-01T18:55:53Z

@hrushikesh-s do you have a suggestion for the timeline? More and more conflicts start to show up and it will only get harder to finally merge

Resolve conflicts: - pyproject.toml: keep main's phonopy<4 pin alongside pheasy/alamode extras - common/flows/phonons.py: keep main's TorchSim-aware phonon_displacement_maker typing together with the phonon_doc_schema switch - common/jobs/phonons.py: adopt main's batched/socket run_phonon_displacements (TorchSim + check_class_name handling) while keeping store_displaced_structures; drop duplicated get_factor in favor of the schemas.phonons implementation - tests/aims: keep compat-accessor assertions with main's updated reference values; drop test_phonon_default_socket_flow (removed on main) - tests/forcefields: keep emmet-schema assertions (flow runs with phonon_doc_schema='emmet'); make reference values CHGNet-variant aware Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TJTjGwg4Finfu8JeXLFBA3

- restore tests/common/schemas/test_phonons.py: the legacy schema is kept, so its tests are kept as well - openff/__init__.py: use the try/except ImportError pattern consistent with the rest of atomate2 (and fix conda-forge typo) - pheasy.py: replace the 1.89 Angstrom->Bohr factor with a full-precision ANGSTROM_TO_BOHR constant (CODATA 2018) - factor band-structure and DOS post-processing/plotting into shared _run_band_structure_and_plot/_run_total_dos_and_plot helpers in common/jobs/phonons.py, reused by pheasy.py (3 duplicated blocks removed) - tests/vasp/flows/test_pheasy.py: assert on the actual phonon results (acoustic sum rule at Gamma, max optical branch frequency, 0 K limits, room-T heat capacity, Dulong-Petit high-T limit) - tests/forcefields: anchor emmet-schema thermo assertions to the established reference values from main for both CHGNet variants - complete the pheasy flow docstring wording Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TJTjGwg4Finfu8JeXLFBA3

- tutorials/pheasy_workflow.ipynb: mock-VASP tutorial for the pheasy lattice-dynamics workflow (mirrors the Si test data), with pointers to the anharmonic/renormalization options and the forcefield PhononMaker - listed in tutorials/tutorials.md toctree - excluded from the notebook CI job (which does not install the pheasy extra), following the openmm/torchsim/lammps pattern Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TJTjGwg4Finfu8JeXLFBA3

JaGeo · 2026-08-15T05:25:46Z

    return Response(output={"plus": plus_struct, "minus": minus_struct})


-@job(data=[PhononBSDOSDoc])


Are you sure this should be removed?

JaGeo · 2026-08-15T05:26:56Z

+    ALM = None
+
+# CODATA 2018: 1 Angstrom = 1 / 0.529177210903 Bohr
+ANGSTROM_TO_BOHR = 1.8897261246257702


Are you using this at multiple places? If you, please make a module for it. Eg "utils.units.py"

leslie-zheng and others added 30 commits September 9, 2024 14:02

Add pheasy branch for phonon calculation using LASSO

0775785

pheasy_phonons

7891554

add_pheasy_to_vasp_folder

d643fc1

Add_pheasy_to_vasp_file

93219ce

Merge branch 'main' into atomate2_jz_pheasy

f4b59c6

Merge branch 'main' into atomate2_jz_pheasy

e514969

Modified some parts based on Janine's comments.

11d546b

Modified some parts based on Janine's comments.

Merge branch 'atomate2_jz_pheasy' of https://github.com/leslie-zheng/…

13acf5a

…atomate2 into atomate2_jz_pheasy

directly import the class methods from phonons

57ab59f

clean up the code

647fe49

remove some files.

94a1acc

minor change

b92e34e

allow the users to define the number of displacements for random-disp…

05650d0

…lacement method.

format_adjustment

0bf1bf8

format_adjustment

e9cd8a6

small update

2bacc86

clean up the code and add more comments

4535497

minor update

eab1fe6

allow the users to control the symmetry precision

36aa5b7

Lower the symmetry precision to allow pheasy to find a correct space …

c69df93

…group for crystals.

Minor update

92ea25a

minor adjustment

5d6f122

minor update for flow/pheasy.py

e17a316

resuse some jobs from phonons

f46c2fd

clean up the job(generate_phonon_displacements)

34a197e

finished cleaning up the pheasy jobs module

be89bce

finished cleaning up the shemas/pheasy

1316b1d

small adjustment to pass the lint

833205a

raise a error if ALM is not installed.

f741a8c

minor update

30de21a

hrushikesh-s added 2 commits March 27, 2026 10:53

fixes to make the phonon related workflows compatible with original a…

e355849

…tomate2 data schema

lint fix and fix to phonon aims tutorial

5072c47

hrushikesh-s and others added 2 commits March 27, 2026 12:46

Backward compatibility for older atomate2 tests/callers

4bf3f8c

Merge branch 'main' into atomate2_jz_pheasy_anharmonic

bfec8ff

JaGeo reviewed Apr 8, 2026

View reviewed changes

Comment thread src/atomate2/common/jobs/pheasy.py Outdated

Apply suggestion from @JaGeo

8c336d5

JaGeo reviewed Apr 8, 2026

View reviewed changes

JaGeo reviewed May 3, 2026

View reviewed changes

Hrushikesh Sahasrabuddhe and others added 4 commits August 15, 2026 03:06

Apply pre-commit fixes to pheasy tutorial notebook

be36d72

JaGeo reviewed Aug 15, 2026

View reviewed changes

Comment thread tests/forcefields/flows/test_phonon.py

JaGeo reviewed Aug 15, 2026

View reviewed changes

		return Response(output={"plus": plus_struct, "minus": minus_struct})


		@job(data=[PhononBSDOSDoc])

		@@ -0,0 +1,362 @@
		"""Flow for calculating (an)harmonic FCs and phonon energy renorma. with pheasy."""

Uh oh!

Conversation

hrushikesh-s commented Nov 22, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Additional dependencies introduced (if any)

Uh oh!

esoteric-ephemera commented Mar 27, 2026

Uh oh!

hrushikesh-s commented Mar 27, 2026

Uh oh!

hrushikesh-s commented Mar 27, 2026

Uh oh!

JaGeo commented Mar 31, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JaGeo commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

esoteric-ephemera commented Apr 8, 2026

Uh oh!

hrushikesh-s commented Apr 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JaGeo commented Jul 1, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

hrushikesh-s commented Nov 22, 2024 •

edited

Loading

JaGeo commented Apr 8, 2026 •

edited

Loading