potentials-library

Complete library directory for the potentials Python package, i.e. contains copies of records from potentials.nist.gov

https://github.com/lmhale99/potentials-library

Repository

Complete library directory for the potentials Python package, i.e. contains copies of records from potentials.nist.gov

README.rst

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

.. code-block:: python

    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.


.. _potentials: https://github.com/usnistgov/potentials
.. _atomman: https://www.ctcms.nist.gov/potentials/atomman
.. _iprPy: https://www.ctcms.nist.gov/potentials/iprPy 

GitHub Events