Package: phaseshifts
PHASESHIFTS PACKAGEThis 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. To quote the original authors' site:"The phase shift calculation is performed in several steps:Calculation of the radial charge density for a free atom.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.Calculation of phase shifts from the muffin-tin potential.Elimination of pi-jumps in the energy dependence of the phase
shifts."[!NOTE]
You can get the original Fortran source (& learn more about thephshiftprograms) from Michel Van Hove's LEED Calculation Home Page:https://www.icts.hkbu.edu.hk/VanHove_files/leed/leedpack.htmlA local copy of the source files can be found underphaseshifts/lib/.phsh.orig/phsh[0-2].f.RunningThephsh.pyscript (available after
installing the package) aims to simplify these steps with a single
command. For more information please read the documentation athttp://pythonhosted.org/phaseshifts/(latest PyPI release) orGitHub
Pages(latest master)The simplest and most reliable cross-platform way to runphsh.pyis through docker:# obtain the imagedockerpullghcr.io/Liam-Deacon/phaseshifts:latest# should only need to do this once# run phsh.py via the docker imagedockerrunghcr.io/Liam-Deacon/phaseshifts:latest# will display usage# or more generally (adjust as needed)dockerrunghcr.io/Liam-Deacon//phaseshifts:latest-v/path/to/host/input/data:/data[<phsh-args>...][!TIP]
Development docker images can be built locally, e.g.DOCKER_TAG=dev make docker[!WARNING]
There is aknown possible
bugwhere the
compiledlibphsh.fis not thread-safe (as ascertained by the fortran
compiler), as such if you anticipate using this library in concurrent
environments then it is advised to runphsh.pyviadocker run ghcr.io/Liam-Deacon/phaseshifts:latestas this works
around this limitation due to the emphereal nature of container
instances created usingdocker run.InstallTDLR;For python 3.11 or older:#  install latest releasepipinstallphaseshifts# development installpipinstallwheelnumpysetuptools# needed for older python/pip versionspipinstall-e.
phsh--helpDetailsThephaseshiftspackage requires CPython 2.7 or later and also uses thenumpy,scipyandperiodictablepackages. 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.Install the numpy, scipy and periodictable packages.On systems compatible with PyPI this can be done using the
command:pipinstallnumpyscipyperiodictableOr if you have the easy_install package:easy_installinstallnumpyscipyperiodictableOlder 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.To install the phaseshifts package:pythonsetup.pyinstallWith 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:>>>importphaseshifts>>>fromphaseshifts.libimportlibphsh# compiled FORTRAN .pyd or .so using f2pyIf 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.[!TIP]
On Windows systems it may be easier to install a scientific python
distibution rather than install the dependencies from source -Python(x,y)orAnacondawith mingw (gcc &
gfortran) installed is highly recommended. Mac OS X users can simply
dobrew install gfortranand Debian/Ubuntu users can dosudo apt-get install -y gfortran.[!NOTE]
On unix systems, setup the virtualenv on Python 3.10 or lower,
activate it and runmake.[!WARNING]
Python 3.12 compatibility is a work in progress due to the removal ofnumpy.distuilsbuild backend forf2pypreventing simple
installation viapip install,this github
issuetracks
progress on fixing this known issue.About the codeThe 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 indoc/folder:phshift2007- a brief user guide/documentation concerning the
input files (& details of the original fortranphshiftpackage).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 thephsh2007document. See theexamples/directory
to get an idea of the structure of the input files (for a random
selection of models & elements). In particular see thecluster_Ni.ifile 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 theabasis vector for
the unit cell (SPA units). Next, after creating a bulk and slab model in
thecluster.iformat, simply use the following python code:>>>fromphaseshifts.phshimportWrapperasphsh>>>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 utilityphsh.pyis provided as a way of
automating the generation of phase shifts as part of a script. For
more information use:phsh.py--help[!NOTE]
Thephaseshifts.leedmodule provides a
conversion class for CLEED.inpand.bulfiles. This is included
as part of thephsh.pymodule, 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 malformatted input at some
point in the future.AlternativesA number of alternatives are available, notably the following:AQuaLEED(with
a usefulposter overview of phaseshifts
calculations).
This is an officially mentioned piece of software on Michel Van
Hove'sLEED Calculation Homepage. Although the
poster mentions that the software is written in python, this
software is not (currently) distributed onhttps://PyPI.org(or via alternative means such as a docker image onDockerHub)  and
therefore harder to integrate with other python LEED-related
projects such asCLEEDandcleedpy.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 eitheropen an
issueor (better yet) create
a PR with changes to this documentation to keep this list up to date.AcknowledgementsAs 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. BarbieriandM.A. Van Hove- who developed most of the
original fortran code. UseA. Barbieri and M.A. Van Hove, private
communication.(seedoc/phsh2007.txtfor 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.ThanksI 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 thelibphsh.ffile needed for the underlying low-level functions in this
package.ContactThis 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 eithercreate an issueor (better yet) submit apull request.[!TIP]
Pleasestarit on GitHub as this will help
to easily indicate that others find the package useful.To DoDocumentation - 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 thesphinxand thenumpydocPyPi packages
then you can try making html or latex manuals usingmake htmlormake latexpdfcommands from thedoc/directory.Test suit to verify the package is working as expected.GUI frontend (Qt ui files are provided in thegui/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 executingmain.pywSee eithertodo issuesorTODO.rstfor more information.ContactsLiam Deacon-current maintainerMichel Van Hove- Contact for
original LEEDPACKphsh[0-3].fprograms