quantum-esperanto

================= Quantum Esperanto

.. image:: https://travis-ci.org/tilde-lab/quantum_esperanto.svg?branch=master :target: https://travis-ci.org/tilde-lab/quantum_esperanto .. image:: https://badge.fury.io/py/quantum_esperanto.svg :target: https://badge.fury.io/py/quantum_esperanto

Quantum Esperanto is a fast parser of XML files output by DFT codes (vasp as of now) written in Cython. It takes advantage of lxml, a Python wrapper around libxml2 library, and its Cython interface. XML files are parsed to a Python dictionary in a transparent way. It is really fast, up to 10 times faster than the parser used by pymatgen_ project.

Installation

The development versions of libraries libxml2 and libxslt must be present in the system. Check with the command:

::

$ xslt-config

Also, C compiler such as gcc must be present. The recommended way of installing Quantum Esperanto is with pip from PyPI:

::

$ pip install quantum_esperanto

If one is interested in obtaining latest versions of the package, it can be installed using the source code from GitHub_:

::

$ git clone https://github.com/tilde-lab/quantum_esperanto $ cd quantum_esperanto $ pip install .

The Python prerequisites for the package are numpy and lxml (should be installed automatically with pip).

It is possible to install the package in development mode. This will install Cython as well as nose test suite. To do it issue the following command after cloning the repository and changing the directory:

::

$ cd quantum_esperanto $ pip install -e .[dev]

After install it is possible to run several tests to check if the installation was completed successfully. It can be done with the following commands in quantum_esperanto directory:

::

$ python setup.py test

If everything is OK, you're all set to start using the package.

Usage

The parser can be used in a very simple way. First, the parser has to be instantiated, and then the parse_file method of the parser returns the dictionary of parsed values:

.. code:: python

from quantum_esperanto.vasp import VaspParser parser = VaspParser() d = parser.parse_file('vasprun.xml')

The possible arguments for the parser are:

recover (boolean, default: True) a flag that allows recovering broken XML. It is very useful in case of unfinished calculations; however, it exits on the first XML error and the returned dictionary contains parsed values up to the first XML error only. When XML recovery is needed, a warning is printed to stderr.

whitelist (list, default: None) the list of parent tag names that are only needed to parsed. If None, then all tags are parsed.

Parsing result

The result of parsing is a dictionary that follows the structure of vasprun.xml. The keys of the dictionary are either tag names (for i, v, varray tags), or tag:tag name construction (for tags that do have name attribute), or just tags themselves. The values are either tag contents converted to the right type (specified by type tag attribute) or (in case of varrays and sets) Numpy arrays. Fortran overflows (denoted by *****) are converted to NaNs in case of float values and to MAXINT in case of integer values.

Example:

xml file

.. code:: xml

1.43300000 1.43300000 1.43300000 1.43300000 -1.43300000 -1.43300000 -1.43300000 1.43300000 -1.43300000 11.77059895 0.34891835 0.34891835 0.00000000 0.34891835 -0.00000000 -0.34891835 -0.00000000 0.34891835 -0.34891835 0.00000000 0.00000000 0.00000000

resulting dictionary (printed with pprint):

.. code:: python

{'structure:primitive_cell': {'crystal': {'basis': array([[ 1.433, 1.433, 1.433], [ 1.433, -1.433, -1.433], [-1.433, 1.433, -1.433]]), 'rec_basis': array([[ 0.34891835, 0.34891835, 0. ], [ 0.34891835, -0. , -0.34891835], [-0. , 0.34891835, -0.34891835]]), 'volume': 11.77059895}, 'positions': array([[ 0., 0., 0.]])}}

License

Quantum Esperanto is licensed under MIT license.

.. _GitHub: http://www.github.com/tilde-lab/quantum_esperanto .. _pymatgen: https://pymatgen.org