.. contents::
   :local:

.. _loa:

-----------
ListOfAtoms
-----------

A ``ListOfAtoms`` object is a collection of atoms.  The ASE
implementation of a ListOfAtoms can be used like this:

>>> from ASE import Atom, ListOfAtoms
>>> m = ListOfAtoms([Atom('C', (0, 0, 0)),
...                  Atom('O', (0, 0, 1.0))])

The first argument to the ``ListOfAtoms`` constructor must be a python
``list`` of atoms.  There are two optional keyword arguments:

``cell``: Unit cell size
  This can be a sequence of three numbers for
  an orthorhombic unit cell or three by three numbers for a general
  unit cell (a sequence of three sequences of three numbers).  The
  default value is ``(1, 1, 1)``.

``periodic``: Boundary conditions
  The default value is ``False`` - a value of ``True`` would give
  periodic boundary conditions along all three axes.  It is possible
  to give a sequence of three booleans to specify periodicity along
  specific axes.


Here is how you could make an infinite gold wire with a bond length of
2.9 �

>>> from ASE import Atom, ListOfAtoms
>>> d = 2.9
>>> L = 10.0
>>> wire = ListOfAtoms([Atom('Au', (L / 2, L / 2, 0))],
...                    cell=(L, L, d), periodic=(0, 0, 1))


You can also use the following methods to work with the unit cell and the
boundary conditions:

``GetUnitCell()``:
  Returns a three by three array.

``SetUnitCell(cell, fix=False)``:
  Change the size of the unit cell.  If the optional argument ``fix``
  is ``True`` (defaults to ``False``), then the positons of the atoms
  are fixed, otherwise the atoms are moved so that their positions
  relative to the unit cell are kept.

``GetBoundaryConditions()``:
  Returns a tuple of three booleans.

Here is how you would do bulk ruthenium (hcp):

>>> from math import sqrt
>>> a = 2.70
>>> c = 1.59 * a
>>> bulk = ListOfAtoms([Atom('Ru', (0, 0, 0)),
...                     Atom('Ru', (1 / 3., 1 / 3., 1 / 2.))],
...                    periodic=True)
>>> bulk.SetUnitCell([(a, 0, 0),
...                   (a / 2, a * sqrt(3) / 2, 0),
...                   (0, 0, c)])


In addition, an ``ListOfAtoms`` instance has the following methods:

``GetKineticEnergy()``:
   Returns the total kinetic energy.

``Copy()``:
   Return a fresh copy.  Everything but a possibly attached
   calculator is copied (next section_ will explain how to attach a
   calculator).

``Repeat(repeat)``:
   The argument ``repeat`` is a sequence of three
   positive integers (``n1``, ``n2``, ``n3`` - one for each axis), and
   a copy of the ``ListOfAtoms`` object repeated ``n1 * n2 * n3``
   times is returned.

.. _section: calculators.html:Calculators


.. warning::
   Using the same atom object in several ListOfAtoms objects is not
   allowed!  Use a copy instead:

   >>> loa1.append(loa2[7])
   RuntimeError: Atom belongs to another ListOfAtoms!
   >>> loa1.append(loa2[7].Copy())



Array methods
-------------

It is possible to work with the properties of atoms in a ListOfAtoms by
using the methods defined for the individual atoms like this:

>>> m = ListOfAtoms([Atom('O', (0, 0, 0)),
...                  Atom('H', (0.773, 0.600, 0)),
...                  Atom('H', (-0.773, 0.600, 0))])
>>> m[1].GetCartesianPosition()
array([ 0.773,  0.6  ,  0.   ])
>>> m[0].SetCartesianPosition((0, -0.1, 0))

However, a ListOfAtoms that conforms to the ASE specification must have a
set of array methods to do the same for all atoms in one step:

>>> m.GetCartesianPositions()
array([[ 0.   ,  0.   ,  0.   ],
       [ 0.773,  0.6  ,  0.   ],
       [-0.773,  0.6  ,  0.   ]])
>>> m.SetCartesianPositions([(0, -0.1, 0),
...                          (0.773, 0.600, 0),
...                          (-0.773, 0.600, 0)])

The following methods must be defined:

===========================  ===========================  =========  ==========
Get methods                  Set methods                  type       shape
===========================  ===========================  =========  ==========
``GetCartesianPositions``    ``SetCartesianPositions``    ``Float``  ``(n, 3)``
``GetCartesianMomenta``      ``SetCartesianMomenta``      ``Float``  ``(n, 3)``
``GetCartesianVelocities``   ``SetCartesianVelocities``   ``Float``  ``(n, 3)``
``GetCartesianForces``       ``SetCartesianForces``       ``Float``  ``(n, 3)``
``GetTags``                  ``SetTags``                  ``Int``    ``(n,)``
``GetAtomicNumbers``         ``SetAtomicNumbers``         ``Int``    ``(n,)``
``GetMasses``                ``SetMasses``                ``Float``  ``(n,)``
``GetKineticEnergies``                                    ``Float``  ``(n,)``
``GetGeneralizedPositions``  ``SetGeneralizedPositions``  ``Float``  ``(n*3,)``
``GetGeneralizedForces``     ``SetGeneralizedForces``     ``Float``  ``(n*3,)``
===========================  ===========================  =========  ==========


The ``Get`` methods will return Numeric_ arrays of the given shape (``n``
is the number of atoms) and type, and the ``Set`` methods will take
anything with the correct shape.

.. _Numeric: http://numpy.sf.net