Structures

StructureContainer

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
import numpy as np

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

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

sensing_matrix, target_energies = 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.
available_properties

List of the available properties.

Return type:List[str]
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, print_minimum=10)[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
  • print_minimum (int) – number of lines printed from the top and the bottom of the orbit list if print_threshold is exceeded
static read(infile)[source]

Reads StructureContainer object from file.

Parameters:infile (Union[str, Binaryio, Textio]) – file from which to read
write(outfile)[source]

Writes structure container to a file.

Parameters:outfile (Union[str, Binaryio, Textio]) – output file name or file object

Structure

class icet.Structure

This class stores the cell metric, positions, chemical symbols, and periodic boundary conditions that describe a structure. It also holds information pertaining to the components that are allowed on each site and provides functionality for computing distances between sites.

Parameters:
  • positions (list of vectors) – list of positions in Cartesian coordinates
  • chemical_symbols (list of strings) – chemical symbol of each case
  • cell (3x3 array) – cell metric
  • pbc (list of booleans) – periodic boundary conditions
  • tolerance (float) – numerical tolerance imposed when testing for equality of positions and distances
atomic_numbers

atomic numbers of species on each site

Type:list of ints
cell

cell metric

Type:list(list(float))
chemical_symbols

chemical symbols of species on each site

Type:list of strings
find_lattice_site_by_position()

Returns the lattice site that matches the position.

Parameters:position (list/NumPy array) – position in Cartesian coordinates
Returns:lattice site
Return type:LatticeSite object
find_lattice_sites_by_positions()

Returns the lattice sites that match the positions.

Parameters:positions (list of lists/NumPy arrays) – list of positions in Cartesian coordinates
Returns:list of lattice sites
Return type:list of LatticeSite object
find_site_by_position()

Returns the index of the site that matches the position.

Parameters:position (list/NumPy array) – position in Cartesian coordinates
Returns:site index
Return type:int
classmethod from_atoms(conf)

Returns the input configuration as an icet Structure object.

Parameters:conf (Atoms) – input configuration
Returns:
Return type:atomic configuration
get_atomic_numbers()

Returns a list of the species occupying each site by atomic number.

get_cell()

Returns the cell metric.

get_chemical_symbols()

Returns a list of the species occupying each site by chemical symbol.

get_distance()

Returns the distance between two sites

Parameters:
  • index1 (int) – index of the first site
  • index2 (int) – index of the second site
  • offset1 (vector) – offset to be applied to the first site
  • offset2 (vector) – offset to be applied to the second site
Returns:

distance in length units

Return type:

float

get_pbc()

Returns the periodic boundary conditions.

get_position()

Returns the position of a specified site

Parameters:site (LatticeSite object) – site of interest
Returns:position in Cartesian coordinates
Return type:vector
get_positions()

Returns the positions in Cartesian coordinates.

Returns:
Return type:list of NumPy arrays
get_unique_site()

Returns the unique site.

Parameters:index (int) – index of site of interest
Returns:index of unique site
Return type:int
get_unique_sites()

Returns the unique sites.

Returns:
Return type:list of ints
pbc

periodic boundary conditions

Type:list(int)
positions

atomic positions in Cartesian coordinates

Type:list of lists
set_atomic_numbers()

Sets the species occupying each site by atomic number.

Parameters:atomic_numbers (list of ints) – new species by atomic number
set_cell()

Sets the cell metric.

set_chemical_symbols()

Sets the species occupying each site by chemical symbol.

Parameters:chemical_symbols (list of strings) – new species by chemical symbol
set_number_of_allowed_species()

Sets the number of allowed species on each site.

This method allows one to specify for each site in the structure the number of species allowed on that site.

Parameters:numbersOfAllowedSpecies (list of int) –

Sets the number of allowed species on each site.

This method allows one to specify for each site in the structure the number of species allowed on that site.

Parameters:numbersOfAllowedSpecies (int) –
set_pbc()

Sets the periodic boundary conditions.

set_positions()

Sets the positions in Cartesian coordinates.

Parameters:positions (list of NumPy arrays) – new positions in Cartesian coordinates
set_unique_sites()

Sets the unique sites.

This method allows one to specify for each site in the structure the unique site it is related to.

Parameters:unique_sites (list of ints) – site of interest
to_atoms()

Returns the structure as an ASE Atoms object.

Returns:
Return type:atomic configuration
unique_sites

unique sites

Type:list of ints