.. include:: /substitutions.rst .. _example_Ir(100)-O: =============================== Example system: Ir(100)-(2×1)-O =============================== In this tutorial we go through a ViPErLEED structure analysis for an Ir(100) surface with adsorbed oxygen, creating a (\ :math:`2\times1`) superstructure. The structure and analysis is based on Ref. :cite:alp:`ferstlStructureOrderingOxygen2016`. The experimental data and input model were provided by Lutz Hammer. We will begin by running a reference calculation and a rough structure optimization. Following this, we move to a finer search grid and run a :ref:`full-dynamic optimization ` of the inner potential |V0i|. After achieving a satisfactory |R factor|, we use the ViPErLEED :ref:`error calculation` to estimate how much small changes of atomic positions affect the |R factor|. This will give margins for the statistical uncertainties of the determined parameters. .. only:: html You can download the input files to follow along :download:`here`. .. only:: not html You can download the input files to follow along in the online version of the documentation at `viperleed.org `__. .. tip:: If you are new to ViPErLEED, check out :ref:`the more basic tutorial` first, which explains the setup in more detail. .. _sec_ir_intro: Introduction ============ We start from experimental |LEED-IV| curves which are saved in file :ref:`EXPBEAMS.csv`. As reference structure, we use a :ref:`POSCAR` file containing an Ir(100) surface that was hand made from a bulk structure. An additional adsorbed oxygen atom is placed at a bridge site, such that each surface iridium atom binds to one oxygen atom. The height above the surface was chosen to achieve a reasonable Ir–O bond length. See :numref:`fig_ir_start` for a visualization of the structure (using :term:`VESTA` :cite:`mommaVESTAThreedimensionalVisualization2011`). In this visualization, we also drew a plane orthogonal to the unit-cell vector |c| at fractional position :math:`c=0.35`. We will use the :ref:`BULK_LIKE_BELOW` parameter to declare that everything below this cutoff is bulklike. .. _fig_ir_start: .. figure:: /_static/example_systems/Ir(100)-O/figures/view_a_b_c.svg :width: 100% :align: center POSCAR rendered in :term:`VESTA`, viewed along |a| (left), |b| (center) and |c| (right). Ir atoms are shown in blue, oxygen in red. .. hint:: Of course there are other possible structural models, including adsorption at hollow, top, or Ir-sharing bridge sites. Even surface reconstructions (e.g., missing row) are conceivable. Here, we concentrate exclusively on the correct structural model, which is known from the literature :cite:p:`johnsonUnusualBridgedSite2000,ferstlStructureOrderingOxygen2016`. Often the adsorption site (or generally, the structural model) may not be known a priori. In that case, at least a rough analysis has to be performed for each reasonable model in order to find the most promising one(s), before further optimization is performed. PARAMETERS and rough DISPLACEMENTS ================================== We start by setting up a rudimentary :ref:`PARAMETERS` file, very similar to the one described in the tutorial for the :ref:`Ag(100)-(1×1) surface`, as per :numref:`list_ir_parameters`. .. _list_ir_parameters: .. literalinclude :: /_static/example_systems/Ir(100)-O/PARAMETERS :language: console :caption: PARAMETERS file for Ir(100)-(2×1)-O. GLOBAL PARAMETERS At the top of the file, we specify some general settings, such as the energy range to be used and our initial guess for the imaginary part of the inner potential |V0i|. We will run a :ref:`reference calculation`, :ref:`delta-amplitude`, and a :ref:`structure search` back to back, so we specify :ref:`RUN = 1-3`. To reduce computation time for this example, we also limit the maximum angular momentum quantum number to be used in the calculations by TensErLEED with the :ref:`LMAX` parameter. PARAMETERS FOR INTERPRETING THE POSCAR As mentioned in the :ref:`sec_ir_intro`, we let ViPErLEED find the bulk-repeat unit by itself. For this, we set the :ref:`BULK_LIKE_BELOW` parameter at the height where we drew the plane in :numref:`fig_ir_start`. Using the :ref:`sitedef` parameter, we specify that the topmost iridium atoms should be treated separately. These Ir atoms are differently coordinated than bulk Ir atoms and thus will presumably have a different vibrational amplitude. For completeness, we also specify the site type ``O_ads`` for the adsorbed oxygen atom. However, since there is only one oxygen atom in the structure, this will not change the behavior and we could also skip that line. PARAMETERS FOR VIBROCC Since we don't have a :ref:`VIBROCC` file yet, we need to specify the parameters :ref:`T_DEBYE`, :ref:`T_EXPERIMENT`, and :ref:`VIBR_AMP_SCALE`. Note that we can only give one value for the Debye temperature for both oxygen and iridium. The initial vibrational amplitudes will be calculated as explained in the section on :ref:`T_DEBYE`. .. tip:: Grouping the settings in the PARAMETERS file as described above is not required, but it helps with readability. For the delta-amplitudes calculation and structure optimization, we also need to set up a :ref:`DISPLACEMENTS` file. Since this is the first run starting from a totally unrelaxed model, we begin with a rather large range and a relatively rough grid, as in :numref:`list_ir_displacements_rough`. .. _list_ir_displacements_rough: .. literalinclude :: /_static/example_systems/Ir(100)-O/DISPLACEMENTS_rough :language: console :caption: DISPLACEMENTS file for the first optimization of Ir(100)-(2×1)-O. By setting multiple search blocks in DISPLACEMENTS, we can tell ViPErLEED to execute them one after the other. When starting to optimize a new system such as here, it is generally a good idea to begin with a geometric optimization perpendicular to the surface (i.e., along :math:`z`). This is because the |LEED-IV| curves are most sensitive to out-of-plane displacements. We then follow up with rough optimizations of in-plane positions and vibrational amplitudes of surface atoms.\ [1]_ For the in-plane optimization, we use a simplified assignment for all four layers, although any movement along the :math:`x` direction (here parallel to the |a| unit vector) is forbidden by symmetry for Ir atoms in the second and fourth layers.\ [2]_ ViPErLEED automatically sorts out any symmetry-forbidden displacements, cf. :numref:`fig_Ir_O_search_progress_2`. .. note:: TensErLEED cannot simultaneously optimize displacements in different directions for a given atom. Vibrational amplitudes can be optimized together with one geometric displacement; here we do it separately to speed up the calculation. However, it is generally advisable to combine vibrational-amplitude displacements and displacements along the :math:`z` direction, as the parameters may be coupled. With the files set up, we can start the ViPErLEED calculation. During the first initialization ViPErLEED will generate :ref:`IVBEAMS` and :ref:`PHASESHIFTS` files. .. note:: You will notice that the first time we run a new system, ViPErLEED stops execution after the initialization. This is on purpose, and is supposed to give the user a chance to double check the recognized symmetry and annotated POSCAR. You will need to **restart the run manually** after making these checks. When the run is finished, we will see in the log file that the |R factor| has decreased quite a bit. The first reference calculation gave a value of :math:`R_\mathrm{P} \approx 0.55`, but |RP| has dropped to around :math:`\approx 0.21` over the search. We can get a better idea of how the search has converged by taking a look at the file :ref:`searchprogresspdf` in the ``SUPP`` directory. .. _fig_Ir_O_search_progress_1: .. figure:: /_static/example_systems/Ir(100)-O/figures/progress_1_page_1.svg :width: 70% :align: center Upper half of page 1 for ``Search-progress.pdf`` for the rough initial structure optimization of Ir(100)-(2×1)-O. :numref:`fig_Ir_O_search_progress_1` shows a plot of the decreasing |R factor| during the various stages of the search. We clearly see that both geometric optimizations made quick progress in terms of convergence. This is expected when starting from an unrelaxed surface slab like the one used here. The other pages of the file give us some insight into how each atomic parameter developed during the structure optimization. .. _fig_Ir_O_search_progress_2: .. figure:: /_static/example_systems/Ir(100)-O/figures/progress_1_page_2.svg :width: 70% :align: center Pages 2–4 of ``Search-progress.pdf`` for the rough initial structure optimization of Ir(100)-(2×1)-O (white space removed). :numref:`fig_Ir_O_search_progress_2` shows that the (:math:`z`) position of the oxygen adsorbate has changed a good amount. Further, we see that the vibrational amplitude of the oxygen atom has gone down, while the amplitude for iridium has gone up. .. important:: We want to accept the optimized positions as the new starting configuration, so we need to replace our old :ref:`POSCAR` and :ref:`VIBROCC` files with the optimized ones. This can be done either manually or automatically by calling the :ref:`bookkeeper utility` with the ``--cont`` flag: .. code-block:: console $ python3 bookkeeper.py --cont #[or ./bookkeeper --cont] Fine DISPLACEMENTS and tensor-LEED error ======================================== The rough optimization has already significantly brought down the |R factor|. We should now continue with a finer search grid. For this, we use a similar :ref:`DISPLACEMENTS` file, but with much smaller range and step size (see :numref:`list_ir_displacements_fine`). We now rerun with :ref:`RUN = 1-3` to perform a fresh reference calculation for the new starting positions. This is advisable because parameter deviations during the previous fit were not negligible. .. _list_ir_displacements_fine: .. literalinclude :: /_static/example_systems/Ir(100)-O/DISPLACEMENTS_fine :language: console :caption: DISPLACEMENTS file for the fine optimization of Ir(100)-(2×1)-O. When looking at the log file after the reference calculation, we further notice something important: The |R factor| of the reference calculation (\ :math:`R_\mathrm{P} \approx 0.18`) *is different* from the one we obtained from the :ref:`superposition` calculation at the end of the previous run (\ :math:`R_\mathrm{P} \approx 0.21`). This comes from the :ref:`error of the tensor-LEED approximation` used for the structure optimization. In this case, the real |R factor| — as obtained from the reference calculation — is lower. However, this is not always the case. You should **never** rely on the |R factor| produced by the superposition calculation as a final result, but rather run a final reference calculation at the end of your analysis.\ [3]_ Full-dynamic optimization ========================= After the finer search run finishes, we see that the |R factor| has again dropped quite significantly. The |R factor| is now below 0.1, which already indicates very good agreement, but we can get better yet. However, before proceeding, we should accept the new best-fit structure by calling the :ref:`bookkeeper utility` with the ``--cont`` flag: .. code-block:: console $ python3 bookkeeper.py --cont #[or ./bookkeeper --cont] Now, remember that in the :ref:`PARAMETERS` file of :numref:`list_ir_parameters` we had to put in an initial guess for the imaginary part of the inner potential |V0i|. We would now like to also optimize this non-structural parameter. However, it is not accessible in :ref:`the tensor-LEED approach`, which can only treat perturbations on an atom-by-atom basis. Instead, we can use the :ref:`full-dynamic optimization` to find an optimal value for |V0i|. During the :ref:`full-dynamic optimization`, multiple reference calculations are run while the chosen global parameter is varied. ViPErLEED then tries to determine an optimal value using a parabola fit. We select |V0i| for optimization by adding the following line to PARAMETERS: .. code-block:: console OPTIMIZE V0i = step 0.5 We then chose to run the :ref:`full-dynamic optimization` by setting the parameter :ref:`RUN = 6` and restarting. Once finished, the log file will let us know of the optimized value for the chosen parameter. ViPErLEED also produces a file called ``FD_Optimization.pdf`` in the ``OUT`` directory which contains a visualization of the |R factor|\ s calculated for the various values of the parameter and a fit parabola. It is shown in :numref:`fig_ir_fdopt`. .. _fig_ir_fdopt: .. figure:: /_static/example_systems/Ir(100)-O/figures/FD_Optimization.svg :width: 60% :align: center ``FD_Optimization.pdf`` file resulting from the full-dynamic optimization of the imaginary part of the inner potential, |V0i|, for Ir(100)-(2×1)-O. .. note:: ViPErLEED will also automatically add the new, optimized value to the :ref:`PARAMETERS` file and comment out the line containing the previous value. Following the |V0i| optimization we can also run a final structure optimization, since the new value for |V0i| may have slightly affected the optimal positions. Using a (very fine) :math:`0.002` Å grid (``DISPLACEMENTS_very_fine`` in the provided example files) we manage to get a final |R factor| of around :math:`R_\mathrm{P} \approx 0.088`. Error calculation ================= Now that we have found a good structure fit, we can run a ViPErLEED :ref:`error calculation` to estimate how sensitive the |R factor| is to small changes of specific parameters. As input for the error calculation, we need a :ref:`DISPLACEMENTS` file containing the desired range and steps. The format of the file is the same as used for the delta-amplitudes calculation and structure search. .. _list_ir_error_calc: .. literalinclude :: /_static/example_systems/Ir(100)-O/DISPLACEMENTS_errors :language: console :caption: DISPLACEMENTS file for the error calculation. Using the DISPLACEMENTS file in :numref:`list_ir_error_calc`, we run the error calculation by selecting the segment :ref:`RUN = 5`. The :ref:`result ` will again be saved in the :file:`OUT` directory. ViPErLEED generates a plot of the error curves in :file:`Errors.pdf` and stores the raw data in :file:`Errors.csv`. The :file:`Errors.pdf` file in :numref:`fig_ir_errors_geo` shows that displacement of surface atoms even by a few picometres drastically increases the |R factor|. Here, atom 1 is the oxygen adsorbate and atoms 2 and 3 are the topmost iridium ones. .. _fig_ir_errors_geo: .. figure:: /_static/example_systems/Ir(100)-O/figures/errors_geo.svg :width: 50% :align: center Part of :file:`Errors.pdf` showing the effects of geometric displacements. .. note:: The point of intersection between the error curve for a parameter and the horizontal line labeled :math:`R_\mathrm{P} + \textrm{var}(R_\mathrm{P})` gives a measure for the statistical error of the parameter :cite:p:`heinzElectronBasedMethods2013` (see also the section on :ref:`Errors`). Changes in the vibrational amplitude of the surface atoms (\ :numref:`fig_ir_errors_vib`) also strongly affect the |R factor|. .. _fig_ir_errors_vib: .. figure:: /_static/example_systems/Ir(100)-O/figures/errors_vib.svg :width: 50% :align: center Part of ``Errors.pdf`` showing the effects of changes in the vibrational amplitude of the topmost atoms. In general, error plots for geometric displacement tend to show a parabolic profile close to the minimum. Error plots for vibrational amplitudes tend to be more asymmetric, as these amplitudes enter the calculation differently (i.e., via the Debye–Waller factor). .. warning:: Error curves are also subject to **errors of the tensor-LEED approximation**. |R-factor| values obtained for large deviations should be taken with care. .. [1] It is not recommended to fit any vibrational amplitude of bulk atoms as long as reliable information about the substrate Debye temperature is available. .. [2] Actually, no in-plane movement is allowed for these Ir atoms. They coincide with twofold rotation axes of the pmm group. See also the ``FreeDir`` column in the POSCAR file after initialization. .. [3] There is one exception to this rule. The full-dynamic reference calculation cannot provide exact results when an atom has mixed chemical composition and the elements have different optimized positions. This is because only one position can be specified for each atom. In this case, the tensor-LEED approximation is the only viable alternative.