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: A load/dump style may have additional Python package requirements in order to work. Check the documentation on each style for more details.

2. Load

Each style defines its own load function, which can be called directly as atomman.load_<style>(), (e.g. atomman.load_poscar()) or by calling atomman.load(style). The underlying code for the load functions can be found in the atomman/load directory.

2.1 atomman.load_<style>()

Style-specific load functions.

Parameters

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

2.2. atomman.load()

Common load function that can be used for any style. Convenient for loading user-specified data as the format style is a string parameter.

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

Similarly, each style defines its own dump function that can be called with atomman.dump_<style>() or atomman.dump(style). The underlying code for the dump functions can be found in the atomman/dump directory.

3.1 atomman.dump_<style>()

Style-specific dump functions.

Parameters

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

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

3.2. atomman.dump()

Common dump function that can be used for any style.

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

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.