.. include:: /substitutions.rst

.. _aseapi:

Atomic Simulation Environment interface
=======================================

.. _aseapi_intro:

Introduction
------------

The |calc| package of supports running directly from surface structures
from the :term:`Atomic Simulation Environment (ASE)<ASE>`. ASE is a widely
used :term:`Python` library for setting up and controlling atomic
simulations such as density functional theory calculations and molecular
dynamics simulations. Via the ASE interface provided in |calc|, an
``ase.Atoms`` object can be used as surface model for a |LEED-IV| calculation.

This can be used to enable automated runs and sample surface structures
generated by any external software.
ViPErLEED can act as a "back-end" for high-throughput calculations which
accepts (almost) arbitrary structure model and returns raw |IV| curves or
the agreement (in terms of |R factor|) with an experimental set of beams.

Surface structures passed to |calc| via the :term:`API` need to fulfill the
same :ref:`conventions<conventions>` (e.g. vacuum side of surface towards
+\ **z** direction) as applicable for :ref:`POSCAR` files.

The ASE API provides a number of Python function that allow calling and
starting |LEED-IV| calculations. For an example of how to use the ASE 
interface, see :ref:`this tutorial<example_Ni(110)>`.
Please note that the ASE interface may require installing the R-factor
extension as described in the
:ref:`installation instructions<rfactor_exentsion>`.

.. note::
    The ViPErLEED ASE interface is an area of active development and may
    change in the future.
    If you have any suggestions for features or feedback concerning the ASE
    interface, feel free to contact the ViPErLEED team (preferably by opening
    an issue on the
    `ViPErLEED GitHub page <https://github.com/viperleed/viperleed>`__).


.. _aseapi_auto_sites:

Automatic site definitions
--------------------------

To facilitate batch processing of structures, the ASE interface allows for a
simplistic automated assignment of site definitions (usually done via the
:ref:`sitedef` parameter).

If the SITE_DEF parameter is not defined in a ViPErLEED run using the
ASE interface, ViPErLEED will try to assign "surface" sites on its own.
For this calculation, every atom is considered as a solid sphere with a
radius proportional to the elements' covalent radius.
Then, going from highest to lowest atom (:math:`z` position), ViPErLEED
checks if an atom is "visible" from vacuum, or if the line of sight is
blocked by higher-up atoms.
Atoms that are "visible" are declared as surface atoms (site ``surf``),
while all other atoms will be given the default site type (``def``).
This will create, at maximum, two site types per species.
If you want to define additional site types, it is currently necessary
to define them explicitly in the :ref:`POSCAR` file.


.. automodule:: viperleed.calc.from_ase
    :members: