Utils

This package contains utility functions for data analytics applied to materials science data. Specifically,

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:

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:

_images/cu_fcc.png

and this is the supercell obtained replicating the unit cells up to a target number of atoms (target_nb_atoms)

_images/cu_fcc_supercell.png

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)
_images/cu_fcc_supercell_vac25.png

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)
_images/supercell_rand_disp_cu_fcc_05A.png

Section author: Angelo Ziletti <angelo.ziletti@gmail.com>

Module contents