alff.phonon

alff.phonon

Modules:

• libpho_gpaw –

  Library for GPAW-based phonon calculations.

• libpho_lammps –

  Library for LAMMPS-based phonon calculations.

• phonon –

  Workflow for phonon calculation.

• utilpho –

  Utility functions for phonon calculations.

libpho_gpaw

Library for GPAW-based phonon calculations.

Classes:

• OperPhononGpawOptimize –
• OperPhononGpawOptimizeFixbox –

  Only need to redefine the prepare() method, to fix box during optimization.

• OperPhononGpawSinglepoint –

  Need to redefine the prepare() and postprocess() methods.

OperPhononGpawOptimize(work_dir, pdict, multi_mdict, mdict_prefix='gpaw')

Bases: OperPESGpawOptimize

Methods:

• prepare –
• postprocess –
• run –

  Function to submit jobs to remote machines.

Attributes:

• work_dir –
• pdict –
• mdict_list –
• task_dirs –
• op_name –
• task_filter –
• commandlist_list (list[list[str]]) –
• forward_files (list[str]) –
• backward_files (list[str]) –
• forward_common_files (list[str]) –
• backward_common_files (list[str]) –

work_dir = work_dir instance-attribute

pdict = pdict instance-attribute

mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute

task_dirs = self._load_task_dirs() instance-attribute

op_name = 'GPAW optimize' instance-attribute

task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': [K.FILE_FRAME_LABEL]} instance-attribute

commandlist_list: list[list[str]] instance-attribute

forward_files: list[str] instance-attribute

backward_files: list[str] instance-attribute

forward_common_files: list[str] instance-attribute

backward_common_files: list[str] = [] instance-attribute

prepare()

postprocess()

run()

Function to submit jobs to remote machines.

Note

• Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.

OperPhononGpawOptimizeFixbox(work_dir, pdict, multi_mdict, mdict_prefix='gpaw')

Bases: OperPESGpawOptimize

Only need to redefine the prepare() method, to fix box during optimization.

Methods:

• prepare –
• postprocess –
• run –

  Function to submit jobs to remote machines.

Attributes:

• op_name –
• work_dir –
• pdict –
• mdict_list –
• task_dirs –
• task_filter –
• commandlist_list (list[list[str]]) –
• forward_files (list[str]) –
• backward_files (list[str]) –
• forward_common_files (list[str]) –
• backward_common_files (list[str]) –

op_name = 'GPAW optimize fixed box' instance-attribute

work_dir = work_dir instance-attribute

pdict = pdict instance-attribute

mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute

task_dirs = self._load_task_dirs() instance-attribute

task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': [K.FILE_FRAME_LABEL]} instance-attribute

commandlist_list: list[list[str]] instance-attribute

forward_files: list[str] instance-attribute

backward_files: list[str] instance-attribute

forward_common_files: list[str] instance-attribute

backward_common_files: list[str] = [] instance-attribute

prepare()

postprocess()

run()

Function to submit jobs to remote machines.

Note

• Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.

OperPhononGpawSinglepoint(work_dir, pdict, multi_mdict, mdict_prefix='gpaw')

Bases: OperPESGpawOptimize

Need to redefine the prepare() and postprocess() methods.

Methods:

• prepare –
• postprocess –

  Postprocess the operation.

• run –

  Function to submit jobs to remote machines.

Attributes:

• op_name –
• work_dir –
• pdict –
• mdict_list –
• task_dirs –
• task_filter –
• commandlist_list (list[list[str]]) –
• forward_files (list[str]) –
• backward_files (list[str]) –
• forward_common_files (list[str]) –
• backward_common_files (list[str]) –

op_name = 'GPAW Singlepoint' instance-attribute

work_dir = work_dir instance-attribute

pdict = pdict instance-attribute

mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute

task_dirs = self._load_task_dirs() instance-attribute

task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': [K.FILE_FRAME_LABEL]} instance-attribute

commandlist_list: list[list[str]] instance-attribute

forward_files: list[str] instance-attribute

backward_files: list[str] instance-attribute

forward_common_files: list[str] instance-attribute

backward_common_files: list[str] = [] instance-attribute

prepare()

postprocess() -> list[list]

Postprocess the operation.

Includes: - Clean up unlabelled extxyz files - Collect forces from the output files

run()

Function to submit jobs to remote machines.

Note

• Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.

libpho_lammps

Library for LAMMPS-based phonon calculations.

Classes:

• OperPhononLammpsOptimize –
• OperPhononLammpsOptimizeFixbox –

  Only need to redefine the prepare() method, to fix box during optimization.

• OperPhononLammpsSinglepoint –

  Class to run LAMMPS singlepoint calculation, used for phonon calculation.

OperPhononLammpsOptimize(work_dir, pdict, multi_mdict, mdict_prefix='lammps')

Bases: OperPESLammpsOptimize

Methods:

• prepare –

  This function does:

• postprocess –

  This function does:

• run –

  Function to submit jobs to remote machines.

Attributes:

• work_dir –
• pdict –
• mdict_list –
• task_dirs –
• op_name –
• task_filter –
• commandlist_list (list[list[str]]) –
• forward_files (list[str]) –
• backward_files (list[str]) –
• forward_common_files (list[str]) –
• backward_common_files (list[str]) –

work_dir = work_dir instance-attribute

pdict = pdict instance-attribute

mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute

task_dirs = self._load_task_dirs() instance-attribute

op_name = 'LAMMPS optimize' instance-attribute

task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': ['frame_label.lmpdump']} instance-attribute

commandlist_list: list[list[str]] instance-attribute

forward_files: list[str] instance-attribute

backward_files: list[str] instance-attribute

forward_common_files: list[str] instance-attribute

backward_common_files: list[str] = [] instance-attribute

prepare()

This function does: - Prepare lammps_optimize and lammps_input files. - Convert extxyz to lmpdata. - Copy potential file to work_dir.

• Prepare the task_list
• Prepare forward & backward files
• Prepare commandlist_list for multi-remote submission

postprocess()

This function does: - Remove unlabeled .extxyz files, just keep the labeled ones. - Convert LAMMPS output to extxyz_labeled.

run()

Function to submit jobs to remote machines.

Note

• Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.

OperPhononLammpsOptimizeFixbox(work_dir, pdict, multi_mdict, mdict_prefix='lammps')

Bases: OperPESLammpsOptimize

Only need to redefine the prepare() method, to fix box during optimization.

Methods:

• prepare –

  This function does:

• postprocess –

  This function does:

• run –

  Function to submit jobs to remote machines.

Attributes:

• op_name –
• work_dir –
• pdict –
• mdict_list –
• task_dirs –
• task_filter –
• commandlist_list (list[list[str]]) –
• forward_files (list[str]) –
• backward_files (list[str]) –
• forward_common_files (list[str]) –
• backward_common_files (list[str]) –

op_name = 'LAMMPS optimize fixed box' instance-attribute

work_dir = work_dir instance-attribute

pdict = pdict instance-attribute

mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute

task_dirs = self._load_task_dirs() instance-attribute

task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': ['frame_label.lmpdump']} instance-attribute

commandlist_list: list[list[str]] instance-attribute

forward_files: list[str] instance-attribute

backward_files: list[str] instance-attribute

forward_common_files: list[str] instance-attribute

backward_common_files: list[str] = [] instance-attribute

prepare()

This function does: - Prepare lammps_optimize and lammps_input files. - Convert extxyz to lmpdata. - Copy potential file to work_dir.

• Prepare the task_list
• Prepare forward & backward files
• Prepare commandlist_list for multi-remote submission

postprocess()

This function does: - Remove unlabeled .extxyz files, just keep the labeled ones. - Convert LAMMPS output to extxyz_labeled.

run()

Function to submit jobs to remote machines.

Note

• Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.

OperPhononLammpsSinglepoint(work_dir, pdict, multi_mdict, mdict_prefix='lammps')

Bases: OperPESLammpsOptimize

Class to run LAMMPS singlepoint calculation, used for phonon calculation. Note: the .postprocess() method returns set_of_forces, a 3D array.

Methods:

• prepare –

  This function does:

• postprocess –

  This function does:

• run –

  Function to submit jobs to remote machines.

Attributes:

• op_name –
• task_filter –
• work_dir –
• pdict –
• mdict_list –
• task_dirs –
• commandlist_list (list[list[str]]) –
• forward_files (list[str]) –
• backward_files (list[str]) –
• forward_common_files (list[str]) –
• backward_common_files (list[str]) –

op_name = 'LAMMPS optimize' instance-attribute

task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': ['frame_label.lmpdump']} instance-attribute

work_dir = work_dir instance-attribute

pdict = pdict instance-attribute

mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute

task_dirs = self._load_task_dirs() instance-attribute

commandlist_list: list[list[str]] instance-attribute

forward_files: list[str] instance-attribute

backward_files: list[str] instance-attribute

forward_common_files: list[str] instance-attribute

backward_common_files: list[str] = [] instance-attribute

prepare()

This function does: - Prepare lammps_optimize and lammps_input files. - Convert extxyz to lmpdata. - Copy potential file to work_dir.

• Prepare the task_list
• Prepare forward & backward files
• Prepare commandlist_list for multi-remote submission

postprocess() -> list[list]

This function does: - Remove unlabeled .extxyz files, just keep the labeled ones. - Convert LAMMPS output to extxyz_labeled.

run()

Function to submit jobs to remote machines.

Note

• Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.

phonon

Workflow for phonon calculation.

Classes:

• WorkflowPhonon –

  Workflow for phonon calculation.

Functions:

• make_structure_phonon –

  Make initial structure for phonon calculation. Recommended settings:

• relax_initial_structure –

  Relax the structure by DFT/MD.

• strain_and_relax –

  Scale and relax the structures while fixing box size. Use when want to compute phonon at different volumes.

• compute_force –

  Compute forces for each scale-relaxed-structure by DFT/MD.

• compute_force_one_scaledstruct –

  Run DFT/MD single-point calculations to compute forces for each relaxed structure.

• compute_phonon –

  Compute phonon properties by phonopy functions.

WorkflowPhonon(params_file: str, machines_file: str)

Bases: Workflow

Workflow for phonon calculation.

Methods:

• run –

  The main function to run the workflow. This default implementation works for simple workflow,

Attributes:

• stage_map –
• wf_name –
• params_file –
• machines_file –
• schema_file –
• multi_mdicts –
• pdict –
• stage_list –

stage_map = {'make_structure': make_structure_phonon, 'relax_initial_structure': relax_initial_structure, 'strain_and_relax': strain_and_relax, 'compute_force': compute_force, 'compute_phonon': compute_phonon} instance-attribute

wf_name = 'PHONON CALCULATION' instance-attribute

params_file = params_file instance-attribute

machines_file = machines_file instance-attribute

schema_file = schema_file instance-attribute

multi_mdicts = config_machine.multi_mdicts instance-attribute

pdict = Config.loadconfig(self.params_file) instance-attribute

stage_list = self._load_stage_list() instance-attribute

run()

The main function to run the workflow. This default implementation works for simple workflow, for more complex workflow (e.g. with iteration like active learning), need to reimplement this .run() function.

make_structure_phonon(pdict, mdict)

Make initial structure for phonon calculation. Recommended settings: 1. Use supercell size to build the input structure. 2. supercell_matrix = [n1, n2, n3] # no matter what the input structure is. 3. Then, use auto_primitive_cell to find the primitive cell from the input structure. This works, but sometime gives unstable result. Use with caution.

relax_initial_structure(pdict, mdict)

Relax the structure by DFT/MD.

strain_and_relax(pdict, mdict)

Scale and relax the structures while fixing box size. Use when want to compute phonon at different volumes.

compute_force(pdict, mdict)

Compute forces for each scale-relaxed-structure by DFT/MD.

compute_force_one_scaledstruct(work_dir: str, pdict, mdict)

Run DFT/MD single-point calculations to compute forces for each relaxed structure.

(the previous step generate a list of scaled&relaxed structures. This function works on each of them). The function does the following: - Initialize the phonopy object - generate supercell_list with displacements - run DFT/MD single-point calculation to compute forces for each supercell - assign forces back to phonopy object - save the phonopy object to a file for latter post-processing

compute_phonon(pdict, mdict)

Compute phonon properties by phonopy functions.

utilpho

Utility functions for phonon calculations.

Note

• Phonon calculations rely on a structure that is tightly converged. It is recommended to run a pre-relaxation with opt_params: {"fmax": 1e-3} or tighter before running phonon calculations.
• [Notice about displacement distance: "A too small displacement distance can lead to numerical noise, while a too large displacement distance can lead to anharmonic effects. A typical value is 0.01-0.05 Angstrom.", But, some notes say 0.05-0.08 Angstroms are need to converge!

Info

• [1] https://phonopy.github.io/phonopy/
• [2] https://github.com/abelcarreras/phonolammps
• [3] https://github.com/lrgresearch/gpaw-tools
• [4] calorine: https://gitlab.com/materials-modeling/calorine/-/blob/master/calorine/tools/phonons.py?ref_type=heads
• [5] quacc: https://github.com/Quantum-Accelerators/quacc/blob/main/src/quacc/atoms/phonons.py
• [6] pymatgen: https://github.com/materialsproject/pymatgen/blob/master/src/pymatgen/io/phonopy.py
• [7] vibes: https://gitlab.com/vibes-developers/vibes/-/tree/master/vibes/phonopy
• [8] https://www.diracs-student.blog/2023/11/unoffical-way-to-use-phonopy-with-ase.html

Functions:

• convert_phonopy2ase –
• convert_ase2phonopy –
• get_primitive_spglib –

  Find the primitive cell using spglib.standardize_cell.

• get_primitive_phonopy –

  Find the primitive cell using phonopy's get_primitive() function. This is more robust than spglib.

• get_band_path –
• get_band_structure –
• get_DOS_n_PDOS –
• get_thermal_properties –

convert_phonopy2ase(struct_ph: PhonopyAtoms) -> Atoms

convert_ase2phonopy(struct: Atoms) -> PhonopyAtoms

get_primitive_spglib(struct: Atoms, no_idealize: bool = True, symprec=1e-05, angle_tolerance=-1.0) -> Atoms

Find the primitive cell using spglib.standardize_cell.

Parameters:

• struct (Atoms) –

  ASE's structure object.

• no_idealize (bool, default: True ) –

  Whether to avoid idealizing the cell shape (lengths and angles). Default is True.

• symprec (float, default: 1e-05 ) –

  Symmetry tolerance. Default is 1e-5.

• angle_tolerance (float, default: -1.0 ) –

  Angle tolerance. Default is -1.0 (i.e., use spglib's default).

Note

• IMPORTANT: Using this function in phonon calculations is unstable. Use with caution.
  • Since spglib.find_primitive may fail to find the primitive cell for some structures.
  • Or the returned primitive cell may not has right symmetry. This can lead to issues in phonon calculations (e.g., negative frequencies).
• Must use .get_scaled_positions() to define the cell in spglib.

get_primitive_phonopy(struct: Atoms, symprec=1e-05) -> Atoms

Find the primitive cell using phonopy's get_primitive() function. This is more robust than spglib.

Parameters:

• struct (Atoms) –

  ASE's structure object.

• symprec (float, default: 1e-05 ) –

  Symmetry tolerance. Default is 1e-5.

get_band_path(atoms: Atoms, path_str: str = '', npoints: int = 61, path_frac=None, labels=None)

get_band_structure(work_dir, pdict)

get_DOS_n_PDOS(work_dir, pdict)

get_thermal_properties(work_dir, pdict)