Skip to main content

matador

PyPI Version Zenodo MIT License GH Actions Coverage Status Documentation Status

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-).

docs/src/img/lipzn.png

Installation

In the simplest case (e.g. you already have Python 3.6+ set up), pip install matador-db is sufficient to get up and running, preferably in a fresh virtual environment. More detailed instructions can be found in the Installation instructions.

Tests can be run on your local machine with python -m unittest discover -v -b or simply with py.test (required pytest to be installed); in order to test CASTEP-running functionality, the tests will look for an MPI-enabled executable named castep on your $PATH.

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

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 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 the source code archive on Zenodo:

Matthew Evans, ml-evs/matador (2020), Zenodo. http://doi.org/10.5281/zenodo.3908574

Metadata

Release files for matador-db 0.9.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for matador-db 0.9.7
File Size Uploaded Provenance Actions
matador-db-0.9.7.tar.gz 5.1 MB Without provenance Details for matador-db-0.9.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for matador-db 0.9.7
File Interpreter ABI Platform Actions
matador_db-0.9.7-py3-none-any.whl Python 3 none any Details for matador_db-0.9.7-py3-none-any.whl

Total release size: 5.5 MB

Release files / matador-db-0.9.7.tar.gz

Download URL matador-db-0.9.7.tar.gz
Size 5.1 MB
Tags Source
SHA-256 checksum
How to use checksums
912cfe3a171d3d4a9df6896b94d1f3285e77200e978c6777153b0b49fb1a39e7
BLAKE2b-256 checksum
How to use checksums
f81e0fa3394db9b3499d93f140f145710fb6c1a5193bb58925561b3b4a0f3eee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.2.0.post20200511 requests-toolbelt/0.9.1 tqdm/4.46.0 CPython/3.7.7

Release files / matador_db-0.9.7-py3-none-any.whl

Download URL matador_db-0.9.7-py3-none-any.whl
Size 416.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b8b069abb457d6a7bd79bb4278b3420ceb893e6dc00bcfac3d60ef86823fadc4
BLAKE2b-256 checksum
How to use checksums
9f846d81187d47562535d8226a0ad3323fb9cfccf98f49805c9469a17a212a87
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/46.2.0.post20200511 requests-toolbelt/0.9.1 tqdm/4.46.0 CPython/3.7.7

Security for matador-db 0.9.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page