Introduction to atomman: Settings and Library

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

Disclaimers

1. Introduction

The atomman package extends the settings and Database tools provided by the potentials package. The settings options allow for the default values of certain parameters to be changed and saved for later sessions. Database provides a single class for interacting with records in the NIST Interatomic Potentials Repository’s database.

Updated version 1.4.0: Major changes in the settings and library behavior due to potentials version 0.3.0.

Library Imports

[1]:
# Standard libraries
from pathlib import Path
import datetime

# https://github.com/usnistgov/atomman
import atomman as am

# 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

2. Settings

Many optional settings can be set and saved for later sessions using atomman.settings. The settings in atomman are identical to those found in potentials.settings meaning that changing the settings in either package will affect the behavior of the other. See the potentials.settings documentation for more details.

3. Database interface

The atomman.library.Database class extends potentials.Database to provide support for crystal structure references in addition to the potentials references. The Database class is used by atomman.load() for ‘prototype’, ‘crystal’ and ‘dft_reference’ styles and by atomman.load_lammps_potential. It can also be directly accessed and used to explore the database for more involved investigations.

See the potentials.Database documentation for information about initializing a Database object and the generic record query methods.

[2]:
# Load a Database with default settings
potdb = am.library.Database(local_name='master')

3.1. Crystal prototypes

Crystal prototype records provide atomic coordinates for a crystal prototype, i.e. a combination of space group and lattice sites without any species-specific information.

3.1.1. get_crystal_prototypes, get_crystal_prototype, and download_crystal_prototypes

These methods extend the generic record methods (see the potentials.Database documentation) by including the following record-specific query parameters

  • id (str or list, optional) Prototype ID(s) to search for. These are unique identifiers for each prototype based on comm.

  • key (str or list, optional) UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

  • commonname (str or list, optional) Common name(s) to limit the search by.

  • prototype (str or list, optional) Prototype identifying composition(s) to limit the search by.

  • pearson (str or list, optional) The Pearson symbol(s) to limit the search by.

  • strukturbericht (str or list, optional) The strukturbericht identifier(s) to limit the search by.

  • sg_number (int or list, optional) The space group number(s) to limit the search by.

  • sg_hm (str or list, optional) The space group Hermann-Maguin identifier(s) to limit the search by.

  • sg_schoenflies (str or list, optional) The space group Schoenflies identifier(s) to limit the search by.

  • crystalfamily (str, optional) The crystal system family to limit the search by.

  • natypes (int, optional) The number(s) of unique atom types to limit the search by.

[3]:
prototypes, prototypes_df = potdb.get_crystal_prototypes(return_df=True, verbose=True)
prototypes_df
Found 19 matching crystal_prototype records in local library
[3]:
name key id url commonname prototype pearson strukturbericht sg_number sg_hm sg_schoenflies crystalfamily natypes
0 A1--Cu--fcc d30980ad-ae18-425d-84cb-abf08577bdc8 A1--Cu--fcc https://potentials.nist.gov/pid/rest/local/pot... face-centered cubic Cu cF4 A1 225 F m -3 m Oh^5 cubic 1
1 A15--Cr3Si f4101896-1e17-4736-a4d1-308b8934e8ce A15--Cr3Si https://potentials.nist.gov/pid/rest/local/pot... beta-tungsten Cr3Si cP8 A15 223 P m -3 n Oh^3 cubic 2
2 A15--beta-W e0126715-c7db-4d79-be80-707c572bebd6 A15--beta-W https://potentials.nist.gov/pid/rest/local/pot... beta-tungsten b-W cP8 A15 223 P m -3 n Oh^3 cubic 1
3 A2--W--bcc bc13827d-e1e6-4d70-8c3a-59399ad78b0f A2--W--bcc https://potentials.nist.gov/pid/rest/local/pot... body-centered cubic W cI2 A2 229 I m -3 m Oh^9 cubic 1
4 A3'--alpha-La--double-hcp 154d1a2b-04da-4477-8962-a0ca0c17c8fc A3'--alpha-La--double-hcp https://potentials.nist.gov/pid/rest/local/pot... double hcp La hP4 A3' 194 P 6_3/m m c D6h^4 hexagonal 1
5 A3--Mg--hcp 4dab7fbb-108a-425e-8adb-d55de7b1134b A3--Mg--hcp https://potentials.nist.gov/pid/rest/local/pot... hexagonal close-packed Mg hP2 A3 194 P 6_3/m m c D6h^4 hexagonal 1
6 A4--C--dc 12654c83-c153-4b58-8805-f6dce43b7842 A4--C--dc https://potentials.nist.gov/pid/rest/local/pot... diamond cubic C cF8 A4 227 F d -3 m Oh^7 cubic 1
7 A5--beta-Sn 821526c5-561e-4f09-8a04-680419dc1495 A5--beta-Sn https://potentials.nist.gov/pid/rest/local/pot... white tin b-Sn tI4 A5 141 I 4_1/a m d D4h^19 tetragonal 1
8 A6--In--bct 76cbf2c1-fa86-41c4-85ae-c24f55c9f13a A6--In--bct https://potentials.nist.gov/pid/rest/local/pot... body-centered tetragonal In tI2 A6 139 I 4/m m m D4h^17 tetragonal 1
9 A7--alpha-As c1e15cf8-6998-40ce-afbd-0b1cb6271a1f A7--alpha-As https://potentials.nist.gov/pid/rest/local/pot... alpha As a-As hR6 A7 166 R -3 m D3d^5 hexagonal 1
10 Ah--alpha-Po--sc ceb6d7cc-b20e-4878-8b2b-1e62185d16af Ah--alpha-Po--sc https://potentials.nist.gov/pid/rest/local/pot... simple cubic a-Po cP1 Ah 221 P m -3 m Oh^1 cubic 1
11 B1--NaCl--rock-salt 133ca871-c927-4073-ae46-b8a27e035f4b B1--NaCl--rock-salt https://potentials.nist.gov/pid/rest/local/pot... rock salt NaCl cF8 B1 225 F m -3 m Oh^5 cubic 2
12 B2--CsCl 7398b231-fd55-4378-b6b2-6607262d3090 B2--CsCl https://potentials.nist.gov/pid/rest/local/pot... cesium chloride CsCl cP2 B2 221 P m -3 m Oh^1 cubic 2
13 B3--ZnS--cubic-zinc-blende ce517a32-6bca-47d0-82a2-2ee48956cff9 B3--ZnS--cubic-zinc-blende https://potentials.nist.gov/pid/rest/local/pot... cubic zinc-blende c-ZnS cF8 B3 216 F -4 3 m Td^2 cubic 2
14 C1--CaF2--fluorite 74171ba0-6605-4956-b8d5-0059672ee7e2 C1--CaF2--fluorite https://potentials.nist.gov/pid/rest/local/pot... fluorite CaF2 cF12 C1 225 F m -3 m Oh^5 cubic 2
15 D0_3--BiF3 8a2eb4b8-1302-46d9-992d-4296c227d966 D0_3--BiF3 https://potentials.nist.gov/pid/rest/local/pot... BiF3 BiF3 cF16 D0_3 225 F m -3 m Oh^5 cubic 2
16 L1_0--AuCu f7b8d5d9-b0eb-401a-9cc3-038170e3ac1c L1_0--AuCu https://potentials.nist.gov/pid/rest/local/pot... AuCu AuCu tP2 L1_0 123 P 4/m m m D4h^1 tetragonal 2
17 L1_2--AuCu3 942ce385-85ab-4cb9-8adc-4bdaaf145831 L1_2--AuCu3 https://potentials.nist.gov/pid/rest/local/pot... AuCu3 AuCu3 cP4 L1_2 221 P m -3 m Oh^1 cubic 2
18 L2_1--AlCu2Mn--heusler 0fb6d590-5ce5-4476-a1bf-7130f96f2af1 L2_1--AlCu2Mn--heusler https://potentials.nist.gov/pid/rest/local/pot... heusler AlCu2Mn cF16 L2_1 225 F m -3 m Oh^5 cubic 3

3.1.2. CrystalPrototype objects

The CrystalPrototype Record objects is a subclass of potentials.Record, and therefore features all of the common Record attributes and methods. CrystalPrototype additionally has attributes for each of the query term listed above, and ucell, which returns the unit cell of the prototype as an atomman.System. Note that the ucell lacks symbol information and the a lattice parameter is by default set to 1.

[4]:
prototype = prototypes[6]

print('name', prototype.name)
print('id', prototype.id)
print('key', prototype.key)
print('commonname', prototype.commonname)
print('prototype', prototype.prototype)
print('pearson', prototype.pearson)
print('strukturbericht', prototype.strukturbericht)
print('sg_number', prototype.sg_number)
print('sg_hm', prototype.sg_hm)
print('sg_schoenflies', prototype.sg_schoenflies)
print('crystalfamily', prototype.crystalfamily)
print('natypes', prototype.natypes)
print()
print('ucell:')
print(prototype.ucell)
name A4--C--dc
id A4--C--dc
key 12654c83-c153-4b58-8805-f6dce43b7842
commonname diamond cubic
prototype C
pearson cF8
strukturbericht A4
sg_number 227
sg_hm F d -3 m
sg_schoenflies Oh^7
crystalfamily cubic
natypes 1

ucell:
avect =  [ 1.000,  0.000,  0.000]
bvect =  [ 0.000,  1.000,  0.000]
cvect =  [ 0.000,  0.000,  1.000]
origin = [ 0.000,  0.000,  0.000]
natoms = 8
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   0.500   0.500   0.000
      2       1   0.500   0.000   0.500
      3       1   0.000   0.500   0.500
      4       1   0.250   0.250   0.250
      5       1   0.250   0.750   0.750
      6       1   0.750   0.250   0.750
      7       1   0.750   0.750   0.250

3.2. Relaxed crystals

RelaxedCrystal records provide crystal structure information obtained by relaxing crystal prototypes and DFT reference structures using the different potentials in the NIST Interatomic Potentials Repository at 0 K. If you are working with a particular interatomic potential, this provides a convenient means to obtain the already relaxed crystal structure for that potential.

3.2.1. get_relaxed_crystals, get_relaxed_crystal and download_relaxed_crystals

These methods extend the generic record methods (see the potentials.Database documentation) by including the following record-specific query parameters

  • key (str or list, optional) UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

  • method (str or list or None, optional) The relaxation method used. Allowed values are dynamic, static and box. Default value is dynamic (the most rigorous relaxation method). All will be loaded if set to None.

  • standing (str or list or None, optional) “good” records are the unique crystals found with the most rigorous relaxation, and with known prototypes over DFT structures. “bad” are records filtered out, usually for being duplicates. Default value is “good”. All will be loaded if set to None.

  • family (str or atomman.library.CrystalPrototype or list, optional) The crystal family associated with the relaxed crystal - either crystal prototype name or MP/OQMD database entry name.

  • parent_key (str or list, optional) The UUID4 key(s) assigned to the calculation that the record is based on.

  • potential_LAMMPS_id (str or list, optional) The id for a LAMMPS implemented potential to limit the search by.

  • potential_LAMMPS_key (str or list, optional) The UUID4 for a LAMMPS implemented potential to limit the search by.

  • potential_id (str or list, optional) The id for a potential to limit the search by.

  • potential_key (str or list, optional) The UUID4 for a potential to limit the search by.

  • symbols (str or list, optional) Element symbols in the crystal to limit the search by.

  • natypes (int or list, optional) The number(s) of unique atom types to limit the search by.

  • natoms (int or list, optional) The number of unique atoms in the crystal’s unit cell to limit the search by.

NOTE #1: The default values of method and standing greatly limit the records being searched. The dynamic relaxation method is the most rigorous, but it also seems to occasionally predict some expected stable structures, like hcp, to transform to unstable structures. In that case, changing the value of method may provide the results you are looking for. NOTE #2: The large number of relaxed_crystal records in the database means that some searches can be very slow. It is recommended to always make the initial search as specific as possible.

[5]:
# Fetch all records for fcc gold
fcc_gold, fcc_gold_df = potdb.get_relaxed_crystals(family='A1--Cu--fcc', symbols='Au', return_df=True)

fcc_gold_df.sort_values('cohesive_energy')[['potential_LAMMPS_id', 'a', 'cohesive_energy']]
[5]:
potential_LAMMPS_id a cohesive_energy
37 2012--Norman-G-E--Au--LAMMPS--ipr1 7.011749 -5.662467
119 2012--Norman-G-E--Au--LAMMPS--ipr1 4.068501 -4.299363
20 2012--Norman-G-E--Au--LAMMPS--ipr1 4.068501 -4.299363
54 2012--Norman-G-E--Au--LAMMPS--ipr1 4.068501 -4.299363
52 EAM_Dynamo_ZhouJohnsonWadley_2004NISTretabulat... 4.080053 -3.930005
... ... ... ...
11 2020--Starikov-S--Si-Au-Al--LAMMPS--ipr2 7.842853 -0.835714
24 2020--Starikov-S--Si-Au-Al--LAMMPS--ipr1 7.842853 -0.835714
60 2012--Norman-G-E--Au--LAMMPS--ipr1 6.210659 -0.613333
118 2012--Norman-G-E--Au--LAMMPS--ipr1 6.210659 -0.613333
17 2012--Norman-G-E--Au--LAMMPS--ipr1 6.210659 -0.613333

133 rows × 3 columns

3.2.2. RelaxedCrystal objects

Just like CrystalPrototype objects, RelaxedCrystal objects have attributes for all of the query terms plus ucell.

[6]:
print(fcc_gold[0].potential_LAMMPS_id)
print(fcc_gold[0].ucell)
EAM_Dynamo_Olsson_2010_Au__MO_228280943430_000
avect =  [ 4.080,  0.000,  0.000]
bvect =  [ 0.000,  4.080,  0.000]
cvect =  [ 0.000,  0.000,  4.080]
origin = [ 0.000,  0.000,  0.000]
natoms = 4
natypes = 1
symbols = ('Au',)
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.040   2.040
      2       1   2.040   0.000   2.040
      3       1   2.040   2.040   0.000

3.3. DFT reference crystals

Reference crystal structures can also be searched for both within the local/NIST database and within the source databases.

3.3.1. get_reference_crystals, get_reference_crystal, download_reference_crystal

These methods extend the generic record methods (see the potentials.Database documentation) by including the following record-specific query parameters

  • id (str or list, optional) The record id(s) to parse by. For reference crystal records, the id are letters identifying the source database “mp-”, “mvc-”, or “oqmd-”, followed by the source database’s identification number.

  • key (str or list, optional) UUID4 key(s) to search for. Each entry has a unique random-generated UUID4 key.

  • sourcename (str or list, optional) The full name of source DFT databases to limit the search by. “Materials Project” or “Open Quantum Materials Database”.

  • sourcelink (str or list, optional) The web link of the source DFT databases to limit the search by.

  • crystalfamily (str or list, optional) The crystal system families to limit the search by.

  • composition (str or list, optional) The reduced compositions of the structures to limit the search by. Element symbols are sorted alphabetically.

  • symbols (str or list, optional) Element symbols in the crystal to limit the search by.

  • natoms (int or list, optional) The number of unique atoms in the crystal’s unit cell to limit the search by.

  • natypes (int or list, optional) The number(s) of unique atom types to limit the search by.

NOTE: These methods only return the reference records that are being stored locally or at potentials.nist.gov and do not search the parent databases.

3.3.2. fetch_reference_crystal, fetch_mp_crystals, fetch_mp_crystal, fetch_oqmd_crystal

fetch_mp_crystals and fetch_mp_crystal retrieve all or one matching record from the Materials Project based on id. fetch_oqmd_crystal retrieves one record from OQMD based on id.

fetch_reference_crystal first calls get_reference_crystal, and if that fails to find a match, calls either fetch_mp_crystal or fetch_oqmd_crystal based on a given id.

[7]:
api_key = 'C:/Users/lmh1/Documents/Materials Project/API key.txt'
ref = potdb.fetch_reference_crystal(id = 'mp-81', api_key=api_key, verbose=True)
Matching record retrieved from local

3.3.3. ReferenceCrystal objects

Same as the others, the ReferenceCrystal objects have attributes for the query terms and ucell.

[8]:
print(ref.ucell)
avect =  [ 4.171,  0.000,  0.000]
bvect =  [ 0.000,  4.171,  0.000]
cvect =  [ 0.000,  0.000,  4.171]
origin = [ 0.000,  0.000,  0.000]
natoms = 4
natypes = 1
symbols = ('Au',)
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.086   2.086
      2       1   2.086   0.000   2.086
      3       1   2.086   2.086   0.000

3.3.4. save_reference_crystal

If you fetch a reference crystal from the parent database, you can then save it to the local database using save_reference_crystal.