Installation

Requirements

Note

This package is compatible with pymatgen 2024.10.3 and later versions. Earlier versions of pymatgen may not work correctly due to API changes.

Installation using pip

surface-pd can be installed directly from its Git repository with pip.

$ pip install git+https://github.com/urban-group/surface-pd.git

Installation from source code

The package can also be built from surface-pd GitHub by git clone and installed locally:

$ git clone https://github.com/urban-group/surface-pd.git
$ cd surface-pd
$ pip install .

Additional requirements

Note

In order to use the enumeration functionalities provided in this package, the enum.x and makestr.x must be in the path.

You can run the following several lines of code to compile the enumlib source code in your terminal.

$ git clone  --branch v2.0.4 --recursive https://github.com/msg-byu/enumlib.git
$ make -C enumlib/symlib/src F90=gfortran
$ make -C enumlib/src F90=gfortran
$ make -C enumlib/src F90=gfortran enum.x
$ make -C enumlib/src F90=gfortran makestr.x

After compilation, copy both executables into a directory on PATH. For example, if ~/.local/bin is already on PATH:

$ cp enumlib/src/enum.x enumlib/src/makestr.x ~/.local/bin/

To check whether the enumeration utilities are available:

$ which enum.x makestr.x

The paths to these two files should be located.

Installation test

After installation, you should be able to see three scripts, they are:

$ surface-enumeration
$ surface-pd-plot
$ generate-discharge-pd

To check whether the surface-pd package is successfully installed, you can try if the following command can be executed:

$ surface-enumeration -h

The user-friendly command-line interfaces with help and usage messages should be automatically generated. Something like:

$ surface-enumeration -h
usage: surface-enumeration [-h] [--generate-poscar] INPUT_JSON
This code will enumerate the input slab model with user defined target
species and composition. The input slab structure should be as small as
possible because the unit cell of the slab will also be enumerated, and it
will increase the number of possibilities that the enumeration can have.
For the detailed algorithm behind the enumeration, please see the
following references below.
(1) Morgan, W. S.; Hart, G. L. W.; Forcade, R. W.
Computational Materials Science 2017, 136, 144–149.
https://doi.org/10.1016/j.commatsci.2017.04.015.
...
...