matador

matador: a Python library for analysing, curating and performing high-throughput density-functional theory calculations - Published in JOSS (2020)

https://github.com/ml-evs/matador

Keywords

Keywords from Contributors

Scientific Fields

Repository

⚗️ matador is an aggregator, manipulator and runner of first-principles calculations, written with a bent towards battery 🔋 electrode materials.

README.rst

=======
matador
=======

| |PyPI Version| |GH Actions| |Binder|
| |Documentation Status| |MIT License| |Coverage Status|
| |JOSS| |Zenodo|


matador is an aggregator, manipulator and runner of first-principles calculations, written with a bent towards battery electrode materials.
The source can be found on `GitHub `_ and online documentation is hosted at `ReadTheDocs `_.

Example Jupyter notebooks and tutorials can be found `online `_ or in the ``examples/`` folder of the matador source code.

Written & maintained by `Matthew Evans `_ (2016-).


.. image:: docs/src/img/hull.png
   :name: LiPZn
   :align: center

Installation
------------

In the simplest case (e.g. you already have Python 3.7+ set up), ``pip install matador-db`` is sufficient to get up and running, preferably in a fresh virtual environment.

Upgrading to the latest version should be as simple as ``pip install -U matador-db``.

For an editable development installation, clone the source code from this repository and run ``pip install -e .`` from the matador folder. Tests can be run on your local machine with ``python -m unittest discover -v -b`` or simply with ``py.test`` after test dependencies have been installed with ``pip install .[test]``. In order to test CASTEP-running functionality, the tests will look for an MPI-enabled executable named ``castep`` on your ``$PATH``.

Further instructions can be found in the `Installation instructions `_.


Usage
------

``matador`` is primarily a Python *library* that can be used inside Python scripts/modules to create a custom workflow. There are, however, several command-line scripts bundled with ``matador`` itself. All of these scripts are listed under `CLI Usage `_.

For basic command-line usage, please explore the help system for each command. Common workflows can be found inside ``examples/`` and in the `online docs `_.

Please consult the full `Python API documentation `_ for programmatic usage.

Core functionality
-------------------

The API has many features that can be explored in the examples and API documentation. As a summary, ``matador`` can be used for:

- Scraping of CASTEP (and Quantum Espresso) input/output files into flexible Python dictionaries/models.
- The creation and curation of MongoDB collections of geometry optimisation calculations, with a powerful querying CLI/API.
- Customisable, publication-ready plots for all models, e.g. phase diagrams, PDF, PXRD, voltage profiles, electronic/vibrational bandstructures etc.
- High-throughput geometry optimisations, electronic and vibrational properties using CASTEP (and Quantum Espresso) with ``run3``. Tested on several supercomputers. ``run3`` is designed primarily for simple workflows and offers little in the way of tools for creating complex workflows; if this is your use case, then check out some of the other codes listed below.
- Creation of phase diagrams and electrochemical voltage profiles from the results of DFT calculations.

This functionality is achieved by interfacing with much of the standard scientific Python stack (`NumPy `_, `SciPy `_, `matplotlib `_), some more materials-specific packages (`spglib `_, `SeeK-path `_, `periodictable `_) and other general packages (`pymongo `_, `python-ternary `_, `numba `_).

Similar packages
----------------

This package is by no means unique in its functionality or goals. Below is a list of similar packages and an overview of where they overlap with ``matador``:

- `ASE `_: manipulation of structures, parsing and exporting files, running jobs and local databases with ``ase-db``. An interface is provided to ASE's ``Atoms`` object.
- `pymatgen `_: similar to ASE, with a focus on the VASP DFT code. An interface is provided to pymatgen's ``Structure`` object. Local databases can be constructed with the `pymatgen-db `_ add-on and high-throughput workflows are achieved with `Fireworks `_.
- `AiiDA `_: high-throughput job running, provenance tracking and database storage for many simulation codes.
- `sumo `_ publication quality plotting, primarily for VASP but also with support for other codes.

If you think this list is outdated, incorrect or simply incomplete, then please raise an issue!

Citing matador
--------------

If you use matador in your work, we kindly ask that you cite

    Matthew L. Evans, Andrew J. Morris, *matador: a Python library for analysing, curating and performing high-throughput density-functional theory calculations* Journal of Open Source Software, 5(54), 2563 (2020)
    `10.21105/joss.02563 `_

Source code archives for all versions above 0.9 can be found at Zenodo `DOI 10.5281/zenodo.3908573 `_.


.. |PyPI Version| image:: https://img.shields.io/pypi/v/matador-db?label=PyPI&logo=pypi
   :target: https://pypi.org/project/matador-db/
.. |GH Actions| image:: https://img.shields.io/github/actions/workflow/status/ml-evs/matador/ci.yml?branch=master
   :target: https://github.com/ml-evs/matador/actions?query=branch%3Amaster
.. |MIT License| image:: https://img.shields.io/badge/license-MIT-blue.svg
   :target: https://github.com/ml-evs/matador/blob/master/LICENSE
.. |Coverage Status| image:: https://img.shields.io/codecov/c/gh/ml-evs/matador/master?logo=codecov
   :target: https://codecov.io/gh/ml-evs/matador
.. |Documentation Status| image:: https://readthedocs.org/projects/matador-db/badge/?version=stable
   :target: https://matador-db.readthedocs.io/en/stable/?badge=stable
.. |Zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3908573.svg
   :target: https://doi.org/10.5281/zenodo.3908573
.. |Binder| image:: https://mybinder.org/badge_logo.svg
   :target: https://mybinder.org/v2/gh/ml-evs/matador/master?filepath=examples/interactive
.. |JOSS| image:: https://joss.theoj.org/papers/4d0eea9bea4362dec4cb6d62ebccc913/status.svg
   :target: https://joss.theoj.org/papers/4d0eea9bea4362dec4cb6d62ebccc913

Owner

JOSS Publication

matador: a Python library for analysing, curating and performing high-throughput density-functional theory calculations

Published

October 27, 2020

DOI

10.21105/joss.02563

Volume 5, Issue 54, Page 2563

Authors

Matthew L. Evans
Theory of Condensed Matter Group, Cavendish Laboratory, University of Cambridge, J. J. Thomson Avenue, Cambridge, CB3 0HE, U.K.

Andrew J. Morris
School of Metallurgy and Materials, University of Birmingham, Edgbaston, Birmingham, B15 2TT, U.K.

Editor

Jeff Gostick

Tags

density-functional theory ab initio crystal structure prediction materials discovery databases castep quantum espresso mongodb

View PDF Review Thread Software Archive

Citation (CITATION.cff)

# YAML 1.2
# Metadata for citation of this software according to the CFF format (https://citation-file-format.github.io/)
cff-version: 1.2.0
message: If you use this software, please cite the following article and versioned archive.
title: "matador"
doi: 10.5281/zenodo.3908573
authors:
- given-names: Matthew L.
  family-names: Evans
  affiliation: University of Cambridge
  orcid: https://orcid.org/0000-0002-1182-9098
repository-code: https://github.com/ml-evs/matador
url: https://github.com/ml-evs/matador
type: software
license: MIT
preferred-citation:
  type: article
  authors:
  - given-names: Matthew L.
    family-names: Evans
    affiliation: University of Cambridge
    orcid: https://orcid.org/0000-0002-1182-9098
  - given-names: Andrew J.
    family-names: Morris
    affiliation: University of Birmingham
    orcid: https://orcid.org/0000-0001-7453-5698
  doi: "10.21105/joss.02563"
  journal: "Journal of Open Source Software"
  title: "matador: a Python library for analysing, curating and performing high-throughput density-functional theory calculations"
  volume: 5
  number: 54
  year: 2020

GitHub Events

Committers

Last synced: 5 months ago

Issues and Pull Requests

Last synced: 4 months ago

Packages