Introduction to atomman: Basic support and analysis tools

Lucas M. Hale, lucas.hale@nist.gov, Materials Science and Engineering Division, NIST.

Disclaimers

1. Introduction

This Notebook outlines some of the other tools in atomman that provide basic support features and simple analysis of the atomistic systems.

Library Imports

[1]:
# Standard Python libraries
import os
from io import open
from copy import deepcopy
import datetime

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

# https://pandas.pydata.org/
import pandas as pd

# https://github.com/usnistgov/atomman
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.11
Notebook executed on 2024-04-29

Construct a demonstration 2x2x2 diamond cubic silicon system

[2]:
a = uc.set_in_units(5.431, 'angstrom')
ucell = am.load('prototype', 'A4--C--dc', a=a, symbols='Si')

system = ucell.supersize(2,2,2)

print(system.natoms)
64

2. Elastic constants

The full elastic constants tensor for a given crystal can be represented with the atomman.ElasticConstants class. The values in an ElasticConstants object can be set and retrieved in a variety of formats and transformed to other Cartesian coordinate systems.

See the 3.1. ElasticConstants class Jupyter Notebook for more details and a full description of all of the class methods.

[3]:
# Define an ElasticConstants object for diamond cubic silicon
# values taken from http://www.ioffe.ru/SVA/NSM/Semicond/Si/mechanic.html
C11 = uc.set_in_units(16.60 * 10**11, 'dyn/cm^2')
C12 = uc.set_in_units( 6.40 * 10**11, 'dyn/cm^2')
C44 = uc.set_in_units( 7.96 * 10**11, 'dyn/cm^2')

C = am.ElasticConstants(C11=C11, C12=C12, C44=C44)
[4]:
# Get 6x6 Cij Voigt representation of elastic constants in GPa
print('Cij (GPa) =')
print(uc.get_in_units(C.Cij, 'GPa'))
Cij (GPa) =
[[166.   64.   64.    0.    0.    0. ]
 [ 64.  166.   64.    0.    0.    0. ]
 [ 64.   64.  166.    0.    0.    0. ]
 [  0.    0.    0.   79.6   0.    0. ]
 [  0.    0.    0.    0.   79.6   0. ]
 [  0.    0.    0.    0.    0.   79.6]]

3. Relative distances between atoms

There are a few built-in tools for investigating the relative positions between atoms of the same and different systems.

3.1. System.dvect()

The System.dvect() method computes the shortest vector(s) between two points or list of points within the System taking into account the System’s periodic dimensions.

Parameters

  • pos_0 (numpy.ndarray or index) Absolute Cartesian vector position(s) to use as reference point(s). If the value can be used as an index, then self.atoms.pos[pos_0] is taken.

  • pos_1 (numpy.ndarray or index) Absolute Cartesian vector position(s) to find relative to pos_0. If the value can be used as an index, then self.atoms.pos[pos_1] is taken.

[5]:
# Calculate shortest vector between atoms 1 and 60
print(system.dvect(1, 60))
[ 4.07325  4.07325 -4.07325]

3.2. System.dmag()

The System dmag() method computes the magnitude of the shortest vector(s) between two points or list of points within the System taking into account the System’s periodic dimensions. This is identical to computing dvect above, then finding the magnitude of those vectors, but should be faster.

[6]:
# Calculate shortest distance between position [5., 5., 5.] and all atoms in system
dmags = system.dmag([5.0, 5.0, 5.0], range(system.natoms))
print(dmags)
[8.66025404 5.95297241 5.95297241 5.95297241 6.30856205 3.87088054
 3.87088054 3.87088054 7.08419092 6.33398788 6.33398788 3.25939281
 5.45266877 2.2175116  5.86626957 5.86626957 7.08419092 6.33398788
 3.25939281 6.33398788 5.45266877 5.86626957 2.2175116  5.86626957
 5.03701519 6.69334927 3.91218142 3.91218142 4.43455051 4.93424363
 4.93424363 7.33774633 7.08419092 3.25939281 6.33398788 6.33398788
 5.45266877 5.86626957 5.86626957 2.2175116  5.03701519 3.91218142
 6.69334927 3.91218142 4.43455051 4.93424363 7.33774633 4.93424363
 5.03701519 3.91218142 3.91218142 6.69334927 4.43455051 7.33774633
 4.93424363 4.93424363 0.7465139  4.4706471  4.4706471  4.4706471
 3.09820588 6.6163557  6.6163557  6.6163557 ]

3.3. displacement()

The atomman.displacement() function compares two systems with the same number of atoms and calculates the vector differences between all atoms with the same atomic id’s. The vectors returned are the shortest vectors after taking periodic boundaries in consideration, i.e. it uses dvect().

Parameters

  • system_0 (atomman.System) The initial system to calculate displacements from.

  • system_1 (atomman.System) The final system to calculate displacements to.

  • box_reference (str or None) Specifies which system’s boundary conditions to use.

    • ‘initial’ uses system_0’s box and pbc.

    • ‘final’ uses system_1’s box and pbc (Default).

    • None computes the straight difference between the positions without accounting for periodic boundaries.

[7]:
# Copy system and randomly displace atoms
system2 = deepcopy(system)
system2.atoms.pos += 3 * np.random.rand(system.natoms, 3)
system2.wrap()

# Show displacement between the two systems
print(am.displacement(system, system2))
[[2.39315582e+00 1.93285757e+00 2.62930773e+00]
 [1.70693199e+00 1.67755942e+00 4.46071098e-01]
 [1.83643203e+00 2.96721168e+00 1.74986897e+00]
 [9.68122262e-01 1.77011698e+00 1.03883896e+00]
 [7.19742667e-01 2.36355181e+00 8.86329527e-01]
 [5.45578861e-01 1.51298915e+00 9.58368954e-01]
 [2.58746893e+00 2.43101206e+00 2.22457166e+00]
 [1.16413297e+00 1.97065000e+00 2.78419884e+00]
 [6.85733642e-01 2.63582318e+00 1.55820432e+00]
 [2.15125684e+00 2.71790059e+00 1.05802562e+00]
 [2.47112179e-01 1.08105801e+00 4.23841004e-01]
 [1.86704329e+00 2.01581120e+00 1.01125816e+00]
 [5.72542380e-01 2.94214296e-01 1.34988394e+00]
 [1.52910691e+00 1.58582017e+00 2.37563107e+00]
 [1.74765534e-01 2.40611978e+00 1.36171703e+00]
 [2.26195277e+00 2.29335455e+00 6.30815064e-01]
 [2.01659168e+00 2.42895666e+00 1.63780516e+00]
 [1.10690501e+00 1.07315550e+00 2.94325138e+00]
 [1.26813155e+00 2.35461542e+00 1.30290216e+00]
 [2.23208893e+00 2.35568387e+00 1.38191313e+00]
 [8.03141909e-01 4.68669770e-01 2.30863006e+00]
 [9.69786434e-01 2.17070593e+00 8.83004993e-01]
 [2.64106916e+00 1.44931436e-03 1.13862900e+00]
 [1.04577933e+00 1.86609396e+00 1.23122119e+00]
 [2.21698769e+00 2.67205670e+00 6.65136655e-02]
 [2.11785460e-01 7.32292912e-01 2.56925160e+00]
 [2.74423006e+00 2.43172841e-01 1.14877798e+00]
 [2.08404682e+00 1.96232221e+00 1.85404217e+00]
 [3.60658551e-01 4.66987696e-01 2.47290750e+00]
 [1.94660925e+00 2.45659821e+00 8.67397975e-01]
 [1.78263433e+00 1.50934818e+00 1.65823051e+00]
 [2.55145130e+00 2.49019416e-01 2.18769565e+00]
 [1.40769026e+00 5.79803116e-02 2.88072842e+00]
 [1.75369282e+00 1.67203177e+00 1.47998012e+00]
 [2.19144508e+00 1.29803453e+00 5.58358633e-01]
 [1.26125531e+00 2.14322673e+00 6.70412330e-01]
 [1.60899869e+00 1.05557449e+00 1.86570279e+00]
 [1.70334504e+00 2.18144488e+00 1.92454559e+00]
 [2.09532232e+00 3.09290869e-01 1.86830451e+00]
 [1.87947882e+00 2.97306530e-01 1.29360306e+00]
 [5.87217512e-01 1.06077965e+00 2.38945799e+00]
 [1.37511304e+00 8.86015737e-02 1.76798507e-01]
 [2.77128283e+00 2.03813406e+00 1.31166355e+00]
 [2.20996054e-01 1.97906751e-02 4.20765266e-01]
 [2.70952990e-01 7.65542891e-01 4.84299731e-01]
 [2.28116297e+00 2.01509415e-01 2.48917275e+00]
 [1.82585953e+00 9.69371397e-01 1.28094488e+00]
 [2.59050294e+00 1.47419654e-01 7.06910218e-01]
 [1.30984808e+00 2.61397189e+00 2.72344953e+00]
 [2.74652851e+00 1.58209073e+00 1.57836668e+00]
 [1.43679801e+00 2.24145701e+00 1.32871416e+00]
 [4.99357678e-01 1.04315152e+00 1.41268256e+00]
 [1.33140686e+00 7.31645886e-01 3.44785594e-01]
 [2.42620345e+00 1.00698349e+00 2.12021083e+00]
 [2.06075608e+00 1.35857464e+00 2.14829359e+00]
 [1.68586009e+00 1.60005374e+00 2.31917278e+00]
 [1.27076902e+00 1.96760602e+00 7.24606935e-01]
 [1.13550297e+00 6.26264775e-02 8.56941760e-01]
 [1.54403223e-01 2.58627534e+00 2.25170839e+00]
 [2.55208173e+00 6.11658215e-01 4.66556435e-02]
 [1.40389684e+00 2.86906306e-01 1.31441216e+00]
 [2.88703390e+00 6.13323665e-01 2.35789525e+00]
 [1.18281832e+00 7.09588218e-01 2.44792041e+00]
 [1.61392296e+00 9.84809705e-01 6.89592295e-01]]

3.4. System.neighborlist()

A list of neighbor atoms within a cutoff can be constructed using the System.neighborlist() method. The list of neighbors is returned as an atomman.NeighborList object.

See the 3.2. NeighborList class Jupyter Notebook for more details on how the list is calculated and can be used.

Parameters

  • cutoff (float, optional) Radial cutoff distance for identifying neighbors. Must be given if model is not given.

  • model (str or file-like object, optional) Gives the file path or content to load. If given, no other parameters are allowed.

  • initialsize (int, optional) The number of neighbor positions to initially assign to each atom. Default value is 20.

  • deltasize (int, optional) Specifies the number of extra neighbor positions to allow each atom when the number of neighbors exceeds the underlying array size. Default value is 10.

Returns

  • (atomman.NeighborList) The compiled list of neighbors.

[8]:
# Identify neighbors within 3 angstroms
neighbors = system.neighborlist(cutoff=3)

The coordinataion numbers for the atoms can be retrieved with coord.

[9]:
# Show average atomic coordination
print('Average coordination =', neighbors.coord.mean())
Average coordination = 4.0

Index selection on the NeighborList object will return the indices of the neighbor atoms.

[10]:
# List neighbor atoms of atom 6
print('Neighbors of atom 6 =', neighbors[6])
Neighbors of atom 6 = [ 2 11 33 40]

The neighbor indices can then be used to filter other properties to only focus on an atom’s neighbors.

[11]:
# List the dmag values between atom 9 and its neighbors
print(system.dmag(9, neighbors[9]))
[2.35169198 2.35169198 2.35169198 2.35169198]

4. Region selectors

Added version 1.3.0

A number of geometric shape definitions are available in the atomman.region submodule to help identify regions in space above/below planes or inside/outside of regions. These are useful for constructing systems by slicing away atoms to create nanostructures, or for performing analysis on only select regions.

See the 3.3. Region selectors Jupyter Notebook for more details and a list of all available shapes.

[12]:
# Define a plane normal to the y axis and positioned halfway across system
plane = am.region.Plane([0,1,0], system.box.bvect / 2)

# Count number of atoms in system, and above/below plane
print(f'{system.natoms} atoms in system')

abovecount = np.sum(plane.above(system.atoms.pos))
print(f'{abovecount} atoms above plane')

belowcount = np.sum(plane.below(system.atoms.pos))
print(f'{belowcount} atoms below plane')

# Define a sphere centered at [0,0,0] with radius = 6
sphere = am.region.Sphere([0,0,0], 6)

# Count atoms inside sphere
insidecount = np.sum(sphere.inside(system.atoms.pos))
print(f'{insidecount} atoms inside sphere')
64 atoms in system
24 atoms above plane
40 atoms below plane
11 atoms inside sphere

5. Basic tools

This lists some of the other basic tools and features in atomman.

5.1. Atomic information

  • atomman.tools.atomic_number() returns the atomic number associated with an element’s atomic symbol.

  • atomman.tools.atomic_symbol() returns the elemental symbol associated with an given atomic number.

  • atomman.tools.atomic_mass() returns the atomic mass of an element or isotope. The atom can be identified with atomic number or atomic/isotope symbol.

[13]:
# Get atomic number for an atomic symbol
num = am.tools.atomic_number('Fe')
print(num)

# Get atomic symbol for an atomic number
symbol = am.tools.atomic_symbol(num)
print(symbol)

# Get atomic mass for an atomic symbol
mass = am.tools.atomic_mass(symbol)
print(mass)

# Get atomic mass for an atomic number
mass = am.tools.atomic_mass(num)
print(mass)
26
Fe
55.845
55.845
[14]:
# Get atomic mass for an isotope
mass = am.tools.atomic_mass('Al-26')
print(mass)
25.986891904

5.2. axes_check()

The axes_check() function is useful when working in Cartesian systems. Given a (3,3) array representing three 3D Cartesian vectors:

  • The three vectors are checked that they are orthogonal and right-handed.

  • The corresponding array of unit vectors are returned. This can then be used for crystal transformations.

[15]:
axes = [[-1, 0, 1],
        [ 1, 0, 1],
        [ 0, 1, 0]]
print(am.tools.axes_check(axes))
[[-0.70710678  0.          0.70710678]
 [ 0.70710678  0.          0.70710678]
 [ 0.          1.          0.        ]]

5.3. filltemplate()

The filltemplate() function takes a template and fills in values for delimited template variables.

[16]:
madlibs = "My friend <name> really likes to use templates to <verb>, says that they are <adjective>!"
s_delimiter = '<'
e_delimiter = '>'

terms = {}
terms['name'] = 'Charlie'
terms['verb'] = 'program'
terms['adjective'] = 'delicious'

print(am.tools.filltemplate(madlibs, terms, s_delimiter, e_delimiter))
My friend Charlie really likes to use templates to program, says that they are delicious!

5.4. indexstr()

Iterates through all indicies of an array with a given shape, returning both the numeric index and a string representation.

[17]:
for index, istr in am.tools.indexstr((3,2)):
    print('index ->', repr(index), ', istr ->', repr(istr))
index -> (0, 0) , istr -> '[0][0]'
index -> (0, 1) , istr -> '[0][1]'
index -> (1, 0) , istr -> '[1][0]'
index -> (1, 1) , istr -> '[1][1]'
index -> (2, 0) , istr -> '[2][0]'
index -> (2, 1) , istr -> '[2][1]'

5.5. uber_open_rmode

uber_open_rmode is a context manager that allows for similar reading of content from a file or from a string variable. It equivalently handles:

  • str path name to a file

  • str content

  • open file-like object

[18]:
# Define str and save to file
text = 'Here I am, read me!'
fname = 'text.txt'
with open(fname, 'w') as f:
    f.write(text)

# Use uber_open_rmode on text
with am.tools.uber_open_rmode(text) as f:
    print(f.read())

# Use uber_open_rmode on file path
with am.tools.uber_open_rmode(fname) as f:
    print(f.read())

# Use uber_open_rmode on file-like object
with open(fname, 'rb') as fobject:
    with am.tools.uber_open_rmode(fobject) as f:
        print(f.read())
b'Here I am, read me!'
b'Here I am, read me!'
b'Here I am, read me!'

5.6. vect_angle()

The vect_angle() function returns the angle between two vectors.

[19]:
vect1 = 2*np.random.rand(3)-1
vect2 = 2*np.random.rand(3)-1

print('Angle between', vect1, 'and', vect2, '=')
print(am.tools.vect_angle(vect1, vect2), 'degrees')
print(am.tools.vect_angle(vect1, vect2, 'radian'), 'radians')
Angle between [-0.85971479 -0.37403948 -0.97612216] and [ 0.96960778 -0.80935489  0.96932714] =
133.27127456898273 degrees
2.3260225395581355 radians

5.7. duplicates_allclose()

Determine duplicates in dataframe based on tolerances. The implementation first uses pandas.DataFrame.duplicated on the dcols argument with keep=False to keep all duplicates. The duplicate sub-dataframe is then sorted on both dcols and fcols. A diff between each row is then done on the sorted duplicates dataframe. The float values are then checked for their tolerances.

Note: False duplicates may be identified if tolerance ranges overlap. Consider dataframe with rows 1,2,3. If row 2 matches row 1 within the tolerances, and row 3 matches row 2 within the tolerances, both rows 2 and 3 will be labeled as tolerances even if row 3 does not match row 1 within the tolerances.

Parameters - dataframe (pandas.DataFrame) The dataframe to search for duplicates - dcols (list) The column names that are tested for exact duplicates. - fcols (dict) The column names (keys) that are tested using absolute tolerances (values).

Returns - (list of bool of length nrows) False for first occurrence of checked values, True for subsequent duplicates.

[20]:
# Generate test DataFrame
df = pd.DataFrame({'A':[1.00001, 1.00002, 3.0000, 1.000000], 'B':['Same', 'Diff', 'Same', 'Same']})
df
[20]:
A B
0 1.00001 Same
1 1.00002 Diff
2 3.00000 Same
3 1.00000 Same
[21]:
# Show unique values
df[~am.tools.duplicates_allclose(df, dcols=['B'], fcols={'A':1e-4})]
[21]:
A B
1 1.00002 Diff
2 3.00000 Same
3 1.00000 Same

5.8. Miller index conversions

  • atomman.tools.miller.vector3to4(indices) converts vectors from three-term Miller indices to four-term Miller-Bravais indices for hexagonal systems. Updated version 1.2.6: now returns vectors with magnitudes consistent withe given vectors rather than rescaling to the smallest integer representations.

  • atomman.tools.miller.vector4to3(indices) converts vectors from four-term Miller-Bravais indices to three-term Miller indices. Updated version 1.2.6: now returns vectors with magnitudes consistent withe given vectors rather than rescaling to the smallest integer representations.

  • atomman.tools.miller.plane3to4(indices) converts planes from three-term Miller indices to four-term Miller-Bravais indices for hexagonal systems. Added version 1.2.8

  • atomman.tools.miller.plane4to3(indices) converts planes from four-term Miller-Bravais indices to three-term Miller indices. Added version 1.2.8

  • atomman.tools.miller.vector_crystal_to_cartesian(indices, box) converts Miller and Miller-Bravais indices to Cartesian vectors based on a supplied box. Updated version 1.2.6 renamed from vectortocartesian for consistency.

  • atomman.tools.miller.plane_crystal_to_cartesian(indices, box) converts Miller and Miller-Bravais plane indices to Cartesian normal vectors based on a supplied box. The method uses the definition of the crystal planes to identify two in-plane crystal vectors, converts them to Cartesian, and obtains the plane normal as the cross product of the two vectors. Added version 1.3.2

  • atomman.tools.miller.vector_primitive_to_conventional(indices, setting) converts vectors relative to a primitive unit cell to a conventional unit cell in the given setting (p, a, b, c, i, f, t1 or t2). Added version 1.2.6 Updated version 1.4.10 to include t1 and t2 options.

  • atomman.tools.miller.vector_conventional_to_primitive(indices, setting) converts vectors relative to a conventional unit cell in the given setting (p, a, b, c, i, f, t1 or t2) to a primitive unit cell. Added version 1.2.6 Updated version 1.4.10 to include t1 and t2 options.

  • atomman.tools.miller.fromstring(str) reads a string representation of a Miller(-Bravais) vector/plane and converts it into a numpy array. Added version 1.4.10

[22]:
# Test single vector conversions
print(am.tools.miller.vector3to4(np.array([3,3,3])))
print(am.tools.miller.vector4to3(np.array([1,1,-2,0])))
[ 1.  1. -2.  3.]
[3. 3. 0.]
[23]:
# Generate random uvw crystal indices
indices = np.random.randint(-5,6, (3,3))
print(indices)
print()

# Convert to hexagonal uvtw's
indices = am.tools.miller.vector3to4(indices)
print(indices)
print()

# Convert back to uvw's and see that values are recovered
indices = am.tools.miller.vector4to3(indices)
print(indices)
[[-4 -5 -1]
 [-2  5  0]
 [ 4  2  0]]

[[-1. -2.  3. -1.]
 [-3.  4. -1.  0.]
 [ 2.  0. -2.  0.]]

[[-4. -5. -1.]
 [-2.  5.  0.]
 [ 4.  2.  0.]]
[24]:
# Test single plane conversions
print(am.tools.miller.plane3to4(np.array([3,3,3])))
print(am.tools.miller.plane4to3(np.array([1,1,-2,0])))
[ 3.  3. -6.  3.]
[1. 1. 0.]
[25]:
# Generate random hkl crystal indices
indices = np.random.randint(-5,6, (3,3))
print(indices)
print()

# Convert to hexagonal hkil's
indices = am.tools.miller.plane3to4(indices)
print(indices)
print()

# Convert back to hkl's and see that values are recovered
indices = am.tools.miller.plane4to3(indices)
print(indices)
[[-4 -1  2]
 [ 5  0  5]
 [ 2 -2 -5]]

[[-4. -1.  5.  2.]
 [ 5.  0. -5.  5.]
 [ 2. -2. -0. -5.]]

[[-4. -1.  2.]
 [ 5.  0.  5.]
 [ 2. -2. -5.]]
[26]:
# Define a hexagonal box
a = uc.set_in_units(2.51, 'angstrom')
c = uc.set_in_units(4.07, 'angstrom')
box = am.Box(a=a, b=a, c=c, gamma=120)

# Pass Miller indices
indices = [[1,0,0],
           [0,1,0],
           [0,0,1]]
print(am.tools.miller.vector_crystal_to_cartesian(indices, box))
print()

# Pass equivalent Miller-Bravais indices
indices = [[ 2/3,-1/3,-1/3, 0],
           [-1/3, 2/3,-1/3, 0],
           [   0,   0,   0, 1]]
print(am.tools.miller.vector_crystal_to_cartesian(indices, box))
[[ 2.51        0.          0.        ]
 [-1.255       2.17372376  0.        ]
 [ 0.          0.          4.07      ]]

[[ 2.51        0.          0.        ]
 [-1.255       2.17372376  0.        ]
 [ 0.          0.          4.07      ]]
[27]:
# Define a hexagonal box
a = uc.set_in_units(2.51, 'angstrom')
c = uc.set_in_units(4.07, 'angstrom')
box = am.Box(a=a, b=a, c=c, gamma=120)

# Pass Miller plane indices
indices = [ 0, 0, 1]
print(am.tools.miller.plane_crystal_to_cartesian(indices, box))
indices = [ 1, 0, 0]
print(am.tools.miller.plane_crystal_to_cartesian(indices, box))
print()

# Pass equivalent Miller-Bravais indices
indices = [ 0, 0, 0, 1]
print(am.tools.miller.plane_crystal_to_cartesian(indices, box))
indices = [ 1, 0,-1, 0]
print(am.tools.miller.plane_crystal_to_cartesian(indices, box))
[ 0. -0.  1.]
[ 0.8660254  0.5       -0.       ]

[ 0. -0.  1.]
[ 0.8660254  0.5       -0.       ]
[28]:
# Define a primitive bcc unit cell box
a = uc.set_in_units(2.86, 'angstrom')
p_box = am.Box.trigonal(a * 3**0.5 / 2, alpha=109.466666667)
p_ucell = am.System(box=p_box)
print(p_ucell)
avect =  [ 2.477,  0.000,  0.000]
bvect =  [-0.825,  2.335,  0.000]
cvect =  [-0.825, -1.167,  2.023]
origin = [ 0.000,  0.000,  0.000]
natoms = 1
natypes = 1
symbols = (None,)
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
[29]:
# Convert conventional box vectors to primitive vectors
a_uvw = am.tools.miller.vector_conventional_to_primitive([1, 0, 0], setting='i')
b_uvw = am.tools.miller.vector_conventional_to_primitive([0, 1, 0], setting='i')
c_uvw = am.tools.miller.vector_conventional_to_primitive([0, 0, 1], setting='i')
p_uvws = np.array([a_uvw, b_uvw, c_uvw])
print('primitive uvws:')
print(p_uvws)

# Convert back to conventional just for consistency
print('conventional uvws:')
print(am.tools.miller.vector_primitive_to_conventional(p_uvws, setting='i'))
primitive uvws:
[[ 0. -1. -1.]
 [ 1.  1.  0.]
 [ 1.  0.  1.]]
conventional uvws:
[[1. 0. 0.]
 [0. 1. 0.]
 [0. 0. 1.]]
[30]:
# rotate system using p_uvws to get conventional unit cell
c_ucell = p_ucell.rotate(p_uvws)
print(c_ucell)
avect =  [ 2.860,  0.000,  0.000]
bvect =  [-0.000,  2.860,  0.000]
cvect =  [-0.000,  0.000,  2.860]
origin = [ 0.000,  0.000,  0.000]
natoms = 2
natypes = 1
symbols = (None,)
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   1.430   1.430   1.430
[31]:
# Read in string representations of the Miller(-Bravais) vectors and planes
miller_strings = [
    '1/2 [1 1 0]',
    '1/3 <1 1 -2 0>',
    '{1 1 1}',
    '(0 0 0 1)',
    '1 4 1'
]
for miller_str in miller_strings:
    print(f'{repr(miller_str):16} -> {repr(am.tools.miller.fromstring(miller_str))}')
'1/2 [1 1 0]'    -> array([0.5, 0.5, 0. ])
'1/3 <1 1 -2 0>' -> array([ 0.33333333,  0.33333333, -0.66666667,  0.        ])
'{1 1 1}'        -> array([1., 1., 1.])
'(0 0 0 1)'      -> array([0., 0., 0., 1.])
'1 4 1'          -> array([1., 4., 1.])

5.9. Crystal lattice identification

Note version 1.4.4 These have been added as methods of the Box class. These stand-alone functions are likely to be depreciated in the next major atomman version.

There are also a few tests for identifying if a supplied box is consistent with a standard representation of a crystal family unit cell.

  • atomman.tools.identifyfamily(box) returns str crystal family if box corresponds to a standard crystal representation. Otherwise, returns None.

  • atomman.tools.iscubic(box)) returns bool indicating if box is a standard cubic box.

  • atomman.tools.ishexagonal(box)) returns bool indicating if box is a standard hexagonal box.

  • atomman.tools.istetragonal(box)) returns bool indicating if box is a standard tetragonal box.

  • atomman.tools.isrhombohedral(box)) returns bool indicating if box is a standard rhombohedral box.

  • atomman.tools.isorthorhombic(box)) returns bool indicating if box is a standard orthorhombic box.

  • atomman.tools.ismonoclinic(box)) returns bool indicating if box is a standard monoclinic box.

  • atomman.tools.istriclinic(box)) returns bool indicating if box is a standard triclinic box.

All of these functions use the following standard representation criteria:

  • cubic:

    • \(a = b = c\)

    • \(\alpha = \beta = \gamma = 90\)

  • hexagonal:

    • \(a = b \ne c\)

    • \(\alpha = \beta = 90\)

    • \(\gamma = 120\)

  • tetragonal:

    • \(a = b \ne c\)

    • \(\alpha = \beta = \gamma = 90\)

  • rhombohedral:

    • \(a = b = c\)

    • \(\alpha = \beta = \gamma \ne 90\)

  • orthorhombic:

    • \(a \ne b \ne c\)

    • \(\alpha = \beta = \gamma = 90\)

  • monoclinic:

    • \(a \ne b \ne c\)

    • \(\alpha = \gamma = 90\)

    • \(\beta \ne 90\)

  • triclinic:

    • \(a \ne b \ne c\)

    • \(\alpha \ne \beta \ne \gamma\)

[32]:
# Define an orthogonal box
a = uc.set_in_units(2.51, 'angstrom')
b = uc.set_in_units(3.13, 'angstrom')
c = uc.set_in_units(4.07, 'angstrom')
box = am.Box(a=a, b=b, c=c)

print('identifyfamily =', am.tools.identifyfamily(box))
print('iscubic =       ', am.tools.iscubic(box))
print('ishexagonal =   ', am.tools.ishexagonal(box))
print('istetragonal =  ', am.tools.istetragonal(box))
print('isrhombohedral =', am.tools.isrhombohedral(box))
print('isorthorhombic =', am.tools.isorthorhombic(box))
print('ismonoclinic =  ', am.tools.ismonoclinic(box))
print('istriclinic =   ', am.tools.istriclinic(box))
identifyfamily = orthorhombic
iscubic =        False
ishexagonal =    False
istetragonal =   False
isrhombohedral = False
isorthorhombic = True
ismonoclinic =   False
istriclinic =    False
[33]:
# Define a non-standard tetragonal box with a=c!=b
box = am.Box(a=a, b=b, c=a)
print('identifyfamily =', am.tools.identifyfamily(box))
identifyfamily = None

5.10. compositionstr()

Added version 1.2.7

Takes a list of symbols and the counts for each and returns a reduced composition string. Used by System.composition.

[34]:
symbols = ['Si', 'Al', 'Si']
counts = [500, 1000, 2000]
print('Composition =', am.tools.compositionstr(symbols, counts))
Composition = Al2Si5

File Cleanup

[35]:
os.remove('text.txt')