examples/01_getting_started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "111ab3e9-2a0f-43e4-bac0-b7bb2cf79610",
   "metadata": {},
   "source": [
    "# Getting started with pyscal"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "08075ab3-ec1d-4aaf-b868-d59819f294f9",
   "metadata": {},
   "source": [
    "## The `System` class"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b477a4d0-140e-4fc2-8a7b-f4b6b4988064",
   "metadata": {},
   "source": [
    "`System` is the central class in pyscal. It is required for setting up calculations. We start by importing the class,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "872fdee1-5a73-462c-a5c4-9974b1112b46",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pyscal import System"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aad02d9d-cd85-4c21-87cb-6e3dbd63bb5e",
   "metadata": {},
   "source": [
    "And then create a system"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "925e7f41-dca5-4398-8639-94c825e39ef0",
   "metadata": {},
   "outputs": [],
   "source": [
    "sys = System()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6435e5ba-908a-4fe1-9717-5429ab2bb5db",
   "metadata": {},
   "source": [
    "`sys` is a `System` object. But at this point, it is completely empty. We have to provide the system with the following information-\n",
    "* the simulation box dimensions\n",
    "* the positions of individual atoms. \n",
    "\n",
    "Let us try to set up a small system, which is the bcc unitcell of lattice constant 1. The simulation box dimensions of such a unit cell\n",
    "would be [[0.0, 1.0], [0.0, 1.0], [0.0, 1.0]] where the first set correspond to the x axis, second to y axis and so on.  \n",
    "The unitcell has 2 atoms and their positions are [0,0,0] and [0.5, 0.5, 0.5]. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "c8def58d-c256-46d9-8fac-d4979358cb56",
   "metadata": {},
   "outputs": [],
   "source": [
    "sys.box = [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c9e81382-a796-44e9-85d4-d52e7e9e9dd0",
   "metadata": {},
   "source": [
    "We can easily check if everything worked by getting the box dimensions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "b50d8ee5-5520-4a45-b023-d9b993c35975",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sys.box"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f6177c9a-1568-495a-86ba-e7e670966461",
   "metadata": {},
   "source": [
    "## The `Atoms` class"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e442a571-e763-429e-8a94-f3e48d506852",
   "metadata": {},
   "source": [
    "We start by importing the `Atoms` class"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "4e7c6044-d170-4e53-b5f4-7a8eb1644b6a",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pyscal import Atoms"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7ba8439b-765c-421e-a028-6fe0607fbccd",
   "metadata": {},
   "source": [
    "The next part is assigning the atoms. This can be done using the `Atom` class."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "62852399-d926-4531-a072-78e055ff0fea",
   "metadata": {},
   "source": [
    "First, we prepare the positions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "c66944d1-6c43-45ca-80ce-b4c2e45b6af7",
   "metadata": {},
   "outputs": [],
   "source": [
    "adict = {\"positions\": [[0, 0, 0], [0.5, 0.5, 0.5]]}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "70f43e55-4652-475c-bab6-bc73e9f88eef",
   "metadata": {},
   "source": [
    "Now we can create atoms"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "56612102-1171-4aad-a3dd-b8daa20ecc46",
   "metadata": {},
   "outputs": [],
   "source": [
    "atoms = Atoms(adict)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "99d6b374-434d-4c67-ab5a-5c7c5b78f67a",
   "metadata": {},
   "source": [
    "`Atoms` is python class and you can access the various keys.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "beb3ab82-2dd5-428e-ad71-058d2163105b",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[[0, 0, 0], [0.5, 0.5, 0.5]]"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "atoms.positions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a56495da-08e1-4252-b57c-b47701833350",
   "metadata": {},
   "source": [
    "It is also a dictionary and you can check the available keys."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "c99c4dbe-027b-4c2f-bb7b-84d2147d9982",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['positions', 'ids', 'ghost', 'types', 'species', 'mask_1', 'mask_2', 'condition', 'head'])"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "atoms.keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7232609e-cf3b-44e7-8d09-f73c1edb7cca",
   "metadata": {},
   "source": [
    "There are more keys that were auto-generated, which is not important for us for the moment."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bd9cd82b-8e8b-4343-a1f4-acd3c55717ca",
   "metadata": {},
   "source": [
    "For more details about the `Atoms` class, please see further examples."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b7f204b-5f0a-41d6-967d-816275bb70ee",
   "metadata": {},
   "source": [
    "## Combining `System` and `Atoms`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f18f7b25-2020-457e-b77e-46ecae775b31",
   "metadata": {},
   "source": [
    "Now we can add the atoms to the `System` we created before."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "cc239692-8225-4c81-9192-51f4b919d75b",
   "metadata": {},
   "outputs": [],
   "source": [
    "sys.atoms = atoms"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aaee93dc-0d8c-4bc7-9442-882143c53f5a",
   "metadata": {},
   "source": [
    "We are all set! The `System` is ready for calculations. However, in most realistic simulation situations, we have many atoms and it can be difficult to set each of them  \n",
    "individually. In this situation we can read in input file directly. An example input file containing 500 atoms in a simulation box can be read in automatically. The file we use for this example is a file of the [lammps-dump](https://lammps.sandia.gov/doc/dump.html) format. pyscal can also read in a number of other file formats. In principle, pyscal only needs the atom positions and simulation box size, so you can write a python function to process the input file, extract the details and pass to pyscal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "f95d8575-ff10-4169-ac03-4b52a76ecbd7",
   "metadata": {},
   "outputs": [],
   "source": [
    "sys = System('conf.dump')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "4b163d62-f7be-4089-8d93-beb6137ee039",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[[-5.66782, -6.06781, -6.58151],\n",
       " [-3.61832, -5.66888, -5.46712],\n",
       " [-0.947172, 10.3193, 11.3033],\n",
       " [-0.10301, -6.35752, -6.44787],\n",
       " [1.61271, -5.30872, -7.68795]]"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sys.atoms.positions[:5]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0019a58-317c-4080-b4bb-7ec89210efca",
   "metadata": {},
   "source": [
    "Alternatively, it can be a two-step process"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "e339a839-8ff8-4130-8942-4b1d68765c74",
   "metadata": {},
   "outputs": [],
   "source": [
    "sys = System()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "528575cd-480b-4f33-90b6-3befed985a20",
   "metadata": {},
   "outputs": [],
   "source": [
    "sys.read_inputfile('conf.dump')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8fd08cee-1d76-43ed-8503-dda015da0acf",
   "metadata": {},
   "source": [
    "The `read_inputfile` function supports a number of other options as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "1be7d3d2-7eb1-4b46-bf80-a3ab7764d7f6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\u001b[0;31mSignature:\u001b[0m\n",
       "\u001b[0msys\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mread_inputfile\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m    \u001b[0mfilename\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m    \u001b[0mformat\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;34m'lammps-dump'\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m    \u001b[0mcompressed\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;32mFalse\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m    \u001b[0mcustomkeys\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;32mNone\u001b[0m\u001b[0;34m,\u001b[0m\u001b[0;34m\u001b[0m\n",
       "\u001b[0;34m\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
       "\u001b[0;31mDocstring:\u001b[0m\n",
       "Read input file that contains the information of system configuration.\n",
       "\n",
       "Parameters\n",
       "----------\n",
       "filename : string\n",
       "    name of the input file.\n",
       "\n",
       "format : {'lammps-dump', 'poscar', 'ase', 'mdtraj'}\n",
       "    format of the input file, in case of `ase` the ASE Atoms object\n",
       "\n",
       "compressed : bool, optional\n",
       "    If True, force to read a `gz` compressed format, default False.\n",
       "\n",
       "customkeys : list\n",
       "    A list containing names of headers of extra data that needs to be read in from the\n",
       "    input file.\n",
       "\n",
       "Returns\n",
       "-------\n",
       "None\n",
       "\n",
       "Notes\n",
       "-----\n",
       "`format` keyword specifies the format of the input file. Currently only\n",
       "a `lammps-dump` and `poscar` files are supported.  Additionaly, the widely\n",
       "use Atomic Simulation environment (https://wiki.fysik.dtu.dk/ase/ase/ase.html).\n",
       "mdtraj objects (http://mdtraj.org/1.9.3/) are also supported by using the keyword\n",
       "`'mdtraj'` for format. Please note that triclinic boxes are not yet supported for\n",
       "mdtraj format.\n",
       "Atoms object can also be used directly. This function uses the\n",
       ":func:`~pyscal.traj_process` module to process a file which is then assigned to system.\n",
       "\n",
       "`compressed` keyword is not required if a file ends with `.gz` extension, it is\n",
       "automatically treated as a compressed file.\n",
       "\n",
       "Triclinic simulation boxes can also be read in.\n",
       "\n",
       "If `custom_keys` are provided, this extra information is read in from input files if\n",
       "available. This information is can be accessed directly as `self.atoms['customkey']`\n",
       "\u001b[0;31mFile:\u001b[0m      ~/miniconda3/envs/pyscal-test/lib/python3.10/site-packages/pyscal/core.py\n",
       "\u001b[0;31mType:\u001b[0m      method\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "sys.read_inputfile?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "85bb1674-2c5f-4bd0-89bb-48f1ca30e12a",
   "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.10.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}