Skip to content

API

alff

ALFF: Framework for Active Learning of GraphNN-based Force Fields and Computation of Material Properties.

Developed and maintained by C.Thang Nguyen

Modules:

Attributes:

ALFF_ROOT = Path(__file__).parent module-attribute

__author__ = 'C.Thang Nguyen' module-attribute

__contact__ = 'http://thangckt.github.io/email' module-attribute

_version

Attributes:

__all__ = ['__version__', '__version_tuple__', 'version', 'version_tuple', '__commit_id__', 'commit_id'] module-attribute

TYPE_CHECKING = False module-attribute

VERSION_TUPLE = Tuple[Union[int, str], ...] module-attribute

COMMIT_ID = Union[str, None] module-attribute

version: str = '0.1.1.dev1' module-attribute

__version__: str = '0.1.1.dev1' module-attribute

__version_tuple__: VERSION_TUPLE = (0, 1, 1, 'dev1') module-attribute

version_tuple: VERSION_TUPLE = (0, 1, 1, 'dev1') module-attribute

commit_id: COMMIT_ID = 'ga87dabe79' module-attribute

__commit_id__: COMMIT_ID = 'ga87dabe79' module-attribute

al

Modules:

active_learning

Functions:

pre_train(iter_idx, pdict, mdict)

This function prepares: - collect data files - prepare training args based MLP engine

run_train(iter_idx, pdict, mdict)
post_train(iter_idx, pdict, mdict)
pre_md(iter_idx, pdict, mdict)

Prepare MD tasks - collect initial configurations - prepare MD args

run_md(iter_idx, pdict, mdict)
post_md(iter_idx, pdict, mdict)
pre_dft(iter_idx, pdict, mdict)

Prepare DFT tasks

run_dft(iter_idx, pdict, mdict)
post_dft(iter_idx, pdict, mdict)

Do post DFT tasks - collect DFT results - remove temporary files

main_al_iteration(configfile_param, configfile_machine)

Run main loop of active learning.

_get_engines(pdict) -> tuple[str]
_check_work_dir(work_dir)
write_iterlog(iter_idx: int, stage_idx: int, stage_name: str, last_iter: bool = True) -> None

Write the current iteration and stage to the iter log file. If last_iter is True, only the last iteration is saved.

read_iterlog() -> list[int]

Read the last line of the iter log file.

iter_str(iter_idx: int) -> str
breakline_iter(iter_idx: int) -> str
breakline_stage(iter_idx: int, stage_idx: int, stage_name: str) -> str

finetune

Functions:

pre_finetune(pdict: dict, mdict: dict)

This function prepares: - collect data files - prepare training args based MLP engine

run_finetune(pdict: dict, mdict: dict)
post_finetune(pdict: dict, mdict: dict)
main_fine_tuning(configfile_param: str, configfile_machine: str)

Fine tune the existed ML models or train a new ML model.

libal_md_ase

Functions:

pre_md_ase_sevenn(work_dir, pdict, mdict)

This function does: - prepare MD args - generate task_dirs for ranges of temperature and press - establish MD tasks and ASE_run_file

run_md_ase_sevenn(work_dir, pdict, mdict)

Refer to the rungen_gpaw_optimize() function.

post_md_ase_sevenn(work_dir, pdict, mdict)

This function does:

temperature_press_mdarg_ase(struct_dirs: list, temperature_list: list = [], press_list: list = [], ase_argdict: dict = {}) -> list

Generate the task_dirs for ranges of temperatures and stresses.

Parameters:

  • struct_dirs (list) –

    List of dirs contains configuration files.

  • temperature_list (list, default: [] ) –

    List of temperatures.

  • press_list (list, default: [] ) –

    List of stresses.

  • ase_argdict (dict, default: {} ) –

    See ase.md schema

libal_md_lammps

Functions:

pre_md_lammps_sevenn(work_dir, pdict, mdict)

This function does: - prepare MD args - generate task_dirs for ranges of temperature and press - establish MD tasks and ASE_run_file

run_md_lammps_sevenn(work_dir, pdict, mdict)

Refer to the run_md_ase_sevenn() function.

post_md_lammps_sevenn(work_dir, pdict, mdict)
_check_committee_select(file: str) -> bool

Check if the sampling result is sastified. Args: file (str): The text file summarizing the sampling result. Returns: bool: True if the sampling result is sastified, False otherwise.

temperature_press_mdarg_lammps(struct_dirs: list, temperature_list: list = [], press_list: list = [], lammps_argdict: dict = {}) -> list

Generate the task_dirs for ranges of temperatures and stresses.

Parameters:

  • struct_dirs (list) –

    List of dirs contains configuration files.

  • temperature_list (list, default: [] ) –

    List of temperatures.

  • press_list (list, default: [] ) –

    List of stresses.

  • lammps_argdict (dict, default: {} ) –

    See lammps.md schema

libal_uncertainty

DO NOT use any alff imports in this file, since it will be used remotely.

Functions:

  • committee_err_energy –

    Committee error for energy on a single configuration

  • committee_err_force –

    Committee error for forces on a single configuration

  • committee_err_stress –

    Committee error for stress on a single configuration

  • committee_error –

    Calculate committee error for energy, forces and stress for a list of configurations

  • committee_judge –

    Decide whether an configuration is candidate, accurate, or inaccurate based on committee error

  • select_candidate –

    Select candidate configurations for DFT calculation

  • remove_inaccurate –

    Remove inaccurate configurations based on committee error. This is used to revise the dataset.

  • select_candidate_SevenNet –

    Select candidate configurations for DFT calculation using SevenNet models.

  • remove_inaccurate_SevenNet –

    Remove inaccurate configurations based on committee error, using SevenNet models.

  • simple_lmpdump2extxyz –

    Convert LAMMPS dump file to extended xyz file. This is very simple version, only convert atomic positions, but not stress tensor.

_assign_calc(struct: Atoms, calc: object) -> Atoms

helper to assign calculator to an Atoms object. Why need this? - Avoids modifying the original Atoms object. - Avoids return 'NoneType' when directly call '.set_calculator(calc)' in list comprehension.

committee_err_energy(struct: Atoms, calc_list: list[Calculator]) -> float

Committee error for energy on a single configuration

Parameters:

  • struct (Atoms) –

    Atoms object

  • calc_list (list[Calculator]) –

    list of ASE's calculators of ML models in the committee.

Returns:

  • e_std ( float ) –

    standard deviation of the energy

committee_err_force(struct: Atoms, calc_list: list[Calculator], rel_force: float = None) -> tuple[float, float, float]

Committee error for forces on a single configuration

Parameters:

  • struct (Atoms) –

    Atoms object

  • calc_list (list[Calculator]) –

    list of ASE's calculators of ML models in the committee.

  • rel_force (float, default: None ) –

    relative force. Defaults to None.

Returns:

  • f_std_mean ( float ) –

    mean of the standard deviation of atomic forces in the configuration

  • f_std_max ( float ) –

    maximum of the standard deviation

  • f_std_min ( float ) –

    minimum of the standard deviation

committee_err_stress(struct: Atoms, calc_list: list[Calculator], rel_stress: float = None) -> tuple[float, float, float]

Committee error for stress on a single configuration

Parameters:

  • struct (Atoms) –

    Atoms object

  • calc_list (list[Calculator]) –

    list of ASE's calculators of ML models in the committee.

  • rel_stress (float, default: None ) –

    relative stress. Defaults to None.

Returns:

  • s_std_mean ( float ) –

    mean of the standard deviation of the stress in the configuration

  • s_std_max ( float ) –

    maximum of the standard deviation

  • s_std_min ( float ) –

    minimum of the standard deviation

committee_error(extxyz_file: str, calc_list: list[Calculator], rel_force: float = None, compute_stress: bool = True, rel_stress: float = None, outfile: str = 'committee_error.txt')

Calculate committee error for energy, forces and stress for a list of configurations

Parameters:

  • extxyz_file (str) –

    extended xyz file containing multiples configurations

  • calc_list (list[Calculator]) –

    list of ASE's calculators of ML models

  • rel_force (float, default: None ) –

    relative force. Defaults to None.

  • compute_stress (bool, default: True ) –

    whether to compute stress. Defaults to True.

  • rel_stress (float, default: None ) –

    relative stress. Defaults to None.

  • outfile (str, default: 'committee_error.txt' ) –

    output file. Defaults to "committee_error.txt".

Returns:

  • outfile ( str ) –

    "committee_error.txt" with the following columns: "e_std f_std_mean f_std_max f_std_min s_std_mean s_std_max s_std_min"

committee_judge(committee_error_file: str, e_std_hi: float = 0.1, e_std_lo: float = 0.0, f_std_hi: float = 0.1, f_std_lo: float = 0.0, s_std_hi: float = None, s_std_lo: float = 0.0) -> tuple[np.ndarray, np.ndarray, np.ndarray]

Decide whether an configuration is candidate, accurate, or inaccurate based on committee error

Parameters:

  • committee_error_file (str) –

    committee error file

  • e_std_hi (float, default: 0.1 ) –

    energy std high. Defaults to 0.1.

  • e_std_lo (float, default: 0.0 ) –

    energy std low. Defaults to 0.05.

  • f_std_hi (float, default: 0.1 ) –

    force std high. Defaults to 0.1.

  • f_std_lo (float, default: 0.0 ) –

    force std low. Defaults to 0.05.

  • s_std_hi (float, default: None ) –

    stress std high. Defaults to 0.1.

  • s_std_lo (float, default: 0.0 ) –

    stress std low. Defaults to 0.05.

Returns:

  • committee_error_file ( s ) –

    files contain candidate, accurate and inaccurate configurations

Note
  • If need to select candidates based on only energy, just set f_std_lo and s_std_lo to a very large values. By this way, the criterion for those terms will never meet.
  • Similarly, if need to select candidates based on only energy and force, set s_std_lo to a very large value. E.g., s_std_lo=1e6 for selecting candidates based on energy and force.
select_candidate(extxyz_file: str, calc_list: list[Calculator], rel_force: float = None, compute_stress: bool = True, rel_stress: float = None, e_std_hi: float = 0.1, e_std_lo: float = 0.0, f_std_hi: float = 0.1, f_std_lo: float = 0.0, s_std_hi: float = None, s_std_lo: float = 0.0)

Select candidate configurations for DFT calculation

Returns:

  • extxyz_file ( str ) –

    candidate configurations

Note: See parameters in functions committee_error and committee_judge.

remove_inaccurate(extxyz_file: str, calc_list: list[Calculator], rel_force: float = None, compute_stress: bool = True, rel_stress: float = None, e_std_hi: float = 0.1, e_std_lo: float = 0.0, f_std_hi: float = 0.1, f_std_lo: float = 0.0, s_std_hi: float = None, s_std_lo: float = 0.0)

Remove inaccurate configurations based on committee error. This is used to revise the dataset.

Returns:

  • extxyz_file ( str ) –

    revise configurations

Note: See parameters in functions committee_error and committee_judge.

select_candidate_SevenNet(extxyz_file: str, checkpoint_files: list, sevenn_args: dict = {}, rel_force: float = None, compute_stress: bool = True, rel_stress: float = None, e_std_hi: float = 0.1, e_std_lo: float = 0.0, f_std_hi: float = 0.1, f_std_lo: float = 0.0, s_std_hi: float = None, s_std_lo: float = 0.0)

Select candidate configurations for DFT calculation using SevenNet models.

Parameters:

  • extxyz_file (str) –

    extended xyz file containing multiples configurations

  • checkpoint_files (list) –

    list of checkpoint_files files SevenNet models

  • sevenn_args (dict, default: {} ) –

    arguments for SevenNetCalculator. Defaults to {}.

Returns:

  • extxyz_file ( str ) –

    candidate configurations

remove_inaccurate_SevenNet(extxyz_file: str, checkpoint_files: list, sevenn_args: dict = {}, rel_force: float = None, compute_stress: bool = True, rel_stress: float = None, e_std_hi: float = 0.1, e_std_lo: float = 0.0, f_std_hi: float = 0.1, f_std_lo: float = 0.0, s_std_hi: float = None, s_std_lo: float = 0.0)

Remove inaccurate configurations based on committee error, using SevenNet models.

Parameters:

  • extxyz_file (str) –

    extended xyz file containing multiples configurations

  • checkpoint_files (list) –

    list of checkpoint_files files SevenNet models

  • sevenn_args (dict, default: {} ) –

    arguments for SevenNetCalculator. Defaults to {}.

Returns:

  • extxyz_file ( str ) –

    revised configurations

simple_lmpdump2extxyz(lmpdump_file: str, extxyz_file: str)

Convert LAMMPS dump file to extended xyz file. This is very simple version, only convert atomic positions, but not stress tensor.

cli

Functions:

Attributes:

Logger = create_logger('alff', level='INFO', log_file=FILE_LOG_ALFF) module-attribute

alff_al()

CLI for active learning

alff_gen()

CLI for data generation

alff_finetune()

CLI for fine-tuning

alff_phonon()

CLI for phonon calculation

alff_elastic()

CLI for elastic constants calculation

alff_pes()

CLI for PES scanning calculation

convert_chgnet_to_xyz()

CLI for converting the MPCHGNet dataset to XYZ format

get_cli_args()

Get the arguments from the command line

elastic

Modules:

elastic

Functions:

relax_initial_structure(pdict, mdict)

Relax the structure by DFT/MD

scale_and_relax(pdict, mdict)

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

compute_stress_strain(pdict: dict, mdict: dict)

Compute stress and strain tensors for each scale-relaxed-structure by DFT/MD.

compute_stress_single_structure(work_dir, pdict, mdict)

The function does the following: - generate supercells with small deformation and compute corresponding strain tensor - run DFT/MD minimize calculation to compute stress tensor for each suppercell. - collect stress and strain tensor for each supercell

compute_elastic_tensor_single_structure(work_dir, pdict: dict, mdict: dict)

Compute elastic tensor for a single structure. - Collect stress and strain tensors from calculations on deformed structures. - Compute elastic constants by fitting stress-strain relations.

compute_elastic(pdict: dict, mdict: dict)

Compute elastic constants from stress-strain tensors.

main_elastic_calculator(configfile_param: str, configfile_machine: str)

Generate initial data for training ML models

lib_elastic

Classes:

  • Elasticity –

    Main class to compute the elastic stiffness tensor of the crystal.

  • ElasticConstant –

    Class to manage elastic constants and compute elastic properties.

Functions:

Elasticity(ref_cryst: Atoms, symprec: float = 1e-05)

Bases: object

Main class to compute the elastic stiffness tensor of the crystal. Steps to compute the elastic tensor: - Initialize the class with the reference structure. - Generate deformed structures with 'elementary deformations' - Compute stress for each deformed structure by DFT/MD. - Input the deformed structures with stress tensors to the method fit_elastic_tensor

Parameters:

  • ref_cryst (Atoms) –

    ASE Atoms object, reference structure (relaxed/optimized structure)

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

    symmetry precision to check the symmetry of the crystal

Methods:

  • generate_deformations –

    Generate deformed structures with 'elementary deformations' for elastic tensor calculation.

  • fit_elastic_tensor –

    Calculate elastic tensor from the stress-strain relation by fitting this relation to the set of linear equations, strains and stresses.

  • get_pressure –

    Return external isotropic (hydrostatic) pressure in ASE units.

  • write_cij –

    Write the elastic constants to a text file.

  • fit_BM_EOS –

    Calculate Birch-Murnaghan Equation of State for the crystal.

  • get_bulk_modulus –

    Calculate bulk modulus using the Birch-Murnaghan equation of state.

  • write_MB_EOS –

    Write the Birch-Murnaghan EOS parameters to a text file.

  • write_MB_EOS_pv_data –

    Write the volume-pressure data to a text file.

Attributes:

ref_cryst = ref_cryst instance-attribute
symprec = symprec instance-attribute
bravais = get_lattice_type(self.ref_cryst, self.symprec)[0] instance-attribute
strain_list = None instance-attribute
stress_list = None instance-attribute
pressure = None instance-attribute
Cij = None instance-attribute
generate_deformations(delta: float = 0.01, n: int = 5)

Generate deformed structures with 'elementary deformations' for elastic tensor calculation. The deformations are created based on the symmetry of the crystal.

Parameters:

  • delta (float, default: 0.01 ) –

    the maximum magnitude of deformation in Angstrom and degrees.

  • n (int, default: 5 ) –

    number of deformations on each non-equivalent axis (number of deformations in each direction)

Returns:

  • –

    list[Atoms]: list of deformed structures. Number of structures = (n * number_of_axes). These structures are then used in MD/DFT to compute the stress tensor.

fit_elastic_tensor(deform_crysts: list[Atoms]) -> tuple[np.array, np.array]

Calculate elastic tensor from the stress-strain relation by fitting this relation to the set of linear equations, strains and stresses. The number of linear equations is computed depends on the symmetry of the crystal.

It is assumed that the crystal is converged (relaxed/optimized) under intended pressure/stress. The geometry and stress on this crystal is taken as the reference point. No additional optimization will be run. Then, the strain and stress tensor is computed for each of the deformed structures (exactly, the stress difference from the reference point).

This function returns tuple of Cij elastic tensor, and the fitting results returned by numpy.linalg.lstsq: Birch coefficients, residuals, solution rank, singular values.

Parameters:

  • deform_crysts (list[Atoms]) –

    list of Atoms objects with calculated deformed structures

Returns:

  • tuple ( tuple[array, array] ) –

    tuple of Cij elastic tensor and fitting results. - Cij: in vector form of Voigt notation. - Bij: float vector, residuals, solution rank, singular values

get_pressure(stress) -> float

Return external isotropic (hydrostatic) pressure in ASE units. If the pressure is positive the system is under external pressure. This is a convenience function to convert output of get_stress function into external pressure.

Parameters:

  • stress(np.array –

    stress tensor in Voight (vector) notation as returned by the .get_stress() method.

Return

float: external hydrostatic pressure in ASE units.

write_cij(filename: str = 'cij.txt')

Write the elastic constants to a text file.

Parameters:

  • filename (str, default: 'cij.txt' ) –

    output file name

fit_BM_EOS(deform_crysts: list[Atoms])

Calculate Birch-Murnaghan Equation of State for the crystal.

\[ P(V) = \frac{B_0}{B'_0}\left[\left({\frac{V}{V_0}}\right)^{-B'_0} - 1\right] \]

It's coefficients are estimated using n single-point structures ganerated from the crystal (cryst) by the scan_volumes function between two relative volumes. The BM EOS is fitted to the computed points by least squares method.

Parameters:

  • cryst (Atoms) –

    Atoms object, reference structure (relaxed/optimized structure)

  • deform_crysts (list[Atoms]) –

    list of Atoms objects with calculated deformed structures

Returns:

  • tuple –

    tuple of EOS parameters ([V0, B0, B0p], pv data)'.

get_bulk_modulus(deform_crysts: list[Atoms])

Calculate bulk modulus using the Birch-Murnaghan equation of state. The bulk modulus is the B_0 coefficient of the B-M EOS. The units of the result are defined by ASE. To get the result in any particular units (e.g. GPa) you need to divide it by ase.units.::

get_bulk_modulus(cryst)/ase.units.GPa

Parameters:

  • cryst (Atoms) –

    Atoms object, reference structure (relaxed/optimized structure)

  • deform_crysts (list[Atoms]) –

    list of Atoms objects with calculated deformed structures

Returns:

  • float –

    bulk modulus B_0 in ASE units.

write_MB_EOS(filename: str = 'BMeos.txt')

Write the Birch-Murnaghan EOS parameters to a text file.

Parameters:

  • filename (str, default: 'BMeos.txt' ) –

    output file name

write_MB_EOS_pv_data(filename: str = 'BMeos_pv_data.txt')

Write the volume-pressure data to a text file.

Parameters:

  • filename (str, default: 'BMeos_pv_data.txt' ) –

    output file name

ElasticConstant(cij_mat: np.array = None, cij_dict: dict = None, bravais_lattice: str = 'Cubic')

Bases: object

Class to manage elastic constants and compute elastic properties.

Parameters:

  • Cij (array) –

    (6, 6) array of Voigt representation of elastic stiffness.

  • bravais_lattice (str, default: 'Cubic' ) –

    Bravais lattice name of the crystal.

  • **kwargs –

    dictionary of elastic constants Cij. Where C11, C12, ... C66 : float,

Methods:

  • Cij –

    The elastic stiffness constants in Voigt 6x6 format

  • Sij –

    The compliance constants in Voigt 6x6 format

  • bulk –

    Returns a bulk modulus estimate.

  • shear –

    Returns a shear modulus estimate.

Attributes:

bravais = bravais_lattice instance-attribute
Cij() -> np.ndarray

The elastic stiffness constants in Voigt 6x6 format

Sij() -> np.ndarray

The compliance constants in Voigt 6x6 format

bulk(style: str = 'Hill') -> float

Returns a bulk modulus estimate.

Parameters:

  • style (str, default: 'Hill' ) –

    style of bulk modulus. Default value is 'Hill'. - 'Voigt': Voigt estimate. Uses Cij. - 'Reuss': Reuss estimate. Uses Sij. - 'Hill': Hill estimate (average of Voigt and Reuss).

shear(style: str = 'Hill') -> float

Returns a shear modulus estimate.

Parameters:

  • style (str, default: 'Hill' ) –

    style of bulk modulus. Default value is 'Hill'. - 'Voigt': Voigt estimate. Uses Cij. - 'Reuss': Reuss estimate. Uses Sij. - 'Hill': Hill estimate (average of Voigt and Reuss).

func_MEOS(v, v0, b0, b0p)

Murnaghan equation of state: https://en.wikipedia.org/wiki/Murnaghan_equation_of_state

func_BMEOS(v, v0, b0, b0p)

Birch-Murnaghan equation of state: https://en.wikipedia.org/wiki/Birch-Murnaghan_equation_of_state

get_lattice_type(cryst: Atoms, symprec=1e-05) -> tuple[int, str, str, int]

Identify the lattice type and the Bravais lattice of the crystal. The lattice type numbers are (numbering starts from 1): Triclinic (1), Monoclinic (2), Orthorhombic (3), Tetragonal (4), Trigonal (5), Hexagonal (6), Cubic (7)

Parameters:

  • cryst (Atoms) –

    ASE Atoms object

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

    symmetry precision to check the symmetry of the crystal

Returns:

  • tuple ( tuple[int, str, str, int] ) –

    Bravais name, lattice type number (1-7), space-group name, space-group number

generate_elementary_deformations(cryst: Atoms, delta: float = 0.01, n: int = 5, bravais_lattice: str = 'Cubic') -> list[Atoms]

Generate deformed structures with 'elementary deformations' for elastic tensor calculation. The deformations are created based on the symmetry of the crystal and are limited to the non-equivalent axes of the crystal.

Parameters:

  • cryst (Atoms) –

    Atoms object, reference structure (relaxed/optimized structure)

  • delta (float, default: 0.01 ) –

    the maximum magnitude of deformation in Angstrom and degrees.

  • n (int, default: 5 ) –

    number of deformations on each non-equivalent axis (number of deformations in each direction)

  • symprec (float) –

    symmetry precision to check the symmetry of the crystal

Returns:

  • list[Atoms] –

    list[Atoms] list of deformed structures. Number of structures = (n * number_of_axes)

deform_1axis(cryst: Atoms, axis: int = 0, delta: float = 0.01) -> Atoms

Return the deformed structure along one of the cartesian directions. The axis is specified as follows:

- tetragonal deformation: 0,1,2 = x,y,z.
- shear deformation: 3,4,5 = yz, xz, xy.

Parameters:

  • cryst (Atoms) –

    reference structure (structure to be deformed)

  • axis (int, default: 0 ) –

    direction of deformation. 0,1,2 = x,y,z; 3,4,5 = yz, xz, xy.

  • delta (float, default: 0.01 ) –

    magnitude of the deformation. Angstrom and degrees.

Return

ase.Atoms: deformed structure

strain_voigt_to_symmetry_matrix(u: list, bravais_lattice: str = 'Cubic') -> np.array

Return the strain matrix to be used in stress-strain equation, to compute elastic tensor. The number of Cij constants depends on the symmetry of the crystal. This strain matrix is computed based on the symmetry to reduce the necessary number of equations to be used in the fitting procedure (also reduce the necessary calculations). Refer Landau's textbook for the details.

- Triclinic: C11, C22, C33, C12, C13, C23, C44, C55, C66, C16, C26, C36, C46, C56, C14, C15, C25, C45
- Monoclinic: C11, C22, C33, C12, C13, C23, C44, C55, C66, C16, C26, C36, C45
- Orthorhombic: C11, C22, C33, C12, C13, C23, C44, C55, C66
- Tetragonal: C11, C33, C12, C13, C44, C66
- Trigonal: C11, C33, C12, C13, C44, C14
- Hexagonal: C11, C33, C12, C13, C44
- Cubic: C11, C12, C44

Parameters:

  • u (list) –

    vector of strain in Voigt notation [ u_xx, u_yy, u_zz, u_yz, u_xz, u_xy ]

  • bravais_lattice (str, default: 'Cubic' ) –

    Bravais lattice name of the lattice

Returns:

  • array –

    np.array: Symmetry defined stress-strain equation matrix

get_cij_list(bravais_lattice: str = 'Cubic') -> list[str]

Return the order of elastic constants for the structure

Parameters:

  • bravais_lattice (str, default: 'Cubic' ) –

    Bravais lattice name of the lattice

Return

list: list of strings C_ij the order of elastic constants

get_cij_6x6matrix(cij_dict: dict[float], bravais_lattice: str = 'Cubic') -> np.array

Return the Cij matrix for the structure based on the symmetry of the crystal.

Parameters:

  • cij_dict (dict) –

    dictionary of elastic constants Cij. Where C11, C12, ... C66 : float, Individual components of Cij for a standardized representation:

    • Triclinic: all Cij where i <= j
    • Monoclinic: C11, C12, C13, C15, C22, C23, C25, C33, C35, C44, C46, C55, C66
    • Orthorhombic: C11, C12, C13, C22, C23, C33, C44, C55, C66
    • Tetragonal: C11, C12, C13, C16, C33, C44, C66 (C16 optional)
    • Trigonal: C11, C12, C13, C14, C33, C44
    • Hexagonal: C11, C12, C13, C33, C44, C66 (2*C66=C11-C12)
    • Cubic: C11, C12, C44
    • Isotropic: C11, C12, C44 (2*C44=C11-C12)
  • bravais_lattice (str, default: 'Cubic' ) –

    Bravais lattice name of the lattice

get_voigt_strain_vector(cryst: Atoms, ref_cryst: Atoms = None) -> np.array

Calculate the strain tensor between the deformed structure and the reference structure. Return strain in vector form of Voigt notation, component order: u_{xx}, u_{yy}, u_{zz}, u_{yz}, u_{xz}, u_{xy}.

Parameters:

  • cryst (Atoms) –

    deformed structure

  • ref_cryst (Atoms, default: None ) –

    reference, undeformed structure

Returns:

  • array –

    np.array: vector of strain in Voigt notation.

lib_elate

libelastic_lammps

Functions:

postelast_lammps_optimize(work_dir, pdict)

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

postelast_lammps_singlepoint(work_dir, pdict)

This function does: - Clean up unlabelled extxyz files - Collect forces from the output files

gdata

Modules:

convert_mpchgnet_to_xyz

Functions:

Attributes:

info_keys = ['uncorrected_total_energy', 'corrected_total_energy', 'energy_per_atom', 'ef_per_atom', 'e_per_atom_relaxed', 'ef_per_atom_relaxed', 'magmom', 'bandgap', 'mp_id'] module-attribute
chgnet_to_ase_atoms(datum: dict[str, dict[str, Any]]) -> list[Atoms]
run_convert()

gendata

Functions:

make_structure(pdict: dict, mdict: dict)

Build structures based on input parameters

optimize_structure(pdict: dict, mdict: dict)

Optimize the structures

sampling_space(pdict: dict, mdict: dict)

Scale and perturb the structures. - Save 2 lists of paths: original and scaled structure paths

run_dft(pdict: dict, mdict: dict)

Run DFT calculations

collect_data(pdict: dict, mdict: dict)

Collect data from DFT simulations

main_data_generator(configfile_param: str, configfile_machine: str)

Main function to generate initial data for training ML models

copy_labeled_structure(src_dir: str, dest_dir: str)

Copy labeled structures - First, try copy labeled structure if it exists. - If there is no labeled structure, copy the unlabeled structure.

scale_x_dim(struct_files: list[str], scale_x_list: list[float])

Scale the x dimension of the structures

scale_y_dim(struct_files: list[str], scale_y_list: list[float])

Scale the y dimension of the structures

scale_z_dim(struct_files: list[str], scale_z_list: list[float])

Scale the z dimension of the structures

perturb_structure(struct_files: list, perturb_num: int, perturb_disp: float)

Perturb the structures

_total_struct_num(pdict: dict)

libgen_gpaw

Functions:

pregen_gpaw_optimize(work_dir, pdict)

This function does: - Prepare task_dirs: select only unlabeled structures to compute at clusters. - Prepare ase_args for GPAW and gpaw_run_file Note: Must define pdict.dft.calc_args.gpaw{} for this function.

rungen_gpaw_optimize(work_dir, pdict, mdict)

This function does: - Read task_dirs from .yml file - Prepare the task_list - Prepare fordward & backward files - Prepare command_list - Submit jobs to the cluster - Download the results when finished

in this function,
  • struct_dirs are relative to run_dir.
  • task_dirs are relative to work_dir.
postgen_gpaw_optimize(work_dir, pdict)

This function does: - Remove unlabeled .extxyz files, just keep the labeled ones.

pregen_gpaw_singlepoint(work_dir: str, pdict: dict)

Refer to the pregen_gpaw_optimize() function.

rungen_gpaw_singlepoint(work_dir: str, pdict: dict, mdict: dict)

Refer to the rungen_gpaw_optimize() function.

postgen_gpaw_singlepoint(work_dir, pdict)

Refer to the postgen_gpaw_optimize() function.

pregen_gpaw_aimd(work_dir, pdict)

Refer to the pregen_gpaw_optimize() function. Note: - structure_dirs: contains the optimized structures without scaling. - scale_structure_dirs: contains the scaled structures.

rungen_gpaw_aimd(work_dir, pdict, mdict)

Refer to the rungen_gpaw_optimize() function.

postgen_gpaw_aimd(work_dir, pdict)

Refer to the postgen_gpaw_optimize() function.

util_dataset

Functions:

split_struct_list(struct_list: list[Atoms], train_ratio: float = 0.9, valid_ratio: float = 0.1, seed: int = None) -> tuple[list[Atoms], list[Atoms], list[Atoms]]

Split a dataset into training, validation, and test sets.

If input (train_ratio + valid_ratio) < 1, the remaining data will be used as the test set.

Parameters:

  • data (list[Atoms]) –

    List of ASE Atoms objects.

  • train_ratio (float, default: 0.9 ) –

    Ratio of training set. Defaults to 0.9.

  • valid_ratio (float, default: 0.1 ) –

    Ratio of validation set. Defaults to 0.1.

  • seed (Optional[int], default: None ) –

    Random seed for reproducibility. Defaults to None.

Returns:

  • tuple[list[Atoms], list[Atoms], list[Atoms]] –

    Tuple[list[Atoms], list[Atoms], list[Atoms]]: Split datasets as train, valid, and test.

split_extxyz_dataset(extxyz_files: list[str], train_ratio: float = 0.9, valid_ratio: float = 0.1, seed: int = None, outfile_prefix: str = 'dataset')

Split a dataset into training, validation, and test sets.

If input (train_ratio + valid_ratio) < 1, the remaining data will be used as the test set.

Parameters:

  • extxyz_files (list[str]) –

    List of file paths in EXTXYZ format.

  • train_ratio (float, default: 0.9 ) –

    Ratio of training set. Defaults to 0.9.

  • valid_ratio (float, default: 0.1 ) –

    Ratio of validation set. Defaults to 0.1.

  • seed (Optional[int], default: None ) –

    Random seed. Defaults to None.

  • outfile_prefix (str, default: 'dataset' ) –

    Prefix for output file names. Defaults to "dataset".

read_list_extxyz(extxyz_files: list[str]) -> list[Atoms]

Read a list of EXTXYZ files and return a list of ASE Atoms objects.

merge_extxyz_files(extxyz_files: list[str], outfile: str, sort_by_atoms: bool = True, sort_pbc_len: bool = True, sort_by_composition: bool = True)

Unify multiple EXTXYZ files into a single file.

Parameters:

  • extxyz_files (list[str]) –

    List of EXTXYZ file paths.

  • outfile (str) –

    Output file path.

  • sort_by_atoms (bool, default: True ) –

    Sort by number of atoms. Defaults to True.

  • sort_by_composition (bool, default: True ) –

    Sort by chemical composition. Defaults to True.

  • sort_pbc_len (bool, default: True ) –

    Sort by periodic length. Defaults to True.

Note

np.lexsort is used to sort by multiple criteria. np.argsort is used to sort by a single criterion.

change_key_in_extxyz(extxyz_file: str, key_pairs: dict[str, str])

Change keys in extxyz file.

Parameters:

  • extxyz_file (str) –

    Path to the extxyz file.

  • key_pairs (dict) –

    Dictionary of key pairs {"old_key": "new_key"} to change. Example: {"old_key": "new_key", "forces": "ref_forces", "stress": "ref_stress"}

Note
  • If Atoms contains internal-keys (e.g., energy, forces, stress, momenta, free_energy,...), there will be a SinglePointCalculator object included to the Atoms, and these keys are stored in dict atoms.calc.results or can be accessed using .get_() methods.
  • These internal-keys are not stored in atoms.arrays or atoms.info. If we want to store (and access) these properties in atoms.arrays or atoms.info, we need to change these internal-keys to custom-keys (e.g., ref_energy, ref_forces, ref_stress, ref_momenta, ref_free_energy,...).
remove_key_in_extxyz(extxyz_file: str, key_list: list[str])

Remove unwanted keys from extxyz file to keep it clean.

select_extxyz_frames(extxyz_file: str, has_symbols: list = None, only_symbols: list = None, exact_symbols: list = None, has_properties: list = None, only_properties: list = None, has_columns: list = None, only_columns: list = None, output_file: str = 'selected_frames.extxyz') -> list[Atoms]

Choose frames from a extxyz trajectory file, based on some criteria.

Parameters:

  • extxyz_file (str) –

    Path to the extxyz file.

  • has_symbols (list, default: None ) –

    List of symbols that each frame must have at least one of them.

  • only_symbols (list, default: None ) –

    List of symbols that each frame must have only these symbols.

  • exact_symbols (list, default: None ) –

    List of symbols that each frame must have exactly these symbols.

  • has_properties (list, default: None ) –

    List of properties that each frame must have at least one of them.

  • only_properties (list, default: None ) –

    List of properties that each frame must have only these properties.

  • has_columns (list, default: None ) –

    List of columns that each frame must have at least one of them.

  • only_columns (list, default: None ) –

    List of columns that each frame must have only these columns.

  • output_file (str, default: 'selected_frames.extxyz' ) –

    Path to the output file.

pes

Modules:

libpes_gpaw

Functions:

prepes_gpaw_optimize(work_dir: str, pdict: dict)

This function does: - Prepare ase_args for GPAW and gpaw_run_file Note: Must define pdict.calc_args.gpaw{} for this function.

runpes_gpaw_optimize(work_dir, pdict, mdict)

Refer to the data.libgen_gpaw.rungen_gpaw_optimize() function.

postpes_gpaw_optimize(work_dir, pdict)
prepes_gpaw_optimize_fixatom(work_dir, pdict)

Perform optimization with some atoms fixed.

runpes_gpaw_optimize_fixatom(work_dir, pdict, mdict)
postpes_gpaw_optimize_fixatom(work_dir, pdict)

libpes_lammps

Functions:

prepes_lammps_optimize(work_dir, pdict)

Prepare LAMMPS optimization scripts.

runpes_lammps_optimize(work_dir, pdict, mdict)
postpes_lammps_optimize(work_dir, pdict)
prepes_lammps_optimize_fixatom(work_dir, pdict)

Perform optimization with some atoms fixed.

runpes_lammps_optimize_fixatom(work_dir, pdict, mdict)
postpes_lammps_optimize_fixatom(work_dir, pdict)

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.

Functions:

relax_initial_structure(pdict, mdict)

Relax the structure by DFT/MD

scanning_space(pdict, mdict)

Scale and perturb the 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.

main_pes_calculator(configfile_param: str, configfile_machine: str)

Main function to perform PES scanning calculation.

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

  • idxs (list[int]) –

    Indices of atoms to displace.

  • dx, dy, dz –

    Displacements (Å).

Returns:

  • Atoms –

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

Notes
  • 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.
_filter_atoms(struct: Atoms, filters: dict) -> list[int]

Get atom indices from structure based on filters (intersection of all filters).

Parameters:

  • struct (Atoms) –

    ASE Atoms object.

  • filters (dict) –

    Supported keys: - "elements": list[str], e.g., ['Mg', 'O'] - "above_mean_z": bool - "below_mean_z": bool - "min_z": float (keep atoms with z > min_z) - "max_z": float (keep atoms with z < max_z)

Returns:

  • list[int] –

    list[int]: Atom indices satisfying all filters.

Raises:

  • ValueError –

    If no filters are provided, or no atoms match.

_extract_dxdydz(mystring: str) -> tuple[float, float, float]

Extract dx, dy, dz from a string like xxx_dx0.1_dy-0.2_dz0.3

_extract_interlayer_distance(struct: Atoms, fix_idxs: list[int]) -> float

Extract interlayer distance from fix_atoms list

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(pes_raw_file: str, grid_size: float = 0.05)

Interpolate PES surface in the xy plane. Args: pes_raw_file: PES raw data file with columns dx dy dz delta_e grid_size: grid size (Å) for interpolation Returns: Xg, Yg, Zg: 2D arrays of grid points and interpolated delta_e values

interp_pes_z(pes_raw_file: str, grid_size: float = 0.05)

Interpolate PES curve in the z direction. Args: pes_raw_file: PES raw data file with columns dx dy dz delta_e grid_size: grid size (Å) for interpolation Returns: Zg, Einter: 1D arrays of grid points and interpolated delta_e values

plot_pes_xy(pes_xy_file: str)

Plot PES surface in the xy plane. Args: pes_xy_file: PES data file after interpolation

plot_pes_z(pes_z_file: str)

Plot PES curve in the z direction. Args: pes_z_file: PES data file after interpolation

plot_pes_3d()

phonon

Modules:

lib_phonopy

Functions:

convert_phonopy2ase(atoms: PhonopyAtoms) -> Atoms
convert_ase2phonopy(atoms: Atoms) -> PhonopyAtoms
get_band_path(atoms: Atoms, path_str: str = None, 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)
_ref_phonon_calc(atoms: Atoms, calc: object, supercell_matrix=[[2, 0, 0], [0, 2, 0], [0, 0, 2]], displacement=0.01, NAC: bool = False) -> object

NOTE: this function is note be used. just for reference.

Parameters:

  • atoms (Atoms) –

    ASE's structure object which is already optimized/relaxed as the ground state.

  • calc (object) –

    ASE calculator object.

  • supercell_matrix (list, default: [[2, 0, 0], [0, 2, 0], [0, 0, 2]] ) –

    The supercell matrix for the phonon calculation.

  • displacement (float, default: 0.01 ) –

    The atomic displacement distance in Angstrom.

  • NAC (bool, default: False ) –

    Whether to use non-analytical corrections (NAC) for the phonon calculation.

NOTE: not yet finished

libpho_gpaw

Functions:

prepho_gpaw_optimize(work_dir: str, pdict: dict)

This function does: - Prepare ase_args for GPAW and gpaw_run_file Note: Must define pdict.calc_args.gpaw{} for this function.

runpho_gpaw_optimize(work_dir, pdict, mdict)

Refer to the data.libgen_gpaw.rungen_gpaw_optimize() function.

postpho_gpaw_optimize(work_dir, pdict)
prepho_gpaw_optimize_fixbox(work_dir, pdict)

Refer to the prepho_gpaw_optimize() function. Only change gpaw_dft for fixed cell optimization.

prepho_gpaw_singlepoint(work_dir: str, pdict: dict)

Refer to the prepho_gpaw_optimize() function.

runpho_gpaw_singlepoint(work_dir: str, pdict: dict, mdict)

Refer to the data.libgen_gpaw.rungen_gpaw_optimize() function.

postpho_gpaw_singlepoint(work_dir, pdict)

This function does: - Clean up unlabelled extxyz files - Collect forces from the output files

libpho_lammps

Functions:

prepho_lammps_optimize(work_dir, pdict)

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

runpho_lammps_optimize(work_dir, pdict, mdict)

This function does: - Read task_dirs from .yml file - Prepare the task_list - Prepare fordward & backward files - Prepare command_list - Submit jobs to the cluster - Download the results when finished

postpho_lammps_optimize(work_dir, pdict)

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

prepho_lammps_optimize_fixbox(work_dir, pdict)

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

prepho_lammps_singlepoint(work_dir, pdict)

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

runpho_lammps_singlepoint(work_dir, pdict, mdict)

Reuse runpho_lammps_optimize()

postpho_lammps_singlepoint(work_dir, pdict)

This function does: - Clean up unlabelled extxyz files - Collect forces from the output files

Note
  • set_of_forces is 3D array, see np.save to save it to a file

phonon

Functions:

make_structure_phonon(pdict: dict, mdict: dict)
relax_initial_structure(pdict: dict, mdict: dict)

Relax the structure by DFT/MD

scale_and_relax(pdict: dict, mdict: dict)

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

compute_force(pdict: dict, mdict: dict)

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

compute_force_single_struct(work_dir: str, pdict: dict, mdict: dict)

Run DFT/MD single-point calculation to compute forces for each single structure in list of supercells. 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.

main_phonon_calculator(configfile_param: str, configfile_machine: str)

Main function to perform phonon calculation.

util

Modules:

ase_cell

Classes:

  • AseCell –
  • CellTransform –

    Tranform the cell and atom properties from old_cell to new_cell orientations.

Functions:

AseCell(array: np.ndarray)

Bases: Cell

Methods:

lower_triangular_form() -> tuple[Cell, np.ndarray]

Rename original function Cell.standard_form(), see https://gitlab.com/ase/ase/-/blob/master/ase/cell.py?ref_type=heads#L333

upper_triangular_form() -> tuple[Cell, np.ndarray]

Rotate axes such that the unit cell is an upper triangular matrix.

CellTransform(old_cell: np.ndarray, new_cell: np.ndarray, pure_rotation: bool = True)

Tranform the cell and atom properties from old_cell to new_cell orientations.

The idea is compute a linear transformation that maps the old cell to the new cell. A = solve(old_cell, new_cell) = old_cell^(-1) new_cell

Generally, this linear transformation A can include rotation R + shear/reshape U (stretching and shearing), i.e., A = R * U.

Therefore, this transformation can be used in two ways: 1. Directly apply A that includes both rotation and shear/stretch. (should avoid using this, since it is not clear how to transform properties like stress/forces) 2. Extract only the rotation part R from A (using polar decomposition), and use it to rotate vectors/tensors, ignoring shear/reshape change. - Extract the closest pure rotation R from A (using polar decomposition) - Use that R to rotate positions, forces, stress, etc.

Parameters:

  • old_cell (ndarray) –

    3x3 matrix represent the old cell.

  • new_cell (ndarray) –

    3x3 matrix represent the new cell.

  • pure_rotation (bool, default: True ) –

    If True, only use the rotation part of the transformation. Defaults to True.

Note
  • np.linalg.solve(A, B) solves AX = B for X. May fail if A is singular (square matrix with a determinant of zero, det(A)=0).
  • Rotation matrix is derived from QR decomposition of the cell, following Prism class

Methods:

Attributes:

old_cell = np.asarray(old_cell, dtype=float) instance-attribute
new_cell = np.asarray(new_cell, dtype=float) instance-attribute
R = _polar_rotation(A) instance-attribute
vectors_forward(vec: np.ndarray) -> np.ndarray

Rotate vectors from the old_cell's orient to the new_cell's orient.

Parameters:

  • vec (ndarray) –

    Nx3 matrix represent the vector properties. (positions, forces, etc. each row is a vector)

Returns:

  • ndarray –

    np.ndarray: Rotated vectors.

vectors_backward(vec: np.ndarray) -> np.ndarray

Rotate vectors back from the new_cell to the old_cell. Same as Prism.vector_to_ase

tensor_forward(tensor: np.ndarray) -> np.ndarray

Rotate the tensor from the old_cell's orient to the new_cell's orient. (T' = Rᵀ T R) rotates the tensor into the rotated coordinate system

Parameters:

  • tensor (ndarray) –

    3x3 matrix represent the tensor properties. (e.g., 3x3 stress tensor)

Returns:

  • ndarray –

    np.ndarray: Transformed tensor.

tensor_backward(tensor: np.ndarray) -> np.ndarray

Rotate the tensor back from the new_cell to the old_cell. Same as Prism.tensor_to_ase (T = R T' Rᵀ) rotates the tensor back into the original coordinate system

make_upper_triangular_cell(atoms: Atoms, zero_tol: float = 1e-12) -> Atoms

Atoms with a box is an upper triangular matrix is a requirement to run NPT class in ASE. [[ ax, ay, az ] [ 0, by, bz ] [ 0, 0, cz ]]

make_lower_triangular_cell(atoms: Atoms, zero_tol: float = 1e-12) -> Atoms

Converts the cell matrix of atoms into a lower triangular, to be used in LAMMPS: [[ ax, 0, 0 ] [ bx, by, 0 ] [ cx, cy, cz ]]

make_triangular_cell_extxyz(extxyz_file: str, form: str = 'lower') -> None

Make the cell of atoms in extxyz file to be triangular. Args: extxyz_file (str): Path to the extxyz file. form (str): 'upper' or 'lower'. Defaults to 'lower'.

_polar_rotation(A: np.ndarray) -> np.ndarray

Return the closest proper rotation to matrix A (polar decomposition).

The purpose of this function is to get only the orientation difference, ignoring any shear/stretch.

Remind: Given a linear transformation A=old_cell^(-1) new_cell (carry old cell vectors into the new cell vectors), we can decompose it into a rotation R and a symmetric positive semi-definite matrix U (which represents stretch/shear) such that A = R * U. The rotation matrix R captures the pure rotational component of the transformation, while U captures the deformation (stretching and shearing) component.

rotate_struct_property(struct: Atoms, new_cell: np.ndarray, wrap: bool = False, custom_vector_props: list[str] | None = None, custom_tensor_props: list[str] | None = None) -> Atoms

Rotate atomic structure and its properties to match a new cell orientation.

Parameters:

  • struct (Atoms) –

    Atoms object.

  • new_cell (ndarray) –

    3x3 matrix represent the new cell.

  • wrap (bool, default: False ) –

    If True, wrap atoms into the new cell.

  • custom_vector_props (list, default: None ) –

    List of vector properties to rotate. This allows to set vector properties with custom names.

  • custom_tensor_props (list, default: None ) –

    List of tensor properties to rotate. This allows to set tensor properties with custom names.

Returns:

  • Atoms –

    ase.Atoms: Atoms object with rotated properties.

Note
  • Important note: deepcopy(struct) copies the struct.calc object, but struct.copy() does not.
sort_task_dirs(task_dirs: list[str], work_dir: str) -> list[str]

Sort the structure paths by its supercell size. This helps to chunk the tasks with similar supercell size together (similar supercell size means similar k-point number), which then lead to running DFT calculations in similar time, avoiding the situation that some tasks are finished while others are still running.

check_bad_box(struct: Atoms, criteria: dict = {'length_ratio': 20, 'wrap_ratio': 0.5, 'tilt_ratio': 0.5}) -> bool

Check if a simulation box is "bad" based on given criteria.

Args:

struct : ase.Atoms Atoms object containing the atomic structure. criteria : dict A dictionary of criteria to check, which contains pairs of {'criteria_name': threshold_value}. Available criteria: - length_ratio: The ratio of the longest to the shortest cell vector. - Formula: max(|a|, |b|, |c|) / min(|a|, |b|, |c|) - Prevents highly elongated simulation boxes. - wrap_ratio: Checks if one cell vector component is excessively wrapped around another. - Formula: [b_x / a_x, c_y / b_y, c_x / a_x] - Prevents excessive skewing. - tilt_ratio: Measures tilting of cell vectors relative to their axes. - Formula: [b_x / b_y, c_y / c_z, c_x / c_z] - Avoids excessive tilting that may disrupt periodic boundaries.

Returns:

is_bad : bool True if the simulation box violates any of the given criteria, otherwise False.

Raises:

RuntimeError If an unknown criterion key is provided.

ase_struct

Functions:

  • build_struct –

    Build atomic configuration, using library ase.build

  • scale_struct –

    Scale the atoms and the cell by the given factors along the three cell vectors.

  • perturb_struct –

    Perturb the atoms by random displacements. This method adds random displacements to the atomic positions. See more

  • slice_struct –

    Slice structure into the first subcell by given numbers along a, b, c (cell vector) directions.

  • align_struct_to_origin –

    Align min atoms position to the origin.

  • add_vacuum –

    Add vacuum padding along the three cell vectors. This function works correctly for non-orthogonal (triclinic) unit cells.

  • poscar2lmpdata –

    Convert POSCAR file to LAMMPS data file.

  • extxyz2lmpdata –

    Convert extxyz file to LAMMPS data file.

  • lmpdata2extxyz –

    Convert LAMMPS data file to extxyz file.

  • lmpdump2extxyz –

    Convert LAMMPS dump file to extxyz file.

  • write_extxyz –

    Write a list of Atoms object to an extxyz file. The exited ase.io.write function does not support writing file if the parent directory does not exist. This function will overcome this problem.

  • read_extxyz –

    Read extxyz file. The exited ase.io.read returns a single Atoms object if file contains only one frame. This function will return a list of Atoms object.

  • check_bad_box_extxyz –

    Check structure in extxyz file whether it has bad box.

  • find_primitive_cell –

    Find the primitive cell of the given atoms object.

build_struct(argdict: dict) -> Atoms

Build atomic configuration, using library ase.build

Supported structure types: - bulk: sc, fcc, bcc, tetragonal, bct, hcp, rhombohedral, orthorhombic, mcl, diamond, zincblende, rocksalt, cesiumchloride, fluorite or wurtzite. - molecule: molecule - mx2: MX2 - graphene: graphene

Parameters:

  • argdict (dict) –

    Parameters dictionary

Returns:

  • struct ( Atoms ) –

    ASE Atoms object

Notes
  • build.graphene() does not set the cell c vector along z axis, so we need to modify it manually.
scale_struct(struct: Atoms, factors: list = [1.0, 1.0, 1.0]) -> Atoms

Scale the atoms and the cell by the given factors along the three cell vectors.

Parameters:

  • struct (Atoms) –

    ASE Atoms object to scale.

  • factors (list, default: [1.0, 1.0, 1.0] ) –

    Scaling factors along cell-vectors a, b, c (not x, y, z dims in Cartersian axes).

Returns:

  • atoms ( Atoms ) –

    New scaled Atoms object.

perturb_struct(struct: Atoms, std_disp: float) -> Atoms

Perturb the atoms by random displacements. This method adds random displacements to the atomic positions. See more

slice_struct(struct: Atoms, slice_num=(2, 2, 2), tol=1e-05) -> Atoms

Slice structure into the first subcell by given numbers along a, b, c (cell vector) directions.

align_struct_to_origin(struct: Atoms) -> Atoms

Align min atoms position to the origin.

add_vacuum(struct: Atoms, distances: list = [0.0, 0.0, 0.0]) -> Atoms

Add vacuum padding along the three cell vectors. This function works correctly for non-orthogonal (triclinic) unit cells.

Parameters:

  • struct (Atoms) –

    ASE Atoms object to add vacuum.

  • distances (list, default: [0.0, 0.0, 0.0] ) –

    Distances to add along cell vectors a, b, c (not x, y, z dims in Cartersian axes). Must be a list of 3 floats.

Returns:

  • struct ( Atoms ) –

    A new Atoms object with an expanded cell and centered atoms.

Raises:

  • ZeroDivisionError –

    If any of the cell vectors has zero length, a division by zero will occur.

Notes
  • This expands each cell vector v to v + (vacuum * unit_v), where unit_v is the normalized direction of the vector.
  • Atom positions are not scaled, only the cell is resized and atoms are centered.
poscar2lmpdata(poscar_file: str, lmpdata_file: str, atom_style: str = 'atomic') -> list[str]

Convert POSCAR file to LAMMPS data file.

extxyz2lmpdata(extxyz_file: str, lmpdata_file: str, atom_style: str = 'atomic') -> list[str]

Convert extxyz file to LAMMPS data file. Note: need to save 'original_cell' to able to revert the original orientation of the crystal.

lmpdata2extxyz(lmpdata_file: str, extxyz_file: str, original_cell_file: str = None)

Convert LAMMPS data file to extxyz file.

lmpdump2extxyz(lmpdump_file: str, extxyz_file: str, original_cell_file: str = None, stress_file: str = None, lammps_units: str = 'metal')

Convert LAMMPS dump file to extxyz file.

Parameters:

  • lmpdump_file (str) –

    Path to the LAMMPS dump file.

  • extxyz_file (str) –

    Path to the output extxyz file.

  • original_cell_file (str, default: None ) –

    Path to the text file contains original_cell. It should a simple text file that can write/read with numpy. If not provided, try to find in the same directory as lmpdump_file with the extension .original_cell. Defaults to None.

  • stress_file (str, default: None ) –

    Path to the text file contains stress tensor. Defaults to None.

Restriction
  • Current ver: stress is mapped based on frame_index, it requires that frames in text stress file must be in the same "length and order" as in the LAMMPS dump file.
  • struct.info.get("timestep") is a new feature in ASE 3.25 ?
write_extxyz(outfile: str, structs: list[Atoms]) -> None

Write a list of Atoms object to an extxyz file. The exited ase.io.write function does not support writing file if the parent directory does not exist. This function will overcome this problem.

Parameters:

  • structs (list) –

    List of Atoms object.

  • outfile (str) –

    Path to the output file.

read_extxyz(extxyz_file: str, index=':') -> list[Atoms]

Read extxyz file. The exited ase.io.read returns a single Atoms object if file contains only one frame. This function will return a list of Atoms object.

Parameters:

  • extxyz_file (str) –

    Path to the output file.

Returns:

  • list ( list[Atoms] ) –

    List of Atoms object.

Note
  • ase.io.read returns a single Atoms object or a list of Atoms object, depending on the index argument.
    • index=":" will always return a list.
    • index=0 or index=-1 will return a single Atoms object.
  • this function will always return a list of Atoms object, even index=0 or index=-1
check_bad_box_extxyz(extxyz_file: str, criteria: dict = {'length_ratio': 100, 'wrap_ratio': 0.5, 'tilt_ratio': 0.5}) -> list[int]

Check structure in extxyz file whether it has bad box. Return: a file remarking the bad box frames.

find_primitive_cell(struct: Atoms, symprec=1e-05, angle_tolerance=-1.0) -> Atoms

Find the primitive cell of the given atoms object. Note: must use .get_scaled_positions() to define the cell in spglib.

key

Attributes:

time_str = time.strftime('%y%m%d_%H%M%S') module-attribute
DIR_LOG = 'log' module-attribute
FILE_LOG_ALFF = f'{DIR_LOG}/{time_str}_alff.log' module-attribute
FILE_LOG_DISPATCH = FILE_LOG_ALFF module-attribute
FILE_ITERLOG = f'{DIR_LOG}/_alff.iter' module-attribute
DIR_TRAIN = '00_train' module-attribute
DIR_MD = '01_md' module-attribute
DIR_DFT = '02_dft' module-attribute
DIR_DATA = '03_data' module-attribute
DIR_TMP = 'tmp_dir' module-attribute
DIR_TMP_DATA = 'copy_data' module-attribute
DIR_TMP_MODEL = 'copy_model' module-attribute
FILE_DATAPATH = 'data_paths.yml' module-attribute
FILE_MODELPATH = 'model_paths.yml' module-attribute
FILE_CHECKPOINT_PATH = 'checkpoint_paths.yml' module-attribute
FILE_ARG_TRAIN = 'arg_train.yml' module-attribute
FILE_TRAJ_MD = 'traj_md.extxyz' module-attribute
FILE_TRAJ_MD_CANDIDATE = FILE_TRAJ_MD.replace('.extxyz', '_candidate.extxyz') module-attribute
FILE_FINAL_DATA = 'data_label.extxyz' module-attribute
FILE_COLLECT_DATA = 'collect_data_label.extxyz' module-attribute
FMT_ITER = '04d' module-attribute
FMT_STAGE = '02d' module-attribute
FMT_MODEL = '02d' module-attribute
FMT_STRUCT = '05d' module-attribute
FMT_TASK_MD = '06d' module-attribute
FMT_TASK_DFT = '06d' module-attribute
FILE_SCRIPT_LAMMPS = 'cli_lammps.lmp' module-attribute
FILE_ARG_LAMMPS = 'arg_lammps.yml' module-attribute
FILE_ARG_ASE = 'arg_ase.yml' module-attribute
SCRIPT_ASE_PATH = f'{ALFF_ROOT}/util/script_ase' module-attribute
SCHEMA_ASE_RUN = f'{ALFF_ROOT}/util/script_ase/schema_ase_run.yml' module-attribute
SCHEMA_LAMMPS = f'{ALFF_ROOT}/util/script_lammps/schema_lammps.yml' module-attribute
SCHEMA_ACTIVE_LEARN = f'{ALFF_ROOT}/al/schema_active_learn.yml' module-attribute
SCHEMA_FINETUNE = f'{ALFF_ROOT}/al/schema_finetune.yml' module-attribute
DIR_MAKE_STRUCT = '00_make_structure' module-attribute
DIR_SCALE = '01_scale' module-attribute
DIR_GENDATA = '02_gendata' module-attribute
FILE_FRAME_unLABEL = 'conf.extxyz' module-attribute
FILE_FRAME_LABEL = 'conf_label.extxyz' module-attribute
FILE_TRAJ_LABEL = 'traj_label.extxyz' module-attribute
SCHEMA_ASE_BUILD = f'{ALFF_ROOT}/util/script_ase/schema_ase_build.yml' module-attribute
SCHEMA_GENDATA = f'{ALFF_ROOT}/gdata/schema_gendata.yml' module-attribute
SCHEMA_PHONON = f'{ALFF_ROOT}/phonon/schema_phonon.yml' module-attribute
SCHEMA_ELASTIC = f'{ALFF_ROOT}/elastic/schema_elastic.yml' module-attribute
SCHEMA_PES_SCAN = f'{ALFF_ROOT}/pes/schema_pes_scan.yml' module-attribute
DIR_SUPERCELL = '01_supercell' module-attribute
DIR_PHONON = '02_phonon' module-attribute
DIR_ELASTIC = '02_elastic' module-attribute
DIR_SCAN = '01_scan' module-attribute
DIR_PES = '02_pes' module-attribute

script_ase

Modules:

cli_ase_md

Some notes: - Run MD in ase following this tutorial: https://wiki.fysik.dtu.dk/ase/tutorials/md/md.html - For MD run, control symmetry to avoid error: broken symmetry. - Must set txt='calc.txt' in GPAW calculator for backward files. - Defines some print functions that can attach to ASE's dynamics object - param_yaml must contain - a dict ase_calc define calculator. - a dict md with ASE MD parameters.

Functions:

Attributes:

pdict = get_cli_args() module-attribute
ase_calc = pdict.get('calc_args', {}).get('ase', {}) module-attribute
code_lines = f.read() module-attribute
struct_args = pdict['structure'] module-attribute
extxyz_file = struct_args['from_extxyz'] module-attribute
atoms = read(extxyz_file, format='extxyz', index='-1') module-attribute
input_pbc = struct_args.get('pbc', False) module-attribute
md_args = {'ensemble': 'NVE', 'dt': 1, 'temp': 300, 'thermostat': 'langevin', 'barostat': 'parrinello_rahman'} module-attribute
input_md_args = pdict.get('md', {}) module-attribute
thermostat = md_args['thermostat'] module-attribute
support_thermostats = ['langevin', 'nose_hoover', 'nose_hoover_chain'] module-attribute
barostat = md_args['barostat'] module-attribute
support_barostats = ['parrinello_rahman', 'iso_nose_hoover_chain', 'aniso_nose_hoover_chain'] module-attribute
dt = md_args['dt'] * units.fs module-attribute
temp = md_args['temp'] module-attribute
ensemble = md_args['ensemble'] module-attribute
dyn = VelocityVerlet(atoms, timestep=dt) module-attribute
friction = md_args.get('langevin_friction', 0.002) / units.fs module-attribute
tdamp = md_args.get('tdamp', 100) module-attribute
stress = md_args.get('press', None) module-attribute
stress_in_eVA3 = stress / units.GPa module-attribute
pfactor = md_args.get('pfactor', 2000000.0) module-attribute
mask = md_args.get('mask', None) module-attribute
pdamp = barostat.get('pdamp', 1000) module-attribute
equil_steps = md_args.get('equil_steps', 0) module-attribute
num_frames = md_args.get('num_frames', 1) module-attribute
traj_freq = md_args.get('traj_freq', 1) module-attribute
nsteps = num_frames * traj_freq module-attribute
get_cli_args()

Get the arguments from the command line

print_dynamic(atoms=atoms, filename='calc_dyn_properties.txt')

Function to print the potential, kinetic and total energy. Note: Stress printed in this file in GPa, but save in EXTXYZ in eV/Angstrom^3.

write_dyn_extxyz(atoms=atoms, filename='traj_md.extxyz')
cli_gpaw_aimd

Some notes: - Run MD in ase following this tutorial: https://wiki.fysik.dtu.dk/ase/tutorials/md/md.html - For MD run, control symmetry to avoid error: broken symmetry. - Must set txt='calc.txt' in GPAW calculator for backward files. - param_yaml must contain - a dict gpaw_calc with GPAW parameters. - a dict md with ASE MD parameters.

Functions:

Attributes:

pdict = get_cli_args() module-attribute
gpaw_args = pdict['calc_args'].get('gpaw', {}) module-attribute
gpaw_params = {'mode': {'name': 'pw', 'ecut': 500}, 'xc': 'PBE', 'convergence': {'energy': 1e-06, 'density': 0.0001, 'eigenstates': 1e-08}, 'occupations': {'name': 'fermi-dirac', 'width': 0.01}, 'txt': 'calc_aimd.txt', 'symmetry': 'off'} module-attribute
calc1 = GPAW(**gpaw_params) module-attribute
dftd3_args = pdict['calc_args'].get('dftd3', {}) module-attribute
xc = gpaw_params['xc'] module-attribute
damping = dftd3_args.pop('damping', 'd3zero') module-attribute
calc2 = DFTD3(method=xc, damping=damping, **dftd3_args) module-attribute
calc = SumCalculator([calc1, calc2]) module-attribute
struct_args = pdict['structure'] module-attribute
extxyz_file = struct_args['from_extxyz'] module-attribute
atoms = read(extxyz_file, format='extxyz', index='-1') module-attribute
input_pbc = struct_args.get('pbc', False) module-attribute
md_args = {'ensemble': 'NVE', 'dt': 1, 'temp': 300, 'thermostat': 'langevin', 'barostat': 'parrinello_rahman'} module-attribute
input_md_args = pdict.get('md', {}) module-attribute
thermostat = md_args['thermostat'] module-attribute
support_thermostats = ['langevin', 'nose_hoover', 'nose_hoover_chain'] module-attribute
barostat = md_args['barostat'] module-attribute
support_barostats = ['parrinello_rahman', 'iso_nose_hoover_chain', 'aniso_nose_hoover_chain'] module-attribute
dt = md_args['dt'] * units.fs module-attribute
temp = md_args['temp'] module-attribute
ensemble = md_args['ensemble'] module-attribute
dyn = VelocityVerlet(atoms, timestep=dt) module-attribute
friction = md_args.get('langevin_friction', 0.002) / units.fs module-attribute
tdamp = md_args.get('tdamp', 100) module-attribute
stress = md_args.get('press', None) module-attribute
stress_in_eVA3 = stress / units.GPa module-attribute
pfactor = md_args.get('pfactor', 2000000.0) module-attribute
mask = md_args.get('mask', None) module-attribute
pdamp = barostat.get('pdamp', 1000) module-attribute
equil_steps = md_args.get('equil_steps', 0) module-attribute
num_frames = md_args.get('num_frames', 1) module-attribute
traj_freq = md_args.get('traj_freq', 1) module-attribute
nsteps = num_frames * traj_freq module-attribute
get_cli_args()

Get the arguments from the command line

print_dynamic(atoms=atoms, filename='calc_dyn_properties.txt')

Function to print the potential, kinetic and total energy. Note: Stress printed in this file in GPa, but save in EXTXYZ in eV/Angstrom^3.

write_dyn_extxyz(atoms=atoms, filename='traj_label.extxyz')
cli_gpaw_optimize

Some notes - Must set txt='calc.txt' in GPAW calculator for backward files. - param_yaml must contain - a dict gpaw_calc with GPAW parameters. - a dict optimize with ASE optimization parameters.

Functions:

Attributes:

pdict = get_cli_args() module-attribute
gpaw_args = pdict['calc_args'].get('gpaw', {}) module-attribute
gpaw_params = {'mode': {'name': 'pw', 'ecut': 500}, 'xc': 'PBE', 'convergence': {'energy': 1e-06, 'density': 0.0001, 'eigenstates': 1e-08}, 'occupations': {'name': 'fermi-dirac', 'width': 0.01}, 'txt': 'calc_optimize.txt'} module-attribute
calc1 = GPAW(**gpaw_params) module-attribute
dftd3_args = pdict['calc_args'].get('dftd3', {}) module-attribute
xc = gpaw_params['xc'] module-attribute
damping = dftd3_args.pop('damping', 'd3zero') module-attribute
calc2 = DFTD3(method=xc, damping=damping, **dftd3_args) module-attribute
calc = SumCalculator([calc1, calc2]) module-attribute
struct_args = pdict['structure'] module-attribute
extxyz_file = struct_args['from_extxyz'] module-attribute
atoms = read(extxyz_file, format='extxyz', index='-1') module-attribute
input_pbc = struct_args.get('pbc', False) module-attribute
opt_args = pdict.get('optimize', {}) module-attribute
mask = opt_args.get('mask', None) module-attribute
pbc = atoms.get_pbc() module-attribute
constraint_arg = pdict.get('constraint', {}) module-attribute
fix_idxs = constraint_arg['fix_idxs'] module-attribute
fmax = opt_args.get('fmax', 0.05) module-attribute
max_steps = opt_args.get('max_steps', 10000) module-attribute
atoms_filter = FrechetCellFilter(atoms, mask=mask) module-attribute
opt = BFGS(atoms_filter) module-attribute
pot_energy = atoms.get_potential_energy() module-attribute
forces = atoms.get_forces() module-attribute
stress = atoms.get_stress() module-attribute
output_file = extxyz_file.replace('.extxyz', '_label.extxyz') module-attribute
get_cli_args()

Get the arguments from the command line

cli_gpaw_singlepoint

Some notes - Must set txt='calc.txt' in GPAW calculator for backward files. - param_yaml must contain - a dict gpaw_calc with GPAW parameters.

Functions:

Attributes:

pdict = get_cli_args() module-attribute
gpaw_args = pdict['calc_args'].get('gpaw', {}) module-attribute
gpaw_params = {'mode': {'name': 'pw', 'ecut': 500}, 'xc': 'PBE', 'convergence': {'energy': 1e-06, 'density': 0.0001, 'eigenstates': 1e-08}, 'occupations': {'name': 'fermi-dirac', 'width': 0.01}, 'txt': 'calc_singlepoint.txt'} module-attribute
calc1 = GPAW(**gpaw_params) module-attribute
dftd3_args = pdict['calc_args'].get('dftd3', {}) module-attribute
xc = gpaw_params['xc'] module-attribute
damping = dftd3_args.pop('damping', 'd3zero') module-attribute
calc2 = DFTD3(method=xc, damping=damping, **dftd3_args) module-attribute
calc = SumCalculator([calc1, calc2]) module-attribute
struct_args = pdict['structure'] module-attribute
extxyz_file = struct_args['from_extxyz'] module-attribute
atoms = read(extxyz_file, format='extxyz', index='-1') module-attribute
input_pbc = struct_args.get('pbc', False) module-attribute
pot_energy = atoms.get_potential_energy() module-attribute
forces = atoms.get_forces() module-attribute
stress = atoms.get_stress() module-attribute
output_file = extxyz_file.replace('.extxyz', '_label.extxyz') module-attribute
get_cli_args()

Get the arguments from the command line

script_lammps

Modules:

lammps_code_creator

Functions:

generate_script_lammps_singlepoint(units: str = 'metal', atom_style: str = 'atomic', dimension: int = 3, pbc: list = [1, 1, 1], read_data: str = 'path_to_file.lmpdata', read_restart: str = None, pair_style: list[str] = ['eam/alloy'], pair_coeff: list[str] = ['* * Cu.eam.alloy Cu'], output_script: str = 'cli_script_lammps.lmp', **kwargs)

Generate lammps script for single-point calculation.

Parameters:

  • units (str, default: 'metal' ) –

    Units for lammps. Default "metal"

  • atom_style (str, default: 'atomic' ) –

    Atom style of system. Default "atomic"

  • dimension (int, default: 3 ) –

    Dimension of system. Default 3

  • pbc (list, default: [1, 1, 1] ) –

    Periodic boundary conditions. Default [1, 1, 1]

  • read_data (str, default: 'path_to_file.lmpdata' ) –

    Path to the data file. e.g. "path_to_lmpdata"

  • read_restart (str, default: None ) –

    Path to the restart file. e.g. "path_to_restart". If provided, read_restart is used instead of read_data.

  • pair_style (list[str], default: ['eam/alloy'] ) –

    List of pair_style. Default ["eam/alloy"]

  • pair_coeff (list[str], default: ['* * Cu.eam.alloy Cu'] ) –

    List of pair_coeff. Default ["* * Cu.eam.alloy Cu"]

  • output_script (str, default: 'cli_script_lammps.lmp' ) –

    Path to the output script. Default "cli_script_lammps.in"

generate_script_lammps_minimize(units: str = 'metal', atom_style: str = 'atomic', dimension: int = 3, pbc: list = [1, 1, 1], read_data: str = 'path_to_file.lmpdata', read_restart: str = None, pair_style: list[str] = ['eam/alloy'], pair_coeff: list[str] = ['* * Cu.eam.alloy Cu'], min_style: str = 'cg', etol: float = 1e-09, ftol: float = 1e-09, maxiter: int = 100000, maxeval: int = 100000, dmax: float = 0.01, press: Union[list[int], float, bool] = [None, None, None], mask: list[int] = [1, 1, 1], couple: str = 'none', output_script: str = 'cli_script_lammps.lmp', custom_lines: list[str] = None, **kwargs)

Generate lammps script for minimization.

Parameters:

  • etol (float, default: 1e-09 ) –

    Energy tolerance for minimization. Default 1.0e-9

  • ftol (float, default: 1e-09 ) –

    Force tolerance for minimization. Default 1.0e-9

  • maxiter (int, default: 100000 ) –

    Maximum number of iterations. Default 100000

  • maxeval (int, default: 100000 ) –

    Maximum number of evaluations. Default 100000

  • dmax (float, default: 0.01 ) –

    maximum distance for line search to move (distance units). Default: 0.01

  • press (Union[list[int], float, bool], default: [None, None, None] ) –

    float/1x3 list of Pressure values in GPa. If a single value is provided, it is applied to all directions.

  • mask (list[int], default: [1, 1, 1] ) –

    3x1 list of Mask for pressure. Default [1, 1, 1]. Mask to more control which directions is allowed to relax.

  • couple (str, default: 'none' ) –

    "none", xyz, xy, yz, xz. Default "none"

  • output_script (str, default: 'cli_script_lammps.lmp' ) –

    Path to the output script. Default "cli_script_lammps.in"

  • custom_lines (list[str], default: None ) –

    List of custom lines to be added brefore run minimization. Default None.

For control pressure
  • Only control pressure in the periodic directions.
  • If single value is given, it is assumed to be the pressure in all directions.
  • If three values are given, they are assumed to be the pressure in x, y, and z directions, respectively.
  • **kwargs, to accept unused arguments, any other arguments which may be ignored.
generate_script_lammps_md(units: str = 'metal', atom_style: str = 'atomic', dimension: int = 3, pbc: list = [1, 1, 1], read_data: str = 'path_to_file.lmpdata', read_restart: str = None, pair_style: list[str] = ['eam/alloy'], pair_coeff: list[str] = ['* * Cu.eam.alloy Cu'], ensemble: Literal['NVE', 'NVT', 'NPT'] = 'NVE', dt: float = 0.001, num_frames: int = 0, traj_freq: int = 1, equil_steps: int = 0, plumed_file: str = None, thermo_freq: int = 5000, first_minimize: bool = False, temp: float = 300, tdamp: int = 100, thermostat: Literal['nose_hoover_chain', 'langevin'] = 'nose_hoover_chain', press: Optional[Union[float, list[float]]] = None, mask: list[int] = [1, 1, 1], couple: str = 'none', pdamp: int = 1000, barostat: Literal['nose_hoover_chain'] = 'nose_hoover_chain', deform_limit: Optional[float] = None, output_script: str = 'cli_script_lammps.lmp', **kwargs)

Generate lammps script for MD simulation.

Parameters:

  • first_minimize (bool, default: False ) –

    Whether to perform a first minimization before MD simulation. Default False

  • ensemble (Literal['NVE', 'NVT', 'NPT'], default: 'NVE' ) –

    Ensemble for MD simulation. Default "NVE"

  • dt (float, default: 0.001 ) –

    Time step for MD simulation. Default 0.001 ps = 1 fs if unit metal, 1 fs if unit real

  • traj_freq (int, default: 1 ) –

    Frequency to dump trajectory. Default 1

  • num_frames (int, default: 0 ) –

    number of frames to be collected. Then total MD nsteps = (num_frames * traj_freq)

  • equil_steps (int, default: 0 ) –

    Number of steps for first equilibration. Default 0

  • plumed_file (str, default: None ) –

    Path to the plumed file. Default None

  • thermo_freq (int, default: 5000 ) –

    Frequency to print thermo. Default 5000

  • temp (float, default: 300 ) –

    Temperature for MD simulation. Default 300

  • tdamp (int, default: 100 ) –

    Damping time for thermostat. Default 100

  • thermostat (Literal['nose_hoover_chain', 'langevin'], default: 'nose_hoover_chain' ) –

    Thermostat for MD simulation. Default "nose_hoover_chain"

  • press (Union[list[int], float, bool], default: None ) –

    float/1x3 list of Pressure values. If a single value is provided, it is applied to all directions.

  • mask (list[int], default: [1, 1, 1] ) –

    3x1 list of Mask for pressure. Default [1, 1, 1]. Mask to more control which directions is allowed to relax.

  • couple (str, default: 'none' ) –

    "none", xyz, xy, yz, xz. Default "none"

  • pdamp (int, default: 1000 ) –

    Damping time for barostat. Default 1000

  • barostat (Literal['nose_hoover_chain'], default: 'nose_hoover_chain' ) –

    Barostat for MD simulation. Default "nose_hoover_chain"

  • deform_limit (Optional[float], default: None ) –

    Maximum fractional change allowed for any box dimension. The simulation stops if \(abs(L - L0) / L0 > deform_limit\) in any of x, y, or z dim.

  • output_script (str, default: 'cli_script_lammps.lmp' ) –

    Path to the output script. Default "cli_script_lammps.in"

For control pressure
  • Only control pressure in the periodic directions.
  • If single value is given, it is assumed to be the pressure in all directions.
  • If three values are given, they are assumed to be the pressure in x, y, and z directions, respectively.
lmp_section_atom_forcefield(units: str = 'metal', atom_style: str = 'atomic', dimension: int = 3, pbc: list = [1, 1, 1], read_data: str = 'path_to_file.lmpdata', read_restart: str = None, pair_style: list[str] = ['eam/alloy'], pair_coeff: list[str] = ['* * Cu.eam.alloy Cu'], **kwargs) -> list[str]

Generate lammps input block for atom and forcefield.

Parameters:

  • read_data (str, default: 'path_to_file.lmpdata' ) –

    Path to the data file. e.g. "path_to_lmpdata"

  • read_restart (str, default: None ) –

    Path to the restart file. e.g. "path_to_restart". If provided, read_restart is used instead of read_data.

lmp_section_common_setting() -> list[str]
lmp_section_minimize(min_style: str = 'cg', etol: float = 1e-09, ftol: float = 1e-09, maxiter: int = 100000, maxeval: int = 100000, dmax: float = 0.01, press: list = [None, None, None], couple: str = 'none', uid: str = None, **kwargs) -> list[str]

Generate lammps input block for minimization.

lmp_section_dynamic_setting(dt: float, temp: float, thermo_freq: int = 5000, **kwargs) -> list[str]
lmp_section_nve(num_frames: int = 0, traj_freq: int = 1, plumed_file: str = None, dump_result: bool = False, uid: str = None, **kwargs) -> tuple[list[str]]
lmp_section_nvt(num_frames: int = 0, traj_freq: int = 1, temp: float = 300, tdamp: int = 100, thermostat: str = 'nose_hoover_chain', plumed_file: str = None, dump_result: bool = False, uid: str = None, **kwargs) -> list[str]
lmp_section_npt(num_frames: int = 0, traj_freq: int = 1, temp: float = 300, tdamp: int = 100, thermostat: str = 'nose_hoover_chain', press: list = [0, 0, 0], pdamp: int = 1000, barostat: str = 'nose_hoover_chain', mask: list[int] = [1, 1, 1], couple: str = 'none', plumed_file: str = None, dump_result: bool = False, deform_limit: float = None, uid: str = None, **kwargs) -> list[str]

Generate lammps input block for NPT simulation. Support tracking box expension during NPT simulation. The simulation stops if \(abs(L - L0) / L0 > deform_limit\) in any of x, y, or z.

lmp_section_nph()
lmp_section_custom_lines(lines: list[str]) -> list[str]
_lmp_section_dump(traj_freq: int, uid: str = None, single_frame=False) -> tuple[list[str]]
_lmp_section_run0(uid: str = None) -> tuple[list[str]]
_lmp_section_unfix(fixes: list[str] = [], dumps: list[str] = []) -> list[str]
_pbc_string(pbc: list = [1, 1, 1]) -> str

Convert pbc list to string. [1, 1, 0] -> "p p f". See https://docs.lammps.org/boundary.html

Acceptable values: 1, 0, p, f, s, m

_revise_input_pressure(press: Union[list[int], float, bool], pbc: list = [1, 1, 1], mask: list = [1, 1, 1], units: str = 'metal') -> list

Revise pressure string based on pbc and mask. This allows more flexible control of pressure setting, fllowing that: - Pressures only applied to the directions with pbc=1 and mask=1, regardless input press. - If press is a single value, this value is used to all directions. - Convert pressure unit from GPa to lammps unit based on choosen units (e.g. metal, real).

Parameters:

  • press (Union[list[int], float, bool]) –

    float/1x3 list of Pressure values in GPa. If a single value is provided, it is applied to all directions.

  • pbc (list[int], default: [1, 1, 1] ) –

    3x1 list of Periodic boundary conditions. Default [1, 1, 1]

  • mask (list[int], default: [1, 1, 1] ) –

    3x1 list of Mask for pressure. Default [1, 1, 1]. Mask to more control which directions is allowed to relax.

_press_string_minimize(press: list = [0.0, 0.0, 0.0]) -> str

Convert pressure list to lammps-style string. Example:

  • [0.0, 0.0, 0.0] -> 'x 0.0 y 0.0 z 0.0'
  • [None, 0.0, 0.0] -> 'y 0.0 z 0.0'
  • [None, None, None] -> ''
_press_string_md(press: list = [0.0, 0.0, 0.0], pdamp: int = 1000) -> str

Convert pressure list to lammps-style string. Example:

  • [0.0, 0.0, 0.0] -> 'x 0.0 y 0.0 z 0.0'
  • [None, 0.0, 0.0] -> 'y 0.0 z 0.0'
  • [None, None, None] -> error
process_lammps_argdict(argdict: dict) -> dict

LAMMPS argdict must be defined as a dictionary with 4 'top-level' keys: structure, optimize, md, extra. That form requirement is to be validated using LAMMPS args schema.

However, when generating lammps script, we only need the 'sub-level' keys. So, this function is to remove 'top-level' keys, and return 'sub-level' keys only to be used generate lammps script functions.

Parameters:

  • argdict (dict) –

    Dictionary of dicts of lammps arguments.

Returns:

  • dict ( dict ) –

    Processed lammps arguments.

tool

Functions:

text_pkg_info(packages=['ase', 'numpy', 'scipy', 'sevenn', 'phonopy', 'thkit'])
check_supported_calculator(calculator: str)

Check if the calculator is supported.

generate_strain_points(start: float, stop: float, step: float, tol: float = 1e-06) -> np.ndarray

Generate spacing points with including the stop point.

mk_struct_dir(pdict)

Create the directory name for the structure

validate