## 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-l2”, “split-bregman” standardize (bool) – if True the fit matrix is standardized before fitting 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 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 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
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 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

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

## 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

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, atoms)[source]

Provides an interface for inspecting cluster counts.

Parameters: orbit_list (OrbitList object) – orbit list for a primitive structure atoms (ASE Atoms object) – 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.add_vacuum_in_non_pbc(configuration)[source]

Parameters: configuration (Atoms) – input atomic structure input atomic structure with vacuum in non-pbc directions ase.Atoms
icet.tools.geometry.ase_atoms_to_spglib_cell(atoms)[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 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 List[int]
icet.tools.geometry.find_lattice_site_by_position(atoms, position, tol=0.0001)[source]

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

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

Returns the permutation vector that takes permutated to target.

Parameters: target (Sequence[~T]) – a container that supports indexing and its elements contain objects with __eq__ method permutated (Sequence[~T]) – a container that supports indexing and its elements contain objects with __eq__ method List[int]
icet.tools.geometry.fractional_to_cartesian(atoms, frac_positions)[source]

Turns fractional positions into cartesian positions.

Parameters: atoms (Atoms) – input atomic structure frac_positions (List[List[float]]) – fractional positions List[List[float]]
icet.tools.geometry.get_decorated_primitive_structure(atoms, allowed_species, symprec=1e-05)[source]

Returns a decorated primitive structure. Will put hydrogen on sublattice 1, Helium on sublattice 2 and so on

Parameters: atoms (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_fractional_positions_from_ase_neighbor_list(atoms, neighbor_list)[source]

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

Parameters: atoms (Atoms) – input atomic structure neighbor_list (NeighborList) – list of neighbors of the input structure 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: atoms – input atomic structure neighbor_list (NeighborList) – list of lattice neighbors of the input structure List[List[float]]
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(atoms, lattice_site)[source]

Gets the corresponding position from the lattice site.

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

Determines primitive structure using spglib.

Parameters: atoms (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 primitive structure atoms_prim
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 ndarray

## 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(atoms, cutoffs=None)[source]

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

Parameters: atoms (ASE Atoms object / icet Structure object (bi-optional)) – atomic configuration cutoffs – positive floats indicating the cutoffs for the various clusters list of NeighborList objects

## 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(atoms_in, cutoffs)[source]

The orbit list object has 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: atoms (ase.Atoms) – This atoms object will be used to construct a primitive structure on which all the lattice sites in the orbits are based on. cutoffs (list of float) – cutoffs[i] 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(atoms)[source]

Returns an orbit list for a supercell structure.

Parameters: atoms (Atoms) – supercell atomic structure 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 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_atoms(atoms, cutoff, find_prim=True)[source]

Set up a list of permutation maps from an atoms object.

Parameters: atoms (ASE Atoms object) – input structure cutoff (float) – cutoff radius find_primitive (boolean) – if True the symmetries of the primitive structure will be employed the tuple comprises the permutation matrix, the primitive structure, and the neighbor list matrix, icet Structure object, NeighborList object

## Structure¶

This module provides the Structure class.