Configuration

Configuration info and arrays fields

Configurations inherit directly from ase.Atoms objects. Because of this, a Configuration can use its info and arrays dictionaries to store a large variety of information about the inputs/outputs and metadata of a calculation.

  • The Configuration.info dictionary uses strings as keys, and stores any arbitrary information about the Configuration as a whole (e.g., its name, computed energy, metadata labels, …)

  • The Configuration.arrays dictionary uses strings as keys, and stores arrays of per-atom data (e.g., atomic numbers, positions, computed forces, …)

Basics of Configurations

A Configuration stores all of the information about an atomic structure, i.e., the input to a calculation. The Configuration class inherits from the ase.Atoms class, and populates some required fields in its Atoms.info dictionary.

Configurations have four required fields, that are automatically created when a Configuration is instantiated:

  • ASE_ID_FIELD = "_id":

    An ObjectId that is created when the Configuration is instantiated, then never changed. Useful for uniquely identifying the Configuration when stored in a database.

  • ASE_NAME_FIELD = "_name":

    An arbitrary string, often specified by the creator of the Configuration. This should usually be a human-readable string.

  • ASE_LABELS_FIELD = "_labels":

    A set of short strings used for providing queryable metadata about the Configuration.

  • ASE_CONSTRAINTS_FIELD = "_constraints":

    A set of strings that can be used as keys for Configuration.info or Configuration.arrays, specifying that the given fields should be considered as additional inputs to a calculation

Building Configurations

The most common way a Configuration object is built is by loading data files using one of the Converter objects provided in this package. For example, if working with an Extended XYZ file containing multiple structures, a list of Configurations can be created as below:

from colabfit.tools.converters import EXYZConverter

converter = EXYZConverter()

configurations = converter.load(...)

or, equivalently, using the load_data() function.

from colabfit.tools.database import load_data

configurations = load_data(...)
class colabfit.tools.configuration.Configuration(description='', labels=None, constraints=None, *args, **kwargs)

A Configuration is an extension of an ase.Atoms object that is guaranteed to have the following fields in its info dictionary:

  • ATOMS_ID_FIELD = :code:”_id”

  • ATOMS_NAME_FIELD = :code:”_name”

  • ATOMS_LABELS_FIELD = :code:”_labels”

  • ATOMS_CONSTRAINTS_FIELD = :code:”_constraints”

__eq__(other)

Two Configurations are considered to be identical if they have the same hash value. This means that their atomic positions, atomic numbers, simulation cell vectors, and periodic boundary conditions must match to within 16 decimal places.

__hash__()

Generates a hash for self by hashing its length positions, (atomic) numbers, simulation cell, and periodic boundary conditions.

Note that the positions and cell vectors are rounded to 16 decimal places before being compared.

hashlib is used instead of hash() to avoid hash randomisation.

__init__(description='', labels=None, constraints=None, *args, **kwargs)

Constructs a Configuration. Calls ase.Atoms.__init__(), then populates the additional required fields.

Parameters

description (str) – A human-readable description. Can also be a list of strings.

__str__()

Return str(self).

classmethod from_ase(atoms)

Generates a Configuration from an ase.Atoms object.