alff.pes

alff.pes

Modules:

• libpes_gpaw –

  Library for GPAW-based PES operations.

• libpes_lammps –

  Library for LAMMPS-based PES operations.

• pes_scan –

  Implementation of 2d PES scanning.

• utilpes –

  Utility functions for PES scans and analysis.

libpes_gpaw

Library for GPAW-based PES operations.

Classes:

• OperPESGpawOptimize –

  This class does GPAW optimization for a list of structures in task_dirs.

• OperPESGpawOptimizeFixatom –

  Perform optimization with some atoms fixed.

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

Bases: OperGendataGpawOptimize

This class does GPAW optimization for a list of structures in task_dirs.

This class can also be used for phonon GPAW optimization

Subclassed by:

• alff API reference
  • alff.pes  pes  libpes_gpaw  OperPESGpawOptimizeFixatom
  • alff.phonon  phonon  libpho_gpaw
    •  OperPhononGpawOptimize
    •  OperPhononGpawOptimizeFixbox
    •  OperPhononGpawSinglepoint

Methods:

• prepare –

  Prepare the operation.

• 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()

Prepare the operation.

Includes: - Prepare ase_args for GPAW and gpaw_run_file. Note: Must define pdict.dft.calc_args.gpaw{} for this function. - Prepare the task_list - Prepare forward & backward files - Prepare commandlist_list for multi-remote submission

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.

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

Bases: OperPESGpawOptimize

Perform optimization with some atoms fixed.

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 atoms' 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.

libpes_lammps

Library for LAMMPS-based PES operations.

Classes:

• OperPESLammpsOptimize –

  This class does LAMMPS optimization for a list of structures in task_dirs.

• OperPESLammpsOptimizeFixatom –

  The same base class, only need to redefine the .prepare() method.

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

Bases: RemoteOperation

This class does LAMMPS optimization for a list of structures in task_dirs.

This class can also be used for phonon LAMMPS optimization alff.phonon.libphonon_lammps.py

Subclassed by:

• alff API reference
  • alff.pes  pes  libpes_lammps  OperPESLammpsOptimizeFixatom
  • alff.phonon  phonon  libpho_lammps
    •  OperPhononLammpsOptimize
    •  OperPhononLammpsOptimizeFixbox
    •  OperPhononLammpsSinglepoint

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()

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.

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

Bases: OperPESLammpsOptimize

The same base class, only need to redefine the .prepare() method.

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 atoms' 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.

pes_scan

Implementation of 2d PES scanning. - Idea is to incrementally change the relative positions between 2 groups of atoms while calculating the energy of the system.

Classes:

• WorkflowPes –

  Workflow for PES scanning calculation.

Functions:

• relax_initial_structure –

  Relax the structure by DFT/MD.

• scanning_space –

  Displace a group of atoms in a structure to generate a series of structures.

• compute_energy –

  Compute energy for each scan-structure by DFT/MD.

• compute_pes –

  Collect energies computed in the previous stage and do some post-processing.

WorkflowPes(params_file: str, machines_file: str)

Bases: Workflow

Workflow for PES scanning 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, 'relax_initial_structure': relax_initial_structure, 'scanning_space': scanning_space, 'compute_energy': compute_energy, 'compute_pes': compute_pes} instance-attribute

wf_name = 'PES SCANNING 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.

relax_initial_structure(pdict, mdict)

Relax the structure by DFT/MD.

scanning_space(pdict, mdict)

Displace a group of atoms in a structure to generate a series of structures.

• Save 2 lists of paths: original and scaled structure paths

compute_energy(pdict, mdict)

Compute energy for each scan-structure by DFT/MD. Using conditional optimization: fix atoms and optimize the rest.

compute_pes(pdict, mdict)

Collect energies computed in the previous stage and do some post-processing.

utilpes

Utility functions for PES scans and analysis.

Functions:

• scan_x_dim –

  Scan in the x dimension.

• scan_y_dim –

  Scan in the y dimension.

• scan_z_dim –

  Scan in the z dimension.

• displace_group_atoms_2d –

  Displace a selected group of atoms by (dx, dy, dz).

• mapping_dxdydz_to_cartesian –

  Sampling points are in (u,v) coordinates along cell vectors that may not orthogonal.

• interp_pes_xy –

  Interpolate PES surface in the xy plane.

• interp_pes_z –

  Interpolate PES curve in the z direction.

• plot_pes_xy –

  Plot PES surface in the xy plane.

• plot_pes_z –

  Plot PES surface in the xy plane.

• plot_pes_3d –

scan_x_dim(struct_files: list, idxs: list, scan_dx_list: list)

Scan in the x dimension.

scan_y_dim(struct_files: list, idxs: list, scan_dy_list: list)

Scan in the y dimension.

scan_z_dim(struct_files: list, idxs: list, scan_dz_list: list)

Scan in the z dimension.

displace_group_atoms_2d(struct: Atoms, idxs: list[int], dx: float = 0.0, dy: float = 0.0, dz: float = 0.0) -> Atoms

Displace a selected group of atoms by (dx, dy, dz).

Parameters:

• struct (Atoms) –

  ASE Atoms object.

• idxs (list[int]) –

  List of atom indices to displace.

• dx (float, default: 0.0 ) –

  Displacement in x direction (Å).

• dy (float, default: 0.0 ) –

  Displacement in y direction (Å).

• dz (float, default: 0.0 ) –

  Displacement in z direction (Å).

Returns:

• Atoms –

  A new Atoms with updated positions and cell (positions are NOT affinely scaled).

Note

• This function assumes the structure is 2D, and the cell is orthogonal in z direction.
• After displacement, if any atom move outside the current boundaries, it will be wrapped to the cell.
• The displacement of atoms may broke the periodicity at cell's boundaries. A minimization step is needed update the cell correctly.

mapping_dxdydz_to_cartesian(dxdydz: np.ndarray, struct_cell: np.ndarray)

Sampling points are in (u,v) coordinates along cell vectors that may not orthogonal.

This function transform sampling points to real Cartesian coordinates

Parameters:

• dxdydz (ndarray) –

  array (N,3) containing (dx, dy, dz) for N sampling points

• struct_cell (ndarray) –

  array (3,3) containing cell vectors

interp_pes_xy(df: pl.DataFrame, grid_size: float = 0.05) -> pl.DataFrame

Interpolate PES surface in the xy plane.

Parameters:

• df (DataFrame) –

  PES raw data file with columns: dx dy energy

• grid_size (float, default: 0.05 ) –

  grid size (Å) for interpolation

Returns: df: DataFrame with columns: grid_x, grid_y, energy/atom

interp_pes_z(df: pl.DataFrame, grid_size: float = 0.05) -> pl.DataFrame

Interpolate PES curve in the z direction.

Parameters:

• df (DataFrame) –

  PES raw data with columns: dz energy

• grid_size (float, default: 0.05 ) –

  grid size (Å) for interpolation

Returns: df: DataFrame with columns: grid_z, energy/atom

plot_pes_xy(file_pes_grid: str, file_pes_raw: str | None = None)

Plot PES surface in the xy plane.

Parameters:

• file_pes_grid (str) –

  file containing PES data interpolated on a grid

• file_pes_raw (str | None, default: None ) –

  file containing raw PES data (optional, to plot input data points)

plot_pes_z(file_pes_grid: str, file_pes_raw: str | None = None)

Plot PES surface in the xy plane.

Parameters:

• file_pes_grid (str) –

  file containing PES data interpolated on a grid

• file_pes_raw (str | None, default: None ) –

  file containing raw PES data (optional, to plot input data points)

plot_pes_3d()