Additional Python components

BaseOptimizer

BaseOptimizer serves as base for all optimizers.

class icet.fitting.base_optimizer.BaseOptimizer(fit_data, fit_method, standardize=True, check_condition=True, seed=42)[source]

BaseOptimizer class.

Serves as base class for all Optimizers solving the linear \(\boldsymbol{X}\boldsymbol{a} = \boldsymbol{y}\) problem.

Parameters:
  • fit_data (tuple(numpy.ndarray, numpy.ndarray)) – the first element of the tuple represents the NxM-dimensional fit matrix A whereas the second element represents the vector of N-dimensional target values y; here N (=rows of A, elements of y) equals the number of target values and M (=columns of A) equals the number of parameters
  • fit_method (str) – method to be used for training; possible choice are “least-squares”, “lasso”, “elasticnet”, “bayesian-ridge”, “ardr”, “rfe”, “split-bregman”
  • standardize (bool) – if True the fit matrix and target values are standardized before fitting, meaning columns in the fit matrix and th target values are rescaled to have a standard deviation of 1.0.
  • check_condition (bool) – if True the condition number will be checked (this can be sligthly more time consuming for larger matrices)
  • seed (int) – seed for pseudo random number generator
compute_rmse(A, y)[source]

Returns the root mean squared error (RMSE) using \(\boldsymbol{A}\), \(\boldsymbol{y}\), and the vector of fitted parameters \(\boldsymbol{x}\), corresponding to \(\|\boldsymbol{A}\boldsymbol{x}-\boldsymbol{y}\|_2\).

Parameters:
  • A (ndarray) – fit matrix (N,M array) where N (=rows of A, elements of y) equals the number of target values and M (=columns of A) equals the number of parameters (=elements of x)
  • y (ndarray) – vector of target values
Return type:

float

fit_method

fit method

Return type:str
get_contributions(A)[source]

Returns the average contribution for each row of A to the predicted values from each element of the parameter vector.

Parameters:A (ndarray) – fit matrix where N (=rows of A, elements of y) equals the number of target values and M (=columns of A) equals the number of parameters
Return type:ndarray
n_nonzero_parameters

number of non-zero parameters

Return type:int
n_parameters

number of parameters (=columns in A matrix)

Return type:int
n_target_values

number of target values (=rows in A matrix)

Return type:int
parameters

copy of parameter vector

Return type:ndarray
parameters_norm

the norm of the parameters

Return type:float
predict(A)[source]

Predicts data given an input matrix \(\boldsymbol{A}\), i.e., \(\boldsymbol{A}\boldsymbol{x}\), where \(\boldsymbol{x}\) is the vector of the fitted parameters. The method returns the vector of predicted values or a float if a single row provided as input.

Parameters:A (ndarray) – fit matrix where N (=rows of A, elements of y) equals the number of target values and M (=columns of A) equals the number of parameters
Return type:Union[ndarray, float]
seed

seed used to initialize pseudo random number generator

Return type:int
standardize

if True standardize the fit matrix before fitting

Return type:bool
summary

comprehensive information about the optimizer

Return type:Dict[str, Any]
train()[source]
Return type:None
write_summary(fname)[source]

Writes summary dict to file

Cluster

This module provides the Cluster class.

class icet.core.cluster.Cluster
distances

list of distances between sites

Type:list of floats
from_python(lattice_sites, sort=False, clusterIndex=-1)

Construct a cluster from atoms and python lattice sites

order

order of the cluster (= number of sites)

Type:int
print()
radius

the radius of the cluster

Type:float
sites

site indices

Type:list of ints
sorted

True/False if the cluster is sorted/unsorted

Type:boolean
tag

cluster tag (defined for sorted cluster)

Type:int

ClusterCounts

This module provides the ClusterCounts class.

class icet.core.cluster_counts.ClusterCounts(orbit_list, structure)[source]

Provides an interface for inspecting cluster counts.

Parameters:
  • orbit_list (icet.OrbitList) – orbit list for a primitive structure
  • structure (ase.Atoms) – supercell of the structure that orbit_list is based on
cluster_counts

keys are representative clusters (icet Cluster objects) for all distinct orbits in the orbit list, values are dicts where the key is the chemical symbols of the species in a cluster, and the value is the number of counts of such clusters, e.g., {(‘Au’, ‘Ag’): 3, (‘Au’, ‘Au’): 5}.

Type:OrderedDict
count()

Counts the vectors in latticeSites assuming these sets of sites are represented by the cluster cluster.

Parameters:
  • structure (icet Structure) – structure that will have its clusters counted
  • latticeSites (list of list of LatticeSite objects) – group of sites, represented by cluster that will be counted
  • cluster (icet Cluster) – cluster used as identification on what sites the clusters belong to
  • orderIntact (bool) – if true the order of the sites will remain the same otherwise the vector of species being counted will be sorted
count_lattice_neighbors()
count_orbit_list()

Counts sites in the orbit list.

Parameters:
  • structure (icet Structure) –
  • orbit_list (icet OrbitList) –
  • order_intact (bool) – if true do not reorder clusters before comparison (i.e., ABC != ACB)
  • permuteSites (bool) – if true the sites will be permuted according to the corresponding permutations in the orbit
get_cluster_counts()
reset()

Geometry

icet.tools.geometry.ase_atoms_to_spglib_cell(structure)[source]

Returns a tuple of three components: cell metric, atomic positions, and atomic species of the input ASE Atoms object.

Return type:Tuple[ndarray, ndarray, ndarray]
icet.tools.geometry.atomic_number_to_chemical_symbol(numbers)[source]

Returns the chemical symbols equivalent to the input atomic numbers.

Parameters:numbers (List[int]) – atomic numbers
Return type:List[str]
icet.tools.geometry.chemical_symbols_to_numbers(symbols)[source]

Returns the atomic numbers equivalent to the input chemical symbols.

Parameters:symbols (List[str]) – chemical symbols
Return type:List[int]
icet.tools.geometry.find_lattice_site_by_position(structure, position, tol=0.0001)[source]

Tries to construct a lattice site equivalent from position in reference to the ASE Atoms object.

structure
input atomic structure
position
presumed cartesian coordinates of a lattice site
Return type:LatticeSite
icet.tools.geometry.fractional_to_cartesian(structure, frac_positions)[source]

Turns fractional positions into cartesian positions.

Parameters:
  • structure (Atoms) – input atomic structure
  • frac_positions (List[List[float]]) – fractional positions
Return type:

List[List[float]]

icet.tools.geometry.get_fractional_positions_from_neighbor_list(structure, neighbor_list)[source]

Returns the fractional positions of the lattice sites in structure from a neighbor list.

Parameters:
  • structure (Structure) – input atomic structure
  • neighbor_list (NeighborList) – list of lattice neighbors of the input structure
Return type:

List[List[float]]

icet.tools.geometry.get_occupied_primitive_structure(structure, allowed_species, symprec=1e-05)[source]

Returns an occupied primitive structure. Will put hydrogen on sublattice 1, Helium on sublattice 2 and so on

Parameters:
  • structure (Atoms) – input structure
  • allowed_species (List[List[str]]) – chemical symbols that are allowed on each site
  • symprec (float) – tolerance imposed when analyzing the symmetry using spglib

Todo

simplify the revert back to unsorted symbols

Return type:Tuple[Atoms, List[List[str]]]
icet.tools.geometry.get_permutation(container, permutation)[source]

Returns the permuted version of container.

Return type:Sequence[~T]
icet.tools.geometry.get_position_from_lattice_site(structure, lattice_site)[source]

Gets the corresponding position from the lattice site.

Parameters:
  • structure (Atoms) – input atomic structure
  • lattice_site (LatticeSite) – specific lattice site of the input structure
icet.tools.geometry.get_primitive_structure(structure, no_idealize=True, to_primitive=True, symprec=1e-05)[source]

Returns the primitive structure using spglib.

Parameters:
  • structure (Atoms) – input atomic structure
  • no_idealize (bool) – if True lengths and angles are not idealized
  • to_primitive (bool) – convert to primitive structure
  • symprec (float) – tolerance imposed when analyzing the symmetry using spglib
Return type:

Atoms

icet.tools.geometry.get_scaled_positions(positions, cell, wrap=True, pbc=[True, True, True])[source]

Returns the positions in reduced (or scaled) coordinates.

Parameters:
  • positions (ndarray) – atomic positions in cartesian coordinates
  • cell (ndarray) – cell metric
  • wrap (bool) – if True, positions outside the unit cell will be wrapped into the cell in the directions with periodic boundary conditions such that the scaled coordinates are between zero and one.
  • pbc (List[bool]) – periodic boundary conditions flags
Return type:

ndarray

icet.tools.geometry.get_wyckoff_sites(structure, symprec=0.0001)[source]

Returns the Wyckoff symbols of the input structure. The Wyckoff sites are of general interest for symmetry analysis but can be especially useful when setting up, e.g., a SiteOccupancyObserver. The Wyckoff labels can be conveniently attached as an array to the structure object as demonstrated in the Examples section below.

Note

The occupation of the sites is part of the symmetry analysis. Usually it is the symmetry of the “ideally” occupied lattice that is of interest. Hence, be mindful of the occupation when using this function.

Parameters:
  • structure (Atoms) – input structure, note that the occupation of the sites is included in the symmetry analysis
  • symprec (float) – tolerance parameter handed over to spglib

Examples

Wyckoff sites of a hexagonal-close packed structure:

from ase.build import bulk
from icet.tools import get_wyckoff_sites

structure = bulk('Ti')
wyckoff_sites = get_wyckoff_sites(structure)
print(wyckoff_sites)

Running the snippet above will produce the following output:

>> ['2d', '2d']

The Wyckoff labels can also be attached as an array to the structure, in which case the information is also included when storing the Atoms object:

from ase.io import write
structure.new_array('wyckoff_sites', wyckoff_sites, str)
write('structure.xyz', structure)

The function can also be applied to supercells:

structure = bulk('SiC', crystalstructure='zincblende', a=3.0).repeat(2)
wyckoff_sites = get_wyckoff_sites(structure)
print(wyckoff_sites)

This snippet will produce the following output:

>> ['4a', '4c', '4a', '4c', '4a', '4c', '4a', '4c',
    '4a', '4c', '4a', '4c', '4a', '4c', '4a', '4c']
Return type:List[str]

LatticeSite

This module provides a Python interface to the LatticeSite class.

LocalOrbitListGenerator

This module provides a Python interface to the LocalOrbitListGenerator class.

class icet.core.local_orbit_list_generator.LocalOrbitListGenerator
clear()

Clears the list of offsets and primitive-to-supercell map of the LocalOrbitListGenerator object

generate_full_orbit_list()

Generates and returns a local orbit list, which orbits included the equivalent sites of all local orbit list in the supercell.

generate_local_orbit_list()

Generates and returns the local orbit list from an input index corresponding a specific offset of the primitive structure.

Parameters:index (int) – index of the unique offsets list

Generates and returns the local orbit list from a specific offset of the primitive structure.

Parameters:unique_offset (NumPy array) – offset of the primitive structure
get_number_of_unique_offsets()

Returns the number of unique offsets

ManyBodyNeighborList

This module provides a Python interface to the ManyBodyNeighborList class.

class icet.core.many_body_neighbor_list.ManyBodyNeighborList
build()
calculate_intersection()

NeighborList

This module provides a Python interface to the NeighborList class with supplementary functions.

icet.core.neighbor_list.get_neighbor_lists(structure, cutoffs=None)[source]

Returns a list of icet neighbor lists given a configuration and cutoffs.

Parameters:
  • structure (Union[Atoms, Structure]) – atomic configuration
  • cutoffs (Optional[List[float]]) – positive floats indicating the cutoffs for the various clusters
Return type:

List[NeighborList]

Orbit

This module provides the Orbit class.

class icet.core.orbit.Orbit
add_equivalent_sites()
allowed_permutations

Get the list of equivalent permutations for this orbit.

If this orbit is a triplet and the permutation [0,2,1] exists this means that The lattice sites [s1, s2, s3] are equivalent to [s1, s3, s2] This will have the effect that for a ternary CE the cluster functions (0,1,0) will not be considered since it is equivalent to (0,0,1).

equivalent_sites

List of equivalent Lattice Sites

get_all_possible_mc_vector_permutations()

Similar to get all permutations but needs to be filtered through the number of allowed elements.

Parameters:
  • allowed_components (list of int) – The allowed components for the lattice sites, allowed_components[i] correspond to the lattice site self.representative_sites[i].
  • all_mc_vectors (returns) –
get_allowed_sites_permutations()
get_equivalent_sites()
get_equivalent_sites_permutations()
get_mc_vectors()

Return the mc vectors for this orbit given the allowed components. The mc vectors are returned as a list of tuples

Parameters:allowed_components (list of int) – The allowed components for the lattice sites, allowed_components[i] correspond to the number of allowed compoments at lattice site orbit.representative_sites[i].
get_representative_cluster()

The representative cluster represents the geometrical version of what this orbit is.

get_representative_sites()
get_sites_with_permutation()

Return the permuted to representative sites of equivalent_sites[index].

order

Returns the order of the orbit. The order is the same as the number of bodies in the representative cluster or the number of lattice sites per element in equivalent_sites.

permutations_to_representative

list of permutations; permutations_to_representative[i] takes self.equivalent_sites[i] to the same order as self.representative_sites.

This can be used if you for example want to count elements and are interested in difference between ABB, BAB, BBA and so on. If you count the lattice sites that are permuted according to these permutations then you will get the correct counts.

permuted_sites

Get the equivalent sites but permuted to representative site.

radius

Returns the radius of the representative cluster.

representative_cluster

The representative cluster represents the geometrical version of what this orbit is.

representative_sites

The representative sites is a list of lattice sites that are uniquely picked out for this orbit which can be used to represent and distinguish between orbits.

sort()

Sort the equivalent sites list.

OrbitList

This module provides the OrbitList class.

class icet.core.orbit_list.OrbitList(structure_in, cutoffs)[source]

The orbit list object handles an internal list of orbits.

An orbit has a list of equivalent sites with the restriction that at least one site is in the cell of the primitive structure.

Parameters:
  • structure (Atoms) – This structure will be used to construct a primitive structure on which all the lattice sites in the orbits are based.
  • cutoffs (list of float) – the i-th element of this list is the cutoff for orbits with order i+2
add_orbit()

Add an Orbit object to the OrbitList

clear()

Clears the list of orbits.

get_number_of_nbody_clusters()

Returns the number of orbits in the OrbitList

get_orbit()

Returns a copy of the orbit at the position i in the OrbitList

get_orbit_list()

Returns the list of orbits

get_primitive_structure()

Returns the primitive atomic structure used to construct the OrbitList instance

get_supercell_orbit_list(structure)[source]

Returns an orbit list for a supercell structure.

Parameters:structure (Atoms) – supercell atomic structure
Returns:
Return type:An OrbitList object
orbits

list of orbits

Type:list(_icet.Orbit)
permutation_matrix

permutation_matrix

Type:list of list of icet LatticeSite objects
primitive_structure

Returns the primitive structure to which the lattice sites in the orbits are referenced to.

remove_inactive_orbits(allowed_species)[source]

Removes orbits with inactive sites.

Parameters:allowed_species (List[List[str]]) – the list of allowed species on each site in the primitive structure
Return type:None
remove_orbit()

Removes the orbit with the input index.

Parameters:index (int) – index of the orbit to be removed
sort()

Sorts the orbits by orbit comparison

PermutationMatrix

This module provides a Python interface to the PermutationMatrix class with supplementary functions.

icet.core.permutation_matrix.permutation_matrix_from_structure(structure, cutoff, find_prim=True)[source]

Sets up a list of permutation maps from an Atoms object.

Parameters:
  • structure (Atoms) – input structure
  • cutoff (float) – cutoff radius
  • find_primitive – if True the symmetries of the primitive structure will be employed
Return type:

Tuple[ndarray, Structure, NeighborList]

Returns:

  • the tuple that is returned comprises the permutation matrix, the
  • primitive structure, and the neighbor list

Structure

This module provides the Structure class.