Introduction to atomman: prototype loading
Lucas M. Hale, lucas.hale@nist.gov, Materials Science and Engineering Division, NIST.
1. Introduction
The crystal_prototype records found in the NIST Interatomic Potentials Repository database (https://potentials.nist.gov/) define a number of unit cells for standard crystal prototypes. The ‘prototype’ load option allows Systems to be constructed based on the information in these records. The information can be loaded either from a local copy of the database or the remote database.
Updated version 1.4.0. Query parameters and database options updated to be in line with potentials version 0.3.0.
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. atomman.load(‘prototype’)
Accesses the potentials database to retrieve a crystal_prototype record and generate a unit cell System based on it.
Query parameters - name (str or list, optional) Record names to search for. These should be the same values as id. - 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.
Modification parameters
a (float, optional) The a lattice parameter to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.
b (float, optional) The b lattice parameter to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.
c (float, optional) The c lattice parameter to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.
alpha (float, optional) The alpha lattice angle to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.
beta (float, optional) The beta lattice angle to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.
gamma (gamma, optional) The alpha lattice angle to scale the prototype by. Can only be given if it is a unique lattice parameter for the prototype’s crystal family, and if all other unique lattice parameters are given.
symbols (tuple, optional) Allows the list of element symbols to be assigned during loading.
Database option parameters
database (atomman.library.Database, optional) A pre-defined Database object to use. If not given, will initialize a new Database object. Passing in a database can save time if multiple calls are made for the same record type.
localpath (str, optional) The local library path to use when initializing a new Database. IF not given, will use the default localpath. Ignored if database is given.
local (bool, optional) Indicates if the Database object is to look for local records. Default is True. Ignored if database is given.
remote (bool, optional) Indicates if the Database object is to look for remote records. Default is True. Ignored if database is given.
prompt (bool, optional) If prompt=True (default) then a screen input will ask for a selection if multiple matching potentials are found. If prompt=False, then an error will be thrown if multiple matches are found.
refresh_cache (bool, optional) If the local database is of style “local”, indicates if the metadata cache file is to be refreshed. If False, metadata for new records will be added but the old record metadata fields will not be updated. If True, then the metadata for all records will be regenerated, which is needed to update the metadata for modified records.
verbose (bool, optional) If True, info messages will be printed during operations. Default value is False.
Returns
system (atomman.System) The system object generated from the crystal prototype.
2.1. Query parameters
Prototypes can be selected based on a number of different ids.
[2]:
ucell = am.load("prototype", id='A1--Cu--fcc')
print(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 = 4
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.000 0.500 0.500
2 1 0.500 0.000 0.500
3 1 0.500 0.500 0.000
Or, if you give no extra keyword arguments you will get a prompt selection of all prototypes in the database.
[3]:
ucell = am.load("prototype")
print(ucell)
Multiple matching record retrieved from local
1 A1--Cu--fcc
2 A15--Cr3Si
3 A15--beta-W
4 A2--W--bcc
5 A3'--alpha-La--double-hcp
6 A3--Mg--hcp
7 A4--C--dc
8 A5--beta-Sn
9 A6--In--bct
10 A7--alpha-As
11 Ah--alpha-Po--sc
12 B1--NaCl--rock-salt
13 B2--CsCl
14 B3--ZnS--cubic-zinc-blende
15 C1--CaF2--fluorite
16 D0_3--BiF3
17 L1_0--AuCu
18 L1_2--AuCu3
19 L2_1--AlCu2Mn--heusler
Please select one: 2
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 = 2
symbols = (None, 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.500
2 2 0.250 0.000 0.500
3 2 0.750 0.000 0.500
4 2 0.500 0.250 0.000
5 2 0.500 0.750 0.000
6 2 0.000 0.500 0.250
7 2 0.000 0.500 0.750
2.2. Modification parameters
The nature of a crystal prototype is that it is stripped of element-specific information: there are no elements/symbols assigned to the atom types and all lattice constants are scaled based on a=1 and the “ideal” ratios for the reference crystal. Because of this, the lattice constants and symbols can be set within the load method.
NOTE: The allowed lattice constants for this method depend on the independent lattice constants associated with the prototype’s crystal family (cubic, hexagonal, etc.). Either all or none of the independent lattice constants can be set during load.
[4]:
ucell = am.load("prototype", 'A1--Cu--fcc', a=4.05, symbols='Al')
print(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
[5]:
ucell = am.load("prototype", 'A3--Mg--hcp', a=2.95, c=4.70, symbols='Ti')
print(ucell)
avect = [ 2.950, 0.000, 0.000]
bvect = [-1.475, 2.555, 0.000]
cvect = [ 0.000, 0.000, 4.700]
origin = [ 0.000, 0.000, 0.000]
natoms = 2
natypes = 1
symbols = ('Ti',)
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 1.703 2.350