Introduction to atomman: Defining atomic systems

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

1. Introduction

This Notebook provides an introduction to creating and manipulating atomistic systems using atomman.

Library Imports

[1]:

# Standard Python libraries
import os
from copy import deepcopy
import datetime

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

# 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.10
Notebook executed on 2023-07-28

2. Create a System

Atomic systems are represented with three Python objects: Box, Atoms, and System.

2.1. Box

The Box class defines a generic parallelepiped for the system’s boundaries.

See the 1.1. Box class Jupyter Notebook for more detailed information and options.

2.1.1. Create Box

Boxes can be defined using a variety of formats. Here, we’ll define a box using lattice parameters.

[2]:

# a = 4.05 angstroms (Al fcc lattice constant)
a = uc.set_in_units(4.05, 'angstrom')

# Create cubic box
box = am.Box.cubic(a=a)

2.1.2. Access Box properties

The string of Box shows four Cartesian vectors: the three box vectors (avect, bvect, and cvect) and the origin position.

[3]:

print(box)

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]

The parameters of the Box can also be retrieved in a variety of formats. Some examples are shown here.

[4]:

print('a =', box.a)
print('b =', box.b)
print('c =', box.c)
print('alpha =', box.alpha)
print('beta  =', box.beta)
print('gamma =', box.gamma)

a = 4.05
b = 4.05
c = 4.05
alpha = 90.0
beta  = 90.0
gamma = 90.0

2.2. Atoms

The Atoms class collects per-atom properties that can be freely assigned. The only limitations are that the number of atoms is constant, and that values for the per-atom properties must be given for all atoms.

See the 1.2. Atoms class Jupyter Notebook for more detailed information and options.

2.2.1. Create Atoms

When initializing an Atoms object, all keyword arguments (except natoms and prop) will be interpreted as property names. Values for each property must be given for each atom, or only one value given in which case all atoms will be assigned the same value.

By default, each Atoms instance has two per-atom properties:

atype is an integer atomic type. If not given, atype will be set to 1 for all atoms.
pos is the 3D vector position. If not given, pos will be set to [0,0,0] for all atoms.

[5]:

# Create Atoms for an fcc unit cell
atype = 1
pos = [[0.0, 0.0, 0.0],
       [0.5, 0.5, 0.0],
       [0.5, 0.0, 0.5],
       [0.0, 0.5, 0.5]]

atoms = am.Atoms(atype=atype, pos=pos)

2.2.2. Accessing Atoms properties

The string of Atoms shows id, atype, and pos for all atoms.

[6]:

print(atoms)

per-atom properties = ['atype', 'pos']
     id   atype  pos[0]  pos[1]  pos[2]
      0       1   0.000   0.000   0.000
      1       1   0.500   0.500   0.000
      2       1   0.500   0.000   0.500
      3       1   0.000   0.500   0.500

The per-atom properties can be accessed as attributes of the object.

[7]:

print('atoms.atype ->', atoms.atype)
print('atoms.pos[2] ->', atoms.pos[2])

atoms.atype -> [1 1 1 1]
atoms.pos[2] -> [0.5 0.  0.5]

The per-atom properties can also be converted into a flat pandas.DataFrame with the df() method.

[8]:

atoms.df()

[8]:

	atype	pos[0]	pos[1]	pos[2]
0	1	0.0	0.0	0.0
1	1	0.5	0.5	0.0
2	1	0.5	0.0	0.5
3	1	0.0	0.5	0.5

2.3. System

The System class gives a full representation of an atomic configuration by combining an atoms instance, a box instance, periodic boundary condition settings, and a list of element symbols.

See the 1.3. System class Jupyter Notebook for more detailed information and options.

2.3.1. Create system

A System is created by combining its components:

atoms is an Atoms object.
box is a Box object.
pbc is a list of three bools, where True indicates the box is periodic along the corresponding box vector.
symbols is a list of element model symbols for each unique atype value.
scale is a bool that indicates if atoms.pos are to be scaled relative to the box vectors.

[9]:

system = am.System(atoms=atoms, box=box, pbc=[True, False, True], symbols='Al', scale=True)
print(system)

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 False  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   2.025   0.000   2.025
      3       1   0.000   2.025   2.025

2.3.2. View system

Preliminary feature added 1.4.10

You can view a system from within a Jupyter environment. This is useful for taking a quick peak at smaller structures to check that they are correct.

Caution: plotting methods are still preliminary and the method calls are likely to change!

[10]:

am.plot.py3Dmol.view_3d(system, width=400, height=400)

You appear to be running in JupyterLab (or JavaScript failed to load for some other reason). You need to install the 3dmol extension:
jupyter labextension install jupyterlab_3dmol

3. Load a System

Systems can also be created by loading in atomic configurations from either

files of many different formats,
representations of configurations used by other Python packages, or
records stored in the potentials database.

See the 1.4. Load and dump conversions Jupyter Notebook for more detailed information on all the different available styles and options.

3.1. Load from POSCAR

Create content in POSCAR format

[11]:

fcc_poscar = """POSCAR for fcc Al standard unit cell
1.0
4.05 0.00 0.00
0.00 4.05 0.00
0.00 0.00 4.05
Al
4
direct
0.00 0.00 0.00
0.50 0.50 0.00
0.50 0.00 0.50
0.00 0.50 0.50"""

Load content. The load() function parameters are:

style (str) indicates the format of the content being loaded.
content (any) the content to be loaded. For text formats, can be a str of the content, a file path or a file-like object.
**kwargs (any) any extra style-specific keyword arguments.

[12]:

new_system = am.load('poscar', fcc_poscar)
print(new_system)

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   2.025   0.000   2.025
      3       1   0.000   2.025   2.025

3.2. Load a database prototype

The potentials database stores structure information for many crystal prototypes, i.e. space group + wykoff sites without elemental information. Crystals can easily be created from this by loading the prototype and specifying the element(s) and the necessary lattice constants.

[13]:

potdb = am.library.Database()

[14]:

print(potdb.local_database)

database style local at C:\Users\lmh1\Documents\library

[15]:

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

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.3. Load a database crystal

The potentials database also contains relaxed crystal structures for the hosted interatomic potentials. If you know which potential you want to use, then you can load the appropriate relaxed structure.

[16]:

new_system = am.load('crystal', family='A1--Cu--fcc', potential_LAMMPS_id='2003--Zope-R-R--Al--LAMMPS--ipr1')
print(new_system)

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

4. System Manipulations

The System class was defined to make it easy for users to manipulate systems and atomic properties. Additionally, there are a few System class methods that assist with some common manipulations.