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 Ax = y.

Parameters:
  • fit_data (tuple of NumPy (N, M) array and NumPy (N) array) – the first element of the tuple represents the fit matrix A whereas the second element represents the vector of 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) – whether or not to standardize the fit matrix before fitting
  • check_condition (bool) –

    whether or not to carry out a check of the condition number

    N.B.: This can be sligthly more time consuming for larger matrices.

  • seed (int) – seed for pseudo random number generator
compute_rmse(A, y)[source]

Computes the root mean square error using \(A\), \(y\), and the vector of fitted parameters \(x\) corresponding to \(||Ax-y||_2\).

Parameters:
  • A (numpy.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 (numpy.ndarray) – vector of target values
Returns:

root mean squared error

Return type:

float

fit_method

fit method

Type:str
get_contributions(A)[source]

Computes the average contribution to the predicted values from each element of the parameter vector.

Parameters:A (numpy.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
Returns:average contribution for each row of A from each parameter
Return type:numpy.ndarray
n_nonzero_parameters

number of non-zero parameters

Type:int
n_parameters

number of parameters (=columns in A matrix)

Type:int
n_target_values

number of target values (=rows in A matrix)

Type:int
parameters

copy of parameter vector

Type:numpy.ndarray
predict(A)[source]

Predicts data given an input matrix \(A\), i.e., \(Ax\), where \(x\) is the vector of the fitted parameters.

Parameters:A (numpy.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
Returns:vector of predicted values; float if single row provided as input
Return type:numpy.ndarray or float
seed

seed used to initialize pseudo random number generator

Type:int
standardize

whether or not to standardize the fit matrix before fitting

Type:bool
summary

comprehensive information about the optimizer

Type:dict
train()[source]

Cluster

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

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()
get_cluster_counts_info()
print()
reset()
setup_cluster_counts_info()

Geometry

icet.tools.geometry.add_vacuum_in_non_pbc(configuration)[source]

Adds vacuum in non-periodic directions.

Parameters:configuration (Atoms) – input atomic structure
Returns:input atomic structure with vacuum in non-pbc directions
Return type: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.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
Return type:

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
Return type:

List[List[float]]

icet.tools.geometry.get_decorated_primitive_structure(atoms, allowed_species)[source]

Returns a decorated primitive structure

Example

Will put hydrogen on sublattice 1, Helium on sublattice 2 and so on

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
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:
  • atoms – input atomic structure
  • neighbor_list (NeighborList) – list of lattice neighbors of the input structure
Return type:

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
Returns:

primitive structure

Return type:

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
Return type:

ndarray

LatticeSite

LocalOrbitListGenerator

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

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

NeighborList

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
Returns:

Return type:

list of NeighborList objects

Orbit

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

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 object) – 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
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

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
Returns:

the tuple comprises the permutation matrix, the primitive structure, and the neighbor list

Return type:

matrix, icet Structure object, NeighborList object

Structure