1. Introduction

This package is a Python package which produces atomic phase shifts for various LEED packages (including CLEED), as well as for certain XPD packages.

Currently, it uses the Barbieri/Van Hove phase shift calculation package and preliminary support for John Rundgren’s EEASiSSS package as backends. The Fortran components are exposed via the legacy f2py path or the modern scikit-build-core/CMake build (used for Python 3.12+), with Python wrappers providing a user-friendly object-orientated interface for the end user.

The aim of this package is to both automate and simplify the generation of phase shift files in a manner that is easy for the computational hitch-hiker, but powerful for those that wish to extend the package for particular needs.

The phsh.py script unifies many of the steps needed for the phase shift calculations into a single command intended for the end-user. For more information please read the documentation at https://phaseshifts.readthedocs.io/en/latest/

1.1. Barbieri/Van Hove backend

The original phase shift package developed by A. Barbieri & M. A. Van Hove during the 1970’s & 1980’s. To quote the authors’ site:

“The phase shift calculation is performed in several steps:

  1. Calculation of the radial charge density for a free atom.

  2. Calculation of the radial muffin-tin potential for atoms embedded in a surface defined by the user (the surface is represented by a slab that is periodically repeated in 3 dimensions, within vacuum between the repeated slabs); various approximations to the exchange potential are available; relativistic effects are taken into account.

  3. Calculation of phase shifts from the muffin-tin potential.

  4. Elimination of pi-jumps in the energy dependence of the phase shifts.”

Note

You can get the original Fortran source (& learn more about the phshift programs) from here

Please contact Michel Van Hove <vanhove@hkbu.edu.hk> regarding this package.

A local copy of the source files can be found under phaseshifts/lib/.phsh.orig/phsh[0-2].f.

1.2. EEASiSSS backend

The EEASiSSS package [1] [2] [3] can also calculate phase shifts and has been used in several works on oxides from the mid-2000s to early-2010s [4] [5]. In the words of the package’s author, John Rundgren, the main qualifications of the program are:

  • The program accepts three sources of atomic potentials:

    1. E. L. Shirley’s atomic program [6] applied together with Mattheiss’s superposition method.

    2. The DFT-SCF program of V. Eyert using the full-potential Augmented Spherical Wave method [7] .

    3. The DFT-SCF program WIEN2k using the full-potential Augmented Plane Wave method.

  • The exchange-correlation interaction between the scattered electron and the crystal’s electron gas generates an energy-dependent inner potential. The phase shifts are referred to the in-crystal kinetic energy, and it is supposed that an associated LEED code uses the same standard.

  • The crystal potential is everywhere continuous so as to exclude fortuitous standing-wave electron resonances in the muffin-tin spheres and pertaining fortuitous wobblings in the phase shift versus energy curves.

  • The optimization of the muffin-tin radii is made using the method of Differential Evolution , an extremely efficient minimizer.

Note

Please refer to the short APPENDIX II: Elastic Electron-Atom Scattering in Solids and Surface Slabs - User Guide for more information relating to using EEASiSSS.

Please contact John Rundgren <jru@kth.se> for queries, comments or suggestions related to this package.

1.2.1. About the code

The example source code provided in this package are intended to be instructional in calculating phase shifts. While it is not recommended to use the example code in production, the code should be sufficient to explain the general use of the library.

If you aren’t familiar with the phase shift calculation process, you can read further information in doc/ folder:

  • phshift2007.rst - a brief user guide/documentation concerning the input files (& details of the original fortran phshift package).

  • phaseshifts API reference - a more detailed overview of the library functions and how to calculate phase shifts using the convenience functions in this package. This is not yet finished and so the reader is referred to the above document for the time being.

For those wanting a crash course of the Van Hove / Tong programs, I advise reading the phsh2007.txt document. See the examples/ directory to get an idea of the structure of the input files (for a random selection of models & elements). In particular see the cluster_Ni.i file for helpful comments regarding each line of input.

Tip

There is also a nice diagram overview (ignoring the LEED parts) contained within the AQuaLEED poster available online.

Those of you who are eager to generate phase shifts - first look at the example cluster files for a bulk and slab calculation, noting that the atoms in the model are in fractional units of the a basis vector for the unit cell (SPA units). Next, after creating a bulk and slab model in the cluster.i format, simply use the following python code:

>>> from phaseshifts.phsh import Wrapper as phsh
>>> phsh.autogen_from_inputs(bulk_file, slab_file)

This will hopefully produce the desired phase shift output files (at least for simple models) and works by assessing the two models to determine what output to produce. For more detailed documentation and function use refer to the pdf manual.

Tip

A standalone command line utility phsh.py is provided as a way of automating the generation of phase shifts as part of a script. For more information use:

phsh.py --help

Note

The phaseshifts.leed module provides a conversion class for CLEED .inp and .bul files. This is included as part of the phsh.py module, however the file extension is important (needs .inp, .pmin, .bul, or .bmin) and error checking is limited. There are also plans to include a validator to check the files for mal-formatted input at some point in the future.

1.2.1.1. Alternatives

A number of alternatives are available, notably the following:

  1. AQuaLEED (with a useful poster overview of phaseshifts calculations). This is an officially mentioned piece of software on Michel Van Hove’s LEED Calculation Homepage. Furthermore, although the poster mentions that the software is written in python, as of 2025 this software is not distributed on https://PyPI.org (or via alternative means such as a docker image on DockerHub) and therefore harder to integrate with other python LEED-related projects such as CLEED and cleedpy.

  2. ViPErLEED provides a modern LEED I(V) workflow covering spot tracking, extraction, and structural optimization. See the 2025 package papers in Phys. Rev. Research: Package I and Package II.

  3. Elastic Electron-Atom Scattering in Solids and Solid Surfaces (EEASiSSS) is authored by John Rundgren and first described in the paper: “J. Rundgren Phys. Rev. B 68 125405 (2003)”. This program takes a different approach to calculating phase shifts by using optimised muffin-tin potentials for surface slabs with preassigned surface core-level shifts. Whilst the source code is not publicly available online (to this author’s best knowledge), John Rundgren has been more than happy to assist when approached in the past.

    Note

    A pre-alpha EEASiSSS backend is now available via the ViPErLEED toolchain (alias: viperleed; see Scripts for CLI usage). Install with pip install "phaseshifts[viperleed]". Ongoing work is tracked in issue #92.

  4. A fortran program is described in “McGreevy, E., & Stewart, A.L. (- Apr 1978). A program for calculating elastic scattering phase shifts for an electron colliding with a one-electron target using perturbation theory. Computer Physics Communications, 14(1-2), 99-107.”, however this code is not publicly available online (pay-walled by journal).

Note

Should you know of alternatives, please either open an issue or (better yet) create a PR with changes to this documentation to keep this list up to date.