This package is a Python-based implementation of the Barbieri/Van Hove phase shift (a.k.a. phshift) calculation package needed to produce elastic electron atom scattering (EEAS) phase shifts for modelling within various LEED packages (including CLEED), as well as for certain XPD packages.

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 eventual goal is to integrate with LEED-IV/XPD computational packages to iteratively generate phase shifts during model optimisation.

Contributions are welcome. Please see the contribution requirements and workflow in CONTRIBUTING.md, and review the Code of Conduct.

Currently, it primarily uses the Barbieri/Van Hove phase shift calculation package as the calculation backend wrapped using f2py, however, there is also preliminary support for John Rundgren's EEASiSSS package as an alternative backend. Both backends benefit from a few Python modules to provide a more user-friendly interface to automate a lot of the work for the end user.

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."

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

The Elastic Electron-Atom Scattering in Solids and Surface Slabs (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 ⁶ applied together with Mattheiss's superposition method.
  2. The DFT-SCF program of V. Eyert using the full-potential Augmented Spherical Wave method ⁷.
  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.

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

After installing the package, you can use the new CLI entry points:

• Run the main CLI (default phase shift calculation):

  python -m phaseshifts --help
  # or
  python -m phaseshifts phsh [args]

• Run the atomic orbital generator subcommand:

  python -m phaseshifts atorb --output-dir ./atorb_lib --rel --ngrid 2000 --method HF

• You can also invoke the CLI subpackage directly:

  python -m phaseshifts.cli --help

• If installed as a script (via pip/uv), you can use:

  phaseshifts --help
  phaseshifts phsh [args]
  phaseshifts atorb [args]

The CLI provides two main subcommands:

• phsh (default): Phase shift calculation (see phsh.py for details)
• atorb: Generate atomic orbital input files for all known elements

For more information please read the documentation at http://pythonhosted.org/phaseshifts/ (latest PyPI release) or GitHub Pages (latest master)

The simplest and most reliable cross-platform way to run phsh.py is through docker:

# obtain the image
docker pull ghcr.io/Liam-Deacon/phaseshifts:latest  # should only need to do this once

docker run ghcr.io/Liam-Deacon/phaseshifts:latest  # will display usage

# or more generally (adjust as needed)
docker run ghcr.io/Liam-Deacon//phaseshifts:latest -v /path/to/host/input/data:/data [<phsh-args> ...]

Alternatively, if you have uv installed, you can use the following command:

# run phsh.py directly from uv
uv --python=3.11 --from git+https://github.com/Liam-Deacon/phaseshifts.git#master phsh.py

Alternatively, if you have uv installed, you can use the following command:

# run phsh.py directly from uv
uv run --python=3.11 --with=git+https://github.com/Liam-Deacon/phaseshifts.git#master --script phaseshifts/phsh.py

For python 3.11 or older:

#  install latest release
pip install phaseshifts

# optional extras
pip install "phaseshifts[viperleed]" # EEASiSSS backend support (alias: viperleed)
pip install "phaseshifts[input]"     # structured input (YAML/JSON) + validation
pip install "phaseshifts[atorb]"     # extra element helpers for atorb
pip install "phaseshifts[gui]"       # Qt GUI dependencies
pip install "phaseshifts[docs]"      # documentation build deps
pip install "phaseshifts[test]"      # test deps (pytest, pytest-cov)
pip install "phaseshifts[dev]"       # dev tooling (black/isort/ruff, etc.)

# development install
uv --python=3.11 venv # create a virtual environment using uv (optional)
source venv/bin/activate # Linux/Mac systems => activate the virtual environment (optional)
python -m ensurepip
pip install wheel numpy setuptools  # needed for older python/pip versions
pip install -e '.[gui,dev,test]' # extra deps are only needed for development/testing purposes
phsh --help

To enable pre-commit hooks (recommended for local development):

pre-commit install
pre-commit run --all-files

For Windows users, here's a step-by-step guide to install phaseshifts with all necessary build dependencies:

1. Install Python 3.9-3.14 from python.org or via Windows Store

   • Make sure to check "Add Python to PATH" during installation

2. Install Microsoft Visual C++ Build Tools (required for Python package compilation):

   • Download from Microsoft C++ Build Tools
   • Or install Visual Studio Community with C++ development tools

3. Install MinGW-w64 (for Fortran compilation):

   # Using chocolatey (if you have it)
   choco install mingw

   Or download and install manually from: https://www.mingw-w64.org/downloads/

4. Install CMake (for modern build system):

   # Using chocolatey
   choco install cmake

   Or download from: https://cmake.org/download/

1. Create a virtual environment (recommended):

   # Open Command Prompt or PowerShell
   python -m venv phaseshifts-env
   
   # Activate the environment
   phaseshifts-env\Scripts\activate

2. Install build dependencies:

   python -m pip install --upgrade pip setuptools wheel
   pip install numpy scipy periodictable
   
   # For Python 3.12+ (modern build system)
   pip install scikit-build cmake
   
   # For development (optional)
   pip install pytest flake8

3. Install phaseshifts:

   # Latest release from PyPI
   pip install phaseshifts
   
   # Or development version from GitHub
   pip install git+https://github.com/Liam-Deacon/phaseshifts.git
   
   # Or for local development
   git clone https://github.com/Liam-Deacon/phaseshifts.git
   cd phaseshifts
   pip install -e ".[dev,test]"

4. Verify installation:

   python -c "import phaseshifts; print('Success!')"
   phsh.py --help

• "error: Microsoft Visual C++ 14.0 is required": Install Visual Studio Build Tools as described above
• "gfortran not found": Ensure MinGW-w64 is installed and gfortran.exe is in your PATH
• "CMake not found": Install CMake and ensure it's in your PATH
• DLL import errors: Try installing the Visual C++ Redistributable from Microsoft

conda create -n phaseshifts python=3.11 numpy scipy
conda activate phaseshifts
pip install phaseshifts

The phaseshifts package requires CPython 2.7 or later and also uses the numpy, scipy and periodictable packages. Currently, it has only been tested most extensively with Python 2.7 on Windows, so there are no guarantees with other platforms. To perform a setup follow the steps below.

1. Install the numpy, scipy and periodictable packages.

   On systems compatible with PyPI this can be done using the command:

   pip install numpy scipy periodictable

   Or if you have the easy_install package:

   easy_install install numpy scipy periodictable

   Older versions of numpy & scipy did not allow simultaneous installation -if you experience problems then try first installing numpy before attempting to install scipy. The periodictable package allows lookup of the most common crystal structure for a given element and is instrumental in many of the convenience functions contained in the model module.

   Alternatively download and install these packages manually following the instructions provided for the respective packages.

2. To install the phaseshifts package:

   python setup.py install

   With any luck the package has been installed successfully. A set of test scripts are provided, however a simple check may suffice using an interactive session of the python interpreter:

   >>> import phaseshifts
   >>> from phaseshifts.lib import libphsh # compiled FORTRAN .pyd or .so using f2py

   If these execute without errors then it is likely that all is well, but in case of problems or bugs please use the contact provided below and I will do my best to address the problem quickly.

The example source codes 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 - a brief user guide/documentation concerning the input files (& details of the original fortran phshift package).
• phaseshifts API - 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 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.

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.

phsh.py --help

The phaseshifts package incorporates code from the Barbieri/Van Hove phase shift calculation package. Use of this package is subject to the following conditions:

• Citation: If you use phaseshifts in published work, you must acknowledge and cite the original authors as follows:

"The LEED calculations and phase shift computations were performed using the phaseshifts package, which incorporates code from the Barbieri/Van Hove phase shift calculation package."

A. Barbieri and M.A. Van Hove, private communication (https://www.icts.hkbu.edu.hk/vanhove/)

• Redistribution: Redistribution of the Barbieri/Van Hove phase shift calculation package, or any package that includes it (including phaseshifts), is prohibited without prior permission from the original authors. Please direct users to the official repository or website.

• Warranty: This software is provided "as is", without warranty of any kind. Use is at your own risk.

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. 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 is 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.
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).

As with all scientific progress, we stand on the shoulders of giants. If this package is of use to you in publishing papers then please acknowledge the following people who have made this package a reality:

• A. Barbieri and M.A. Van Hove - who developed most of the original fortran code. Use A. Barbieri and M.A. Van Hove, private communication. (see doc/phsh2007.txt for further details).
• E.L. Shirley - who developed part of the fortran code during work towards his PhD thesis (refer to the thesis: E.L. Shirley, "Quasiparticle calculations in atoms and many-body core-valence partitioning", University of Illinois, Urbana, 1991).
• Christoph Gohlke - who developed the elements.py module used extensively throughout for the modelling convenience functions (see 'elements.py' for license details).

I would also be grateful if you acknowledge this python package (phaseshifts) as: L.M. Deacon, private communication.

I wish to personally add a heart-felt thanks to both Eric Shirley and Michel Van Hove who have kindly allowed the use of their code in the libphsh.f file needed for the underlying low-level functions in this package.

The checked-in f2py artifacts phaseshifts/lib/libphshmodule.c and phaseshifts/lib/libphsh-f2pywrappers.f are used for deterministic builds (notably Python 3.8) when f2py generation is skipped. Regenerate them when phaseshifts/lib/libphsh.f or phaseshifts/lib/libphsh.pyf changes.

Requirements:

• f2py version: 1.26.4 (from numpy 1.26.4)
• numpy minimum (build/runtime): numpy>=1.16.6; use numpy==1.26.4 to match the committed wrapper generation
• Python: use Python 3.8-3.11 for regeneration (avoid 3.12+ for f2py distutils removal)
• Fortran compiler: gfortran (Linux/macOS) or MinGW gfortran (Windows)
• C compiler toolchain appropriate for your platform (gcc/clang/MSVC)

Regeneration steps:

1. Create and activate a virtual environment.

2. Install build tooling:

   pip install "numpy==1.26.4" "setuptools<63" "wheel"

3. From the repo root, run:

   python -m numpy.f2py -m libphsh -c phaseshifts/lib/libphsh.pyf \
     phaseshifts/lib/libphsh.f --build-dir /tmp/libphsh-f2py

4. Copy the generated files into the repo:

   • /tmp/libphsh-f2py/libphshmodule.c -> phaseshifts/lib/libphshmodule.c
   • /tmp/libphsh-f2py/libphsh-f2pywrappers.f -> phaseshifts/lib/libphsh-f2pywrappers.f

5. Run the test matrix or at least pytest tests/test_phsh_backend.py -v and commit the updated wrappers.

You can generate gcov/gcovr coverage for the Fortran core:

1. Install test dependencies: pip install '.[test]' (includes gcovr).
2. Build with coverage flags by exporting PHASESHIFTS_FORTRAN_COVERAGE=1 (CMake automatically adds -g -fprofile-arcs -ftest-coverage; you can also set CMAKE_ARGS="-DENABLE_FORTRAN_COVERAGE=ON" explicitly).
3. Run tests with pytest tests -v --fortran-coverage --cov=phaseshifts --cov-report=xml. When coverage data exists, fortran-coverage.xml is written at the repo root and uploaded by CI on Linux runners.

This package is developed/maintained in my spare time so any bug reports, patches, or other feedback are very welcome.

The project is (still) in the early developmental stages and so anyone who wishes to get involved are most welcome. Please either create an issue or (better yet) submit a pull request.

For agentic coding guidelines, Copilot instructions, and best practices, please see AGENTS.md in the root of this repository. The file .github/copilot-instructions.md is a pointer to AGENTS.md for compatibility with GitHub and Copilot workflows.

1. Documentation - the manual has been started, but is not complete and thus is a high priority. The current aim is to use sphinx to generate html and latex documents for semi-automated generation of both the tutorial and supporting website. If you have the phaseshifts source and the sphinx and the numpydoc PyPi packages then you can try making html or latex manuals using make html or make latexpdf commands from the doc/ directory.
2. Test suit to verify the package is working as expected.
3. GUI frontend (Qt ui files are provided in the gui/ directory for anyone wishing to undertake this challenge). Other front ends are welcome (I use Qt due to familiarity/experience). For those wishing a sneak preview, try executing main.pyw

See either todo issues or TODO.rst for more information.

• Liam Deacon - current maintainer
• Michel Van Hove - Contact for original LEEDPACK phsh[0-3].f programs