FPdataViewer

Reads first-principle atomic structures files and graphs various statistics to provide a small overview of the file's content using matplotlib. Built around VASP MLFF input and output files: ML_AB and ML_ABN. Either saves to a PDF file (plot) or launches matplotlib (plot --interactive).

Also provides some tools for converting between file types using ASE (convert), repairing broken files (validate), and quickly inspecting the contents files (inspect). Some of these tools are also provided by the ASE CLI, and will become obsolete when the vasp-mlab format is implemented).

Table of contents

• Installation
• Requirements
• Usage
  • plot
  • inspect
  • convert
  • validate
• Config

Installation

pip

The easiest method is to install through pip.

pip install fpdataviewer

Installation through pip is the preferred method, but will pull in a number of large libraries used in analysis, some of which may not be supported on Windows. If this is not preferable, consider installing with --no-deps and using --skip to avoid said libraries (see requirements and options).

conda

# NOT CURRENTLY AVAILABLE

Requirements

Not all dependencies are required when --skip is used.

Usage

fpdataviewer plot

Main functionality. Graphs statistics into pdf or onto screen (with `--interactive``).

# Basic PDF generation
fpdataviewer plot -i examples/ML_AB -o overview.pdf

# Interactive plots
fpdataviewer plot -i examples/ML_AB --interactive

# Specify custom config
fpdataviewer plot -i examples/ML_AB --config mlab_viewer.json

# Skip radial distribution functions and image rendering, rasterize remaining graphs
fpdataviewer plot --rasterize --skip rdf img

fpdataviewer inspect

Summarized file contents to console, no analysis. Recommened to use before plotting large files.

fpdataviewer inspect -i examples/ML_AB

fpdataviewer convert

Converts between file types using ASE. Useful for reading ML_AB files, otherwise recommended to use ASE CLI directly instead.

# Convert first structure in ML_AB file to a POSCAR file
fpdataviewer convert -i examples/ML_AB -o examples/POSCAR -f vasp-mlab -t vasp -x 0

fpdataviewer validate

Validates the input file and reports problems. Some formats (like VASP's ML_AB) contain redundant or possibly self-contradictory information that can cause parsers to fail unpredictably. This option will check the input file against specifications to minimize these errors and help the user repair the broken file.

fpdataviewer validate -i examples/ML_AB

Config file

Specifying a custom config will override settings from the default, which is located in config.py.

{
  "global": {
    "bins": 100
  },
  "rdf": {
    "bins": 1000,
    "structures": 1.0,
    "r_min": 0.0,
    "r_max": "auto",
    "skip_pairs": []
  },
  "descriptors": {
    "structures": 1.0,
    "soap": {
      "r_cut": "auto",
      "n_max": 8,
      "l_max": 8
    }
  },
  "rendering": {
    "width": 1024,
    "height": 1024
  }
}

Most settings are self-explanatory, but more specifically:

• "descriptors"
  • See DScribe documentation. The inner content is fed to the respective (local) descriptor object. It should specify one of
    • "soap"
    • "acsf"
    • "lmbtr"
• "rdf"
  • "skip_pairs" is an array of values "<atom 1>-<atom 2>" (e.g. "Bi-O"). Usually RDF calculations are fast enough for this to be unnecessary.
• Anywhere
  • "structures" specify the number of structures to be included in some calculation, chosen at random. It should specify
    • 0.0 < x < 1.0 for a portion
    • x > 1 for a specific number
  • "auto" will be replaced with the maximum possible radius such that radii never overlap in a periodic structure (the non periodic distance in the overview panel).