{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quick start\n",
    "\n",
    "This simple tutorial will illustrate the basic capabilities of the package.\n",
    "\n",
    "## Table of Contents\n",
    "\n",
    "- [Basic interactive usage](#Basic-interactive-usage)\n",
    "  - [Getting single elements](#Getting-single-elements)\n",
    "  - [Getting-list-of-elements](#Getting-list-of-elements)\n",
    "- [Extended attributes](#Extended-attributes)\n",
    "  - [Oxidation states](#Oxidation-states)\n",
    "  - [Ionization energies](#Ionization-energies)\n",
    "  - [Isotopes](#Isotopes)\n",
    "  - [Ionic radii](#Ionic-radii)\n",
    "  - [Electronic configuration](#Electronic-configuration)\n",
    "- [Useful functions for calculating properties](#Useful-functions-for-calculating-properties)\n",
    "- [Electronegativity](#Electronegativity)\n",
    "- [CLI utility](#CLI-utility)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic interactive usage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Getting single elements\n",
    "\n",
    "The simplest way of accessing the elements is importing them directly from `mendeleev` by symbols"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mendeleev import Si, Fe, O\n",
    "\n",
    "print(\"Si's name: \", Si.name)\n",
    "print(\"Fe's atomic number:\", Fe.atomic_number)\n",
    "print(\"O's atomic weight: \", O.atomic_weight)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An alternative interface to the data is through the ``element`` function that returns a single ``Element`` object or a list of ``Element`` object depending on the arguments.\n",
    "\n",
    "The function can be imported directly from the ``mendeleev`` package"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "from mendeleev import element"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``element`` method accepts unique identifiers: **atomic number**, **atomic symbol** or **element’s name** in English. To retrieve the entries on Silicon by symbol type"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "si = element(\"Si\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "si"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly to access the data by atomic number or element names type"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "al = element(13)\n",
    "print(al.name)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "o = element(\"Oxygen\")\n",
    "print(o.atomic_number)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Getting list of elements"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ``element`` method also accepts list or tuple of identifiers and then returns a list of ``Element`` objects"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "c, h, o = element([\"C\", \"Hydrogen\", 8])\n",
    "print(c.name, h.name, o.name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Extended attributes\n",
    "\n",
    "Next to simple attributes returning ``str``, ``int`` or ``float``, there are extended attributes \n",
    "\n",
    "* ``oxistates``, returns a list of oxidation states\n",
    "* ``ionenergies``, returns a dictionary of ionization energies\n",
    "* ``isotopes``, returns a list of ``Isotope`` objects\n",
    "* ``ionic_radii`` returns a list of ``IonicRadius`` objects\n",
    "* ``ec``, electronic configuration object\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Oxidation states\n",
    "\n",
    "``oxistates`` returns a list of most common oxidation states for a given element"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "fe = element(\"Fe\")\n",
    "print(fe.oxistates)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Ionization energies\n",
    "\n",
    "The ``ionenergies`` returns a dictionary with ionization energies in `eV` as values and degrees of ionization as keys"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "o = element(\"O\")\n",
    "o.ionenergies"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Isotopes\n",
    "\n",
    "The ``isotopes`` attribute returns a list of ``Isotope`` objects with the following attributes per isotope\n",
    "\n",
    "* abundance\n",
    "* abundance_uncertainty\n",
    "* atomic_number\n",
    "* discovery_year\n",
    "* g_factor\n",
    "* g_factor_uncertainty\n",
    "* half_life\n",
    "* half_life_uncertainty\n",
    "* half_life_unit\n",
    "* is_radioactive\n",
    "* mass\n",
    "* mass_number\n",
    "* mass_uncertainty\n",
    "* parity\n",
    "* quadrupole_moment\n",
    "* quadrupole_moment_uncertainty\n",
    "* spin"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "print(\n",
    "    \"{0:^4s} {1:^4s} {2:^10s} {3:8s} {4:6s} {5:5s}\\n{6}\".format(\n",
    "        \"AN\", \"MN\", \"Mass\", \"Unc.\", \"Abu.\", \"Rad.\", \"-\" * 42\n",
    "    )\n",
    ")\n",
    "for iso in fe.isotopes:\n",
    "    print(\n",
    "        \"{0:4d} {1:4d} {2:10.5f} {3:8.2e} {4:} {5:}\".format(\n",
    "            iso.atomic_number,\n",
    "            iso.mass_number,\n",
    "            iso.mass,\n",
    "            iso.mass_uncertainty,\n",
    "            iso.abundance,\n",
    "            iso.is_radioactive,\n",
    "        )\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Accessing isotopes\n",
    "\n",
    "Similarly to ``element`` function that can be used to fetch specific isotopes by:\n",
    "\n",
    "- ``atomic_number`` and ``mass_number`` or\n",
    "- ``symbol`` and ``mass_number``"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from mendeleev import isotope"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "isotope(\"Fe\", mass_number=57)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# tritium\n",
    "isotope(1, 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Radioactive isotopes can have multiple decay modes and that data is available as `decay_modes` attrobute for each `Isotope`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "isotope(\"Li\", 11).decay_modes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Ionic radii\n",
    "\n",
    "Another composite attribute is ``ionic_radii`` which returns a list of ``IonicRadius`` object with the following attributes\n",
    "\n",
    "* ``atomic_number``, atomic number of the ion\n",
    "* ``charge``, charge of the ion\n",
    "* ``econf``, electronic configuration of the ion\n",
    "* ``coordination``, coordination type of the ion\n",
    "* ``spin``, spin state of the ion (HS or LS)\n",
    "* ``crystal_radius``, crystal radius in pm\n",
    "* ``ionic_radius``, ionic radius in pm\n",
    "* ``origin``, source of the data\n",
    "* ``most_reliable``, recommended value, (see the original paper for more information)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "for ir in fe.ionic_radii:\n",
    "    print(ir)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Useful functions for calculating properties\n",
    "\n",
    "Next to stored attributes there is a number of useful functions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "si = element(\"Si\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# get the number of valence electrons\n",
    "si.nvalence()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# calculate softness for an ion\n",
    "si.softness(charge=2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# calcualte hardness for an ion\n",
    "si.hardness(charge=4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# calculate the effective nuclear charge for a subshell using Slater's rules\n",
    "si.zeff(n=3, o=\"s\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# calculate the effective nuclear charge for a subshell using Clemneti's and Raimondi's exponents\n",
    "si.zeff(n=3, o=\"s\", method=\"clementi\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Electronegativity\n",
    "\n",
    "Currently there are 9 electronagativity scales implemented that can me accessed though the common ``electronegativity`` method, the scales are:\n",
    "\n",
    "* ``allen``\n",
    "* ``allred-rochow``\n",
    "* ``cottrell-sutton``\n",
    "* ``ghosh``\n",
    "* ``gordy``\n",
    "* ``li-xue``\n",
    "* ``martynov-batsanov``\n",
    "* ``mulliken``\n",
    "* ``nagle``\n",
    "* ``pauling``\n",
    "* ``sanderson``\n",
    "\n",
    "More information can be found in the [documentation](http://mendeleev.readthedocs.org/en/latest/electronegativity.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "si.electronegativity(scale=\"pauling\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "si.electronegativity(scale=\"allen\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# calculate mulliken electronegativity for a neutral atom or ion\n",
    "si.electronegativity(scale=\"mulliken\", charge=1)"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.12.0"
  },
  "toc-autonumbering": false,
  "toc-showcode": false,
  "toc-showmarkdowntxt": false,
  "toc-showtags": false
 },
 "nbformat": 4,
 "nbformat_minor": 4
}