.. contents::
   :local:

-----
Atoms
-----

ASE defines a python class called ``Atom``.  It is the basic building
block of a `ListOfAtoms <list_of_atoms.html#ListOfAtoms>`_.  From a python script,
atoms are created like this:

>>> from ASE import Atom
>>> a1 = Atom('Si', (0, 0, 0))
>>> a2 = Atom('H', (1.3, 0, 0), mass=2)
>>> a3 = Atom(position=(0, 0, 0), Z=14)  # same is a1

The first argument to the constructor of an ``Atom`` object is the
chemical symbol, and the second argument is the position.  The
position can be any numerical sequence of length three.  The
properties of an atom can also be set using keywords like it is done
in the ``a2`` example.  The following keywords can be used:

============ =============== ========= ============= ========================
keyword      description       type    default value method name
============ =============== ========= ============= ========================
``symbol``   chemical symbol ``str``                 ``GetChemicalSymbol``
``position`` position        `seq`     ``(0, 0, 0``) ``GetCartesianPosition``
``Z``        atomic number   ``int``                 ``GetAtomicNumber``
``mass``     mass            ``float``               ``GetMass``
``tag``      tag             ``int``   ``0``         ``GetTag``
``momentum`` momentum        `seq`     ``(0, 0, 0)`` ``GetCartesianMomentum``
``velocity`` velocity        `seq`     ``(0, 0, 0)`` ``GetCartesianVelocity``
``magmom``   magnetic moment ``float`` ``0``         ``GetMagneticMoment``
============ =============== ========= ============= ========================

`seq`: A sequence of three numbers.

One of the keywords ``symbol`` or ``Z`` must be given - other keywords
have default values.  The default value for the mass is set acording
to ``symbol`` or ``Z``:

>>> a1.GetMass()
28.0855

Here we used one of the ``Get`` methods from the last column.  An atom
also has the corresponding ``Set`` methods, like
``SetCartesianVelocity`` and ``SetMass``:

>>> a1.SetCartesianVelocity((0, 0, 0.1))

There is also a method for calculating the kinetic energy of an atom:

>>> a1.GetKineticEnergy()
0.14042750000000004

An atom also has two methods for interacting with a force calculator_:
``GetCartesianForce()`` and ``_SetCartesianForce(force)``.

.. _calculator: calculators.html#calculators


-------------------------------
The ``ChemicalElements`` module
-------------------------------

The ``ChemicalElements`` module defines an function ``Element()`` that
can take an atomic number or a chemical symbol as argument:

>>> from ASE.ChemicalElements import Element
>>> e = Element('Fe')
>>> e.number
26
>>> e.mass
55.847000000000001
>>> Element(99).name
'Einsteinium'

The ``Element()`` function returns a special object with the following
attributes: ``symbol``, ``number``, ``name`` and, if it makes sence,
also ``mass``, ``covalent_radius``, ``cpk_color`` and ``crystal_structure``.

The individual properties are also avilable as lists:

>>> from ASE.ChemicalElements.name import names
>>> names[5:11]
['Boron', 'Carbon', 'Nitrogen', 'Oxygen', 'Fluorine', 'Neon']





..
 Another example:

  >>> ru = elements['Ru']
  >>> ru['state']
  'hcp'
  >>> a = ru['a']
  >>> c = ru['c/a'] * a