Introduction to atomman: conventional-primitive cell dumping

1. Introduction

The ‘conventional_to_primitive’ and ‘primitive_to_conventional’ dump styles provide a means of converting between primitive and conventional representations of unit cells in a reversible way. These system conversions are based on the vector_primitive_to_conventional and vector_conventional_to_primitive operations in atomman.tools.miller, which makes it possible to easily switch between the two reference states.

NOTE: These conversion methods should only be used on unit cells in which you know what the proper conventional cell setting is. For more general primitive cell identification, use the ‘primitive_cell’ dump method.

Added version 1.4.8

Library Imports

[1]:

# Standard Python libraries
import datetime

# http://www.numpy.org/
import numpy as np

import atomman as am
import atomman.unitconvert as uc

# Show atomman version
print('atomman version =', am.__version__)

# Show date of Notebook execution
print('Notebook executed on', datetime.date.today())

atomman version = 1.4.10
Notebook executed on 2023-07-28

2. Dump conventional_to_primitive

Transforms a conventional unit cell system of a specified Bravais space lattice setting into a primitive unit cell. The primitive_to_conventional and conventional_to_primitive dump styles are meant to be inverse operations, within floating point precision, to provide compatible primitive and conventional unit cells.

NOTE: This dump style expects that the original starting system is a conventional unit cell, and only limited checks are performed to assert this! Use the ‘primitive_cell’ dump style for a more comprehensive primitive unit cell identifier.

Parameters

• system (atomman.System) A conventional unit cell system to find the corresponding primitive unit cell for.

• setting (str, optional) The conventional cell space lattice setting. Allowed values are ‘p’ for primitive, ‘f’ for face-centered, ‘i’ for body centered, and ‘a’, ‘b’, or ‘c’ for side-centered.

• smallshift (array-like object or None, optional) A small rigid body shift to apply to the atomic positions when searching for which atoms are within the primitive cell. This helps avoid identification issues when atoms are directly on the box boundaries. The default value of None will use a smallshift of [0.001, 0.001, 0.001].

• rtol (float, optional) Relative tolerance to use for numpy.isclose. This is used here to check that the conventional cell has atoms in the expected lattice positions for the given setting.

• atol (float, optional) Absolute tolerance to use for numpy.isclose. This is used here to check that the conventional cell has atoms in the expected lattice positions for the given setting.

• check_basis (bool, optional) If True (default), a quick check will be performed on the system to see if it appears consistent with a Bravais space lattice with the given setting. Turning this check off may be necessary for more complex cases, such as non-conventional cell representations and complex unit cells where no atoms are at the lattice site [0, 0, 0].

• check_family (bool, optional) If True (default), then the Bravais space lattice check will include a check that the crystal family is consistent with a Bravais lattice of the given setting. For example, Bravais lattices with setting ‘f’ only exist for cubic and orthogonal cells. This check is not done if either check_family or check_basis is False. Turning this off allows for transformations of non-conventional cells.

• return_transform (bool, optional) Indicates if the Cartesian transformation matrix associated with rotating from the conventional cell to primitive cell orientations is returned. Default value is False.

Returns

• p_ucell (atomman.System) The primitive unit cell obtained by transforming the given conventional unit cell system.

• transform (numpy.ndarray) The Cartesian transformation matrix associated with converting from the primitive cell orientation to the conventional cell orientation. Only returned if return_transform is True.

[2]:

c_ucell = am.load('prototype', 'A1--Cu--fcc', a=4.05, symbols='Al')
print(c_ucell)

avect =  [ 4.050,  0.000,  0.000]
bvect =  [ 0.000,  4.050,  0.000]
cvect =  [ 0.000,  0.000,  4.050]
origin = [ 0.000,  0.000,  0.000]
natoms = 4
natypes = 1
symbols = ('Al',)
pbc = [ True  True  True]
per-atom properties = ['atype', 'pos']
     id   atype  pos[0]  pos[1]  pos[2]
      0       1   0.000   0.000   0.000
      1       1   0.000   2.025   2.025
      2       1   2.025   0.000   2.025
      3       1   2.025   2.025   0.000

[3]:

p_ucell = c_ucell.dump('conventional_to_primitive', setting='f')
print(p_ucell)

avect =  [ 2.864,  0.000,  0.000]
bvect =  [ 1.432,  2.480,  0.000]
cvect =  [ 1.432,  0.827,  2.338]
origin = [ 0.000,  0.000,  0.000]
natoms = 1
natypes = 1
symbols = ('Al',)
pbc = [ True  True  True]
per-atom properties = ['atype', 'pos']
     id   atype  pos[0]  pos[1]  pos[2]
      0       1   0.000   0.000   0.000

3. Dump primitive_to_conventional

Transforms a primitive unit cell system into a conventional unit cell system of the given Bravais space lattice setting. The primitive_to_conventional and conventional_to_primitive dump styles are meant to be inverse operations, within floating point precision, to provide compatible primitive and conventional unit cells.

NOTE: This dump style expects that the original starting system is a primitive unit cell, although no checks are performed to assert this!

Parameters

• system (atomman.System) A primitive unit cell system to find the corresponding conventional unit cell for.

• setting (str, optional) The conventional cell space group lattice setting. Allowed values are ‘p’ for primitive, ‘f’ for face-centered, ‘i’ for body centered, and ‘a’, ‘b’, or ‘c’ for side-centered.

• return_transform (bool, optional) Indicates if the Cartesian transformation matrix associated with rotating from the primitive cell to conventional cell orientations is returned. Default value is False.

Returns

• c_ucell (atomman.System) The conventional unit cell obtained by transforming the given primitive unit cell system.

• transform (numpy.ndarray) The Cartesian transformation matrix associated with converting from the primitive cell orientation to the conventional cell orientation. Only returned if return_transform is True.

[4]:

c_ucell2 = p_ucell.dump('primitive_to_conventional', setting='f')
print(c_ucell2)

avect =  [ 4.050,  0.000,  0.000]
bvect =  [ 0.000,  4.050,  0.000]
cvect =  [ 0.000,  0.000,  4.050]
origin = [ 0.000,  0.000,  0.000]
natoms = 4
natypes = 1
symbols = ('Al',)
pbc = [ True  True  True]
per-atom properties = ['atype', 'pos']
     id   atype  pos[0]  pos[1]  pos[2]
      0       1   0.000   0.000   0.000
      1       1   2.025   2.025   0.000
      2       1   0.000   2.025   2.025
      3       1   2.025   0.000   2.025