Add thermal expansion workflow (CTEMaker) by hrushikesh-s · Pull Request #1559 · materialsproject/atomate2

hrushikesh-s · 2026-09-24T15:56:10Z

Summary

This PR adds a workflow for the thermal expansion tensor from third-order force constants. It builds on #1558 and needs its anharmonic fit options. Until #1558 is merged, this PR also shows its changes.

New CTEMaker for VASP (atomate2.vasp.flows.cte) and for force fields (atomate2.forcefields.flows.cte), with a shared BaseCTEMaker in atomate2.common.flows.cte.
The flow runs a tight relaxation. The relaxed structure then goes to the pheasy PhononMaker and to the existing ElasticMaker, with no second relaxation in either. The two sub-flows do not depend on each other. The elastic fit gets the stress of the relaxation, as in the elastic flow.
The pheasy phonon maker runs with cal_anhar_fcs=True, the one-shot fit, 0.03 Å displacements and min_length=12.0. The fit methods are set by anhar_fit_methods of the phonon maker, so the cocktail fit can be used too.
New job compute_cte reads the force constants from the pheasy job folder. CTEDocument.from_force_constants then gets the mode Grüneisen tensors from phono3py and computes the thermal expansion tensor from the mode heat capacities, the Grüneisen tensors and the elastic compliance.
If a frequency on the q-point mesh is below -tol_imaginary_modes (0.1 THz by default), a warning is raised and the thermal expansion of that fit is not computed.
The job checks that the elastic structure has the same lattice and atoms as the phonon unit cell, so both tensors are in the same frame.
New output schema CTEDocument, with one CTEResult per fit method. Each result holds the thermal expansion tensor and the volumetric thermal expansion at each temperature, the heat-capacity weighted mean Grüneisen tensor, and the lowest frequency on the mesh.
duecredit entries for phonopy and phono3py.
A new section in docs/user/codes/vasp.md, with an example and a note on r2SCAN.
Tutorial: tutorials/cte_workflow.ipynb runs the workflow with three MACE potentials. Section 1 runs NaCl, KCl, MgO, CaO and GaAs at the default settings and checks the results against finite displacements with phono3py. Section 2 converges the third-order cutoff and the supercell for Si.

Additional dependencies introduced (if any)

phono3py>=4.5 is added to the pheasy extra. It computes the mode Grüneisen tensors from the second- and third-order force constants. phono3py 4.5.0 requires phonopy 4.5, so atomate2[pheasy] installs phonopy 4.5.

TODO (if any)

There is no VASP test with mock data yet. It needs reference data for an anharmonic phonon run and an elastic run.
To merge Fix pheasy anharmonic fitting and add fit options #1558 first. This branch will then be rebased onto main.

Checklist

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 · 2026-09-24T15:58:25Z

Hi @JaGeo, we will also share benchmarking results for this PR.
Either @ZKC19940412 or I will post them here.

JaGeo · 2026-09-24T17:00:34Z

@hrushikesh-s is there a connection to the qha Maker that one could exploit?

# Conflicts: # pyproject.toml

…iles

…nsion tutorial

… and on GitHub

…displacement references

hrushikesh-s · 2026-10-02T01:10:30Z

@hrushikesh-s is there a connection to the qha Maker that one could exploit?

I went through the QHA workflow for parts to reuse. The two workflows get the thermal expansion in different ways. QhaMaker runs harmonic phonons at several volumes, and phonopy's QHA fits the free energy against volume. CTEMaker runs one pheasy fit with third-order force constants at one volume, and phono3py gives the mode Grüneisen tensors from them. The thermal expansion tensor then follows from these tensors and the elastic compliance. So the volume scan, the EOS fit and PhonopyQHA have no counterpart in CTEMaker.

CTEMaker already reuses the pheasy PhononMaker, the ElasticMaker, structure_to_primitive and structure_to_conventional, and the PhononDoc type and job folder lookup from the Grüneisen jobs.

hrushikesh-s · 2026-10-02T01:11:26Z

Hi @JaGeo, this is ready for review as well. It builds on #1558 and includes the same --tol change. The benchmarks we promised are in the tutorial, tutorials/cte_workflow.ipynb. Five materials are run with three MACE potentials at the default settings and checked against finite displacements in the same supercell and in larger ones. Si has a full cutoff and supercell convergence study, with finite displacements up to a 10x10x10 supercell. I ran the notebook end-to-end on NERSC's Perlmutter with the final code.

JaGeo · 2026-10-02T06:08:59Z

Let's start with the other one

…easy supercell job

# Conflicts: # docs/user/codes/vasp.md # pyproject.toml

JaGeo · 2026-10-02T16:12:05Z


 Alternatively, users can accelerate the calculation of interatomic force constants using the machine-learning-based [Pheasy code](https://doi.org/10.48550/arXiv.2508.01020).
 The `pheasy` extra, `pip install "atomate2[pheasy]"`, installs the pheasy version this workflow needs, together with phonopy and ALM.
+It also installs phono3py for the thermal expansion workflow.


Should we have an additional field for that? historically, phono3py had lots of installation issues and I would only install it of necessary

Yess valid point. I have now moved phono3py installation out of the pheasy extra into a new phono3py extra!

JaGeo · 2026-10-02T16:16:52Z

+    return np.array(alphas), mean_gruneisen
+
+
+def _expand_born_to_unitcell(phonon: Phonopy) -> np.ndarray:


This is a specific requirement of this workflow, right? Or do we need this elsewhere as well?

Yes, this is specific to this workflow.. The other phonon workflows pass the Born charges to phonopy, which maps them onto its cells itself.
phonopy.yaml stores the Born charges for phonopy's primitive cell, but phono3py uses the whole unit cell as its primitive cell. With the default primitive cell the two are the same and the charges are passed through. With use_symmetrized_structure="conventional" the unit cell is larger, so the charges are copied onto the matching unit cell atoms.

Nothing else in atomate2 builds a phono3py object from phonopy output, so I have kept it as a private helper next to the code that uses it...

JaGeo · 2026-10-02T16:21:53Z

Rest looks good. I would make a note in the Workflow itself and the documentation that more testing might be required

hrushikesh-s · 2026-10-02T16:29:42Z

Rest looks good. I would make a note in the Workflow itself and the documentation that more testing might be required

@JaGeo, I have now added this note!

hrushikesh-s · 2026-10-02T16:48:21Z

@JaGeo, does this PR look good now?
Is this ready to merge?

JaGeo · 2026-10-02T16:52:57Z

It does look good but from the current workflow ouput, I cannot see if the tests actually run. Can you try to change the verbosity of the pytest outputs so that we can confirm all tests are running?

@hrushikesh-s

JaGeo · 2026-10-02T16:56:44Z

The time difference makes the PRs always a bit challenging 😅.

hrushikesh-s · 2026-10-02T17:40:38Z

It does look good but from the current workflow ouput, I cannot see if the tests actually run. Can you try to change the verbosity of the pytest outputs so that we can confirm all tests are running?

@hrushikesh-s

Done @JaGeo! I have now added -v to the pytest command of the test-non-ase jobs, so each test now prints its own line.

The time difference makes the PRs always a bit challenging 😅.

Yeah 😅

JaGeo · 2026-10-02T17:49:09Z

thanks! Can you also do that for all forcefield tests? Then, I think we are good to merge 😃

hrushikesh-s · 2026-10-02T18:04:01Z

thanks! Can you also do that for all forcefield tests? Then, I think we are good to merge 😃

@JaGeo, done!

JaGeo · 2026-10-02T18:06:50Z

@hrushikesh-s thanks! I did not find the tests yet? Could you check that the forcfield ones run?

JaGeo · 2026-10-02T18:09:17Z

Ah, they are in common! but you do use a forcefield right?

hrushikesh-s · 2026-10-02T18:24:26Z

Ah, they are in common! but you do use a forcefield right?

Yes, correct. I have now moved the two force field CTE tests to tests/forcefields/flows/test_cte.py. They only need EMT, so the numpy-limited forcefield job now also installs pheasy, ALM and phono3py and runs them there.
I have kept the other tests of get_cte and the Born charge mapping stay in tests/common/jobs/test_cte.py.

JaGeo · 2026-10-02T18:37:07Z

Just to make sure: the pheasy tests are also running in forcefields, right?

hrushikesh-s · 2026-10-02T18:38:11Z

Just to make sure: the pheasy tests are also running in forcefields, right?

No, they are not... I think they are in common.. Let me fix those as well.

JaGeo · 2026-10-02T18:39:22Z

Thanks and sorry that I overlooked this as well!

JaGeo · 2026-10-02T18:40:47Z

Maybe as an addition: so far, we had all workflows that can be run with focefields in the 'forcefield/flows' folder as well.

hrushikesh-s · 2026-10-02T18:56:49Z

@JaGeo, thanks for checking these issues!
The force field tests of both workflows are now in tests/forcefields/flows. test_pheasy.py runs the force field pheasy PhononMaker end to end with EMT forces for fcc Cu, and test_cte.py does the same for the force field CTEMaker. Both run in the numpy-limited forcefield job.

JaGeo · 2026-10-02T19:08:46Z

Thank you @hrushikesh-s !

Fix pheasy anharmonic fitting and add fit options

471a07b

leslie-zheng and others added 5 commits September 29, 2026 20:17

Update pheasy.py

db70c81

Update pheasy.py

e0e191b

Fix lint in pheasy job comments

537609c

Merge remote-tracking branch 'origin/main' into pheasy-anharmonic-fixes

26c433e

# Conflicts: # pyproject.toml

Run the pheasy short-cutoff refit in its own folder with the matrix f…

ac4d511

…iles

hrushikesh-s force-pushed the cte-workflow branch from 10c9ee2 to 4ad570c Compare September 30, 2026 16:17

hrushikesh-s added 5 commits September 30, 2026 15:46

Make pheasy read the supercell of the force data

c486887

Add thermal expansion workflow

c8734b5

Standardize the input cell in the thermal expansion workflow

7d25de7

Allow force field jobs without torch installed

2347c18

Add a thermal expansion tutorial

5bee251

hrushikesh-s force-pushed the cte-workflow branch from 389bfe9 to 5bee251 Compare September 30, 2026 23:00

hrushikesh-s added 6 commits October 1, 2026 06:04

Pin pheasy to the commit with the faster sensing matrix

f3f113a

Add the five-material and Si convergence sections to the thermal expa…

cecd36e

…nsion tutorial

Write the K^-1 units as plain text so the tutorial renders in VS Code…

32d7441

… and on GitHub

Converge the anharmonic LASSO fit with --tol 1e-8

c27615d

Update the thermal expansion tutorial with converged fits and finite-…

42b98c2

…displacement references

Update the run times in the thermal expansion tutorial

bc5f382

hrushikesh-s mentioned this pull request Oct 2, 2026

Fix pheasy anharmonic fitting and add fit options #1558

Merged

5 tasks done

hrushikesh-s requested a review from JaGeo October 2, 2026 01:14

hrushikesh-s changed the title ~~[WIP] Add thermal expansion workflow (CTEMaker)~~ Add thermal expansion workflow (CTEMaker) Oct 2, 2026

hrushikesh-s added 3 commits October 2, 2026 07:29

Link the phonon database and pass get_supercell_size_kwargs to the ph…

729ef46

…easy supercell job

Merge remote-tracking branch 'origin/main' into cte-workflow

c7a34d4

Note in the docs that the anharmonic pheasy workflow is less tested

ce11cb8

Merge remote-tracking branch 'origin/main' into cte-workflow

b10d4d5

# Conflicts: # docs/user/codes/vasp.md # pyproject.toml

JaGeo reviewed Oct 2, 2026

View reviewed changes

Move phono3py into its own extra

fc53293

Note that the thermal expansion workflow needs more testing

cb91f95

Run the non-ase tests with -v so each test shows in the CI log

ff0582a

Run the forcefield tests with -v as well

dcde48d

Move the force field CTE tests to tests/forcefields

8de4e04

Skip the force field CTE tests before importing pheasy

d46d2c9

hrushikesh-s added 2 commits October 2, 2026 11:48

Move the force field pheasy test to tests/forcefields

0a2256e

Run the force field pheasy workflow end to end with EMT

3b4d220

JaGeo merged commit c35d865 into materialsproject:main Oct 2, 2026
18 checks passed

hrushikesh-s mentioned this pull request Oct 2, 2026

Add a finite-temperature phonon workflow #1560

Open

4 tasks done

		return np.array(alphas), mean_gruneisen


		def _expand_born_to_unitcell(phonon: Phonopy) -> np.ndarray:

Conversation

hrushikesh-s commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Additional dependencies introduced (if any)

TODO (if any)

Checklist

Uh oh!

hrushikesh-s commented Sep 24, 2026

Uh oh!

JaGeo commented Sep 24, 2026

Uh oh!

hrushikesh-s commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hrushikesh-s commented Oct 2, 2026

Uh oh!

JaGeo commented Oct 2, 2026

Uh oh!

JaGeo Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

hrushikesh-s Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

JaGeo Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

hrushikesh-s Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

JaGeo commented Oct 2, 2026

Uh oh!

hrushikesh-s commented Oct 2, 2026

Uh oh!

hrushikesh-s commented Oct 2, 2026

Uh oh!

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

Uh oh!

Uh oh!

JaGeo commented Oct 2, 2026

Uh oh!

hrushikesh-s commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JaGeo commented Oct 2, 2026

Uh oh!

hrushikesh-s commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JaGeo commented Oct 2, 2026

Uh oh!

JaGeo commented Oct 2, 2026

Uh oh!

hrushikesh-s commented Oct 2, 2026

Uh oh!

JaGeo commented Oct 2, 2026

Uh oh!

hrushikesh-s commented Oct 2, 2026

Uh oh!

JaGeo commented Oct 2, 2026

Uh oh!

JaGeo commented Oct 2, 2026

Uh oh!

hrushikesh-s commented Oct 2, 2026

Uh oh!

Uh oh!

JaGeo commented Oct 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hrushikesh-s commented Sep 24, 2026 •

edited

Loading

hrushikesh-s commented Oct 2, 2026 •

edited

Loading

JaGeo commented Oct 2, 2026 •

edited

Loading

hrushikesh-s commented Oct 2, 2026 •

edited

Loading

hrushikesh-s commented Oct 2, 2026 •

edited

Loading