Schema for PES sanning calculations¶
The schema to configure parameters for potential energy surface (PES) scanning calculations.
Schema:¶
### Schema for for PES scanning
stages: ### ANCHOR: Define stages to run
type: list
required: True
allowed:
- make_structure # build the atomic structures
- relax_initial_structure # relax initial structures
- scanning_space # explore the sampling space
- compute_energy # run optimization oby DFT/MD calculators
- compute_pes # conpute the potential energy surface (PES) from the DFT/MD results
structure: ### ANCHOR: Define atomic structure
type: dict
required: True
schema:
from_extxyz: # list-of-paths to the EXTXYZ files to be used as the initial structure. If provided, the structure will be read from the file, and the other structure parameters will be ignored.
type: list
from_scratch: # build the structure from scratch. See [Schema for building structure](https://thangckt.github.io/alff_doc/schema/manual_schema_ase_build/)
type: dict
calculator: # choices: 'lammps', 'gpaw', 'ase'. Calculator to calculate atomic forces. Default: 'lammps'
type: dict
required: True
schema:
name: # calculator name
type: string
allowed: ['lammps', 'gpaw', 'ase']
required: True
calc_args: ### SECTION Parameters of calculators
type: dict
required: True
schema:
gpaw: ### ANCHOR: GPAW calculator. Accept all GPAW parameters: https://gpaw.readthedocs.io/documentation/basic.html
type: dict ### Accept all parameters as in [ASE schema](https://thangckt.github.io/alff_doc/schema/config_ase/) `calc_args.gpaw`, and additional perameters as below
allow_unknown: True
dftd3: ### ANCHOR: DFT-D3 calculator for Van der Waals correction
type: dict
schema:
damping: # damping method. Choices: "zero", "bj", "zerom", "bjm". Default is "zero"
type: string
### ANCHOR: Define ASE's calculator by two ways: using 'pyfile' or 'pyscript'.
py_file: # python file that defines ASE's calculator. Python script must return the variable `calc`.
type: string
py_script: # list[str] of python-code to directly define ASE's calculator. Python script must return the variable `calc`. Example:
type: list
lammps: ### ANCHOR: LAMMPS parameters
type: dict
schema:
pair_style: # list of LAMMPS pair_style. e.g., ["tersoff"]
type: list
pair_coeff: # list of LAMMPS pair_coeff. Must use form "../potential_file", since potential files in parent dir. E.g., ["* * ../SiC.tersoff C Si"]. Do not attach atoms if use `auto_atom_names: True`, example: ["* * ../file_potential1", "* * ../file_potential2"], then the atom types will be automatically assigned based on the order of elements in the input structure.
type: list
auto_atom_names: # auto assign atoms in `pair_coeff` lines. Default is False.
type: boolean
default: False
file_potentials: # list of potential files (relative to run_dir). E.g., ["SiC.tersoff"]
type: list
optimize_args: ### ANCHOR: Parameters to run optimization the structure
type: dict
required: True
schema:
gpaw: # GPAW optimization parameters.
type: dict
allow_unknown: True
schema:
fmax: # force convergence criteria. Default is 0.05 eV/Ang
type: float
default: 0.05
max_steps: # maximum number of optimization steps. Default is 10000
type: integer
default: 10000
mask: # 1x3 array of booleans: 1 for relax, 0 for fixed.
required: True
type: list
# all other parameters as in ASE schema.optimize https://thangckt.github.io/alff_doc/schema/manual_schema_ase_run/#schema
lammps: ### LAMMPS optimization parameters. See Schema for LAMMPS optimize https://thangckt.github.io/alff_doc/schema/manual_schema_lammps/
type: dict
allow_unknown: True
schema:
min_style: # minimization style supported by LAMMPS. Choices: 'cg', 'sd', 'fire',... Default is 'cg'
type: string
etol: # energy convergence criteria. Default is 1.0e-9 eV
type: float
ftol: # force convergence criteria. Default is 1.0e-9 eV/Ang
type: float
mask: # 1x3 array of booleans: 1 for relax, 0 for fixed.
required: True
type: list
# all other parameters as in LAMMPS schema.optimize https://thangckt.github.io/alff_doc/schema/manual_schema_lammps/
scanning_space: ### ANCHOR: Define scanning space
type: dict
schema:
scan_x: # list of displacements in x-direction. Accept composite ranges. E.g., [0.6, '0.7-0.9', '1.1-1.5:0.2']
type: list
scan_y: # list of displacements in y-direction. Accept composite ranges.
type: list
scan_z: # list of displacements in z-direction. Accept composite ranges.
type: list
constraint: ### ANCHOR: Define constraints.
type: dict
schema:
displace_atoms: ## define atoms to be displaced during the scanning step.
type: dict
schema:
idxs: # list of atom indices , e.g., [0, 1, 2]
type: list
filters: # filters to select atoms if keyword `idxs` is not provided. Accept multiple filters.
type: dict
allow_unknown: False
schema:
elements: # list of element names to select atoms, e.g., ['Mg', 'O']
type: list
above_mean_z: # select all atoms with z-coordinate larger than the mean z-coordinate of the structure
type: boolean
below_mean_z: # select all atoms with z-coordinate smaller than the mean z-coordinate of the structure
type: boolean
min_z: # select all atoms with z-coordinate larger than this value
type: float
max_z: # select all atoms with z-coordinate smaller than this value
type: float
fix_atoms: ## define atoms to be fixed during optimization runs to calculate energy. #NOTE: Only contraints atom positions in z-direction.
type: dict
schema:
idxs: # list of atom indices , e.g., [0, 1, 2]
type: list
filters: # filters to select atoms if keyword `idxs` is not provided. Accept multiple filters.
type: dict
allow_unknown: False
schema:
elements: # list of element names to select atoms, e.g., ['Mg', 'O']
type: list
above_mean_z: # select all atoms with z-coordinate larger than the mean z-coordinate of the structure
type: boolean
below_mean_z: # select all atoms with z-coordinate smaller than the mean z-coordinate of the structure
type: boolean
min_z: # select all atoms with z-coordinate larger than this value
type: float
maxZ: # select all atoms with z-coordinate smaller than this value
type: float
fix_only_z: # if True, only fix atom positions in z-direction. This is useful when sampling in z-dim only. Default is False (fix all directions)
type: boolean
default: False
pes:
type: dict
schema:
interp_pes_xy: # interpolate PES surface in the xy plane
type: boolean
default: True
interp_pes_z: # interpolate PES curve in the z direction
type: boolean
default: False
grid_size: # grid size for interpolation (Angstrom). Default is 0.01
type: float
default: 0.01
Example config 1:¶
### Example configuration file for PES scan using GPAW
stages:
- make_structure # build initial atomic structures
- relax_initial_structure # relax initial structures
- scanning_space # explore the sampling space
- compute_energy # run optimization oby DFT/MD calculators
- compute_pes # conpute the potential energy surface (PES) from the DFT/MD results
structure: # atomic structure information
# from_extxyz: ["MoS2_mx2_2H_02x02x02.extxyz"]
from_scratch: # build the structure from scratch
structure_type: "graphene"
chem_formula: "C2"
supercell: [ 2, 2, 2 ]
pbc: [1, 1, 1]
set_vacuum: [0, 0, 20]
ase_build_arg:
a: 2.46
thickness: 3.35
scanning_space:
scan_x: [-0.05, '0.1-3.0:0.1'] # range of dislacements in x-direction. Accept composite ranges.
scan_y: [-0.05, '0.1-3.0:0.1']
# scan_z: [-0.05, '0.1-3.0:0.1']
constraint: ### ANCHOR: Define constraints.
displace_atoms: ## define atoms to be displaced during the scanning step.
filters: # filters to select atoms if keyword `idx` is not provided. Accept multiple filters.
# element: ['Mo'] # list of element names to select atoms, e.g., ['Mg', 'O']
above_mean_z: True # select all atoms with z-coordinate larger than the mean z-coordinate of the structure
fix_atoms: ## define atoms to be fixed during optimization runs to calculate energy. #NOTE: Only contraints atom positions in z-direction.
filters: # filters to select atoms if keyword `idx` is not provided, e.g., {'element': 'Mo'} or {'element': ['Mo', 'S']}
elements: ['C'] # list of element names to select atoms, e.g., ['Mg', 'O']
# above_mean_z: True # select all atoms with z-coordinate larger than the mean z-coordinate of the structure
calculator:
name: "gpaw" # choices: 'lammps', 'gpaw'. Calculator to calculate atomic forces. Default: 'lammps'
calc_args:
gpaw: # accept GPAW parameters
mode:
name: 'pw' # use PlaneWave method energy cutoff in eV
ecut: 500
xc: "PBE" # exchange-correlation functional
kpts: {"density": 6, "gamma": False} # if not set `kpts`, then only Gamma-point is used
dftd3: ### DFT-D3 method for Van der Waals correction
damping: "d3zero"
optimize_args: # parameter to minimize the structure by MD (relax_type: 'min')
gpaw: # parameter to optimize the structure by DFT/MS (relax_type: 'opt')
fmax: 0.02 # force convergence criteria
mask: [1, 1, 0] # strain components to optimize. -> fixed zz
pes:
interp_pes_xy: True # interpolate PES surface in the xy plane
interp_pes_z: False # interpolate PES along z direction
Example config 2:¶
### Example configuration file for PES scan using LAMMPS
stages:
- make_structure # build initial atomic structures
- relax_initial_structure # relax initial structures
- scanning_space # explore the sampling space
- compute_energy # run optimization oby DFT/MD calculators
- compute_pes # conpute the potential energy surface (PES) from the DFT/MD results
structure: # atomic structure information
# from_extxyz: ["MoS2_mx2_2H_02x02x02.extxyz"]
from_scratch: # build the structure from scratch
structure_type: "graphene"
chem_formula: "C2"
supercell: [ 2, 2, 2 ]
pbc: [1, 1, 1]
set_vacuum: [0, 0, 20]
ase_build_arg:
a: 2.46
thickness: 1.35
scanning_space:
scan_x: [-0.05, '0.1-3.0:0.1'] # range of dislacements in x-direction. Accept composite ranges.
scan_y: [-0.05, '0.1-3.0:0.1']
# scan_z: [-0.05, '0.1-3.0:0.1']
constraint: ### ANCHOR: Define constraints.
displace_atoms: ## define atoms to be displaced during the scanning step.
filters: # filters to select atoms if keyword `idx` is not provided. Accept multiple filters.
# element: ['Mo'] # list of element names to select atoms, e.g., ['Mg', 'O']
above_mean_z: True # select all atoms with z-coordinate larger than the mean z-coordinate of the structure
fix_atoms: ## define atoms to be fixed during optimization runs to calculate energy. #NOTE: Only contraints atom positions in z-direction.
filters: # filters to select atoms if keyword `idx` is not provided, e.g., {'element': 'Mo'} or {'element': ['Mo', 'S']}
elements: ['C'] # list of element names to select atoms, e.g., ['Mg', 'O']
# above_mean_z: True # select all atoms with z-coordinate larger than the mean z-coordinate of the structure
calculator:
name: "lammps" # choices: 'lammps', 'gpaw'. Calculator to calculate atomic forces. Default: 'lammps'
calc_args:
lammps: # accept LAMMPS parameters
pair_style: ["tersoff"] # LAMMPS pair_style
pair_coeff: ["* * ../SiC.tersoff"] # LAMMPS pair_coeff
auto_atom_names: True # auto assign atoms in `pair_coeff` lines.
file_potentials: ["SiC.tersoff"] # path to the potential file
optimize_args: # parameter to minimize the structure by MD (relax_type: 'min')
lammps: # LAMMPS optimization parameters.
ftol: 1.0e-12 # force convergence criteria
etol: 1.0e-9 # energy convergence criteria
dmax: 0.001 # maximum distance for line search to move (distance units). Default: 0.01
mask: [1,1,0] # mask to control which directions to relax. E.g., [1,1,0] means only relax in x and y directions.
pes:
interp_pes_xy: True # interpolate PES surface in the xy plane
interp_pes_z: False # interpolate PES along z direction