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
scanning_space: ### ANCHOR: Define scanning space
type: dict
schema:
range_x: # range of displacements in x-direction. E.g., {'start': 0.0, 'stop': 0.1, 'step': 0.01}
type: dict
schema:
start: # start value of the scan range
type: float
stop: # stop value of the scan range
type: float
step: # step value of the scan range
type: float
range_y: # range of displacements in y-direction. E.g., {'start': 0.0, 'stop': 0.1, 'step': 0.01}
type: dict
schema:
start: # start value of the scan range
type: float
stop: # stop value of the scan range
type: float
step: # step value of the scan range
type: float
range_z: # range of displacements in z-direction. E.g., {'start': -0.01, 'stop': 0.01, 'step': 0.01}
type: dict
schema:
start: # start value of the scan range
type: float
stop: # stop value of the scan range
type: float
step: # step value of the scan range
type: float
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
calculator: # choices: 'lammps', 'gpaw', 'ase'. Calculator to calculate atomic forces. Default: 'lammps'
type: string
allowed: ['lammps', 'gpaw', 'ase']
default: 'lammps'
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: # use DFT-D3 damping. Default is "d3zero" (zero-damping). Choices: "d3bj","d3zero","d3bjm","d3zerom","d3op".
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" to use potential files in parent dir. E.g., ["* * ../SiC.tersoff C Si"].
type: list
auto_pair_coeff: # This option to generate `pair_coeff` automatically if `pair_coeff` is not provided. Then, pair_coeff will be generate in this form ["* * ../file_potential1 Si C", "* * ../file_potential2 O H"]. Default is False.
type: boolean
default: False
file_potentials: # list of potential files (relative to run_dir). E.g., ["SiC.tersoff"]
type: list
optimize: ### ANCHOR: Parameters to run optimization the structure
type: dict
schema:
gpaw_opt: # 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
# all other parameters as in ASE schema.optimize https://thangckt.github.io/alff_doc/schema/manual_schema_ase_run/#schema
lammps_opt: ### 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
# all other parameters as in LAMMPS schema.optimize https://thangckt.github.io/alff_doc/schema/manual_schema_lammps/
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
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]
add_vacuum: [0, 0, 20]
ase_build_arg:
a: 2.46
thickness: 3.35
scanning_space:
range_x: {'start': 0.0, 'stop': 6, 'step': 0.25} # range of dislacements in x-direction.
range_y: {'start': 0.0, 'stop': 6, 'step': 0.25}
# range_z: {'start': 0.0, 'stop': 0.5, 'step': 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: "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: # parameter to minimize the structure by MD (relax_type: 'min')
gpaw_opt: # 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]
add_vacuum: [0, 0, 20]
ase_build_arg:
a: 2.46
thickness: 1.35
scanning_space:
range_x: {'start': 0.0, 'stop': 6, 'step': 0.25} # range of dislacements in x-direction.
range_y: {'start': 0.0, 'stop': 6, 'step': 0.25}
# range_z: {'start': 0.0, 'stop': 0.5, 'step': 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: "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 Si C"] # LAMMPS pair_coeff
auto_pair_coeff: True # generate `pair_coeff` automatically if not provided.
file_potentials: ["SiC.tersoff"] # path to the potential file
optimize: # parameter to minimize the structure by MD (relax_type: 'min')
lammps_opt: # 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