Introduction to atomman: Settings and Library
Lucas M. Hale, lucas.hale@nist.gov, Materials Science and Engineering Division, NIST.
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.10
Notebook executed on 2023-07-28
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
100%|██████████████████████████████████████████████████████████████████████████████████| 19/19 [00:00<00:00, 79.23it/s]
Found 19 matching crystal_prototype records in remote library
- 0 remote records are new
[3]:
| name | key | id | commonname | prototype | pearson | strukturbericht | sg_number | sg_hm | sg_schoenflies | crystalfamily | natypes | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | A1--Cu--fcc | d30980ad-ae18-425d-84cb-abf08577bdc8 | A1--Cu--fcc | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | rock salt | NaCl | cF8 | B1 | 225 | F m -3 m | Oh^5 | cubic | 2 |
| 12 | B2--CsCl | 7398b231-fd55-4378-b6b2-6607262d3090 | B2--CsCl | 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 | 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 | 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 | 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 | 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 | 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 | 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']]
100%|████████████████████████████████████████████████████████████████████████████████| 130/130 [00:11<00:00, 10.17it/s]
[5]:
| potential_LAMMPS_id | a | cohesive_energy | |
|---|---|---|---|
| 36 | 2012--Norman-G-E--Au--LAMMPS--ipr1 | 7.011749 | -5.662467 |
| 117 | 2012--Norman-G-E--Au--LAMMPS--ipr1 | 4.068501 | -4.299363 |
| 20 | 2012--Norman-G-E--Au--LAMMPS--ipr1 | 4.068501 | -4.299363 |
| 53 | 2012--Norman-G-E--Au--LAMMPS--ipr1 | 4.068501 | -4.299363 |
| 63 | 2004--Zhou-X-W--Cu-Ag-Au--LAMMPS--ipr2 | 4.080053 | -3.930005 |
| ... | ... | ... | ... |
| 31 | 2020--Starikov-S--Si-Au-Al--LAMMPS--ipr2 | 7.842853 | -0.835714 |
| 11 | 2020--Starikov-S--Si-Au-Al--LAMMPS--ipr2 | 7.842853 | -0.835714 |
| 59 | 2012--Norman-G-E--Au--LAMMPS--ipr1 | 6.210659 | -0.613333 |
| 116 | 2012--Norman-G-E--Au--LAMMPS--ipr1 | 6.210659 | -0.613333 |
| 17 | 2012--Norman-G-E--Au--LAMMPS--ipr1 | 6.210659 | -0.613333 |
130 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.