#!/usr/bin/env python
# coding: utf-8

# # Quick start
# 
# This simple tutorial will illustrate the basic capabilities of the package.
# 
# ## Table of Contents
# 
# - [Basic interactive usage](#Basic-interactive-usage)
#   - [Getting single elements](#Getting-single-elements)
#   - [Getting-list-of-elements](#Getting-list-of-elements)
# - [Extended attributes](#Extended-attributes)
#   - [Oxidation states](#Oxidation-states)
#   - [Ionization energies](#Ionization-energies)
#   - [Isotopes](#Isotopes)
#   - [Ionic radii](#Ionic-radii)
#   - [Electronic configuration](#Electronic-configuration)
# - [Useful functions for calculating properties](#Useful-functions-for-calculating-properties)
# - [Electronegativity](#Electronegativity)
# - [CLI utility](#CLI-utility)

# ## Basic interactive usage

# ### Getting single elements
# 
# The simplest way of accessing the elements is importing them directly from `mendeleev` by symbols

# In[ ]:


from mendeleev import Si, Fe, O

print("Si's name: ", Si.name)
print("Fe's atomic number:", Fe.atomic_number)
print("O's atomic weight: ", O.atomic_weight)


# 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.
# 
# The function can be imported directly from the ``mendeleev`` package

# In[ ]:


from mendeleev import element


# 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

# In[ ]:


si = element("Si")


# In[ ]:


si


# Similarly to access the data by atomic number or element names type

# In[ ]:


al = element(13)
print(al.name)


# In[ ]:


o = element("Oxygen")
print(o.atomic_number)


# ### Getting list of elements

# The ``element`` method also accepts list or tuple of identifiers and then returns a list of ``Element`` objects

# In[ ]:


c, h, o = element(["C", "Hydrogen", 8])
print(c.name, h.name, o.name)


# ## Extended attributes
# 
# Next to simple attributes returning ``str``, ``int`` or ``float``, there are extended attributes 
# 
# * ``oxistates``, returns a list of oxidation states
# * ``ionenergies``, returns a dictionary of ionization energies
# * ``isotopes``, returns a list of ``Isotope`` objects
# * ``ionic_radii`` returns a list of ``IonicRadius`` objects
# * ``ec``, electronic configuration object
# 

# ### Oxidation states
# 
# ``oxistates`` returns a list of most common oxidation states for a given element

# In[ ]:


fe = element("Fe")
print(fe.oxistates)


# ### Ionization energies
# 
# The ``ionenergies`` returns a dictionary with ionization energies in `eV` as values and degrees of ionization as keys

# In[ ]:


o = element("O")
o.ionenergies


# ### Isotopes
# 
# The ``isotopes`` attribute returns a list of ``Isotope`` objects with the following attributes per isotope
# 
# * abundance
# * abundance_uncertainty
# * atomic_number
# * discovery_year
# * g_factor
# * g_factor_uncertainty
# * half_life
# * half_life_uncertainty
# * half_life_unit
# * is_radioactive
# * mass
# * mass_number
# * mass_uncertainty
# * parity
# * quadrupole_moment
# * quadrupole_moment_uncertainty
# * spin

# In[ ]:


print(
    "{0:^4s} {1:^4s} {2:^10s} {3:8s} {4:6s} {5:5s}\n{6}".format(
        "AN", "MN", "Mass", "Unc.", "Abu.", "Rad.", "-" * 42
    )
)
for iso in fe.isotopes:
    print(
        "{0:4d} {1:4d} {2:10.5f} {3:8.2e} {4:} {5:}".format(
            iso.atomic_number,
            iso.mass_number,
            iso.mass,
            iso.mass_uncertainty,
            iso.abundance,
            iso.is_radioactive,
        )
    )


# #### Accessing isotopes
# 
# Similarly to ``element`` function that can be used to fetch specific isotopes by:
# 
# - ``atomic_number`` and ``mass_number`` or
# - ``symbol`` and ``mass_number``

# In[ ]:


from mendeleev import isotope


# In[ ]:


isotope("Fe", mass_number=57)


# In[ ]:


# tritium
isotope(1, 3)


# Radioactive isotopes can have multiple decay modes and that data is available as `decay_modes` attrobute for each `Isotope`

# In[ ]:


isotope("Li", 11).decay_modes


# ### Ionic radii
# 
# Another composite attribute is ``ionic_radii`` which returns a list of ``IonicRadius`` object with the following attributes
# 
# * ``atomic_number``, atomic number of the ion
# * ``charge``, charge of the ion
# * ``econf``, electronic configuration of the ion
# * ``coordination``, coordination type of the ion
# * ``spin``, spin state of the ion (HS or LS)
# * ``crystal_radius``, crystal radius in pm
# * ``ionic_radius``, ionic radius in pm
# * ``origin``, source of the data
# * ``most_reliable``, recommended value, (see the original paper for more information)
# 

# In[ ]:


for ir in fe.ionic_radii:
    print(ir)


# ## Useful functions for calculating properties
# 
# Next to stored attributes there is a number of useful functions

# In[ ]:


si = element("Si")


# In[ ]:


# get the number of valence electrons
si.nvalence()


# In[ ]:


# calculate softness for an ion
si.softness(charge=2)


# In[ ]:


# calcualte hardness for an ion
si.hardness(charge=4)


# In[ ]:


# calculate the effective nuclear charge for a subshell using Slater's rules
si.zeff(n=3, o="s")


# In[ ]:


# calculate the effective nuclear charge for a subshell using Clemneti's and Raimondi's exponents
si.zeff(n=3, o="s", method="clementi")


# ### Electronegativity
# 
# Currently there are 9 electronagativity scales implemented that can me accessed though the common ``electronegativity`` method, the scales are:
# 
# * ``allen``
# * ``allred-rochow``
# * ``cottrell-sutton``
# * ``ghosh``
# * ``gordy``
# * ``li-xue``
# * ``martynov-batsanov``
# * ``mulliken``
# * ``nagle``
# * ``pauling``
# * ``sanderson``
# 
# More information can be found in the [documentation](http://mendeleev.readthedocs.org/en/latest/electronegativity.html).

# In[ ]:


si.electronegativity(scale="pauling")


# In[ ]:


si.electronegativity(scale="allen")


# In[ ]:


# calculate mulliken electronegativity for a neutral atom or ion
si.electronegativity(scale="mulliken", charge=1)