Tutorials for QHA and Grüneisen workflows (#1122)

* add info on jobflow remote and lobster workflow

* remove file and fix linting

* add another phonon example

* add tutorial for phonons including mock_vasp

* add tutorial test

* test tutorial test

* test tutorial test

* test tutorial test

* test tutorial test

* split up workflow again

* split up workflow again

* split up workflow again

* split up workflow again

* add automerge

* add automerge

* add mock lobster and a lobster tutorial

* fix bug in tutorial and fix calc summary

* add plot

* fix linting

* fix linting

* more type hints

* fix linting

* fix linting

* fix linting

* fix linting

* fix more linting

* fix final linting

* Update pyproject.toml

* adapt tutorial

* fix linting and add a tmp dir to tutorial execution

* remove file

* print ref and actual values in testing.lobster.verify_inputs ValueError

* add a qha tutorial

* add unit in document

* add tutorials to doc

* fix linting

* fix syntax

* add tutorials to doc attempt2

* fix line length

* fix line length

* final fix linting

* test fixing the linter again

* update tests

* fix linting

* fix linting

* fix more linting

* fix more linting

* fix more linting

* fix tutorial

* update gruneisen workflow

* update gruneisen workflow

* update gruneisen workflow

* update test

* fix linting

* fix linting

* fix linting

* fix linting

* hopefully fix linting errors

* exclude grunisen file from ruff

* ADD COMMENTS

---------

Co-authored-by: Janosh Riebesell <[email protected]>

Author: JaGeo

.github/workflows/docs.yml

@@ -35,6 +35,12 @@ jobs:
           python -m pip install --upgrade pip
           pip install .[strict,docs]
 
+      - name: Copy tutorials
+        run: |
+          cp -r tutorials docs/
+          jupyter nbconvert --to markdown docs/tutorials/*.ipynb
+          jupyter nbconvert --to markdown docs/tutorials/*/*.ipynb
+
       - name: Build
         run: sphinx-build docs docs_build
 

.gitignore

@@ -5,6 +5,8 @@ docs/_build/*
 docs/_build/*/*
 docs/_build/*/*/*
 docs_build/*
+docs/tutorials/*
+docs/tutorials/*/*
 
 # C extensions
 *.so

.pre-commit-config.yaml

@@ -7,6 +7,7 @@ repos:
   hooks:
   - id: ruff
     args: [--fix]
+    exclude: tutorials/grueneisen_workflow.ipynb
   - id: ruff-format
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v5.0.0

docs/index.md

@@ -95,6 +95,12 @@ def make(self, structure: Structure, prev_dir: str | Path = None) -> Flow:
             )
             relax_flow.name = "EOS equilibrium relaxation"
 
+            try:
+                if len(relax_flow.jobs) > 1:
+                    for job in relax_flow.jobs:
+                        job.append_name(" EOS equilibrium relaxation")
+            except AttributeError:
+                pass
             flow_output["initial_relax"] = {
                 "E0": relax_flow.output.output.energy,
                 "V0": relax_flow.output.structure.volume,
@@ -153,6 +159,12 @@ def make(self, structure: Structure, prev_dir: str | Path = None) -> Flow:
                 prev_dir=prev_dir,
             )
             relax_job.name += f" deformation {frame_idx}"
+            try:
+                if len(relax_job.jobs) > 1:
+                    for job in relax_job.jobs:
+                        job.append_name(f" deformation {frame_idx}")
+            except AttributeError:
+                pass
             jobs["relax"].append(relax_job)
 
             if self.static_maker:

src/atomate2/common/flows/eos.py

@@ -37,8 +37,8 @@ class PhononQHADoc(StructureMetadata, extra="allow"):  # type: ignore[call-arg]
     )
     helmholtz_volume: Optional[list[list[float]]] = Field(
         None,
-        description="Free energies at temperatures and volumes."
-        "shape (temperatures, volumes)",
+        description="Free energies (eV) at temperatures and volumes (Angstrom^3)."
+        "shape (temperatures, volumes)",  # TODO: add units here
     )
     volume_temperature: Optional[list[float]] = Field(
         None,

src/atomate2/common/schemas/qha.py

@@ -13,8 +13,8 @@
 
 # mapping from job name to directory containing test files
 ref_paths = {
-    "Relaxation calculation 1": "double-relax-si/relax-1",
-    "Relaxation calculation 2": "double-relax-si/relax-2",
+    "Relaxation calculation 1 EOS equilibrium relaxation": "double-relax-si/relax-1",
+    "Relaxation calculation 2 EOS equilibrium relaxation": "double-relax-si/relax-2",
     "Relaxation calculation (fixed cell) deformation 0": "eos-si/0",
     "Relaxation calculation (fixed cell) deformation 1": "eos-si/1",
     "Relaxation calculation (fixed cell) deformation 2": "eos-si/2",

tests/aims/test_flows/test_eos.py

@@ -0,0 +1 @@
+[]

tests/test_data/vasp/Si_gruneisen_tutorial/dft_phonon_static_1_1_ground_24/inputs/INCAR.gz

@@ -0,0 +1 @@
+{"job":{"@module":"jobflow.core.job","@class":"Job","@version":"0.1.18","function":{"@module":"atomate2.vasp.jobs.base","@callable":"BaseVaspMaker.make","@bound":{"@module":"atomate2.vasp.jobs.phonons","@class":"PhononDisplacementMaker","@version":"0.0.18","name":"dft phonon static eos deformation 1","input_set_generator":{"@module":"atomate2.vasp.sets.core","@class":"StaticSetGenerator","@version":"0.0.18","structure":null,"config_dict":{"PARENT":"VASPIncarBase","INCAR":{"ALGO":"Fast","EDIFF":0.00001,"EDIFFG":-0.02,"ENAUG":1360,"ENCUT":680,"IBRION":2,"ISIF":3,"ISMEAR":0,"ISPIN":2,"LAECHG":true,"LASPH":true,"LCHARG":true,"LELF":false,"LMIXTAU":true,"LORBIT":11,"LREAL":false,"LVTOT":true,"LWAVE":false,"NELM":200,"NSW":99,"PREC":"Accurate","SIGMA":0.05,"MAGMOM":{"Ce":5,"Ce3+":1,"Co":0.6,"Co3+":0.6,"Co4+":1,"Cr":5,"Dy3+":5,"Er3+":3,"Eu":10,"Eu2+":7,"Eu3+":6,"Fe":5,"Gd3+":7,"Ho3+":4,"La3+":0.6,"Lu3+":0.6,"Mn":5,"Mn3+":4,"Mn4+":3,"Mo":5,"Nd3+":3,"Ni":5,"Pm3+":4,"Pr3+":2,"Sm3+":5,"Tb3+":6,"Tm3+":2,"V":5,"W":5,"Yb3+":1},"GGA":"PS","LDAU":true,"LDAUJ":{"F":{"Co":0,"Cr":0,"Fe":0,"Mn":0,"Mo":0,"Ni":0,"V":0,"W":0},"O":{"Co":0,"Cr":0,"Fe":0,"Mn":0,"Mo":0,"Ni":0,"V":0,"W":0}},"LDAUL":{"F":{"Co":2,"Cr":2,"Fe":2,"Mn":2,"Mo":2,"Ni":2,"V":2,"W":2},"O":{"Co":2,"Cr":2,"Fe":2,"Mn":2,"Mo":2,"Ni":2,"V":2,"W":2}},"LDAUTYPE":2,"LDAUU":{"F":{"Co":3.32,"Cr":3.7,"Fe":5.3,"Mn":3.9,"Mo":4.38,"Ni":6.2,"V":3.25,"W":6.2},"O":{"Co":3.32,"Cr":3.7,"Fe":5.3,"Mn":3.9,"Mo":4.38,"Ni":6.2,"V":3.25,"W":6.2}},"LDAUPRINT":1},"POTCAR_FUNCTIONAL":"PBE_54","POTCAR":{"Ac":"Ac","Ag":"Ag","Al":"Al","Am":"Am","Ar":"Ar","As":"As","At":"At","Au":"Au","B":"B","Ba":"Ba_sv","Be":"Be","Bi":"Bi_d","Br":"Br","C":"C","Ca":"Ca_sv","Cd":"Cd","Ce":"Ce","Cf":"Cf","Cl":"Cl","Cm":"Cm","Co":"Co","Cr":"Cr_pv","Cs":"Cs_sv","Cu":"Cu","Dy":"Dy_3","Er":"Er_3","Eu":"Eu_2","F":"F","Fe":"Fe","Fr":"Fr_sv","Ga":"Ga_d","Gd":"Gd_3","Ge":"Ge_d","H":"H","He":"He","Hf":"Hf_pv","Hg":"Hg","Ho":"Ho_3","I":"I","In":"In_d","Ir":"Ir","K":"K_sv","Kr":"Kr","La":"La","Li":"Li_sv","Lu":"Lu_3","Mg":"Mg","Mn":"Mn_pv","Mo":"Mo_sv","N":"N","Na":"Na_pv","Nb":"Nb_sv","Nd":"Nd_3","Ne":"Ne","Ni":"Ni","Np":"Np","O":"O","Os":"Os","P":"P","Pa":"Pa","Pb":"Pb_d","Pd":"Pd","Pm":"Pm_3","Po":"Po_d","Pr":"Pr_3","Pt":"Pt","Pu":"Pu","Ra":"Ra_sv","Rb":"Rb_sv","Re":"Re","Rh":"Rh_pv","Rn":"Rn","Ru":"Ru_pv","S":"S","Sb":"Sb","Sc":"Sc_sv","Se":"Se","Si":"Si","Sm":"Sm_3","Sn":"Sn_d","Sr":"Sr_sv","Ta":"Ta_pv","Tb":"Tb_3","Tc":"Tc_pv","Te":"Te","Th":"Th","Ti":"Ti_sv","Tl":"Tl_d","Tm":"Tm_3","U":"U","V":"V_sv","W":"W_sv","Xe":"Xe","Y":"Y_sv","Yb":"Yb_3","Zn":"Zn","Zr":"Zr_sv"},"KPOINTS":{"reciprocal_density":64,"reciprocal_density_metal":200}},"files_to_transfer":{},"user_incar_settings":{"GGA":"PE","IBRION":-1,"ISPIN":1,"ISMEAR":0,"ISIF":3,"ENCUT":700,"EDIFF":1e-7,"LAECHG":false,"LREAL":false,"ALGO":"Normal","NSW":0,"LCHARG":false,"LWAVE":false,"LVTOT":false,"LORBIT":null,"LOPTICS":false,"SIGMA":0.05,"ISYM":0,"KSPACING":0.1,"NPAR":4},"user_kpoints_settings":{},"user_potcar_settings":{},"constrain_total_magmom":false,"sort_structure":true,"user_potcar_functional":"PBE_54","force_gamma":true,"reduce_structure":null,"vdw":null,"use_structure_charge":false,"standardize":false,"sym_prec":0.1,"international_monoclinic":true,"validate_magmom":true,"inherit_incar":false,"auto_kspacing":false,"auto_ismear":true,"auto_ispin":false,"auto_lreal":false,"auto_metal_kpoints":true,"bandgap_tol":0.0001,"bandgap":null,"prev_incar":null,"prev_kpoints":null,"_valid_potcars":null,"lepsilon":false,"lcalcpol":false},"write_input_set_kwargs":{},"copy_vasp_kwargs":{},"run_vasp_kwargs":{"handlers":{}},"task_document_kwargs":{},"stop_children_kwargs":{},"write_additional_data":{}}},"function_args":[],"function_kwargs":{"structure":{"@module":"pymatgen.core.structure","@class":"Structure","charge":0.0,"lattice":{"matrix":[[5.4688440475333735,1.9420841e-9,-1.3631176e-9],[1.8873996e-9,5.468844039752649,1.36496088e-8],[-1.6414625e-9,1.36385824e-8,5.468844048018874]],"pbc":[true,true,true],"a":5.4688440475333735,"b":5.468844039752649,"c":5.468844048018874,"alpha":89.99999971410811,"beta":90.00000003147827,"gamma":89.99999995987942,"volume":163.5635832932623},"properties":{},"sites":[{"species":[{"element":"Si","occu":1}],"abc":[0.7499999987630162,0.7499999947041829,0.2499999997033413],"properties":{},"label":"Si","xyz":[4.101633029890342,4.101633005718698,1.3672110195972067]},{"species":[{"element":"Si","occu":1}],"abc":[6.7221535e-9,0.4999999981637231,0.4999999924107712],"properties":{},"label":"Si","xyz":[3.688537771407228e-8,2.7344220166533035,2.7344219893299324]},{"species":[{"element":"Si","occu":1}],"abc":[0.7499999989151149,0.2500000047586823,0.7499999999638405],"properties":{},"label":"Si","xyz":[4.101633028957716,1.3672110476481534,4.101633038206469]},{"species":[{"element":"Si","occu":1}],"abc":[5.6380927e-9,0.9999999999281641,5.5413096e-9],"properties":{},"label":"Si","xyz":[3.272124929260494e-8,5.46884403935979,4.3954166815523935e-8]},{"species":[{"element":"Si","occu":1}],"abc":[0.2500000002832934,0.7499999958083237,0.7500000001514664],"properties":{},"label":"Si","xyz":[1.3672110136170836,4.10163301760532,4.101633046738929]},{"species":[{"element":"Si","occu":1}],"abc":[0.4999999951448473,0.4999999996027782,6.4697545e-9],"properties":{},"label":"Si","xyz":[2.7344219981583135,2.7344220186750223,4.1525323990664546e-8]},{"species":[{"element":"Si","occu":1}],"abc":[0.2499999992626485,0.2500000068831767,0.2500000011144152],"properties":{},"label":"Si","xyz":[1.3672110079123674,1.3672110514763487,1.3672110211709045]},{"species":[{"element":"Si","occu":1}],"abc":[0.4999999952708336,1.509619e-10,0.4999999946451084],"properties":{},"label":"Si","xyz":[2.7344219970828822,8.615920254827166e-9,2.7344219940428114]}]},"prev_dir":"i03r09c03s03.sng.lrz.de:/hppfs/scratch/00/di82tut/autoplex_test/run/00/0a/cc/000acc98-19af-49ee-9f52-378a2e2f0951_1"},"output_schema":{"@module":"emmet.core.tasks","@callable":"TaskDoc","@bound":null},"uuid":"8a70ab31-57c5-4b5d-a2f3-1d23e48fc4a1","index":1,"name":"dft phonon static eos deformation 1","metadata":{},"config":{"@module":"jobflow.core.job","@class":"JobConfig","@version":"0.1.18","resolve_references":true,"on_missing_references":"error","manager_config":{"resources":{"nodes":3,"partition":"micro","time":"02:55:00","ntasks":144,"qverbatim":"#SBATCH --get-user-env","mail_user":"your_email@adress","mail_type":"ALL","account":"pn73da"}},"expose_store":false,"pass_manager_config":true,"response_manager_config":{}},"hosts":["1c58eab1-79aa-4589-b8ca-a553c147b0ec","83dc9f79-ca39-42c0-810e-1fadbc7002e1","ed2bede8-1222-41e6-b874-b420bbe11000"],"metadata_updates":[],"config_updates":[{"config":{"manager_config":{"resources":{"nodes":3,"partition":"micro","time":"02:55:00","ntasks":144,"qverbatim":"#SBATCH --get-user-env","mail_user":"your_email@adress","mail_type":"ALL","account":"pn73da"}}},"name_filter":"dft phonon static","function_filter":null,"attributes":null}],"name_updates":[{"append_str":" eos deformation 1","prepend":false}],"data":[{"@module":"pymatgen.electronic_structure.bandstructure","@callable":"BandStructure","@bound":null},{"@module":"pymatgen.electronic_structure.bandstructure","@callable":"BandStructureSymmLine","@bound":null},{"@module":"pymatgen.electronic_structure.dos","@callable":"DOS","@bound":null},{"@module":"pymatgen.electronic_structure.dos","@callable":"Dos","@bound":null},{"@module":"pymatgen.electronic_structure.dos","@callable":"CompleteDos","@bound":null},{"@module":"pymatgen.io.vasp.outputs","@callable":"Locpot","@bound":null},{"@module":"pymatgen.io.vasp.outputs","@callable":"Chgcar","@bound":null},{"@module":"pymatgen.io.vasp.outputs","@callable":"Wavecar","@bound":null},{"@module":"pymatgen.core.trajectory","@callable":"Trajectory","@bound":null},"force_constants","normalmode_eigenvecs","bandstructure"]},"store":{"@module":"jobflow.core.store","@class":"JobStore","@version":"0.1.18","docs_store":{"@module":"jobflow_remote.remote.data","@class":"StdJSONStore","@version":"0.1.4","paths":["/hppfs/scratch/00/di82tut/autoplex_test/run/8a/70/ab/8a70ab31-57c5-4b5d-a2f3-1d23e48fc4a1_1/remote_job_data.json"]},"additional_stores":{"data":{"@module":"jobflow_remote.remote.data","@class":"StdJSONStore","@version":"0.1.4","paths":["/hppfs/scratch/00/di82tut/autoplex_test/run/8a/70/ab/8a70ab31-57c5-4b5d-a2f3-1d23e48fc4a1_1/additional_store_data.json"]}},"save":{},"load":false}}

tests/test_data/vasp/Si_gruneisen_tutorial/dft_phonon_static_1_1_ground_24/inputs/POSCAR.gz

@@ -0,0 +1 @@
+{"response": {"output": null, "detour": null, "addition": null, "replace": null, "stored_data": {"custodian": [{"corrections": [], "job": {"@module": "custodian.vasp.jobs", "@class": "VaspJob", "@version": "2024.10.3", "vasp_cmd": ["vasp6", "-n", "144", ">vasp.out"], "output_file": "vasp.out", "stderr_file": "std_err.txt", "suffix": "", "final": true, "backup": true, "auto_npar": false, "auto_gamma": true, "settings_override": null, "gamma_vasp_cmd": ["vasp6", "-n", "144", "-s", "gam", ">vasp.out"], "copy_magmom": false, "auto_continue": false, "update_incar": false}, "@module": "emmet.core.tasks", "@class": "CustodianDoc", "@version": null}]}, "stop_children": false, "stop_jobflow": false, "job_dir": null, "@module": "jobflow.core.job", "@class": "Response", "@version": "0.1.18"}, "error": null, "start_time": {"@module": "datetime", "@class": "datetime", "string": "2025-02-12 10:21:44.978482"}, "end_time": {"@module": "datetime", "@class": "datetime", "string": "2025-02-12 10:24:33.289795"}}

tests/test_data/vasp/Si_gruneisen_tutorial/dft_phonon_static_1_1_ground_24/inputs/POTCAR.spec.gz

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+#SBATCH --partition=micro
+#SBATCH --job-name=dft_phonon_static_eos_deformation_1
+#SBATCH --nodes=3
+#SBATCH --ntasks=144
+#SBATCH --time=02:55:00
+#SBATCH --account=pn73da
+#SBATCH --mail-user=your_email@adress
+#SBATCH --mail-type=ALL
+#SBATCH --output=/hppfs/scratch/00/di82tut/autoplex_test/run/8a/70/ab/8a70ab31-57c5-4b5d-a2f3-1d23e48fc4a1_1/queue.out
+#SBATCH --error=/hppfs/scratch/00/di82tut/autoplex_test/run/8a/70/ab/8a70ab31-57c5-4b5d-a2f3-1d23e48fc4a1_1/queue.err
+#SBATCH --get-user-env
+cd /hppfs/scratch/00/di82tut/autoplex_test/run/8a/70/ab/8a70ab31-57c5-4b5d-a2f3-1d23e48fc4a1_1
+export ATOMATE2_CONFIG_FILE="/dss/dsshome1/00/di82tut/.atomate2/config/atomate2.yaml"
+source activate autoplex_test
+module load slurm_setup
+module load vasp/6.1.2
+
+jf -fe execution run /hppfs/scratch/00/di82tut/autoplex_test/run/8a/70/ab/8a70ab31-57c5-4b5d-a2f3-1d23e48fc4a1_1