Utils¶
This package contains utility functions for data analytics applied to materials science data. Specifically,
ai4materials.utils.utils_config
: functions to set up useful parameters for calculations.ai4materials.utils.utils_crystals
: functions related to crystal structuresai4materials.utils.utils_data_retrieval
: functions to retrieve data.ai4materials.utils.utils_mp
: functions for parallel execution.ai4materials.utils.utils_plotting
: functions for plotting results of modelling.ai4materials.utils.utils_vol_data
: functions to deal with three-dimensional volumetric data.
Utils crystals¶
This package contains functions to build pristine and defective supercells, starting from ASE (Atomistic Simulation Environment) Atoms object [link]. It also allows to obtain the spacegroup of a given structure, or to get the standard conventional cell (using Pymatgen).
Pristine and defective supercell generation¶
The main functions available to modify crystal structures are:
ai4materials.utils.utils_crystals.create_supercell
creates a pristine supercell starting from a given atom structure.ai4materials.utils.utils_crystals.random_displace_atoms
creates a supercell with randomly displace atoms.ai4materials.utils.utils_crystals.create_vacancies
creates a supercell with vacancies.ai4materials.utils.utils_crystals.substitute_atoms
creates a supercell with randomly substitute atoms.
For additional details on each function, see their respective descriptions below.
Example: pristine supercell creation¶
Starting from a given ASE structure, the script below uses ai4materials.utils.utils_crystals.create_supercell
to generate a supercell of (approximately) 128 atoms:
from ase.io import write
from ase.build import bulk
import matplotlib.pyplot as plt
from ase.visualize.plot import plot_atoms
from ai4materials.utils.utils_crystals import create_supercell
cu_fcc = bulk('Cu', 'fcc', a=3.6, orthorhombic=True)
supercell_cu_fcc = create_supercell(cu_fcc, create_replicas_by='nb_atoms', target_nb_atoms=128)
write('cu_fcc.png', cu_fcc)
write('cu_fcc_supercell.png', supercell_cu_fcc)
This is the original structure:
and this is the supercell obtained replicating the unit cells up to a target number of atoms (target_nb_atoms
)
Example: defective supercell creation¶
Starting from a given ASE structure, the script below uses ai4materials.utils.utils_crystals.create_vacancies
to generate a defective supercell of (approximately) 128 atoms with 25% vacancies:
from ase.io import write
from ase.build import bulk
import matplotlib.pyplot as plt
from ase.visualize.plot import plot_atoms
from ai4materials.utils.utils_crystals import create_vacancies
cu_fcc = bulk('Cu', 'fcc', a=3.6, orthorhombic=True)
supercell_vac25_cu_fcc = create_vacancies(cu_fcc, target_vacancy_ratio=0.25, create_replicas_by='nb_atoms', target_nb_atoms=128)
write('cu_fcc.png', cu_fcc)
write('cu_fcc_supercell_vac25.png', supercell_vac25_cu_fcc)
Similarly, it is possible to generate a supercell with randomly displaced atoms with
ai4materials.utils.utils_crystals.random_displace_atoms
.
In the script below,
we generate a defective supercell of (approximately) 200 atoms with displacements sampled from a Gaussian
distribution with standard deviation of 0.5 Angstrom:
from ase.io import write
from ase.build import bulk
import matplotlib.pyplot as plt
from ase.visualize.plot import plot_atoms
from ai4materials.utils.utils_crystals import random_displace_atoms
cu_fcc = bulk('Cu', 'fcc', a=3.6, orthorhombic=True)
supercell_rand_disp_cu_fcc = random_displace_atoms(cu_fcc, displacement=0.5, create_replicas_by='nb_atoms', noise_distribution='gaussian', target_nb_atoms=256)
write('cu_fcc.png', cu_fcc)
write('supercell_rand_disp_cu_fcc_05A.png', supercell_rand_disp_cu_fcc)
Section author: Angelo Ziletti <angelo.ziletti@gmail.com>
Submodules¶
- ai4materials.utils.unit_conversion module
- ai4materials.utils.utils_binaries module
- ai4materials.utils.utils_config module
- ai4materials.utils.utils_crystals module
- ai4materials.utils.utils_data_retrieval module
- ai4materials.utils.utils_mp module
- ai4materials.utils.utils_parsing module
- ai4materials.utils.utils_plotting module
- ai4materials.utils.utils_vol_data module