Structure containers

class icet.StructureContainer(cluster_space: icet.core.cluster_space.ClusterSpace)[source]

This class serves as a container for structure objects as well as their fit properties and cluster vectors.


cluster_space (icet.ClusterSpace) – cluster space used for evaluating the cluster vectors


The following snippet illustrates the initialization and usage of a StructureContainer object. The construction of a structure container is convenient for compiling the data needed to train a cluster expansion, i.e., a sensing matrix and target energies:

>>> from import bulk
>>> from icet import ClusterSpace, StructureContainer
>>> from import enumerate_structures
>>> from random import random

>>> # create cluster space
>>> prim = bulk('Au')
>>> cs = ClusterSpace(prim, cutoffs=[7.0, 5.0],
...                   chemical_symbols=[['Au', 'Pd']])

>>> # build structure container
>>> sc = StructureContainer(cs)
>>> for structure in enumerate_structures(prim, range(5), ['Au', 'Pd']):
>>>     sc.add_structure(structure,
...                      properties={'my_random_energy': random()})
>>> print(sc)

>>> # fetch sensing matrix and target energies
>>> A, y = sc.get_fit_data(key='my_random_energy')
add_structure(structure: ase.atoms.Atoms, user_tag: Optional[str] = None, properties: Optional[dict] = None, allow_duplicate: bool = True, sanity_check: bool = True)[source]

Adds a structure to the structure container.

  • structure – the atomic structure to be added

  • user_tag – custom user tag to label structure

  • properties – scalar properties. If properties are not specified the structure object will be checked for an attached ASE calculator object with a calculated potential energy

  • allow_duplicate – whether or not to add the structure if there already exists a structure with identical cluster-vector

  • sanity_check – whether or not to carry out a sanity check before adding the structure. This includes checking occupations and volume.

property available_properties: List[str]

List of the available properties.

property cluster_space: icet.core.cluster_space.ClusterSpace

Cluster space used to calculate the cluster vectors.

get_condition_number(structure_indices: Optional[List[int]] = None, key: str = 'energy')float[source]

Returns the condition number for the sensing matrix.

A very large condition number can be a sign of multicollinearity, read more here

  • structure_indices – list of structure indices; by default (None) the method will return all fit data available.

  • key – key of properties dictionary


Return type

condition number of the sensing matrix

get_fit_data(structure_indices: Optional[List[int]] = None, key: str = 'energy')Tuple[numpy.ndarray, numpy.ndarray][source]

Returns fit data for all structures. The cluster vectors and target properties for all structures are stacked into numpy arrays.

  • structure_indices – list of structure indices; by default (None) the method will return all fit data available.

  • key – key of properties dictionary


Return type

cluster vectors and target properties for desired structures

get_structure_indices(user_tag: Optional[str] = None)List[int][source]

Get structure indices via user_tag


user_tag – user_tag used for selecting structures


List of structure’s indices

Return type

list of integers

print_overview(print_threshold: Optional[int] = None)[source]

Prints a list of structures in the structure container.


print_threshold – if the number of orbits exceeds this number print dots

static read(infile: Union[str, BinaryIO, TextIO])[source]

Reads StructureContainer object from file.


infile – file from which to read

write(outfile: Union[str, BinaryIO, TextIO])[source]

Writes structure container to a file.


outfile – output file name or file object