potentials-library

Introduction

This repository provides a regular archival copy of the records from the database at https://potentials.nist.gov. The associated records provide the listing information for the potentials hosted by the NIST Interatomic Potentials Repository, as well as reference data used and generated by the Repository. The purpose of this archive is to allow heavy users to easily download a personal copy of the NIST repository and be able to keep it updated using git commands.

IMPORTANT SETUP INFO!

Some of the newer machine-learning potentials have parameter files larger than what github likes. Because of this, there are some parameter files that will need to be unzipped and extracted to the potential's directory after you download the repository if you wish to use them. These files are

• potential_LAMMPS/2022--Erhard-L-C--Si-O--LAMMPS--ipr1/silica_gap.xml.sparseX.GAP_2021_4_19_120_7_32_55_3364.zip
• potential_LAMMPS/2022--Erhard-L-C--Si-O--LAMMPS--ipr1/silica_gap.xml.sparseX.GAP_2021_4_19_120_7_32_55_3365.zip

Python APIs

Once downloaded, the records in this git repository can be interacted with using the Python packages created by the NIST interatomic Potentials Repository project

• potentials provides the core database interactions allowing for records to be explored both from the downloaded local copy as well as from https://potentials.nist.gov. The package is designed to interact with the records in the database related to interatomic potentials.
• atomman contains tools for representing atomic configurations and for creating Python scripts that represent calculation methodologies built around LAMMPS simulations. In terms of the database interactions, atomman inherits all of the features of potentials and adds in the ability to interact with records representing atomic configurations.
• iprPy collects the complete calculation methodologies used by the NIST repository for computing basic materials properties, as well as workflow tools for running the calculations in high-throughput. The iprPy package extends the record interpretation to include input parameter sets for defect structures, and calculation results and metadata.

Interfacing the Python APIs with the library

All three of the Python packages listed above share the same settings file, meaning that changes to the settings of one package will be reflected in the others.

Once you have downloaded/cloned the library, you can set it as the default local location for the potentials and atomman packages to search for records using the following commands

import potentials
potentials.settings.set_local_database(PATH)

Here, PATH is the local path to the directory where this git repository is located.

Library Contents

potentials records

These are the record styles in the library that are supported by potentials, atomman and iprPy.

• Citation contains the citation information associated with the interatomic potentials stored in the database. If the citation has a DOI, then the entry is named using the DOI with any forward slashes replaced with underscores to be a valid file name. If the citation does not have a DOI, then an ID is generated based on the content creator(s) and year of creation.
• Potential contains records that are used to generate the listings for interatomic potentials found on the NIST Interatomic Potentials Repository. These records collect citation information, usage notes, the different available implementations, and specify the URLs where any associated parameter files can be downloaded. The records are uniquely named based on citation/creation year, authors, and included interactions.
• potential_LAMMPS contains records that allow the potentials package to generate LAMMPS command lines for a specific LAMMPS-compatible interatomic potential. These records also contain the download URLs for any associated parameter files. The records are uniquely named based on citation/creation year, first author, included interactions, format, and version number.
• potential_LAMMPS_KIM contains records collecting metadata information about openKIM models so that the potentials package can integrate installed KIM models in with the native LAMMPS potentials. The records are named based on the unique KIM shortcode id. Each record links the KIM model to one or more Potential records and lists all known full KIM ids associated with the different versions of the model.

atomman records

These are the record styles in the library that are supported by atomman and iprPy.

• crystal_prototype contains records that detail crystal prototypes, i.e. crystal structures that have been generalized by excluding composition and absolute dimensions. These are used by the atomman Python package for generating crystal structures. The records are uniquely named through a combination of the available associated Strukturbericht symbol, compositional prototype and/or a common descriptor.
• relaxed_crystal HAVE BEEN REMOVED!!! The relaxed_crystal records describe potential-specific relaxed crystals. These have been removed from this library repository, but can still be found at https://potentials.nist.gov. The large number of relaxed_crystal records was causing issues with git, accessing the records locally was prohibitively too slow, and a large number of such records are routinely added/updated. Records can be downloaded from there for offline operations. If you plan on using a large number of relaxed_crystal records, it is recommended to use a MongoDB instance for performance reasons.

iprPy records

These are the record styles in the library that are supported by only iprPy.

• dislocation contains records that provide input parameter sets for iprPy calculations to generate straight dislocations for common dislocation types. The records are uniquely named based on crystal prototype, Burgers vector, character, and slip plane family.
• free_surface contains records that provide input parameter sets for iprPy calculations to generate atomic systems with an ideally sliced free surface along a crystal plane. The records are uniquely named based on crystal prototype and surface plane family.
• grain_boundary contains records that provide input parameter sets for iprPy calculations to generate grain boundary atomic configurations. The records are uniquely named based on crystal protoype and grain boundary descriptors.
• point_defect contains records that provide input parameter sets for iprPy calculations to generate atomic systems containing a point defect or point defect cluster. The records are uniquely named based on crystal prototype and defect type.
• stacking_fault contains records that provide input parameter sets for iprPy calculations to generate atomic systems containing generalized stacking faults along a slip plane. The records are uniquely named based on crystal prototype and slip plane family, with "sf" added at the end to differentiate them from the free surface records.

Other content

• related-interactions.json lists the element and binary model interactions for the NIST-hosted potentials and groups the related interaction models together. Interaction models are considered to be "related" if predictions from the two potentials are (nearly) identical for atomic configurations typically explored by atomistic calculations. This characterization of "related" is not a robust definition as there is some ambiguity if purposeful changes to an old potential constitute an entirely new model or not. The remote version of this file can be obtained at https://www.ctcms.nist.gov/potentials/site/related-interactions.json.