Command-line usage

Many of matador’s entry points will make use of any .matadorrc config file they find. Customisation options can be found under getting_started.

Main entry points

matador has 3 main CLI entry points that are added to your $PATH on installation:

  • matador: used to interact with databases.

  • run3: used to run calculations at high-throughput on the local machine.

  • dispersion: used to plot electronic or vibrational properties from local files containing the output of the relevant calculations.

Each of these has many options/sub-commands, which can be explored using --help.

Script entry points

There are also several convenience scripts bundled with matador. These scripts are not as well-supported as the main API, but please raise an issue on GitHub if they do not behave as expected. These scripts are also added to your $PATH on installation and can be found in the scripts/ folder of a development install. If you have a workflow that only requires simple script usage but is not yet supported, or if you have a script you would like to contribute, please raise an issue on GitHub.

Analysis scripts

  • compare_pdfs: compute PDF overlaps and plot differences from .res file input.

  • pxrd_calculator: compute, plot and export PXRD patterns from .cif file input.

  • dbtools: simple script for dropping MongoDB collections created by matador.

  • oddjob: a script for spawning jobs on compute nodes with no queuing and shared filesystems, e.g. oddjob 'run3 <seed>' -n 1 3 5 -p cpu- will spawn run3 processes on compute nodes with names cpu-1, cpu-3 and cpu-5.

  • fryan: a stripped down version of matador query that operates on folders of .res files.

  • plot_convergence: plots the output of a run3 convergence run.

  • standardize_cell: for an input .res file, standardize the cell (optionally to primitive) with spglib and write out a new file.

File converter scripts

These scripts all use matador’s internal file readers/writers to operate on lists of files provided at the CLI: e.g. x3y *.x will read all .x files in a folder and output a series of .y files. This is not an all-to-all process, these scripts have only been written when needed. If you need quick access to a file converter, either write your own script based on the below, or request the converter script in an issue on GitHub.

  • atoms3shx: use ASE’s file reader on any arbitrary file, and output a .res file.

  • castep3shx, castep3cell: convert a CASTEP output file into .res or .cell respectively.

  • cell3shx, cif3shx, magres3shx: convert a CASTEP .cell, .cif, .magres or Quantum Espresso output file into a .res file.

  • shx3cell, shx3cif, shx3pwscf: convert a .res file into either .cell, .cif, or Quantum Espresso .in input file.