
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples_generated/gettingstarted/00-n2cu.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_examples_generated_gettingstarted_00-n2cu.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_examples_generated_gettingstarted_00-n2cu.py:

.. _introductionexample:

ASE Introduction: Nitrogen on copper
====================================

This section gives a quick (and incomplete) overview of what ASE can do.
You can download the code shown in this tutorial (and others in the same style)
as python scripts or jupyter notebooks at the bottom of this page.

We will calculate the adsorption energy of a nitrogen
molecule on a copper surface.
This is done by calculating the total
energy for the isolated slab and for the isolated molecule. The
adsorbate is then added to the slab and relaxed, and the total energy
for this composite system is calculated. The adsorption energy is
obtained as the sum of the isolated energies minus the energy of the
composite system.

You will be able to see an image of the system after relaxation,
later in the "Visualization" section.

Please have a look at the following script:

.. GENERATED FROM PYTHON SOURCE LINES 24-51

.. code-block:: Python


    from ase import Atoms
    from ase.build import add_adsorbate, fcc111
    from ase.calculators.emt import EMT
    from ase.constraints import FixAtoms
    from ase.optimize import QuasiNewton

    h = 1.85
    d = 1.10

    slab = fcc111('Cu', size=(4, 4, 2), vacuum=10.0)

    slab.calc = EMT()
    e_slab = slab.get_potential_energy()

    molecule = Atoms('2N', positions=[(0.0, 0.0, 0.0), (0.0, 0.0, d)])
    molecule.calc = EMT()
    e_N2 = molecule.get_potential_energy()

    add_adsorbate(slab, molecule, h, 'ontop')
    constraint = FixAtoms(mask=[a.symbol != 'N' for a in slab])
    slab.set_constraint(constraint)
    dyn = QuasiNewton(slab, trajectory='N2Cu.traj')
    dyn.run(fmax=0.05)

    print('Adsorption energy:', e_slab + e_N2 - slab.get_potential_energy())





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

                    Step[ FC]     Time          Energy          fmax
    BFGSLineSearch:    0[  0] 09:16:36       11.689927       1.0797
    BFGSLineSearch:    1[  2] 09:16:36       11.670814       0.4090
    BFGSLineSearch:    2[  4] 09:16:36       11.625880       0.0409
    Adsorption energy: 0.32351942231764497




.. GENERATED FROM PYTHON SOURCE LINES 52-66

Assuming you have ASE setup correctly (:ref:`download_and_install`)
you can copy it into a python file (e.g. N2Cu.py) and run the script::

 python N2Cu.py

Please read below what the script does.

Atoms
-----

The :class:`~ase.Atoms` object is a collection of atoms.  Here
is how to define a N2 molecule by directly specifying the position of
two nitrogen atoms


.. GENERATED FROM PYTHON SOURCE LINES 66-70

.. code-block:: Python


    d = 1.10
    molecule = Atoms('2N', positions=[(0.0, 0.0, 0.0), (0.0, 0.0, d)])








.. GENERATED FROM PYTHON SOURCE LINES 71-75

You can also build crystals using, for example, the lattice module
which returns :class:`~ase.Atoms` objects corresponding to
common crystal structures. Let us make a Cu (111) surface


.. GENERATED FROM PYTHON SOURCE LINES 75-80

.. code-block:: Python


    from ase.build import fcc111

    slab = fcc111('Cu', size=(4, 4, 2), vacuum=10.0)








.. GENERATED FROM PYTHON SOURCE LINES 81-90

Adding calculator
-----------------

In this overview we use the effective medium theory (EMT) calculator,
as it is very fast and hence useful for getting started.

We can attach a calculator to the previously created
:class:`~ase.Atoms` objects


.. GENERATED FROM PYTHON SOURCE LINES 90-96

.. code-block:: Python


    from ase.calculators.emt import EMT

    slab.calc = EMT()
    molecule.calc = EMT()








.. GENERATED FROM PYTHON SOURCE LINES 97-101

and use it to calculate the total energies for the systems by using
the :meth:`~ase.Atoms.get_potential_energy` method from the
:class:`~ase.Atoms` class


.. GENERATED FROM PYTHON SOURCE LINES 101-105

.. code-block:: Python


    e_slab = slab.get_potential_energy()
    e_N2 = molecule.get_potential_energy()








.. GENERATED FROM PYTHON SOURCE LINES 106-113

Structure relaxation
--------------------

Let's use the :class:`~ase.optimize.QuasiNewton` minimizer to optimize the
structure of the N2 molecule adsorbed on the Cu surface. First add the
adsorbate to the Cu slab, for example in the on-top position


.. GENERATED FROM PYTHON SOURCE LINES 113-117

.. code-block:: Python


    h = 1.85
    add_adsorbate(slab, molecule, h, 'ontop')








.. GENERATED FROM PYTHON SOURCE LINES 118-123

In order to speed up the relaxation, let us keep the Cu atoms fixed in
the slab by using :class:`~ase.constraints.FixAtoms` from the
:mod:`~ase.constraints` module. Only the N2 molecule is then allowed
to relax to the equilibrium structure


.. GENERATED FROM PYTHON SOURCE LINES 123-129

.. code-block:: Python


    from ase.constraints import FixAtoms

    constraint = FixAtoms(mask=[a.symbol != 'N' for a in slab])
    slab.set_constraint(constraint)








.. GENERATED FROM PYTHON SOURCE LINES 130-135

Now attach the :class:`~ase.optimize.QuasiNewton` minimizer to the
system and save the trajectory file. Run the minimizer with the
convergence criteria that the force on all atoms should be less than
some ``fmax``


.. GENERATED FROM PYTHON SOURCE LINES 135-141

.. code-block:: Python


    from ase.optimize import QuasiNewton

    dyn = QuasiNewton(slab, trajectory='N2Cu.traj')
    dyn.run(fmax=0.05)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

                    Step[ FC]     Time          Energy          fmax
    BFGSLineSearch:    0[  0] 09:16:36       11.689927       1.0797
    BFGSLineSearch:    1[  2] 09:16:36       11.670814       0.4090
    BFGSLineSearch:    2[  4] 09:16:36       11.625880       0.0409

    np.True_



.. GENERATED FROM PYTHON SOURCE LINES 142-156

.. note::

  The general documentation on
  :ref:`structure optimizations <structure_optimizations>` contains
  information about different algorithms, saving the state of an optimizer
  and other functionality which should be considered when performing
  expensive relaxations.

Input-output
------------

Writing the atomic positions to a file is done with the
:func:`~ase.io.write` function


.. GENERATED FROM PYTHON SOURCE LINES 156-161

.. code-block:: Python


    from ase.io import write

    write('slab.xyz', slab)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    /build/python-ase-iXAd1o/python-ase-3.28.0/ase/io/extxyz.py:320: UserWarning: Skipping unhashable information adsorbate_info
      warnings.warn('Skipping unhashable information '




.. GENERATED FROM PYTHON SOURCE LINES 162-176

This will write a file in the xyz-format.  Possible formats are:

========  ===========================
format    description
========  ===========================
``xyz``   Simple xyz-format
``cube``  Gaussian cube file
``pdb``   Protein data bank file
``traj``  ASE's own trajectory format
``py``    Python script
========  ===========================

Reading from a file is done like this


.. GENERATED FROM PYTHON SOURCE LINES 176-181

.. code-block:: Python


    from ase.io import read

    slab_from_file = read('slab.xyz')








.. GENERATED FROM PYTHON SOURCE LINES 182-187

If the file contains several configurations, the default behavior of
the :func:`~ase.io.write` function is to return the last
configuration. However, we can load a specific configuration by
doing


.. GENERATED FROM PYTHON SOURCE LINES 187-192

.. code-block:: Python


    read('N2Cu.traj')  # last configuration
    read('N2Cu.traj', -1)  # same as above
    read('N2Cu.traj', 0)  # first configuration





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    Atoms(symbols='Cu32N2', pbc=[True, True, False], cell=[[10.210621920333747, 0.0, 0.0], [5.105310960166873, 8.842657971447272, 0.0], [0.0, 0.0, 22.08423447177455]], tags=..., constraint=FixAtoms(indices=[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31]), calculator=SinglePointCalculator(...))



.. GENERATED FROM PYTHON SOURCE LINES 193-199

Visualization
-------------

The simplest way to visualize the atoms is the :func:`~ase.visualize.view`
function


.. GENERATED FROM PYTHON SOURCE LINES 201-222

.. code-block:: python

   from ase.visualize import view
   view(slab)

This will pop up a :mod:`ase.gui` window.  Alternative viewers can be used
by specifying the optional keyword ``viewer=...`` - use one of
'ase.gui', 'gopenmol', 'vmd', or 'rasmol'. (Note that these alternative
viewers are not a part of ASE and will need to be installed by the user
separately.) The VMD viewer can take an optional ``data`` argument to
show 3D data


.. code-block:: python

   view(slab, viewer='VMD', data=array)



If you do not want a gui to open and plot this directly, you can do
this with plot_atoms in Matplotlib

.. GENERATED FROM PYTHON SOURCE LINES 223-233

.. code-block:: Python



    import matplotlib.pyplot as plt

    from ase.visualize.plot import plot_atoms

    fig, ax = plt.subplots()
    plot_atoms(slab_from_file, ax)
    ax.set_axis_off()




.. image-sg:: /examples_generated/gettingstarted/images/sphx_glr_00-n2cu_001.png
   :alt: 00 n2cu
   :srcset: /examples_generated/gettingstarted/images/sphx_glr_00-n2cu_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 234-245

Molecular dynamics
------------------

Let us look at the nitrogen molecule as an example of molecular
dynamics with the :class:`VelocityVerlet <ase.md.verlet.VelocityVerlet>`
algorithm. We first create the :class:`VelocityVerlet
<ase.md.verlet.VelocityVerlet>` object giving it the molecule and the time
step for the integration of Newton's law. We then perform the dynamics
by calling its :meth:`~ase.md.verlet.VelocityVerlet.run` method and
giving it the number of steps to take:


.. GENERATED FROM PYTHON SOURCE LINES 246-256

.. code-block:: Python


    from ase import units
    from ase.md.verlet import VelocityVerlet

    dyn = VelocityVerlet(molecule, timestep=1.0 * units.fs)
    for i in range(10):
        pot = molecule.get_potential_energy()
        kin = molecule.get_kinetic_energy()
        print('%2d: %.5f eV, %.5f eV, %.5f eV' % (i, pot + kin, pot, kin))
        dyn.run(steps=20)




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

     0: 0.44034 eV, 0.44034 eV, 0.00000 eV
     1: 0.43816 eV, 0.26289 eV, 0.17527 eV
     2: 0.44058 eV, 0.43142 eV, 0.00916 eV
     3: 0.43874 eV, 0.29292 eV, 0.14582 eV
     4: 0.44015 eV, 0.41839 eV, 0.02176 eV
     5: 0.43831 eV, 0.28902 eV, 0.14929 eV
     6: 0.43947 eV, 0.36902 eV, 0.07045 eV
     7: 0.43951 eV, 0.35507 eV, 0.08444 eV
     8: 0.43959 eV, 0.36221 eV, 0.07738 eV
     9: 0.43933 eV, 0.36044 eV, 0.07889 eV





.. _sphx_glr_download_examples_generated_gettingstarted_00-n2cu.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 00-n2cu.ipynb <00-n2cu.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 00-n2cu.py <00-n2cu.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: 00-n2cu.zip <00-n2cu.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_
