Usage

The UPFDict class is the heart of upf-tools. It is an ordered dictionary with a few extra functionalities.

class UPFDict(version, filename=None, *args, **kwargs)

Class that contains all of the information of a UPF pseudopotential file.

Note that it will usually be more convenient to create a UPFDict object using the class method UPFDict.from_upf(...) i.e.

from upf_tools import UPFDict
psp = UPFDict.from_upf("/path/to/file.upf")

instead of direct instantiation.

Parameters:

version (str, Version) – the UPF version number
filename (Union[str, Path, None]) – the name of the UPF file
args – arguments used to construct the dictionary of UPF entries (header, mesh, local, …)
kwargs – keyword arguments used to construct the dictionary of UPF entries

property filename: Path: The filename of the pseudopotential (including the path), protected to always be a Path.

classmethod from_str(string)

Create a UPFDict object from a string (typically the contents of a .upf file).

Return type:: UPFDict

classmethod from_upf(filename)

Create a UPFDict object from a .upf file.

Return type:: UPFDict

to_dat()

Generate a .dat file from a UPFDict object.

These files contain projectors that wannier90.x can read.

Raises:: ValueError – The pseudopotential does not contain the pseudo-wavefunctions necessary to generate a .dat file
Return type:: str
Returns:: the contents of a .dat file

to_input()

Extract the contents of the input file block.

Return type:: str

to_ld1_input()

Extract the ld1.x input file used to generate the pseudopotential.

Return type:: str

to_oncvpsp_input()

Extract the oncvpsp.x input file used to generate the pseudopotential.

Return type:: ONCVPSPInput

to_str()

Serialise this UPFDict back to UPF text.

Currently only UPF v2 (the modern XML format) is supported on write. Reading is unaffected; v1 files can still be loaded but not written back out.

The result is not byte-for-byte the file that was read. Two differences affect PP_INFO in particular:

a block that contains a PP_INPUTFILE keeps only that input file, the human-readable summary alongside it having been discarded on read;
ampersands are written escaped, so the namelist that ld1.x quotes verbatim comes back as &input.

Raises:: NotImplementedError – if version is below 2.0.
Return type:: str
Returns:: the UPF file contents as a string

to_upf(filename)

Write this UPFDict to filename in UPF v2 format.

Parameters:: filename (Union[Path, str]) – destination path
Return type:: Path
Returns:: the Path written to

property version: Version: The UPF version of the pseudopotential file, protected to always be a Version.

When only the header of a pseudopotential is wanted, read_header fetches it without reading the body.

read_header(source)

Read the header of a UPF file without reading or parsing its body.

The file is read only as far as the end of its header, so a body that upf_tools.UPFDict.from_upf() chokes on still yields a header:

from upf_tools import read_header

read_header("Si.upf")["pseudo_type"]  # 'NC', 'US', 'USPP', 'PAW', ...

The entries are those the full parser puts under psp["header"]. UPF v1 headers carry no pseudo_type; there the US/NC/PAW field is reported as the boolean is_ultrasoft, again matching the full parser.

A header that is absent or malformed raises ValueError.

Parameters:: source (Union[str, Path, IO[Any]]) – path to a UPF file, or an open stream holding one
Return type:: Dict[str, Any]
Returns:: the header entries, keyed and typed as the full parser reports them

header_from_str(contents)

Extract the header from the contents of a UPF file.

contents need only reach the end of the header; what follows is ignored, whether or not upf_tools.UPFDict.from_str() could parse it. A header that is absent or malformed raises ValueError.

Parameters:: contents (str) – a UPF file, or enough of one to contain the header
Return type:: Dict[str, Any]
Returns:: the header entries, keyed and typed as the full parser reports them