{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Welcome to the OpenKIM tutorial!\n",
    "This tutorial demonstrates the basic usage of KIM models in LAMMPS and ASE. Other supported calculators are listed [here](https://openkim.org/projects-using-kim/). Also included is a demonstration of advanced querying of the new EquilibriumCrystalStructure tests for arbitrary crystals to construct a thermodynamic convex hull for an interatomic potential.\n",
    "\n",
    "To run any cells with code, click on them and press shift+enter or press the run button. Commands with a leading ``!\" are shell commands, otherwise they are Python. \n",
    "\n",
    "This Binder is an instance of the [KIM Developer Platform (KDP)](https://openkim.org/doc/evaluation/kim-developer-platform/). Most of the examples in this tutorial are relevant to using OpenKIM models in production simulations. If you are interested in the special features of the KDP for KIM content development, see the following notebook:\n",
    "\n",
    "[KIM Content development using the KIM Developer Platform](kdp.ipynb)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using OpenKIM models in your simulations"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To use KIM models, the [KIM API](https://openkim.org/kim-api/) must be installed, as well as the models you wish to use. See [Obtaining KIM Models](https://openkim.org/doc/usage/obtaining-models/) for instructions on installing the API and models separately or as a single package.\n",
    "\n",
    "The KIM API is already installed in this Binder. In addition to the API for using KIM models in simulations, it provides the `kim-api-collections-management` utility with several subcommands, some of which are demonstrated here. Use it to install some models now (first set for the LAMMPS demo, second for the ASE demo):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!kim-api-collections-management install user SW_StillingerWeber_1985_Si__MO_405512056662_006\n",
    "!kim-api-collections-management install user Sim_LAMMPS_ReaxFF_ManzanoMoeiniMarinelli_2012_CaSiOH__SM_714124634215_000"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!kim-api-collections-management install user EAM_Dynamo_SongMendelev_2021_AlSm__MO_722733117926_000"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following command shows the installed models:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!kim-api-collections-management list"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you are ready to use OpenKIM in your preferred simulator:\n",
    "\n",
    "[LAMMPS example](lammps_examples/lammps.ipynb)\n",
    "\n",
    "[ASE example](ase.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Querying OpenKIM\n",
    "\n",
    "Because everything archived in OpenKIM can be queried, the possibilities of using OpenKIM queries are endless. We have already seen how they can be used to query lattice constants to set up simulations. For more information about ways to query OpenKIM, see:\n",
    "\n",
    "https://openkim.org/doc/usage/kim-query/\n",
    "\n",
    "https://query.openkim.org/\n",
    "\n",
    "As a simple example, we can use the kim-query Python package to query the bulk moduli of the two models we examined in the LAMMPS example to see if we ranked them correctly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from kim_query import get_bulk_modulus_isothermal_cubic\n",
    "\n",
    "print(get_bulk_modulus_isothermal_cubic([\"SW_StillingerWeber_1985_Si__MO_405512056662_006\"],[\"diamond\"],[\"Si\"],[\"GPa\"]))\n",
    "print(get_bulk_modulus_isothermal_cubic([\"Sim_LAMMPS_ReaxFF_ManzanoMoeiniMarinelli_2012_CaSiOH__SM_714124634215_000\"],[\"diamond\"],[\"Si\"],[\"GPa\"]))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Thermodynamic convex hull of an interatomic potential\n",
    "\n",
    "As the final demo we show how to use advanced querying to construct a thermodynamic convex hull from the results of the new [EquilibriumCrystalStructure test driver](https://openkim.org/id/EquilibriumCrystalStructure__TD_457028483760_000) and compare them to reference data. A [convex hull](https://arxiv.org/pdf/1806.06901.pdf) is a common product of of DFT materials discovery databases such as AFLOW. Compounds on the hull, and only those on the hull, are predicted to be stable. Now that OpenKIM is able to compute properties for arbitrary multi-species crystals, we can compare the hulls computed by interatomic potentials to those computed by DFT.\n",
    "\n",
    "*Note that for now we have only created tests and reference data for the AFLOW-ICSD catalog, so the number of structures is sparse and the reference data was computed using the Hubbard U correction, which is not the preferred type of calculation for convex hull construction. Stay tuned as we incorporate all 3.5 million materials from AFLOW!*\n",
    "\n",
    "You are encouraged to look at the included Python file [hull_functions.py](hull_functions.py) to see how the advanced querying works."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from hull_functions import plot_model_hull_vs_rd\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "species=[\"Al\",\"Ti\"]\n",
    "\n",
    "model=\"EAM_Dynamo_ZopeMishin_2003_TiAl__MO_117656786760_005\"\n",
    "#model=\"EAM_Dynamo_FarkasJones_1996_NbTiAl__MO_042691367780_000\"\n",
    "#model=\"MEAM_LAMMPS_AlmyrasSangiovanniSarakinos_2019_NAlTi__MO_958395190627_001\"\n",
    "#model=\"MEAM_LAMMPS_KimKimJung_2016_AlTi__MO_618133763375_001\"\n",
    "#model=\"MEAM_LAMMPS_KimKimJung_2017_NiAlTi__MO_478967255435_001\"\n",
    "#model=\"MEAM_LAMMPS_SunRamachandranWick_2018_TiAl__MO_022920256108_001\"\n",
    "#model=\"Tersoff_LAMMPS_PlummerRathodSrivastava_2021_TiAlC__MO_992900971352_000\"\n",
    "\n",
    "assert len(species)==2\n",
    "\n",
    "plot_model_hull_vs_rd(species,model)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Bonded Force Fields\n",
    "[LAMMPS quartz example using IFF bonded force field](bonded/bonded.ipynb)"
   ]
  }
 ],
 "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.8.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}