doc/html/.doctrees/nbsphinx/tutorial/1.5._Settings_and_databases.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to atomman: Settings and Library\n",
    "\n",
    "__Lucas M. Hale__, [lucas.hale@nist.gov](mailto:lucas.hale@nist.gov?Subject=ipr-demo), _Materials Science and Engineering Division, NIST_.\n",
    "    \n",
    "[Disclaimers](http://www.nist.gov/public_affairs/disclaimer.cfm) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Introduction<a id='section1'></a>\n",
    "\n",
    "The atomman package extends the settings and Database tools provided by the [potentials package](https://github.com/usnistgov/potentials).  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.\n",
    "\n",
    "*Updated version 1.4.0*: Major changes in the settings and library behavior due to potentials version 0.3.0."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Library Imports**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "atomman version = 1.4.4\n",
      "Notebook executed on 2022-03-31\n"
     ]
    }
   ],
   "source": [
    "# Standard libraries\n",
    "from pathlib import Path\n",
    "import datetime       \n",
    "\n",
    "# https://github.com/usnistgov/atomman\n",
    "import atomman as am            \n",
    "\n",
    "# Show atomman version\n",
    "print('atomman version =', am.__version__)\n",
    "\n",
    "# Show date of Notebook execution\n",
    "print('Notebook executed on', datetime.date.today())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Settings<a id='section2'></a>\n",
    "\n",
    "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](https://github.com/lmhale99/potentials/blob/master/doc/3.%20Change%20Default%20Settings.html) meaning that changing the settings in either package will affect the behavior of the other.  See the [potentials.settings](https://github.com/lmhale99/potentials/blob/master/doc/3.%20Change%20Default%20Settings.html) documentation for more details."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Database interface <a id='section3'></a>\n",
    "\n",
    "The atomman.library.Database class extends [potentials.Database](https://github.com/lmhale99/potentials/blob/master/doc/4.%20Database%20Class.html) to provide support for crystal structure references in addition to the potentials references.  The Database class is used by atomman.load() for ['prototype'](1.4.10._prototype_loading.html), ['crystal'](1.4.11._crystal_loading.html) and ['dft_reference'](1.4.12._DFT_reference_crystal_loading.html) styles and by [atomman.load_lammps_potential](2.1._Potential_class.html).  It can also be directly accessed and used to explore the database for more involved investigations.\n",
    "\n",
    "See the [potentials.Database documentation](https://github.com/lmhale99/potentials/blob/master/doc/4.%20Database%20Class.html) for information about initializing a Database object and the generic record query methods. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load a Database with default settings\n",
    "potdb = am.library.Database()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.1. Crystal prototypes\n",
    "\n",
    "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.    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.1.1. get_crystal_prototypes, get_crystal_prototype, and download_crystal_prototypes\n",
    "\n",
    "These methods extend the generic record methods (see the [potentials.Database documentation](https://github.com/lmhale99/potentials/blob/master/doc/4.%20Database%20Class.html)) by including the following record-specific query parameters\n",
    "\n",
    "- __id__ (*str or list, optional*) Prototype ID(s) to search for.  These are unique identifiers for each prototype based on comm.\n",
    "- __key__ (*str or list, optional*) UUID4 key(s) to search for.  Each entry has a unique random-generated UUID4 key.\n",
    "- __commonname__ (*str or list, optional*) Common name(s) to limit the search by.\n",
    "- __prototype__ (*str or list, optional*) Prototype identifying composition(s) to limit the search by.\n",
    "- __pearson__ (*str or list, optional*) The Pearson symbol(s) to limit the search by.\n",
    "- __strukturbericht__ (*str or list, optional*) The strukturbericht identifier(s) to limit the search by.\n",
    "- __sg_number__ (*int or list, optional*) The space group number(s) to limit the search by.\n",
    "- __sg_hm__ (*str or list, optional*) The space group Hermann-Maguin identifier(s) to limit the search by.\n",
    "- __sg_schoenflies__ (*str or list, optional*) The space group Schoenflies identifier(s) to limit the search by.\n",
    "- __crystalfamily__ (*str, optional*) The crystal system family to limit the search by. \n",
    "- __natypes__ (*int, optional*) The number(s) of unique atom types to limit the search by.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Found 19 matching crystal_prototype records in local library\n",
      "Found 19 matching crystal_prototype records in remote library\n",
      " - 0 remote records are new\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>name</th>\n",
       "      <th>key</th>\n",
       "      <th>id</th>\n",
       "      <th>commonname</th>\n",
       "      <th>prototype</th>\n",
       "      <th>pearson</th>\n",
       "      <th>strukturbericht</th>\n",
       "      <th>sg_number</th>\n",
       "      <th>sg_hm</th>\n",
       "      <th>sg_schoenflies</th>\n",
       "      <th>crystalfamily</th>\n",
       "      <th>natypes</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>A1--Cu--fcc</td>\n",
       "      <td>d30980ad-ae18-425d-84cb-abf08577bdc8</td>\n",
       "      <td>A1--Cu--fcc</td>\n",
       "      <td>face-centered cubic</td>\n",
       "      <td>Cu</td>\n",
       "      <td>cF4</td>\n",
       "      <td>A1</td>\n",
       "      <td>225</td>\n",
       "      <td>F m -3 m</td>\n",
       "      <td>Oh^5</td>\n",
       "      <td>cubic</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>A15--Cr3Si</td>\n",
       "      <td>f4101896-1e17-4736-a4d1-308b8934e8ce</td>\n",
       "      <td>A15--Cr3Si</td>\n",
       "      <td>beta-tungsten</td>\n",
       "      <td>Cr3Si</td>\n",
       "      <td>cP8</td>\n",
       "      <td>A15</td>\n",
       "      <td>223</td>\n",
       "      <td>P m -3 n</td>\n",
       "      <td>Oh^3</td>\n",
       "      <td>cubic</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>A15--beta-W</td>\n",
       "      <td>e0126715-c7db-4d79-be80-707c572bebd6</td>\n",
       "      <td>A15--beta-W</td>\n",
       "      <td>beta-tungsten</td>\n",
       "      <td>b-W</td>\n",
       "      <td>cP8</td>\n",
       "      <td>A15</td>\n",
       "      <td>223</td>\n",
       "      <td>P m -3 n</td>\n",
       "      <td>Oh^3</td>\n",
       "      <td>cubic</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>A2--W--bcc</td>\n",
       "      <td>bc13827d-e1e6-4d70-8c3a-59399ad78b0f</td>\n",
       "      <td>A2--W--bcc</td>\n",
       "      <td>body-centered cubic</td>\n",
       "      <td>W</td>\n",
       "      <td>cI2</td>\n",
       "      <td>A2</td>\n",
       "      <td>229</td>\n",
       "      <td>I m -3 m</td>\n",
       "      <td>Oh^9</td>\n",
       "      <td>cubic</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>A3'--alpha-La--double-hcp</td>\n",
       "      <td>154d1a2b-04da-4477-8962-a0ca0c17c8fc</td>\n",
       "      <td>A3'--alpha-La--double-hcp</td>\n",
       "      <td>double hcp</td>\n",
       "      <td>La</td>\n",
       "      <td>hP4</td>\n",
       "      <td>A3'</td>\n",
       "      <td>194</td>\n",
       "      <td>P 6_3/m m c</td>\n",
       "      <td>D6h^4</td>\n",
       "      <td>hexagonal</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>A3--Mg--hcp</td>\n",
       "      <td>4dab7fbb-108a-425e-8adb-d55de7b1134b</td>\n",
       "      <td>A3--Mg--hcp</td>\n",
       "      <td>hexagonal close-packed</td>\n",
       "      <td>Mg</td>\n",
       "      <td>hP2</td>\n",
       "      <td>A3</td>\n",
       "      <td>194</td>\n",
       "      <td>P 6_3/m m c</td>\n",
       "      <td>D6h^4</td>\n",
       "      <td>hexagonal</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>A4--C--dc</td>\n",
       "      <td>12654c83-c153-4b58-8805-f6dce43b7842</td>\n",
       "      <td>A4--C--dc</td>\n",
       "      <td>diamond cubic</td>\n",
       "      <td>C</td>\n",
       "      <td>cF8</td>\n",
       "      <td>A4</td>\n",
       "      <td>227</td>\n",
       "      <td>F d -3 m</td>\n",
       "      <td>Oh^7</td>\n",
       "      <td>cubic</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>A5--beta-Sn</td>\n",
       "      <td>821526c5-561e-4f09-8a04-680419dc1495</td>\n",
       "      <td>A5--beta-Sn</td>\n",
       "      <td>white tin</td>\n",
       "      <td>b-Sn</td>\n",
       "      <td>tI4</td>\n",
       "      <td>A5</td>\n",
       "      <td>141</td>\n",
       "      <td>I 4_1/a m d</td>\n",
       "      <td>D4h^19</td>\n",
       "      <td>tetragonal</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>A6--In--bct</td>\n",
       "      <td>76cbf2c1-fa86-41c4-85ae-c24f55c9f13a</td>\n",
       "      <td>A6--In--bct</td>\n",
       "      <td>body-centered tetragonal</td>\n",
       "      <td>In</td>\n",
       "      <td>tI2</td>\n",
       "      <td>A6</td>\n",
       "      <td>139</td>\n",
       "      <td>I 4/m m m</td>\n",
       "      <td>D4h^17</td>\n",
       "      <td>tetragonal</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>A7--alpha-As</td>\n",
       "      <td>c1e15cf8-6998-40ce-afbd-0b1cb6271a1f</td>\n",
       "      <td>A7--alpha-As</td>\n",
       "      <td>alpha As</td>\n",
       "      <td>a-As</td>\n",
       "      <td>hR6</td>\n",
       "      <td>A7</td>\n",
       "      <td>166</td>\n",
       "      <td>R -3 m</td>\n",
       "      <td>D3d^5</td>\n",
       "      <td>hexagonal</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>10</th>\n",
       "      <td>Ah--alpha-Po--sc</td>\n",
       "      <td>ceb6d7cc-b20e-4878-8b2b-1e62185d16af</td>\n",
       "      <td>Ah--alpha-Po--sc</td>\n",
       "      <td>simple cubic</td>\n",
       "      <td>a-Po</td>\n",
       "      <td>cP1</td>\n",
       "      <td>Ah</td>\n",
       "      <td>221</td>\n",
       "      <td>P m -3 m</td>\n",
       "      <td>Oh^1</td>\n",
       "      <td>cubic</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>11</th>\n",
       "      <td>B1--NaCl--rock-salt</td>\n",
       "      <td>133ca871-c927-4073-ae46-b8a27e035f4b</td>\n",
       "      <td>B1--NaCl--rock-salt</td>\n",
       "      <td>rock salt</td>\n",
       "      <td>NaCl</td>\n",
       "      <td>cF8</td>\n",
       "      <td>B1</td>\n",
       "      <td>225</td>\n",
       "      <td>F m -3 m</td>\n",
       "      <td>Oh^5</td>\n",
       "      <td>cubic</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>12</th>\n",
       "      <td>B2--CsCl</td>\n",
       "      <td>7398b231-fd55-4378-b6b2-6607262d3090</td>\n",
       "      <td>B2--CsCl</td>\n",
       "      <td>cesium chloride</td>\n",
       "      <td>CsCl</td>\n",
       "      <td>cP2</td>\n",
       "      <td>B2</td>\n",
       "      <td>221</td>\n",
       "      <td>P m -3 m</td>\n",
       "      <td>Oh^1</td>\n",
       "      <td>cubic</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>13</th>\n",
       "      <td>B3--ZnS--cubic-zinc-blende</td>\n",
       "      <td>ce517a32-6bca-47d0-82a2-2ee48956cff9</td>\n",
       "      <td>B3--ZnS--cubic-zinc-blende</td>\n",
       "      <td>cubic zinc-blende</td>\n",
       "      <td>c-ZnS</td>\n",
       "      <td>cF8</td>\n",
       "      <td>B3</td>\n",
       "      <td>216</td>\n",
       "      <td>F -4 3 m</td>\n",
       "      <td>Td^2</td>\n",
       "      <td>cubic</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>14</th>\n",
       "      <td>C1--CaF2--fluorite</td>\n",
       "      <td>74171ba0-6605-4956-b8d5-0059672ee7e2</td>\n",
       "      <td>C1--CaF2--fluorite</td>\n",
       "      <td>fluorite</td>\n",
       "      <td>CaF2</td>\n",
       "      <td>cF12</td>\n",
       "      <td>C1</td>\n",
       "      <td>225</td>\n",
       "      <td>F m -3 m</td>\n",
       "      <td>Oh^5</td>\n",
       "      <td>cubic</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>15</th>\n",
       "      <td>D0_3--BiF3</td>\n",
       "      <td>8a2eb4b8-1302-46d9-992d-4296c227d966</td>\n",
       "      <td>D0_3--BiF3</td>\n",
       "      <td>BiF3</td>\n",
       "      <td>BiF3</td>\n",
       "      <td>cF16</td>\n",
       "      <td>D0_3</td>\n",
       "      <td>225</td>\n",
       "      <td>F m -3 m</td>\n",
       "      <td>Oh^5</td>\n",
       "      <td>cubic</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>16</th>\n",
       "      <td>L1_0--AuCu</td>\n",
       "      <td>f7b8d5d9-b0eb-401a-9cc3-038170e3ac1c</td>\n",
       "      <td>L1_0--AuCu</td>\n",
       "      <td>AuCu</td>\n",
       "      <td>AuCu</td>\n",
       "      <td>tP2</td>\n",
       "      <td>L1_0</td>\n",
       "      <td>123</td>\n",
       "      <td>P 4/m m m</td>\n",
       "      <td>D4h^1</td>\n",
       "      <td>tetragonal</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>17</th>\n",
       "      <td>L1_2--AuCu3</td>\n",
       "      <td>942ce385-85ab-4cb9-8adc-4bdaaf145831</td>\n",
       "      <td>L1_2--AuCu3</td>\n",
       "      <td>AuCu3</td>\n",
       "      <td>AuCu3</td>\n",
       "      <td>cP4</td>\n",
       "      <td>L1_2</td>\n",
       "      <td>221</td>\n",
       "      <td>P m -3 m</td>\n",
       "      <td>Oh^1</td>\n",
       "      <td>cubic</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>18</th>\n",
       "      <td>L2_1--AlCu2Mn--heusler</td>\n",
       "      <td>0fb6d590-5ce5-4476-a1bf-7130f96f2af1</td>\n",
       "      <td>L2_1--AlCu2Mn--heusler</td>\n",
       "      <td>heusler</td>\n",
       "      <td>AlCu2Mn</td>\n",
       "      <td>cF16</td>\n",
       "      <td>L2_1</td>\n",
       "      <td>225</td>\n",
       "      <td>F m -3 m</td>\n",
       "      <td>Oh^5</td>\n",
       "      <td>cubic</td>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                          name                                   key  \\\n",
       "0                  A1--Cu--fcc  d30980ad-ae18-425d-84cb-abf08577bdc8   \n",
       "1                   A15--Cr3Si  f4101896-1e17-4736-a4d1-308b8934e8ce   \n",
       "2                  A15--beta-W  e0126715-c7db-4d79-be80-707c572bebd6   \n",
       "3                   A2--W--bcc  bc13827d-e1e6-4d70-8c3a-59399ad78b0f   \n",
       "4    A3'--alpha-La--double-hcp  154d1a2b-04da-4477-8962-a0ca0c17c8fc   \n",
       "5                  A3--Mg--hcp  4dab7fbb-108a-425e-8adb-d55de7b1134b   \n",
       "6                    A4--C--dc  12654c83-c153-4b58-8805-f6dce43b7842   \n",
       "7                  A5--beta-Sn  821526c5-561e-4f09-8a04-680419dc1495   \n",
       "8                  A6--In--bct  76cbf2c1-fa86-41c4-85ae-c24f55c9f13a   \n",
       "9                 A7--alpha-As  c1e15cf8-6998-40ce-afbd-0b1cb6271a1f   \n",
       "10            Ah--alpha-Po--sc  ceb6d7cc-b20e-4878-8b2b-1e62185d16af   \n",
       "11         B1--NaCl--rock-salt  133ca871-c927-4073-ae46-b8a27e035f4b   \n",
       "12                    B2--CsCl  7398b231-fd55-4378-b6b2-6607262d3090   \n",
       "13  B3--ZnS--cubic-zinc-blende  ce517a32-6bca-47d0-82a2-2ee48956cff9   \n",
       "14          C1--CaF2--fluorite  74171ba0-6605-4956-b8d5-0059672ee7e2   \n",
       "15                  D0_3--BiF3  8a2eb4b8-1302-46d9-992d-4296c227d966   \n",
       "16                  L1_0--AuCu  f7b8d5d9-b0eb-401a-9cc3-038170e3ac1c   \n",
       "17                 L1_2--AuCu3  942ce385-85ab-4cb9-8adc-4bdaaf145831   \n",
       "18      L2_1--AlCu2Mn--heusler  0fb6d590-5ce5-4476-a1bf-7130f96f2af1   \n",
       "\n",
       "                            id                commonname prototype pearson  \\\n",
       "0                  A1--Cu--fcc       face-centered cubic        Cu     cF4   \n",
       "1                   A15--Cr3Si             beta-tungsten     Cr3Si     cP8   \n",
       "2                  A15--beta-W             beta-tungsten       b-W     cP8   \n",
       "3                   A2--W--bcc       body-centered cubic         W     cI2   \n",
       "4    A3'--alpha-La--double-hcp                double hcp        La     hP4   \n",
       "5                  A3--Mg--hcp    hexagonal close-packed        Mg     hP2   \n",
       "6                    A4--C--dc             diamond cubic         C     cF8   \n",
       "7                  A5--beta-Sn                 white tin      b-Sn     tI4   \n",
       "8                  A6--In--bct  body-centered tetragonal        In     tI2   \n",
       "9                 A7--alpha-As                  alpha As      a-As     hR6   \n",
       "10            Ah--alpha-Po--sc              simple cubic      a-Po     cP1   \n",
       "11         B1--NaCl--rock-salt                 rock salt      NaCl     cF8   \n",
       "12                    B2--CsCl           cesium chloride      CsCl     cP2   \n",
       "13  B3--ZnS--cubic-zinc-blende         cubic zinc-blende     c-ZnS     cF8   \n",
       "14          C1--CaF2--fluorite                  fluorite      CaF2    cF12   \n",
       "15                  D0_3--BiF3                      BiF3      BiF3    cF16   \n",
       "16                  L1_0--AuCu                      AuCu      AuCu     tP2   \n",
       "17                 L1_2--AuCu3                     AuCu3     AuCu3     cP4   \n",
       "18      L2_1--AlCu2Mn--heusler                   heusler   AlCu2Mn    cF16   \n",
       "\n",
       "   strukturbericht  sg_number        sg_hm sg_schoenflies crystalfamily  \\\n",
       "0               A1        225     F m -3 m           Oh^5         cubic   \n",
       "1              A15        223     P m -3 n           Oh^3         cubic   \n",
       "2              A15        223     P m -3 n           Oh^3         cubic   \n",
       "3               A2        229     I m -3 m           Oh^9         cubic   \n",
       "4              A3'        194  P 6_3/m m c          D6h^4     hexagonal   \n",
       "5               A3        194  P 6_3/m m c          D6h^4     hexagonal   \n",
       "6               A4        227     F d -3 m           Oh^7         cubic   \n",
       "7               A5        141  I 4_1/a m d         D4h^19    tetragonal   \n",
       "8               A6        139    I 4/m m m         D4h^17    tetragonal   \n",
       "9               A7        166       R -3 m          D3d^5     hexagonal   \n",
       "10              Ah        221     P m -3 m           Oh^1         cubic   \n",
       "11              B1        225     F m -3 m           Oh^5         cubic   \n",
       "12              B2        221     P m -3 m           Oh^1         cubic   \n",
       "13              B3        216     F -4 3 m           Td^2         cubic   \n",
       "14              C1        225     F m -3 m           Oh^5         cubic   \n",
       "15            D0_3        225     F m -3 m           Oh^5         cubic   \n",
       "16            L1_0        123    P 4/m m m          D4h^1    tetragonal   \n",
       "17            L1_2        221     P m -3 m           Oh^1         cubic   \n",
       "18            L2_1        225     F m -3 m           Oh^5         cubic   \n",
       "\n",
       "    natypes  \n",
       "0         1  \n",
       "1         2  \n",
       "2         1  \n",
       "3         1  \n",
       "4         1  \n",
       "5         1  \n",
       "6         1  \n",
       "7         1  \n",
       "8         1  \n",
       "9         1  \n",
       "10        1  \n",
       "11        2  \n",
       "12        2  \n",
       "13        2  \n",
       "14        2  \n",
       "15        2  \n",
       "16        2  \n",
       "17        2  \n",
       "18        3  "
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "prototypes, prototypes_df = potdb.get_crystal_prototypes(return_df=True, verbose=True)\n",
    "prototypes_df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.1.2. CrystalPrototype objects\n",
    "\n",
    "The CrystalPrototype Record objects is a subclass of [potentials.Record](https://github.com/usnistgov/potentials/blob/master/doc/5.%20Record%20Classes.html), 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.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "name A4--C--dc\n",
      "id A4--C--dc\n",
      "key 12654c83-c153-4b58-8805-f6dce43b7842\n",
      "commonname diamond cubic\n",
      "prototype C\n",
      "pearson cF8\n",
      "strukturbericht A4\n",
      "sg_number 227\n",
      "sg_hm F d -3 m\n",
      "sg_schoenflies Oh^7\n",
      "crystalfamily cubic\n",
      "natypes 1\n",
      "\n",
      "ucell:\n",
      "avect =  [ 1.000,  0.000,  0.000]\n",
      "bvect =  [ 0.000,  1.000,  0.000]\n",
      "cvect =  [ 0.000,  0.000,  1.000]\n",
      "origin = [ 0.000,  0.000,  0.000]\n",
      "natoms = 8\n",
      "natypes = 1\n",
      "symbols = (None,)\n",
      "pbc = [ True  True  True]\n",
      "per-atom properties = ['atype', 'pos']\n",
      "     id |   atype |  pos[0] |  pos[1] |  pos[2]\n",
      "      0 |       1 |   0.000 |   0.000 |   0.000\n",
      "      1 |       1 |   0.500 |   0.500 |   0.000\n",
      "      2 |       1 |   0.500 |   0.000 |   0.500\n",
      "      3 |       1 |   0.000 |   0.500 |   0.500\n",
      "      4 |       1 |   0.250 |   0.250 |   0.250\n",
      "      5 |       1 |   0.250 |   0.750 |   0.750\n",
      "      6 |       1 |   0.750 |   0.250 |   0.750\n",
      "      7 |       1 |   0.750 |   0.750 |   0.250\n"
     ]
    }
   ],
   "source": [
    "prototype = prototypes[6]\n",
    "\n",
    "print('name', prototype.name)\n",
    "print('id', prototype.id)\n",
    "print('key', prototype.key)\n",
    "print('commonname', prototype.commonname)\n",
    "print('prototype', prototype.prototype)\n",
    "print('pearson', prototype.pearson)\n",
    "print('strukturbericht', prototype.strukturbericht)\n",
    "print('sg_number', prototype.sg_number)\n",
    "print('sg_hm', prototype.sg_hm)\n",
    "print('sg_schoenflies', prototype.sg_schoenflies)\n",
    "print('crystalfamily', prototype.crystalfamily) \n",
    "print('natypes', prototype.natypes)\n",
    "print()\n",
    "print('ucell:')\n",
    "print(prototype.ucell)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.2. Relaxed crystals\n",
    "\n",
    "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.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.2.1. get_relaxed_crystals, get_relaxed_crystal and download_relaxed_crystals\n",
    "\n",
    "These methods extend the generic record methods (see the [potentials.Database documentation](https://github.com/lmhale99/potentials/blob/master/doc/4.%20Database%20Class.html)) by including the following record-specific query parameters\n",
    "\n",
    "- __key__ (*str or list, optional*) UUID4 key(s) to search for.  Each entry has a unique random-generated UUID4 key.\n",
    "- __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.\n",
    "- __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.\n",
    "- __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.\n",
    "- __parent_key__ (*str or list, optional*) The UUID4 key(s) assigned to the calculation that the record is based on.\n",
    "- __potential_LAMMPS_id__ (*str or list, optional*) The id for a LAMMPS implemented potential to limit the search by.\n",
    "- __potential_LAMMPS_key__ (*str or list, optional*) The UUID4 for a LAMMPS implemented potential to limit the search by.\n",
    "- __potential_id__ (*str or list, optional*) The id for a potential to limit the search by.\n",
    "- __potential_key__ (*str or list, optional*) The UUID4 for a potential to limit the search by.\n",
    "- __symbols__ (*str or list, optional*) Element symbols in the crystal to limit the search by.\n",
    "- __natypes__ (*int or list, optional*) The number(s) of unique atom types to limit the search by.\n",
    "- __natoms__ (*int or list, optional*) The number of unique atoms in the crystal's unit cell to limit the search by.\n",
    "\n",
    "__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.\n",
    "__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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>potential_LAMMPS_id</th>\n",
       "      <th>a</th>\n",
       "      <th>cohesive_energy</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>13</th>\n",
       "      <td>2012--Norman-G-E--Au--LAMMPS--ipr1</td>\n",
       "      <td>7.011749</td>\n",
       "      <td>-5.662467</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>104</th>\n",
       "      <td>2012--Norman-G-E--Au--LAMMPS--ipr1</td>\n",
       "      <td>4.068501</td>\n",
       "      <td>-4.299363</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>10</th>\n",
       "      <td>2012--Norman-G-E--Au--LAMMPS--ipr1</td>\n",
       "      <td>4.068501</td>\n",
       "      <td>-4.299363</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>37</th>\n",
       "      <td>2012--Norman-G-E--Au--LAMMPS--ipr1</td>\n",
       "      <td>4.068501</td>\n",
       "      <td>-4.299363</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>50</th>\n",
       "      <td>2004--Zhou-X-W--Cu-Ag-Au--LAMMPS--ipr2</td>\n",
       "      <td>4.080053</td>\n",
       "      <td>-3.930005</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>2020--Starikov-S--Si-Au-Al--LAMMPS--ipr2</td>\n",
       "      <td>7.842853</td>\n",
       "      <td>-0.835714</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>14</th>\n",
       "      <td>2020--Starikov-S--Si-Au-Al--LAMMPS--ipr1</td>\n",
       "      <td>7.842853</td>\n",
       "      <td>-0.835714</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>47</th>\n",
       "      <td>2012--Norman-G-E--Au--LAMMPS--ipr1</td>\n",
       "      <td>6.210659</td>\n",
       "      <td>-0.613333</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>103</th>\n",
       "      <td>2012--Norman-G-E--Au--LAMMPS--ipr1</td>\n",
       "      <td>6.210659</td>\n",
       "      <td>-0.613333</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>49</th>\n",
       "      <td>2012--Norman-G-E--Au--LAMMPS--ipr1</td>\n",
       "      <td>6.210659</td>\n",
       "      <td>-0.613333</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>118 rows × 3 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "                          potential_LAMMPS_id         a  cohesive_energy\n",
       "13         2012--Norman-G-E--Au--LAMMPS--ipr1  7.011749        -5.662467\n",
       "104        2012--Norman-G-E--Au--LAMMPS--ipr1  4.068501        -4.299363\n",
       "10         2012--Norman-G-E--Au--LAMMPS--ipr1  4.068501        -4.299363\n",
       "37         2012--Norman-G-E--Au--LAMMPS--ipr1  4.068501        -4.299363\n",
       "50     2004--Zhou-X-W--Cu-Ag-Au--LAMMPS--ipr2  4.080053        -3.930005\n",
       "..                                        ...       ...              ...\n",
       "9    2020--Starikov-S--Si-Au-Al--LAMMPS--ipr2  7.842853        -0.835714\n",
       "14   2020--Starikov-S--Si-Au-Al--LAMMPS--ipr1  7.842853        -0.835714\n",
       "47         2012--Norman-G-E--Au--LAMMPS--ipr1  6.210659        -0.613333\n",
       "103        2012--Norman-G-E--Au--LAMMPS--ipr1  6.210659        -0.613333\n",
       "49         2012--Norman-G-E--Au--LAMMPS--ipr1  6.210659        -0.613333\n",
       "\n",
       "[118 rows x 3 columns]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Fetch all records for fcc gold\n",
    "fcc_gold, fcc_gold_df = potdb.get_relaxed_crystals(family='A1--Cu--fcc', symbols='Au', return_df=True)\n",
    "\n",
    "fcc_gold_df.sort_values('cohesive_energy')[['potential_LAMMPS_id', 'a', 'cohesive_energy']]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.2.2. RelaxedCrystal objects\n",
    "\n",
    "Just like CrystalPrototype objects, RelaxedCrystal objects have attributes for all of the query terms plus ucell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "EAM_Dynamo_AdamsFoilesWolfer_1989_Au__MO_087738844640_000\n",
      "avect =  [ 4.080,  0.000,  0.000]\n",
      "bvect =  [ 0.000,  4.080,  0.000]\n",
      "cvect =  [ 0.000,  0.000,  4.080]\n",
      "origin = [ 0.000,  0.000,  0.000]\n",
      "natoms = 4\n",
      "natypes = 1\n",
      "symbols = ('Au',)\n",
      "pbc = [ True  True  True]\n",
      "per-atom properties = ['atype', 'pos']\n",
      "     id |   atype |  pos[0] |  pos[1] |  pos[2]\n",
      "      0 |       1 |   0.000 |   0.000 |   0.000\n",
      "      1 |       1 |   0.000 |   2.040 |   2.040\n",
      "      2 |       1 |   2.040 |   0.000 |   2.040\n",
      "      3 |       1 |   2.040 |   2.040 |   0.000\n"
     ]
    }
   ],
   "source": [
    "print(fcc_gold[0].potential_LAMMPS_id)\n",
    "print(fcc_gold[0].ucell)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.3. DFT reference crystals \n",
    "\n",
    "Reference crystal structures can also be searched for both within the local/NIST database and within the source databases."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.3.1. get_reference_crystals, get_reference_crystal, download_reference_crystal\n",
    "\n",
    "These methods extend the generic record methods (see the [potentials.Database documentation](https://github.com/lmhale99/potentials/blob/master/doc/4.%20Database%20Class.html)) by including the following record-specific query parameters\n",
    "\n",
    "- __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.\n",
    "- __key__ (*str or list, optional*) UUID4 key(s) to search for.  Each entry has a unique random-generated UUID4 key.\n",
    "- __sourcename__ (*str or list, optional*) The full name of source DFT databases to limit the search by. \"Materials Project\" or \"Open Quantum Materials Database\".            \n",
    "- __sourcelink__ (*str or list, optional*) The web link of the source DFT databases to limit the search by.\n",
    "- __crystalfamily__ (*str or list, optional*) The crystal system families to limit the search by.\n",
    "- __composition__ (*str or list, optional*) The reduced compositions of the structures to limit the search by. Element symbols are sorted alphabetically.\n",
    "- __symbols__ (*str or list, optional*) Element symbols in the crystal to limit the search by.\n",
    "- __natoms__ (*int or list, optional*) The number of unique atoms in the crystal's unit cell to limit the search by.\n",
    "- __natypes__ (*int or list, optional*) The number(s) of unique atom types to limit the search by.\n",
    "\n",
    "__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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.3.2. fetch_reference_crystal, fetch_mp_crystals, fetch_mp_crystal, fetch_oqmd_crystal\n",
    "\n",
    "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.\n",
    "\n",
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Crystal retrieved from Materials Project\n"
     ]
    }
   ],
   "source": [
    "api_key = 'C:/Users/lmh1/Documents/Materials Project/API key.txt'\n",
    "ref = potdb.fetch_reference_crystal(id = 'mp-81', api_key=api_key, verbose=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.3.3. ReferenceCrystal objects\n",
    "\n",
    "Same as the others, the ReferenceCrystal objects have attributes for the query terms and ucell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "avect =  [ 4.171,  0.000,  0.000]\n",
      "bvect =  [ 0.000,  4.171,  0.000]\n",
      "cvect =  [ 0.000,  0.000,  4.171]\n",
      "origin = [ 0.000,  0.000,  0.000]\n",
      "natoms = 4\n",
      "natypes = 1\n",
      "symbols = ('Au',)\n",
      "pbc = [ True  True  True]\n",
      "per-atom properties = ['atype', 'pos']\n",
      "     id |   atype |  pos[0] |  pos[1] |  pos[2]\n",
      "      0 |       1 |   0.000 |   0.000 |   0.000\n",
      "      1 |       1 |   0.000 |   2.086 |   2.086\n",
      "      2 |       1 |   2.086 |   0.000 |   2.086\n",
      "      3 |       1 |   2.086 |   2.086 |   0.000\n"
     ]
    }
   ],
   "source": [
    "print(ref.ucell)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.3.4. save_reference_crystal\n",
    "\n",
    "If you fetch a reference crystal from the parent database, you can then save it to the local database using save_reference_crystal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}