Command Line Interface (CLI)
While surfaxe
has a full python API (see our tutorials page for example usage) it also has an
intuitive command line interface (CLI). Below are some simple examples of what you can do with
surfaxe
at the command line.
You can get a full list of accepted flags and what they do for each command using
the --help
or -h
flag, e.g.:
$ surfaxe-bonds -h
> usage: surfaxe-bonds [-h] [-s STRUCTURE] [-b BOND [BOND ...]]
[--oxi-list OX_STATES_LIST [OX_STATES_LIST ...]]
[--oxi-dict OX_STATES_DICT] [--no-csv]
[--csv-fname CSV_FNAME] [--no-plot]
[--plt-fname PLT_FNAME] [-c COLOR] [--width WIDTH]
[--height HEIGHT] [--dpi DPI] [--yaml]
Parses the structure looking for bonds between atoms. Check the validity of
the nearest neighbour method on the bulk structure before using it on slabs.
optional arguments:
-h, --help show this help message and exit
-s STRUCTURE, --structure STRUCTURE
Filename of structure file in any format supported by
pymatgen (default: POSCAR
-b BOND [BOND ...], --bond BOND [BOND ...]
List of elements e.g. Ti O for a Ti-O bond
--oxi-list OX_STATES_LIST [OX_STATES_LIST ...]
Add oxidation states to the structure as a list
e.g. 3 3 -2 -2 -2
--oxi-dict OX_STATES_DICT
Add oxidation states to the structure as a dictionary
e.g. Fe:3,O:-2
--no-csv Prints data to terminal
--csv-fname CSV_FNAME
Filename of the csv file (default: bond_analysis.csv)
--no-plot Turns off plotting
--plt-fname PLT_FNAME
Filename of the plot (default: bond_analysis.png)
-c COLOR, --color COLOR
Color of the marker in any format supported by mpl
e.g. "#eeefff" hex colours starting with # need to be
surrounded with quotation marks
--width WIDTH Width of the figure in inches (default: 6)
--height HEIGHT Height of the figure in inches (default: 5)
--dpi DPI Dots per inch (default: 300)
--yaml YAML Read all args from a yaml config file. Completely
overrides any other flags set
The behaviour of default parameters of the functions is extensively documented in
the surfaxe
python package section of the docs.
Pre-processing commands
surfaxe-generate-slabs: Generates all unique slabs with specific Miller indices or up to a maximum Miller index for a set of slab and vacuum thicknesses.
Example: surfaxe-generate -s bulk_structure.cif --hkl 1,1,0 -t 20 40 -v 20 40 -f
generates
all slabs for the (1,1,0) direction for minimum slab and vacuum thicknesses of 20 Å and 40 Å.
The -f
option organises these into subdirectories with all required VASP input
files required to run singleshot calculations uisng default settings. It includes all combinations
for zero-dipole terminations with inversion symmetry.
The directory structure produced is:
100/ <-- Miller index
├── 20_20_0/ <-- slab-thickness_vacuum-thickness_termination-number
├── 20_40_0/
├── 40_20_0/
└── 40_40_0/
├── POSCAR <-- VASP files
├── INCAR
├── POTCAR
└── KPOINTS
Note: The hkl flag must be comma-separated with no spaces and the list of thicknesses and vacuums must be space-separated.
Note: To use the :mod:`-f` option you must first set up the `pymatgen POTCAR environment <https://pymatgen.org/installation.html#potcar-setup>`_.
Similarly, to above the script can be modified to consider multiple Miller indices.
Example: surfaxe-generate -s bulk_structure.cif --hkl 1,1,0 1,1,1 -t 20 40 -v 20 40 -f
generates all (1,1,0) and (1,1,1) slabs with minimum slab and vacuum thicknesses of 20 Å and 40 Å.
Note: h,k,l are comma-separated with no spaces, while the two (or more) Miller indices are space-separated.
Lastly, a maximum hkl value can be supplied as an integer so that the script finds all zero-dipole slabs up to that maximum Miller index.
Example: surfaxe-generate -s SnO2.cif --hkl 2 -t 20 40 -v 30
generates all slabs with Miller
indices up to a maximum value of 2, with minimum slab thicknesses of 20 Å and of 40 Å, and
minimum vacuum thickness of 30 Å.
Post-processing commands
surfaxe-parse-energies: Parses data produced by electronic structure codes once calculations have been run in then directory structures produced by the pre-processing commands. Can optionally collect vacuum and core energies.
Example: surfaxe-parse-energies --hkl 0,0,1 -b 8.83099
saves a csv file of surface energies
and energies per atom for each slab-vacuum combination. See the Tutorials directory for examples.
surfaxe-plot-surfen and surfaxe-plot-enatom can be used to customise the surface energy and energy per atom plots independetnly based on the data already collated with surfaxe-parse-energies.
surfaxe-parse-structures: Parses the (relaxed) structures from convergence calculations and collates them into the same json format as is created when surface slabs are generated. Can optionally perform bond analysis for multiple specified bonds. Useful for comparison of relaxed and unrelaxed surfaces slabs and determination of convergence.
Analysis commands
surfaxe-potential: Reads the local electrostatic potential file and plots the planar and macroscopic averages normal to the surface. Currently only the VASP LOCPOT file is supported as input.
Example: surfaxe-potential -l LOCPOT -v 11.5
produces a plot assuming a lattice vector of
11.5 Angstroms and saves the plot data to a csv file.
surfaxe-bonds: Analyse bonding in the structure using Pymatgen’s local_env module. Average bond lengths for each pair of species of interest can be plotted as a function of c lattice vector (normal to the slab surface). This can be useful for checking whether the center of the slab has converged, where bond distances should be bulk-like.
Example: surfaxe-bonds -s CONTCAR -b Sn O
plots the average Sn-O bond length from the
VASP output structure file. A csv file of the data plotted is also produced.
surfaxe-plot-potential and surfaxe-plot-bonds can be used to generate the plots based on the data collated with surfaxe-potential and surfaxe-bonds, allowing customisation of plots without having to re-analyse the data. All plotting functionality is accessible through the main functions as well.
surfaxe-simplenn and surfaxe-complexnn: Analyse the bonding in the slab, again using Pymatgen functions. simplenn is faster, but less reliable for systems with more complex bonding. complexnn is more robust but requires a dictionary of cutoff bond lengths to be supplied for each pair of species. See the analysis tutorial for further explanation.
Example: surfaxe-complexnn -s CONTCAR_bivo4 -b Bi3+ O2- 2.46 V5+ O2- 1.73
will
analyse the coordination of atoms in this BiVO4 slab and save them to a csv file.
Data commands
There are some simple convenience commands that can also be used to extract key values from
raw data files produced by solid state codes. Currently only commands relating to VASP output
files are included, which rely on the surfaxe vasp_data
module. We hope to expand this
in the future.
surfaxe-vacuum and surfaxe-core can be used to extract vacuum and core energies, respectively, that are needed to calculate absolute electron energies (ionisation potential and electron affinity). See the Macrodensity tutorials for more information on the steps needed to do this.
YAML input files
Most CLI commands allow use of YAML input files containing all the arguments which cannot be
used in conjunction with other command line argument flags. This is done by specifying
the --yaml
flag which overrides any other flags set in command line by loading the
surfaxe_config.yaml
file.
Sample YAML input files for each of the functions, with defaults and comments are in
the surfaxe/cli/templates
folder.
All **kwargs
of the main function can be passed in the YAML file.
Example: Generation of (1,0,1) CdTe slabs could easily customised so that all VASP input files are created with specific INCAR tags using the following config.yaml file:
structure: CdTe.cif
hkl: (1,0,1)
thicknesses: [20, 40]
vacuums: [20, 40]
make_fols: True
make_files: True
max_size: 500
center_slab: True
ox_states:
Cd: 2
Te: -2
fmt: poscar
name: POSCAR
config_dict: PBE_config.json
user_incar_settings:
ENCUT: 460
KPAR: 3
user_kpoints_settings:
reciprocal_density: 35
The slabs would then be generated using surfaxe-gethkl --yaml config.yaml