# Structure containers¶

class icet.StructureContainer(cluster_space)[source]

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

Parameters

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

Example

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 ase.build import bulk
>>> from icet import ClusterSpace, StructureContainer
>>> from icet.tools 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']):
...                      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, user_tag=None, properties=None, allow_duplicate=True, sanity_check=True)[source]

Adds a structure to the structure container.

Parameters
• structure (Atoms) – the atomic structure to be added

• user_tag (Optional[str]) – custom user tag to label structure

• properties (Optional[dict]) – 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 (bool) – whether or not to add the structure if there already exists a structure with identical cluster-vector

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

property available_properties

List of the available properties.

Return type

List[str]

property cluster_space

Cluster space used to calculate the cluster vectors.

Return type

ClusterSpace

get_condition_number(structure_indices=None, key='energy')[source]

Returns the condition number for the sensing matrix.

A very large condition number can be a sign of multicollinearity, read more here https://en.wikipedia.org/wiki/Condition_number

Parameters
• structure_indices (Optional[List[int]]) – list of structure indices; by default (None) the method will return all fit data available.

• key (str) – key of properties dictionary

Returns

Return type

condition number of the sensing matrix

get_fit_data(structure_indices=None, key='energy')[source]

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

Parameters
• structure_indices (Optional[List[int]]) – list of structure indices; by default (None) the method will return all fit data available.

• key (str) – key of properties dictionary

Returns

Return type

cluster vectors and target properties for desired structures

get_structure_indices(user_tag=None)[source]

Get structure indices via user_tag

Parameters

user_tag (Optional[str]) – user_tag used for selecting structures

Returns

List of structure’s indices

Return type

list of integers

print_overview(print_threshold=None)[source]

Prints a list of structures in the structure container.

Parameters

print_threshold (Optional[int]) – if the number of orbits exceeds this number print dots

static read(infile)[source]

infile (Union[str, BinaryIO, TextIO]) – file from which to read
write(outfile)[source]
outfile (Union[str, BinaryIO, TextIO]) – output file name or file object