Introduction to atomman: Load and dump conversions

Lucas M. Hale, lucas.hale@nist.gov, Materials Science and Engineering Division, NIST.

Disclaimers

1. Introduction

Atomman features an number of built-in converters between the atomman.System class and other representations of atomic configurations. This includes text-based representations for storing atomic information as files, and representations used by other Python packages. All conversions between the different format options are handled in a similar manner by defining the two operations

  • load creates a System object based on another representation.

  • dump converts a System object to another representation.

NOTE: Some of the load/dump styles have additional Python package requirements in order to work. Check the documentation on each style for more details.

NOTE Updated versions 1.4.4-1.4.6 The individual load_{style} and dump_{style} functions were removed in favor of using load(style) and dump(style) exclusively. This was done to allow for more modular handling of the different styles.**

2. Load

Common load function that accesses the different load styles. The underlying code for the load styles can be found in the atomman/load directory.

2.1. atomman.load()

Parameters

  • style (str) indicates the format of the content being loaded.

  • content (any) the content to be loaded. For text formats, can be a str of the content, a file path or a file-like object.

  • **kwargs (any) any extra style-specific keyword arguments.

3. Dump

3.1. atomman.dump()

Common dump function that accesses the different dump styles. The underlying code for the dump styles can be found in the atomman/dump directory.

Parameters

  • style (str) indicates the format of the content to dump to.

  • system (atomman.System) The system to convert.

  • **kwargs (any) any extra style-specific keyword arguments.

3.2. System.dump()

The System class also defines a dump() method that calls atomman.dump() on itself.

Parameters

  • style (str) indicates the format of the content to dump to.

  • **kwargs (any) any extra style-specific keyword arguments.

4. Supported styles

This is the list of currently supported styles and links to more in-depth discussion of each.

system_model The JSON/XML data model designed for representing all data associated with an atomman.System object.

poscar POSCAR is a common text format used by VASP and other DFT-centric codes.

cif CIF is a standard format for representing crystallographic data.

table Tabulation of per-atom properties. This is primarily used by other methods.

atom_data LAMMPS data files used to define initial atomic data.

atom_dump LAMMPS dump files used to retrieve computed atomic properties.

ase_Atoms, phonopy_Atoms The Python class representation of atomic systems used by the ase and phonopy Python packages.

pymatgen_Structure The Python class representation of atomic systems used by the pymatgen Python package.

spglib_cell The atomic data used by the spglib Python package for analyzing space group information.

prototype A crystal_prototype record found in the NIST Interatomic Potentials Repository database.

crystal A relaxed_crystal record found in the NIST Interatomic Potentials Repository database. Each relaxed crystal is specific to an interatomic potential.

dft_reference A reference crystal structure from a DFT database (Materials Project or OQMD).

primitive_cell Identifies and returns the primitive unit cell for a system. Uses [spglib].

conventional_to_primitive and primitive_to_conventional Converts standard unit cells between primitive and conventional settings with the focus on allowing crystal operations relative to either setting.