Skip to content

clff.pes¤

clff.pes ¤

Potential Energy Surface package.

Modules:

  • libpes_ase –

    Library for ASE-based PES operations.

  • 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_ase ¤

Library for ASE-based PES operations.

Classes:

OpPESAseOptimize(work_dir, pdict, multi_mdict, mdict_prefix='ase') ¤

Bases: OpGendataAseOptimize

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

This class can also be used for phonon ASE optimization

Subclassed by:

Methods:

Attributes:

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 = 'ASE 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.

Notes
  • 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.

OpPESAseOptimizeFixatom(work_dir, pdict, multi_mdict, mdict_prefix='ase') ¤

Bases: OpPESAseOptimize

Perform optimization with some atoms fixed.

Methods:

Attributes:

op_name = 'ASE 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.

Notes
  • 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_gpaw ¤

Library for GPAW-based PES operations.

Classes:

OpPESGpawOptimize(work_dir, pdict, multi_mdict, mdict_prefix='gpaw') ¤

Bases: OpGendataGpawOptimize

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:

Methods:

Attributes:

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.

Notes
  • 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.

OpPESGpawOptimizeFixatom(work_dir, pdict, multi_mdict, mdict_prefix='gpaw') ¤

Bases: OpPESGpawOptimize

Perform optimization with some atoms fixed.

Methods:

Attributes:

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.

Notes
  • 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:

OpPESLammpsOptimize(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 clff.phonon.libphonon_lammps.py

Subclassed by:

Methods:

  • prepare –

    This function does:

  • postprocess –

    This function does:

  • run –

    Function to submit jobs to remote machines.

Attributes:

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.

Notes
  • 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.

OpPESLammpsOptimizeFixatom(work_dir, pdict, multi_mdict, mdict_prefix='lammps') ¤

Bases: OpPESLammpsOptimize

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

Notes
  • 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 = {'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 Concurrent Learning), need to reimplement this .run() function.

Notes: - Force garbage collection before running the workflow to release unreachable objects (may reduce retained memory from previous stages such as prepare())..

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

map_dxdydz_to_cartesian(dxdydz: np.ndarray, struct_cell: np.ndarray) ¤

Sampling points are (u,v) grid steps uniformly along non-orthogonal crystal lattice vectors. If you plot this raw grid directly into a standard 2D Cartesian \((X, Y)\) plotter like matplotlib, the plotter assumes the axes are at \(90^\\circ\). This creates an artificial shear distortion.

This function transform sampling points to Cartesian space to preserve the true physical metrics, isotropic gradients, and highly symmetric paths (like \(\\Gamma \rightarrow \text{M} \rightarrow \text{K} \rightarrow \\Gamma\)) without squashing the hexagonal symmetry into a rectangular format.

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

set_pesplot_style() -> None ¤

Set plot style for PES plots.

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)

Note

The interpolated data is in flattened meshgrid form, therefore we need to reshape it into a 2D grid for plotting.

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