Note: Requires
symfcandphonopy.
pypolymlp supports stochastic self-consistent harmonic approximation (SSCHA) calculations to evaluate lattice vibrational properties, including anharmonic contributions effectively.
pypolymlp employs an iterative procedure for SSCHA calculations, in which property evaluations (energy, forces, and stress tensors) for sampled structures using a polynomial MLP and the estimation of effective force constants via linear regression are performed repeatedly.
This procedure is repeated until the effective force constants converge.
Once the effective force constants are obtained, vibrational free energy and related properties can be evaluated within the SSCHA framework.
To perform accurate SSCHA calculations for target compounds and structures across a range of volumes and temperatures, it is necessary to use either general-purpose polynomial MLPs or on-the-fly polynomial MLPs. These models should enable accurate property evaluations for structures with large atomic displacements generated from the effective harmonic Hamiltonian in SSCHA calculations.
When SSCHA calculations are performed for many target structures using a single MLP, it is preferable to use a general-purpose MLP with high predictive power across a wide range of structures. In contrast, when SSCHA calculations are carried out for a single compound under a specific condition or across a range of volumes and temperatures, developing an on-the-fly MLP can be a suitable option, as it can provide higher accuracy for the target system than a general-purpose MLP.
See Development of On-the-fly MLP for more details.
SSCHA calculations can be performed using the pypolymlp-sscha command.
Given a structure specified by the --poscar option, a supercell size specified by the --supercell option, and a polynomial MLP specified by the --pot option, a single SSCHA calculation can be performed as follows.
> pypolymlp-sscha --poscar POSCAR --pot polymlp.yaml --supercell 3 3 2 --temp 300 --mixing 0.5 --tol 0.01In this example, the temperature is set to 300 K.
Also, the tolerance and mixing parameters for the force constants are set to 0.01 and 0.5, respectively.
If the SSCHA calculations complete successfully, sscha_results.yaml and the effective force constants file fc2.hdf5 are generated for each temperature.
When a single temperature is used for the SSCHA calculation, the --temp option can be used to specify the temperature.
When SSCHA calculations are performed sequentially at multiple temperatures, the --temp_min, --temp_max, and --temp_step options can be used to define the temperature sequence:
--temp_min 100 --temp_max 500 --temp_step 100Alternatively, the --n_temp option can be used instead of --temp_step to specify the number of temperature points:
--temp_min 100 --temp_max 500 --n_temp 10When SSCHA calculations are performed at multiple temperatures sequentially, the calculation at each temperature starts from the converged force constants obtained at the previous temperature, which helps accelerate convergence to the desired force-constant states.
If the --ascending_temp option is enabled, the temperature sequence is generated in ascending order:
--temp_min 100 --temp_max 500 --temp_step 100 --ascending_tempIn this case, the temperature sequence is [100, 200, 300, 400, 500]. Otherwise, the temperature sequence is generated in descending order.
The choice of initial force constants may lead to different converged solutions.
In pypolymlp, the harmonic force constants for a given structure, calculated using the specified polynomial MLP, are used as the default initial force constants.
--init harmonicAlternatively, random force constants, constant force constants, or force constants read from a file can also be used:
--init random
--init const
--init file --init_file fc2.hdf5The tolerance parameter is used as a convergence criterion for the SSCHA iterations.
The iterations stop when the change in the force constants satisfies the following condition defined by the tolerance parameter
where
A mixing scheme is applied to the updated force constants to improve the stability of convergence. The mixing parameter controls the contribution of the force constants from the previous iteration and is defined as:
where
Here,
Within the SSCHA framework, the anharmonic contribution to the free energy is evaluated as an ensemble average over structures with atomic displacements sampled according to the effective force constants. The forces acting on atoms and the stress tensor at a given temperature are also computed from these sampled structures. Therefore, the number of samples required to accurately evaluate these properties and achieve convergence within a given tolerance strongly depends on the number of independent force-constant components and the chosen tolerance parameter.
In general, more samples are required for low-symmetry compounds with a larger number of independent force constants.
In pypolymlp, the number of sample structures is automatically determined based on the number of independent force constants and the tolerance parameter, if it is not explicitly specified.
When the number of sample structures is explicitly specified, the --n_samples option can be used.
The first value is used to obtain the converged effective force constants, while the second value is used to evaluate the SSCHA free energy and related properties.
To accurately evaluate these properties, it is recommended to set a larger value for the second number than for the first:
--n_samples 3000 6000In this example, 3000 and 6000 structures are used to obtain the converged effective force constants and to evaluate the SSCHA free energy, respectively.
Other main parameters that can be specified via options are as follows.
--mesh MESH MESH MESH q-mesh for reciprocal space calculation
--born_vasprun BORN_VASPRUN vasprun.xml file for parsing born effective charges
--cutoff_fc2 CUTOFF_FC2 Cutoff radius for effective force constants.
--write_pdos Save projected DOS.
Thanks to the low computational cost of polynomial MLPs, volume-dependent SSCHA calculations can be performed efficiently. Thermal expansion, as well as pressure- and temperature-dependent thermodynamic properties, can be evaluated by carrying out SSCHA calculations at multiple volumes. See Thermodynamic Calculations for more details.
Once the converged effecitive force constants are obtained, random structures and their properties (energy, forces, and virial stress tensor) according to the effective force constants can be evaluated using the given polynomial MLP.
The command pypolymlp-sscha-post with the --distribution option evaluates these properties of randomly generated structures, which can be regarded as real space atomic distribution of the effective harmonic Hamiltonian described by the converged force constants.
To parse the result of the SSCHA calculation, two files of sscha_results.yaml and fc2.hdf5 are needed.
By specifying the number of sample structures using the --n_samples option, the structures and their properties will be calculated:
Once the converged effective force constants are obtained, random structures and their properties (energy, forces, and virial stress tensor) can be evaluated using the given polynomial MLP, based on the distribution defined by the effective force constants.
The pypolymlp-sscha-post command with the --distribution option evaluates these properties for randomly generated structures.
These structures can be regarded as real-space atomic configurations sampled from the effective harmonic Hamiltonian defined by the converged force constants.
To process the results of the SSCHA calculation, the files sscha_results.yaml and fc2.hdf5 are required.
By specifying the number of sample structures using the --n_samples option, the structures and their properties are computed accordingly:
pypolymlp-sscha-post --distribution --yaml sscha_results.yaml --fc2 fc2.hdf5 --n_samples 20 --pot polymlp.yamlSSCHA calculations with polynomial MLPs can also be performed using the Python API in pypolymlp:
import numpy as np
from pypolymlp.api.api_calculator import PypolymlpCalcProperties
polymlp = PypolymlpCalcProperties(verbose=True)
polymlp.set_polymlp(pot="polymlp.yaml")
unitcell = polymlp.load_poscar("POSCAR")
# Optional function if NAC parameters are needed.
enable_nac = False
if enable_nac:
nac_params = polymlp.get_nac_params("vasprun.xml", (3, 3, 3))
else:
nac_params = None
polymlp.set_sscha_calculator(
unitcell=unitcell,
supercell_matrix=(3, 3, 3),
temp_min=0,
temp_max=1000,
temp_step=100,
ascending_temp=False,
n_samples_init=None,
n_samples_final=None,
tol=0.005,
max_iter=30,
mixing=0.5,
mesh=(10, 10, 10),
nac_params=nac_params,
init_fc_algorithm="harmonic",
fc2=None,
cutoff_radius=None,
)
free_energy, force, stress = polymlp.eval(unitcell)
"""
Attributes
----------
force_constants: FC2 at the final temperature, shape=(n_atom, n_atom, 3, 3).
"""
fc2 = polymlp.force_constantsRandom structures can be sampled using the Python API. An example of how to generate structures from the converged force constants is shown below.
from pypolymlp.api.pypolymlp_sscha_post import PypolymlpSSCHAPost
sscha = PypolymlpSSCHAPost(verbose=True)
sscha.init_structure_distribution(
yamlfile="./sscha/1000/sscha.yaml",
fc2file="./sscha/1000/fc2.hdf5",
pot="polymlp.yaml",
)
sscha.run_structure_distribution(n_samples=1000)
sscha.save_structure_distribution(path=".", save_poscars=False)
"""
Attributes
----------
displacements: Displacements in structures sampled from density matrix.
shape = (n_supercell, 3, n_atom), in Angstroms.
forces: Forces of structures sampled from density matrix.
shape = (n_supercell, 3, n_atom), in eV/Angstroms.
energies: Energies of structures sampled from density matrix.
shape = (n_supercell), in eV/supercell.
static_potential: Static potential of equilibrium supercell structure in eV/supercell.
supercells: Supercell structures sampled from density matrix.
unitcell: Unitcell structure.
"""
energies = sscha.energies
supercells = sscha.supercells