kliff.dataset.configuration

class kliff.dataset.configuration.Configuration(cell, species, coords, PBC, energy=None, forces=None, stress=None, weight=None, identifier=None)[source]

Class of atomic configuration. This is used to store the information of an atomic configuration, e.g. supercell, species, coords, energy, and forces.

Parameters:

  • cell (ndarray) – A 3x3 matrix of the lattice vectors. The first, second, and third rows are a_1, a_2, and a_3, respectively.

  • species (List[str]) – A list of N strings giving the species of the atoms, where N is the number of atoms.

  • coords (ndarray) – A Nx3 matrix of the coordinates of the atoms, where N is the number of atoms.

  • PBC (List[bool]) – A list with 3 components indicating whether periodic boundary condition is used along the directions of the first, second, and third lattice vectors.

  • energy (Optional[float]) – energy of the configuration.

  • forces (Optional[ndarray]) – A Nx3 matrix of the forces on atoms, where N is the number of atoms.

  • stress (Optional[List[float]]) – A list with 6 components in Voigt notation, i.e. it returns \sigma=[\sigma_{xx},\sigma_{yy},\sigma_{zz},\sigma_{yz},\sigma_{xz}, \sigma_{xy}]. See: https://en.wikipedia.org/wiki/Voigt_notation

  • weight (Optional[Weight]) – an instance that computes the weight of the configuration in the loss function.

  • identifier (Union[str, Path, None]) – a (unique) identifier of the configuration

classmethod from_file(filename, weight=None, file_format='xyz')[source]

Read configuration from file.

Parameters:

  • filename (Path) – Path to the file that stores the configuration.

  • file_format (str) – Format of the file that stores the configuration (e.g. xyz).

to_file(filename, file_format='xyz')[source]

Write the configuration to file.

Parameters:

  • filename (Path) – Path to the file that stores the configuration.

  • file_format (str) – Format of the file that stores the configuration (e.g. xyz).

classmethod from_colabfit(database_client, data_object, weight=None)[source]

Read configuration from colabfit database .

Parameters:

  • database_client (MongoDatabase) – Instance of connected MongoDatabase client, which can be used to fetch database from colabfit-tools dataset.

  • data_object (dict) – colabfit data object dictionary to be associated with current configuration and property.

  • weight (Optional[Weight]) – an instance that computes the weight of the configuration in the loss function.

to_colabfit(database_client, data_object, weight=None)[source]

Save configuration from colabfit database.

Parameters:

  • database_client (MongoDatabase)

  • data_object (dict)

  • weight (Optional[Weight])

Returns:

classmethod from_ase_atoms(atoms, weight=None, energy_key='energy', forces_key='forces', stress_key='stress')[source]

Read configuration from ase.Atoms object.

Parameters:

  • atoms (Atoms) – ase.Atoms object.

  • weight (Optional[Weight]) – an instance that computes the weight of the configuration in the loss function.

  • energy_key (str) – Name of the field in extxyz that stores the energy.

  • forces_key (str) – Name of the field in extxyz that stores the forces.

  • stress_key (str) – Name of the field in extxyz that stores the stress.

to_ase_atoms()[source]

Convert the configuration to ase.Atoms object.

Returns:

ase.Atoms representation of the Configuration

property cell: ndarray

3x3 matrix of the lattice vectors of the configurations.

property PBC: List[bool]

A list with 3 components indicating whether periodic boundary condition is used along the directions of the first, second, and third lattice vectors.

property species: List[str]

Species string of all atoms.

property coords: ndarray

A Nx3 matrix of the Cartesian coordinates of all atoms.

property energy: float | None

Potential energy of the configuration.

property forces: ndarray

Return a Nx3 matrix of the forces on each atoms.

property stress: List[float]

Stress of the configuration. The stress is given in Voigt notation i.e \sigma=[\sigma_{xx},\sigma_{yy},\sigma_{zz},\sigma_{yz},\sigma_{xz}, \sigma_{xy}].

property weight

Get the weight class of the loss function.

property identifier: str

Return identifier of the configuration.

property fingerprint

Return the stored fingerprint of the configuration.

property path: Path | None

Return the path of the file containing the configuration. If the configuration is not read from a file, return None.

property metadata: dict

Return the metadata of the configuration.

get_num_atoms()[source]

Return the total number of atoms in the configuration.

Return type:

int

get_num_atoms_by_species()[source]

Return a dictionary of the number of atoms with each species.

Return type:

Dict[str, int]

get_volume()[source]

Return volume of the configuration.

Return type:

float

count_atoms_by_species(symbols=None)[source]

Count the number of atoms by species.

Parameters:

symbols (Optional[List[str]]) – species to count the occurrence. If None, all species present in the configuration are used.

Returns:

with key the species string, and value the number of

atoms with each species.

Return type:

{specie, count}

order_by_species()[source]

Order the atoms according to the species such that atoms with the same species have contiguous indices.

to_dict()[source]
Return type:

dict

classmethod bulk(**kwargs)[source]

Transparent wrapper to get KLIFF configuration from bulk ASE atoms. Mostly for convenience.

Parameters:

**kwargs – All the args that will be passed to ase.build.bulk

Return type:

Configuration

Returns:

Configuration

get_supercell(nx=1, ny=1, nz=1)[source]

Generate supercell from a configuration.

Parameters:

  • nx (int) – repetition along x-axis

  • ny (int) – repetition along y-axis

  • nz (int) – repetition along z-axis

Return type:

Configuration

Returns:

Configuration

exception kliff.dataset.configuration.ConfigurationError(msg)[source]