Skip to content

API reference

alff


ALFF: Frameworks for Active Learning Graph-based Force Fields and Material Properties Calculations.

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

al

Modules:

  • active_learning –

    Active Learning workflow implementation.

  • finetune –

    Classes and functions for fine-tuning ML models.

  • libal_md_ase –

    Library for ASE MD with SevenNet model.

  • libal_md_lammps –

    Library for LAMMPS MD with SevenNet model.

  • utilal –

    Utilities for Active Learning workflow.

  • utilal_uncertainty –

    Utilities for uncertainty estimation using models committee.

active_learning

Active Learning workflow implementation.

Classes:

Functions:

WorkflowActiveLearning(params_file: str, machines_file: str)

Bases: Workflow

Workflow for active learning. Note: Need to redefine .run() method, since the Active Learning workflow is different from the base class.

Methods:

Attributes:

stage_map = {'ml_train': stage_train, 'md_explore': stage_md, 'dft_label': stage_dft} instance-attribute
wf_name = 'ACTIVE LEARNING' 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()
stage_train(iter_idx, pdict, mdict)

Stage function for ML training tasks.

This function includes: preparing training data and args, running training, and postprocessing. - collect data files - prepare training args based on MLP engine

stage_md(iter_idx, pdict, mdict)

Stage function for MD exploration tasks.

Including: pre, run, post MD. - Collect initial configurations - Prepare MD args - Submit MD jobs to remote machines - Postprocess MD results

stage_dft(iter_idx, pdict, mdict)

Stage function for DFT labeling tasks. Including: pre, run, post DFT.

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

Classes and functions for fine-tuning ML models.

Classes:

  • WorkflowFinetune –

    Workflow for fine-tuning the existed ML models or train a new ML model.

Functions:

  • stage_train –

    Stage function for ML training tasks.

WorkflowFinetune(params_file: str, machines_file: str)

Bases: Workflow

Workflow for fine-tuning the existed ML models or train a new ML model. Needs to override self.stage_list in base class, because the stages are fixed here.

Methods:

  • run –

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

Attributes:

stage_map = {'ml_train': stage_train} instance-attribute
wf_name = 'FINE-TUNING' instance-attribute
stage_list = ['ml_train'] 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
run()

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

stage_train(pdict, mdict)

Stage function for ML training tasks.

libal_md_ase

Library for ASE MD with SevenNet model.

Classes:

Functions:

OperAlmdAseSevennet(work_dir, pdict, multi_mdict, mdict_prefix='md')

Bases: RemoteOperation

This class runs ASE md for a list of structures in task_dirs.

Methods:

Attributes:

op_name = 'ASE MD with SevenNet' instance-attribute
task_filter = {'has_files': ['conf.extxyz'], 'no_files': ['committee_error.txt']} 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()

Prepare MD tasks.

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

postprocess()
run()

Function to submit jobs to remote machines.

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

Prepare MD args.

Includes: - copy ML models to work_dir - collect initial configurations - prepare ASE args - generate task_dirs for ranges of temperature and press

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

Library for LAMMPS MD with SevenNet model.

Classes:

Functions:

OperAlmdLammpsSevennet(work_dir, pdict, multi_mdict, mdict_prefix='md')

Bases: RemoteOperation

This class runs LAMMPS md for a list of structures in task_dirs.

Methods:

Attributes:

op_name = 'LAMMPS MD with SevenNet' instance-attribute
task_filter = {'has_files': ['conf.lmpdata'], 'no_files': ['committee_error.txt']} 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()

Prepare MD tasks.

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

postprocess()
run()

Function to submit jobs to remote machines.

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

Prepare MD args.

Includes: - copy ML models to work_dir - collect initial configurations - prepare lammps args - generate task_dirs for ranges of temperature and press

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

utilal

Utilities for Active Learning workflow.

Classes:

  • D3ParamMD –

    Different packages use different names for D3 parameters.

  • D3ParamDFT –

    Different packages use different names for D3 parameters.

  • MLP2Lammps –

    Convert MLP model to be used in LAMMPS.

D3ParamMD(d3package: str = 'sevenn')

Different packages use different names for D3 parameters. This class to 'return' standard D3 parameter names for different packages used for MD.

Subclassed by:

Methods:

Attributes:

d3package: str = d3package instance-attribute
default_cutoff: float = 50.2022 instance-attribute
default_cn_cutoff: float = 21.1671 instance-attribute
param_names = params['params'] instance-attribute
damping_map = params['damping_map'] instance-attribute
get_params() -> dict

Return D3 parameter names according to different packages.

check_supported_damping(damping: str)

Check if the damping method is supported in the selected package.

angstrom_to_bohr(value_in_angstrom: float) -> float staticmethod

Convert Angstrom to Bohr.

angstrom_to_bohr2(value_in_angstrom: float) -> float staticmethod

Convert Angstrom to Bohr^2. To used in sevenn package.

D3ParamDFT(d3package: str = 'sevenn')

Bases: D3ParamMD

Different packages use different names for D3 parameters. This class to 'return' standard D3 parameter names for different packages used for DFT.

Methods:

Attributes:

d3package: str = d3package instance-attribute
default_cutoff: float = 50.2022 instance-attribute
default_cn_cutoff: float = 21.1671 instance-attribute
param_names = params['params'] instance-attribute
damping_map = params['damping_map'] instance-attribute
get_params() -> dict

Return D3 parameter names according to different packages.

check_supported_damping(damping: str)

Check if the damping method is supported in the selected package.

angstrom_to_bohr(value_in_angstrom: float) -> float staticmethod

Convert Angstrom to Bohr.

angstrom_to_bohr2(value_in_angstrom: float) -> float staticmethod

Convert Angstrom to Bohr^2. To used in sevenn package.

MLP2Lammps(mlp_model: str = 'sevenn')

Convert MLP model to be used in LAMMPS.

Methods:

Attributes:

mlp_model: str = mlp_model instance-attribute
convert(checkpoint: str, outfile: str = 'deployed.pt', **kwargs)

Convert MLP model to LAMMPS format.

Parameters:

  • checkpoint (str) –

    Path to checkpoint file of MLP model.

  • outfile (str, default: 'deployed.pt' ) –

    Path to output LAMMPS potential file.

  • **kwargs –

    Additional arguments for specific conversion methods.

convert_sevenn(checkpoint: str, outfile: str = 'deploy_sevenn', parallel_type=False, **kwargs) staticmethod

Parameters:

  • checkpoint (str) –

    Path to checkpoint file of sevenn model.

  • outfile (str, default: 'deploy_sevenn' ) –

    Path to output LAMMPS potential file.

  • parallel_type (bool, default: False ) –

    Convert to potential for run in parallel simulations.

Notes

Single mode: will generate file as "outfile.pt" Parallel mode: will generate files as "outfile/deployed_parallel_0.pt", "outfile/deployed_parallel_1.pt", ...

convert_sevenn_mliap(checkpoint: str, outfile: str = 'deploy_sevenn_mliap.pt', modal: str | None = None, use_cueq: bool = False, use_flash: bool = False, cutoff: float | None = None) staticmethod

Convert sevenn model to be used in LAMMPS MLIAP.

Parameters:

  • checkpoint (str) –

    Path to checkpoint file of sevenn model.

  • outfile (str, default: 'deploy_sevenn_mliap.pt' ) –

    Path to output LAMMPS potential file.

  • modal (str, default: None ) –

    Channel of multi-task model.

  • use_cueq (bool, default: False ) –

    Use cueq.

  • use_flash (bool, default: False ) –

    Use flashTP.

  • cutoff (float, default: None ) –

    Neighbor cutoff (Angstrom). Required if it cannot be inferred from the model.

utilal_uncertainty

Utilities for uncertainty estimation using models committee. - DO NOT import any alff libs in this file, since this file will be used remotely.

Classes:

  • ModelCommittee –

    A class to manage a committee of models for uncertainty estimation.

Functions:

  • simple_lmpdump2extxyz –

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

  • chunk_list –

    Yield successive n-sized chunks from input_list.

ModelCommittee(mlp_model: str, model_files: list[str], calc_kwargs: dict | None = None, compute_stress: bool = False, rel_force: float | None = None, rel_stress: float | None = None, e_std_lo: float = 0.05, e_std_hi: float = 0.1, f_std_lo: float = 0.05, f_std_hi: float = 0.1, s_std_lo: float = 0.05, s_std_hi: float = 0.1, block_size: int = 1000)

A class to manage a committee of models for uncertainty estimation.

Parameters:

  • mlp_model (str) –

    MLP model engine, e.g., 'sevenn'.

  • model_files (list[str]) –

    List of model files for the committee.

  • calc_kwargs (dict, default: None ) –

    Additional arguments for the MLP calculator. Defaults to {}.

  • compute_stress (bool, default: False ) –

    Whether to compute stress. Defaults to False.

  • rel_force (float, default: None ) –

    Relative force to normalize force std. Defaults to None.

  • rel_stress (float, default: None ) –

    Relative stress to normalize stress std. Defaults to None.

  • e_std_lo (float, default: 0.05 ) –

    energy std low. Defaults to 0.05.

  • e_std_hi (float, default: 0.1 ) –

    energy std high. Defaults to 0.1.

  • f_std_lo (float, default: 0.05 ) –

    force std low. Defaults to 0.05.

  • f_std_hi (float, default: 0.1 ) –

    force std high. Defaults to 0.1.

  • s_std_lo (float, default: 0.05 ) –

    stress std low. Defaults to 0.05.

  • s_std_hi (float, default: 0.1 ) –

    stress std high. Defaults to 0.1.

  • block_size (int, default: 1000 ) –

    Block size of configurations to compute 'committee error' at once, just to avoid flooding memory. Defaults to 1000.

Notes
  • Consider using @staticmethod for some functions to avoid recursive messing.

Methods:

  • compute_committee_error_blockwise –

    Compute committee error for energy, forces, and stress for a multiple configurations in a block-wise manner.

  • committee_judge –

    Decide whether a 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.

Attributes:

mlp_model = mlp_model instance-attribute
model_files = model_files instance-attribute
calc_kwargs = calc_kwargs or {} instance-attribute
compute_stress = compute_stress instance-attribute
rel_force = rel_force instance-attribute
rel_stress = rel_stress instance-attribute
block_size = block_size instance-attribute
e_std_lo = e_std_lo instance-attribute
e_std_hi = e_std_hi instance-attribute
f_std_lo = f_std_lo instance-attribute
f_std_hi = f_std_hi instance-attribute
s_std_lo = s_std_lo instance-attribute
s_std_hi = s_std_hi instance-attribute
calc_list = self._get_calc_list() instance-attribute
committee_error_file: str = 'committee_error.txt' instance-attribute
committee_judge_file: str = 'committee_judge_summary.yml' instance-attribute
compute_committee_error_blockwise(struct_list: list[Atoms])

Compute committee error for energy, forces, and stress for a multiple configurations in a block-wise manner.

Parameters:

  • struct_list (list[Atoms]) –

    List of Atoms objects.

Notes

The output file is controlled by the class attribute self.committee_error_file.

committee_judge() -> tuple[np.ndarray, np.ndarray, np.ndarray]

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

Returns:

  • committee_judge_file ( s ) –

    files contain candidate, accurate and inaccurate configurations

Note
  • If need to select candidates based on only energy, just set f_std_hi and s_std_hi to a very large values. By this way, the criterion for those terms will always meet.
  • Similarly, if need to select candidates based on only energy and force, set s_std_hi to a very large value. E.g., s_std_hi=1e6 for selecting candidates based on energy and force.
select_candidate(extxyz_file: str)

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)

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

Returns:

  • extxyz_file ( str ) –

    revise configurations

Notes
  • blockwise functions requires all configurations in block have the same number of atoms. So if the input extxyz file contains configurations with different number of atoms, must use block_size=1 when initializing ModelCommittee class.
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.

chunk_list(input_list: list, chunk_size: int) -> Generator[list, None, None]

Yield successive n-sized chunks from input_list.

Parameters:

  • input_list (list) –

    Input list to be chunked.

  • chunk_size (int) –

    Chunk size (number of elements per chunk).

base

Base classes for ALFF workflows and remote operations.

Classes:

  • Workflow –

    Base class for workflows.

  • RemoteOperation –

    Base class for operations on remote machines.

  • KEY –

    A class to hold various constant keys used throughout the ALFF package.

Functions:

Attributes:

logger = cast(ColorLogger, _LoggerProxy()) module-attribute

Workflow(params_file: str, machines_file: str, schema_file: str | None = None)

Bases: ABC

Base class for workflows.

Workflow class is the central part of ALFF. Each workflow contains list of stages to be executed.

Subclass MUST reimplement
  • __init__(): initialize the workflow, need to override these attributes:
    • self.stage_map
    • self.wf_name
  • run(): the main function to run the workflow. The default implementation is a loop over stages in self.stage_map, just for simple workflow. For complex workflow (e.g. with iteration like active learning), need to reimplement the .run() function.

Example: 

class WorkflowExample(Workflow):
    def __init__(self, params_file: str, machines_file: str):
        super().__init__(params_file, machines_file, SCHEMA_EXAMPLE)
        self.stage_map = {
            "stage_name1": stage_function1,
            "stage_name2": stage_function2,
            "stage_name3": stage_function3,
        }
        self.wf_name = "Name of the workflow"
        return

Notes
  • multi_mdicts in this class is a dictionary containing multiple remote machines, and will be used RemoteOperation class.
  • All @abtractmethod must be reimplemented in subclasses.
Subclassed by:

Methods:

  • run –

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

Attributes:

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
stage_map: dict[str, Callable] instance-attribute
wf_name: str instance-attribute
run()

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

RemoteOperation(work_dir, pdict, multi_mdicts, mdict_prefix='')

Bases: ABC

Base class for operations on remote machines.

Each operation includes atl east 3 methods: - prepare - run - postprocess

Subclass must reimplement these methods
  • __init__(): initialize the operation, need to override these attributes:
  • prepare(): prepare all things needed for the run() method.
  • postprocess(): postprocess after the run() method.
Notes
  • Before using this class, must prepare a file work_dir/task_dirs.yml
  • All paths (work_dir, task_dirs,...) are in POSIX format, and relative to run_dir (not work_dir).
  • All @abtractmethod must be reimplemented in subclasses.
  • Do not change the .run() method unless you know what you are doing.
  • task_filter to filter task directories (filter already labelled structures). 
    self.task_filter = {"has_files": ["file1.txt", "file2.txt"], "no_files": ["file3.txt"]}
Subclassed by:

Methods:

  • prepare –

    Prepare all things needed for run() method.

  • postprocess –

    Postprocess after run() method.

  • run –

    Function to submit jobs to remote machines.

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: str instance-attribute
task_filter: dict[str, list[str]] 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() abstractmethod

Prepare all things needed for run() method.

This method need to implement the following attributes
  • self.commandlist_list: list[list[str]]
  • self.forward_files: list[str]
  • self.backward_files: list[str]
  • self.forward_common_files: list[str]
  • self.backward_common_files: list[str] # rarely used
postprocess() -> None | list abstractmethod

Postprocess after run() method.

run()

Function to submit jobs to remote machines.

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

KEY

A class to hold various constant keys used throughout the ALFF package.

Attributes:

time_str = time.strftime('%y%m%d_%H%M%S') class-attribute instance-attribute
DIR_LOG = 'log' class-attribute instance-attribute
FILE_LOG_ALFF = f'{DIR_LOG}/{time_str}_alff.log' class-attribute instance-attribute
FILE_ITERLOG = '_alff.iter' class-attribute instance-attribute
DIR_TRAIN = '00_train' class-attribute instance-attribute
DIR_MD = '01_md' class-attribute instance-attribute
DIR_DFT = '02_dft' class-attribute instance-attribute
DIR_DATA = '03_data' class-attribute instance-attribute
DIR_TMP = 'tmp_dir' class-attribute instance-attribute
DIR_COLLECTDATA = 'collect_data' class-attribute instance-attribute
DIR_FWDATA = 'fw_data' class-attribute instance-attribute
FILE_DATAPATH = 'data_paths.yml' class-attribute instance-attribute
FILE_CHECKPOINTS = 'checkpoints.yml' class-attribute instance-attribute
FILE_ARG_TRAIN = 'arg_train.yml' class-attribute instance-attribute
FILE_TRAJ_MD = 'traj_md.extxyz' class-attribute instance-attribute
FILE_TRAJ_MD_CANDIDATE = FILE_TRAJ_MD.replace('.extxyz', '_candidate.extxyz') class-attribute instance-attribute
FILE_ITER_DATA = 'label_data.extxyz' class-attribute instance-attribute
FILE_COLLECT_DATA = 'collect_label_data.extxyz' class-attribute instance-attribute
FMT_ITER = '04d' class-attribute instance-attribute
FMT_STAGE = '02d' class-attribute instance-attribute
FMT_MODEL = '02d' class-attribute instance-attribute
FMT_STRUCT = '05d' class-attribute instance-attribute
FMT_TASK_MD = '06d' class-attribute instance-attribute
FMT_TASK_DFT = '06d' class-attribute instance-attribute
RUNFILE_LAMMPS = 'cli_lammps.lmp' class-attribute instance-attribute
FILE_ARG_LAMMPS = 'arg_lammps.yml' class-attribute instance-attribute
FILE_ARG_ASE = 'arg_ase.yml' class-attribute instance-attribute
SCRIPT_ASE_PATH = f'{ALFF_ROOT}/util/script_ase' class-attribute instance-attribute
SCHEMA_ASE_RUN = f'{ALFF_ROOT}/util/script_ase/schema_ase_run.yml' class-attribute instance-attribute
SCHEMA_LAMMPS = f'{ALFF_ROOT}/util/script_lammps/schema_lammps.yml' class-attribute instance-attribute
SCHEMA_ACTIVE_LEARN = f'{ALFF_ROOT}/al/schema_active_learn.yml' class-attribute instance-attribute
SCHEMA_FINETUNE = f'{ALFF_ROOT}/al/schema_finetune.yml' class-attribute instance-attribute
DIR_MAKE_STRUCT = '00_make_structure' class-attribute instance-attribute
DIR_STRAIN = '01_strain' class-attribute instance-attribute
DIR_GENDATA = '02_gendata' class-attribute instance-attribute
FILE_FRAME_UNLABEL = 'conf.extxyz' class-attribute instance-attribute
FILE_FRAME_LABEL = 'conf_label.extxyz' class-attribute instance-attribute
FILE_TRAJ_LABEL = 'traj_label.extxyz' class-attribute instance-attribute
SCHEMA_ASE_BUILD = f'{ALFF_ROOT}/util/script_ase/schema_ase_build.yml' class-attribute instance-attribute
SCHEMA_GENDATA = f'{ALFF_ROOT}/gdata/schema_gendata.yml' class-attribute instance-attribute
SCHEMA_PHONON = f'{ALFF_ROOT}/phonon/schema_phonon.yml' class-attribute instance-attribute
SCHEMA_ELASTIC = f'{ALFF_ROOT}/elastic/schema_elastic.yml' class-attribute instance-attribute
SCHEMA_PES_SCAN = f'{ALFF_ROOT}/pes/schema_pes_scan.yml' class-attribute instance-attribute
DIR_SUPERCELL = '01_supercell' class-attribute instance-attribute
DIR_PHONON = '02_phonon' class-attribute instance-attribute
FILE_PHONOPYwFORCES = 'phonopy_with_forces.yml' class-attribute instance-attribute
DIR_ELASTIC = '02_elastic' class-attribute instance-attribute
DIR_SCAN = '01_scan' class-attribute instance-attribute
DIR_PES = '02_pes' class-attribute instance-attribute

init_alff_logger() -> ColorLogger

Initializing the logger.

get_logger()

cli

Command line interfaces for ALFF workflows.

Functions:

alff_al()

CLI for active learning.

alff_finetune()

CLI for fine-tuning.

alff_gen()

CLI for data generation.

alff_phonon()

CLI for phonon calculation.

alff_pes()

CLI for PES scanning calculation.

alff_elastic()

CLI for elastic constants calculation.

convert_chgnet_to_xyz()

CLI for converting the MPCHGNet dataset to XYZ format.

get_cli_args() -> tuple[str, str]

Get arguments from the command line.

elastic

Modules:

elastic

Classes:

Functions:

WorkflowElastic(params_file: str, machines_file: str)

Bases: Workflow

Workflow for Elastic tensor 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, 'strain_and_relax': strain_and_relax, 'compute_stress': compute_stress_strain, 'compute_elastic': compute_elastic} instance-attribute
wf_name = 'ELASTIC CONSTANTS CALCULATION' instance-attribute
params_file = params_file instance-attribute
machines_file = machines_file instance-attribute
schema_file = schema_file instance-attribute
multi_mdicts = config_machine.multi_mdicts instance-attribute
pdict = Config.loadconfig(self.params_file) instance-attribute
stage_list = self._load_stage_list() instance-attribute
run()

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

relax_initial_structure(pdict, mdict)

Relax the structure by DFT/MD

strain_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, mdict)

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.

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)

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

symprec (float): 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')

Class to manage elastic constants and compute elastic properties.

bravais_lattice (str): 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

utilelastic

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

Data generation workflow implementation.

Classes:

  • WorkflowGendata –

    Workflow for generate initial data for training ML models.

Functions:

WorkflowGendata(params_file: str, machines_file: str)

Bases: Workflow

Workflow for generate initial data for training ML models.

Methods:

  • run –

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

Attributes:

stage_map = {'make_structure': make_structure, 'optimize_structure': optimize_structure, 'sampling_space': sampling_space, 'run_dft': run_dft, 'collect_data': collect_data} instance-attribute
wf_name = 'DATA GENERATION' instance-attribute
params_file = params_file instance-attribute
machines_file = machines_file instance-attribute
schema_file = schema_file instance-attribute
multi_mdicts = config_machine.multi_mdicts instance-attribute
pdict = Config.loadconfig(self.params_file) instance-attribute
stage_list = self._load_stage_list() instance-attribute
run()

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

make_structure(pdict, mdict)

Build structures based on input parameters.

optimize_structure(pdict, mdict)

Optimize the structures.

sampling_space(pdict, mdict)

Explore the sampling space.

Sampling space includes: - Range of strains (in x, y, z directions) + range of temperatures - Range of temperatures + range of stresses

Notes - Structure paths are save into 2 lists: original and sampling structure paths

run_dft(pdict, mdict)

Run DFT calculations.

collect_data(pdict, mdict)

Collect data from DFT simulations.

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.

strain_x_dim(struct_files: list[str], strain_x_list: list[float])

Scale the x dimension of the structures.

strain_y_dim(struct_files: list[str], strain_y_list: list[float])

Scale the y dimension of the structures.

strain_z_dim(struct_files: list[str], strain_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.

libgen_gpaw

Classes:

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

Bases: RemoteOperation

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

Subclassed by:

Methods:

  • prepare –

    Prepare the operation.

  • postprocess –

    This function does:

  • run –

    Function to submit jobs to remote machines.

Attributes:

op_name = 'GPAW optimize' instance-attribute
task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': [K.FILE_FRAME_LABEL]} 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()

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

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

run()

Function to submit jobs to remote machines.

Note
  • Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.
OperGendataGpawSinglepoint(work_dir, pdict, multi_mdict, mdict_prefix='gpaw')

Bases: OperGendataGpawOptimize

Methods:

Attributes:

op_name = 'GPAW singlepoint' instance-attribute
work_dir = work_dir instance-attribute
pdict = pdict instance-attribute
mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute
task_dirs = self._load_task_dirs() instance-attribute
task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': [K.FILE_FRAME_LABEL]} instance-attribute
commandlist_list: list[list[str]] instance-attribute
forward_files: list[str] instance-attribute
backward_files: list[str] instance-attribute
forward_common_files: list[str] instance-attribute
backward_common_files: list[str] = [] instance-attribute
prepare()
postprocess()

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

run()

Function to submit jobs to remote machines.

Note
  • Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.
OperGendataGpawAIMD(work_dir, pdict, multi_mdict, mdict_prefix='gpaw')

Bases: RemoteOperation

See class OperGendataGpawOptimize for more details.

Methods:

  • prepare –

    Refer to the pregen_gpaw_optimize() function.

  • postprocess –

    Refer to the postgen_gpaw_optimize() function.

  • run –

    Function to submit jobs to remote machines.

Attributes:

op_name = 'GPAW aimd' instance-attribute
task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': [K.FILE_TRAJ_LABEL]} 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()

Refer to the pregen_gpaw_optimize() function.

Note: - This function differs from OperGendataGpawOptimize.prepare() in the aspects that ase_args now in task_dirs (not in work_dir). So, the forward files and commandlist_list are different. - structure_dirs: contains the optimized structures without scaling. - strain_structure_dirs: contains the scaled structures.

postprocess()

Refer to the postgen_gpaw_optimize() function.

run()

Function to submit jobs to remote machines.

Note
  • Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.
OperAlGpawSinglepoint(work_dir, pdict, multi_mdict, mdict_prefix='gpaw')

Bases: OperGendataGpawOptimize

Methods:

Attributes:

op_name = 'GPAW singlepoint' instance-attribute
work_dir = work_dir instance-attribute
pdict = pdict instance-attribute
mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute
task_dirs = self._load_task_dirs() instance-attribute
task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': [K.FILE_FRAME_LABEL]} instance-attribute
commandlist_list: list[list[str]] instance-attribute
forward_files: list[str] instance-attribute
backward_files: list[str] instance-attribute
forward_common_files: list[str] instance-attribute
backward_common_files: list[str] = [] instance-attribute
prepare()
postprocess()

Do post DFT tasks.

run()

Function to submit jobs to remote machines.

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

util_dataset

Utility functions for handling dataset files.

Functions:

split_extxyz_dataset(extxyz_files: list[str], train_ratio: float = 0.9, valid_ratio: float = 0.1, seed: int | None = 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_natoms: bool = True, sort_by_composition: bool = True, sort_pbc_len: 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_natoms (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.
  • np.lexsort does not support descending order, so we reverse the sorted indices using idx[::-1].
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_structs_from_extxyz(extxyz_file: str, has_symbols: list | None = None, only_symbols: list | None = None, exact_symbols: list | None = None, has_properties: list | None = None, only_properties: list | None = None, has_columns: list | None = None, only_columns: list | None = None, natoms: int | None = None, tol: float = 1e-06)

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.

  • natoms (int, default: None ) –

    total number of atoms in frame.

  • tol (float, default: 1e-06 ) –

    Tolerance for comparing floating point numbers.

sort_atoms_by_position(struct: Atoms) -> Atoms

Sorts the atoms in an Atoms object based on their Cartesian positions.

are_structs_identical(input_struct1: Atoms, input_struct2: Atoms, tol=1e-06) -> bool

Checks if two Atoms objects are identical by first sorting them and then comparing their attributes.

Parameters:

  • input_struct1 (Atoms) –

    First Atoms object.

  • input_struct2 (Atoms) –

    Second Atoms object.

  • tol (float, default: 1e-06 ) –

    Tolerance for position comparison.

Returns:

  • bool ( bool ) –

    True if the structures are identical, False otherwise.

are_structs_equivalent(struct1: Atoms, struct2: Atoms) -> bool

Check if two Atoms objects are equivalent using ase.utils.structure_comparator.SymmetryEquivalenceCheck.compare().

Parameters:

  • struct1 (Atoms) –

    First Atoms object.

  • struct2 (Atoms) –

    Second Atoms object.

Returns:

  • bool ( bool ) –

    True if the structures are equivalent, False otherwise.

Notes
  • It is not clear what is "equivalent"?
remove_duplicate_structs_serial(extxyz_file: str, tol=1e-06) -> None

Check if there are duplicate structs in a extxyz file.

Parameters:

  • extxyz_file (str) –

    Path to the extxyz file.

  • tol (float, default: 1e-06 ) –

    Tolerance for comparing atomic positions. Defaults to 1e-6.

Returns:

  • None –

    extxyz_file without duplicate structs.

remove_duplicate_structs_parallel(extxyz_file: str, tol=1e-06, n_jobs=None) -> None

Remove duplicate structures from an extxyz file using built-in parallelism.

Parameters:

  • extxyz_file (str) –

    Path to the extxyz file.

  • tol (float, default: 1e-06 ) –

    Tolerance for comparing atomic positions. Defaults to 1e-6.

  • n_jobs (int, default: None ) –

    Number of worker processes. Defaults to None (use all cores).

Returns:

  • None –

    None. Writes a new file with unique structures.

Notes
  • This approach is the O(N²) pairwise checks, so it scales badly as the number of structures grows.
  • This parallel version has not helped much in practice. Use the hashing approach instead.
remove_duplicate_structs_hash(extxyz_file: str, tol=1e-06) -> bool

Remove duplicate structures using hashing (very fast).

Notes
  • Much less memory overhead compared to pairwise are_structs_identical calls.
  • This reduces duplicate checking to O(N) instead of O(N²). No parallelism needed — it's already O(N)

pes

Modules:

  • libpes_gpaw –

    Library for GPAW-based PES operations.

  • libpes_lammps –

    Library for LAMMPS-based PES operations.

  • pes_scan –

    Implementation of 2d PES scanning.

  • utilpes –

    Utility functions for PES scans and analysis.

libpes_gpaw

Library for GPAW-based PES operations.

Classes:

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

Bases: OperGendataGpawOptimize

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

This class can also be used for phonon GPAW optimization

Subclassed by:

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.

Note
  • Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.
OperPESGpawOptimizeFixatom(work_dir, pdict, multi_mdict, mdict_prefix='gpaw')

Bases: OperPESGpawOptimize

Perform optimization with some atoms fixed.

Methods:

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.

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

libpes_lammps

Library for LAMMPS-based PES operations.

Classes:

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

Bases: RemoteOperation

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

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

Subclassed by:

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.

Note
  • Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.
OperPESLammpsOptimizeFixatom(work_dir, pdict, multi_mdict, mdict_prefix='lammps')

Bases: OperPESLammpsOptimize

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

Methods:

  • prepare –

    This function does:

  • postprocess –

    This function does:

  • run –

    Function to submit jobs to remote machines.

Attributes:

op_name = 'LAMMPS optimize fixed atoms' instance-attribute
work_dir = work_dir instance-attribute
pdict = pdict instance-attribute
mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute
task_dirs = self._load_task_dirs() instance-attribute
task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': ['frame_label.lmpdump']} instance-attribute
commandlist_list: list[list[str]] instance-attribute
forward_files: list[str] instance-attribute
backward_files: list[str] instance-attribute
forward_common_files: list[str] instance-attribute
backward_common_files: list[str] = [] instance-attribute
prepare()

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

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

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

run()

Function to submit jobs to remote machines.

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

pes_scan

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

Classes:

  • WorkflowPes –

    Workflow for PES scanning calculation.

Functions:

  • relax_initial_structure –

    Relax the structure by DFT/MD.

  • scanning_space –

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

  • compute_energy –

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

  • compute_pes –

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

WorkflowPes(params_file: str, machines_file: str)

Bases: Workflow

Workflow for PES scanning calculation.

Methods:

  • run –

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

Attributes:

stage_map = {'make_structure': make_structure, 'relax_initial_structure': relax_initial_structure, 'scanning_space': scanning_space, 'compute_energy': compute_energy, 'compute_pes': compute_pes} instance-attribute
wf_name = 'PES SCANNING CALCULATION' instance-attribute
params_file = params_file instance-attribute
machines_file = machines_file instance-attribute
schema_file = schema_file instance-attribute
multi_mdicts = config_machine.multi_mdicts instance-attribute
pdict = Config.loadconfig(self.params_file) instance-attribute
stage_list = self._load_stage_list() instance-attribute
run()

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

relax_initial_structure(pdict, mdict)

Relax the structure by DFT/MD.

scanning_space(pdict, mdict)

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

  • Save 2 lists of paths: original and scaled structure paths
compute_energy(pdict, mdict)

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

compute_pes(pdict, mdict)

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

utilpes

Utility functions for PES scans and analysis.

Functions:

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

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.
mapping_dxdydz_to_cartesian(dxdydz: np.ndarray, struct_cell: np.ndarray)

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

This function transform sampling points to real Cartesian coordinates

Parameters:

  • dxdydz (ndarray) –

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

  • struct_cell (ndarray) –

    array (3,3) containing cell vectors

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

Interpolate PES surface in the xy plane.

Parameters:

  • df (DataFrame) –

    PES raw data file with columns: dx dy energy

  • grid_size (float, default: 0.05 ) –

    grid size (Å) for interpolation

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

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

Interpolate PES curve in the z direction.

Parameters:

  • df (DataFrame) –

    PES raw data with columns: dz energy

  • grid_size (float, default: 0.05 ) –

    grid size (Å) for interpolation

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

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

Plot PES surface in the xy plane.

Parameters:

  • file_pes_grid (str) –

    file containing PES data interpolated on a grid

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

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

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

Plot PES surface in the xy plane.

Parameters:

  • file_pes_grid (str) –

    file containing PES data interpolated on a grid

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

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

plot_pes_3d()

phonon

Modules:

  • libpho_gpaw –

    Library for GPAW-based phonon calculations.

  • libpho_lammps –

    Library for LAMMPS-based phonon calculations.

  • phonon –

    Workflow for phonon calculation.

  • utilpho –

    Utility functions for phonon calculations.

libpho_gpaw

Library for GPAW-based phonon calculations.

Classes:

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

Bases: OperPESGpawOptimize

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

Function to submit jobs to remote machines.

Note
  • Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.
OperPhononGpawOptimizeFixbox(work_dir, pdict, multi_mdict, mdict_prefix='gpaw')

Bases: OperPESGpawOptimize

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

Methods:

Attributes:

op_name = 'GPAW optimize fixed box' instance-attribute
work_dir = work_dir instance-attribute
pdict = pdict instance-attribute
mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute
task_dirs = self._load_task_dirs() instance-attribute
task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': [K.FILE_FRAME_LABEL]} instance-attribute
commandlist_list: list[list[str]] instance-attribute
forward_files: list[str] instance-attribute
backward_files: list[str] instance-attribute
forward_common_files: list[str] instance-attribute
backward_common_files: list[str] = [] instance-attribute
prepare()
postprocess()
run()

Function to submit jobs to remote machines.

Note
  • Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.
OperPhononGpawSinglepoint(work_dir, pdict, multi_mdict, mdict_prefix='gpaw')

Bases: OperPESGpawOptimize

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

Methods:

  • prepare –
  • postprocess –

    Postprocess the operation.

  • run –

    Function to submit jobs to remote machines.

Attributes:

op_name = 'GPAW Singlepoint' instance-attribute
work_dir = work_dir instance-attribute
pdict = pdict instance-attribute
mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute
task_dirs = self._load_task_dirs() instance-attribute
task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': [K.FILE_FRAME_LABEL]} instance-attribute
commandlist_list: list[list[str]] instance-attribute
forward_files: list[str] instance-attribute
backward_files: list[str] instance-attribute
forward_common_files: list[str] instance-attribute
backward_common_files: list[str] = [] instance-attribute
prepare()
postprocess() -> list[list]

Postprocess the operation.

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

run()

Function to submit jobs to remote machines.

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

libpho_lammps

Library for LAMMPS-based phonon calculations.

Classes:

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

Bases: OperPESLammpsOptimize

Methods:

  • prepare –

    This function does:

  • postprocess –

    This function does:

  • run –

    Function to submit jobs to remote machines.

Attributes:

work_dir = work_dir instance-attribute
pdict = pdict instance-attribute
mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute
task_dirs = self._load_task_dirs() instance-attribute
op_name = 'LAMMPS optimize' instance-attribute
task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': ['frame_label.lmpdump']} instance-attribute
commandlist_list: list[list[str]] instance-attribute
forward_files: list[str] instance-attribute
backward_files: list[str] instance-attribute
forward_common_files: list[str] instance-attribute
backward_common_files: list[str] = [] instance-attribute
prepare()

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

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

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

run()

Function to submit jobs to remote machines.

Note
  • Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.
OperPhononLammpsOptimizeFixbox(work_dir, pdict, multi_mdict, mdict_prefix='lammps')

Bases: OperPESLammpsOptimize

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

Methods:

  • prepare –

    This function does:

  • postprocess –

    This function does:

  • run –

    Function to submit jobs to remote machines.

Attributes:

op_name = 'LAMMPS optimize fixed box' instance-attribute
work_dir = work_dir instance-attribute
pdict = pdict instance-attribute
mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute
task_dirs = self._load_task_dirs() instance-attribute
task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': ['frame_label.lmpdump']} instance-attribute
commandlist_list: list[list[str]] instance-attribute
forward_files: list[str] instance-attribute
backward_files: list[str] instance-attribute
forward_common_files: list[str] instance-attribute
backward_common_files: list[str] = [] instance-attribute
prepare()

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

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

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

run()

Function to submit jobs to remote machines.

Note
  • Orginal taks_dirs is relative to run_dir, and should not be changed. But the sumbmission function needs taks_dirs relative path to work_dir, so we make temporary change here.
OperPhononLammpsSinglepoint(work_dir, pdict, multi_mdict, mdict_prefix='lammps')

Bases: OperPESLammpsOptimize

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

Methods:

  • prepare –

    This function does:

  • postprocess –

    This function does:

  • run –

    Function to submit jobs to remote machines.

Attributes:

op_name = 'LAMMPS optimize' instance-attribute
task_filter = {'has_files': [K.FILE_FRAME_UNLABEL], 'no_files': ['frame_label.lmpdump']} instance-attribute
work_dir = work_dir instance-attribute
pdict = pdict instance-attribute
mdict_list = self._select_machines(multi_mdicts, mdict_prefix) instance-attribute
task_dirs = self._load_task_dirs() instance-attribute
commandlist_list: list[list[str]] instance-attribute
forward_files: list[str] instance-attribute
backward_files: list[str] instance-attribute
forward_common_files: list[str] instance-attribute
backward_common_files: list[str] = [] instance-attribute
prepare()

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

  • Prepare the task_list
  • Prepare forward & backward files
  • Prepare commandlist_list for multi-remote submission
postprocess() -> list[list]

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

run()

Function to submit jobs to remote machines.

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

phonon

Workflow for phonon calculation.

Classes:

Functions:

WorkflowPhonon(params_file: str, machines_file: str)

Bases: Workflow

Workflow for phonon calculation.

Methods:

  • run –

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

Attributes:

stage_map = {'make_structure': make_structure_phonon, 'relax_initial_structure': relax_initial_structure, 'strain_and_relax': strain_and_relax, 'compute_force': compute_force, 'compute_phonon': compute_phonon} instance-attribute
wf_name = 'PHONON CALCULATION' instance-attribute
params_file = params_file instance-attribute
machines_file = machines_file instance-attribute
schema_file = schema_file instance-attribute
multi_mdicts = config_machine.multi_mdicts instance-attribute
pdict = Config.loadconfig(self.params_file) instance-attribute
stage_list = self._load_stage_list() instance-attribute
run()

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

make_structure_phonon(pdict, mdict)

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

relax_initial_structure(pdict, mdict)

Relax the structure by DFT/MD.

strain_and_relax(pdict, mdict)

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

compute_force(pdict, mdict)

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

compute_force_one_scaledstruct(work_dir: str, pdict, mdict)

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

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

compute_phonon(pdict, mdict)

Compute phonon properties by phonopy functions.

utilpho

Utility functions for phonon calculations.

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

Functions:

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

Find the primitive cell using spglib.standardize_cell.

Parameters:

  • struct (Atoms) –

    ASE's structure object.

  • no_idealize (bool, default: True ) –

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

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

    Symmetry tolerance. Default is 1e-5.

  • angle_tolerance (float, default: -1.0 ) –

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

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

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

Parameters:

  • struct (Atoms) –

    ASE's structure object.

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

    Symmetry tolerance. Default is 1e-5.

get_band_path(atoms: Atoms, path_str: str = '', npoints: int = 61, path_frac=None, labels=None)
get_band_structure(work_dir, pdict)
get_DOS_n_PDOS(work_dir, pdict)
get_thermal_properties(work_dir, pdict)

util

Modules:

ase_tool

Utility functions for ASE-related tasks.

Functions:

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

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_args = pdict.get('calc_args', {}).get('ase', {}) module-attribute
code_lines = f.read() module-attribute
dftd3_args = ase_calc_args.get('dftd3', {}) module-attribute
xc = dftd3_args.get('xc', 'pbe').lower() module-attribute
calc_d3 = DFTD3(method=xc, **dftd3_args) module-attribute
calc = SumCalculator([calc_ase, calc_d3]) module-attribute
struct_args = pdict['structure'] module-attribute
extxyz_file = struct_args['from_extxyz'] module-attribute
atoms = cast(Atoms, atoms) 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
struct = atoms.copy() 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
calc_args = pdict.get('calc_args', {}) module-attribute
gpaw_args = 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
calc_pw = GPAW(**gpaw_params) module-attribute
dftd3_args = calc_args.get('dftd3', {}) module-attribute
xc = dftd3_args.get('xc', 'pbe').lower() module-attribute
calc_d3 = DFTD3(method=xc, **dftd3_args) module-attribute
calc = SumCalculator([calc_pw, calc_d3]) module-attribute
struct_args = pdict['structure'] module-attribute
extxyz_file = struct_args['from_extxyz'] module-attribute
atoms = cast(Atoms, atoms) 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
struct = atoms.copy() module-attribute
get_cli_args()

Get the arguments from the command line.

print_dynamic(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, 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
calc_args = pdict.get('calc_args', {}) module-attribute
gpaw_args = 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
calc_pw = GPAW(**gpaw_params) module-attribute
dftd3_args = calc_args.get('dftd3', {}) module-attribute
xc = gpaw_params['xc'].lower() module-attribute
calc_d3 = DFTD3(method=xc, **dftd3_args) module-attribute
calc = SumCalculator([calc_pw, calc_d3]) module-attribute
struct_args = pdict['structure'] module-attribute
extxyz_file = struct_args['from_extxyz'] module-attribute
atoms = cast(Atoms, atoms) module-attribute
input_pbc = struct_args.get('pbc', False) module-attribute
constraint_arg = pdict.get('constraint', None) module-attribute
c = [] module-attribute
fix_idxs = constraint_arg['fix_atoms']['fix_idxs'] module-attribute
symprec = constraint_arg['fix_symmetry'].get('symprec', 1e-05) module-attribute
opt_args = pdict.get('optimize', {}) module-attribute
mask = opt_args.get('mask', None) 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
struct = atoms.copy() 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
calc_args = pdict.get('calc_args', {}) module-attribute
gpaw_args = 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
calc_pw = GPAW(**gpaw_params) module-attribute
dftd3_args = calc_args.get('dftd3', {}) module-attribute
xc = gpaw_params['xc'].lower() module-attribute
calc_d3 = DFTD3(method=xc, **dftd3_args) module-attribute
calc = SumCalculator([calc_pw, calc_d3]) module-attribute
struct_args = pdict['structure'] module-attribute
extxyz_file = struct_args['from_extxyz'] module-attribute
atoms = cast(Atoms, atoms) 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 = None, pair_style: list[str] | None = None, pair_coeff: list[str] | None = None, 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] | None, default: None ) –

    List of pair_style, e.g., ["eam/alloy"]. Default is None

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

    List of pair_coeff,e.g., ["* * Cu.eam.alloy Cu"]. Default is None

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

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

  • **kwargs –

    Any other arguments which may be ignored.

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 = None, pair_style: list[str] | None = None, pair_coeff: list[str] | None = None, min_style: str = 'cg', etol: float = 1e-09, ftol: float = 1e-09, maxiter: int = 100000, maxeval: int = 100000, dmax: float = 0.01, press: list[int] | float | bool = [None, None, None], mask: list[int] = [1, 1, 1], couple: str = 'none', output_script: str = 'cli_script_lammps.lmp', **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"

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 = None, pair_style: list[str] | None = None, pair_coeff: list[str] | None = None, 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 = 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: float | list[float] | None = None, mask: list[int] = [1, 1, 1], couple: str = 'none', pdamp: int = 1000, barostat: Literal['nose_hoover_chain'] = 'nose_hoover_chain', deform_limit: float | None = 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 = None, pair_style: list[str] | None = None, pair_coeff: list[str] | None = None, **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.

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

    List of pair_style, e.g., ["eam/alloy"]. Default is None

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

    List of pair_coeff,e.g., ["* * Cu.eam.alloy Cu"]. Default is None

lmp_section_common_setting(extra_settings: list | None = None, **kwargs) -> list[str]

Generate lammps input block for common settings.

Parameters:

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

    List of extra settings to be added. Default None.

Notes
  • The fix balance requires setting pair_coeff before it.
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 = 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 = None, dump_result: bool = False, uid: str | None = 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 = None, dump_result: bool = False, uid: str | None = 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 = None, dump_result: bool | None = False, deform_limit: float | None = None, uid: str | None = 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()
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

General utility functions for ALFF.

Functions:

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

Check if the calculator is supported.

mk_struct_dir(pdict)

Create the directory name for the structure.

validate