# C++ classes and functions¶

## Cluster¶

class Cluster

This class handles information pertaining to a single cluster.

Public Functions

Cluster()
Cluster(const Structure &structure, const std::vector<LatticeSite> &latticeSites, const bool sorted = true, const int tag = 0)

Create cluster from a structure and a set of lattice sites.

Create an instance of a cluster.

Parameters
• structure: icet structure object
• latticeSites: list of lattice sites that form the cluster
• sorted: cluster will be sorted if True
• tag: integer identifier

void sort()

Sort cluster.

This function sorts the sites and their corresponding distances. This ensures the uniqueness of the cluster representation and enables sorting using class specific operators.

Algorithm for sorting

First the distances associated with each site i are sorted..

If there is one smallest distance then i is the first site and its first neighbor is the second site and so on/

There are then some special cases which need to be distinguished.

Case 1: Two or more distances are equal

Problem: Which site is picked as the first?

Case 2: Two or more distances are equal in i_dist.

Problem: It is unclear which site is site 2, 3 (if i_dist[0]==i_dist[1]).

Case 3: Two or more distances are equal in j_dist where j is in i_nbrs.

Problem: What is the problem here?

Solution for case 1: 1) assume case 2 and 3 do not apply. a) get “getDistIndices” and getReorderedSites for each case b) compare to each other. The lowest should be the one to use 2) if case 2 applies as well: a) for each smallest i_dist get solution from case 2 b) compare case 2 solutions of i_dist to find minimum.

Solution case 2: for each j,k,l.. indices in i_nbr that have i_dists equal:

for combination in all_combinations(j,k,l,...):
get "getDistIndices" and getReorderedSites

take the get_dist_indices and reordered sites that are the smallest and use the corresponding combination of indices.

void validateSorting()

Validate sorting of clusters.

This validates the sorting by testing all possible combinations of sites and sees if there is a lower state of the cluster.

void swapSites(const int i, const int j)

Swap two sites.

void print() const

Print the cluster to stdout.

Print the cluster to standard out.

Format is first distances then sites

unsigned int order() const

Returns the order (i.e., the number of sites) of the cluster.

double radius() const

Returns the radius of the cluster.

std::vector<int> sites() const
std::vector<double> distances() const
LocalEnvironment getLocalEnvironment(const size_t i_index)

Returns the local environment of a site (point) in the cluster.

bool isSorted() const

Returns true if this is a sorted cluster.

int tag() const

Returns the cluster tag used for identification (if distances/sites are not used for distinction).

void setTag(const int tag)

Set the cluster tag and mark the cluster as unsorted.

std::tuple<std::vector<int>, std::vector<double>, std::vector<int>> findMinimumClusterByBruteForce()

Brute force attempt to find minimum clusters.

std::vector<LocalEnvironment> getEqualMinimumFirstSites(const std::vector<LocalEnvironment> &i_neighbors) const

Find all equal nearestNeighborDistances that are identical to the minimum one.

Get all equal nearestNeighborDistances that are identical to the minimum one Equality means all distances and sites are equal.

bool isEqualFirstDists(const std::vector<std::pair<double, int>> &dist_index1, const std::vector<std::pair<double, int>> &dist_index2) const

Returns true if dist_index1 is equal to dist_index2.

Returns true if dist_index1 is equal to dist_index2

THe hitch is that dist_index1[i].second is a index in the cluster and has to be checked what site is on that index when comparing

std::tuple<std::vector<double>, std::vector<int>, std::vector<int>> case1_min_indices(const std::vector<LocalEnvironment> &equal_minimum_i_neighbors) const

Arguments: equal_minimum_i_neighbors a vector of all the minimum first dists Do case 1: solutions case 1: 1) assume case2 and case3 is not active. a) get “getDistIndices” and getReorderedSites for each case b) compare to each other. The lowest should be the one to use 2) if case2 is active also: a )for each smallest i_dist: get solution from case 2 b) compare case2 solutions of i_dist to find minimum.

std::vector<int> getOrderFromFirstDists(const std::pair<std::vector<std::pair<double, int>>, std::pair<int, int>> &nearestNeighborDistances) const

Gets the min order of indices as given by this “first dists”

this format is used throughout this code to simpler extract the indices from a given first dist (i_dists)

The format is nearestNeighborDistances.first = a vector of distances and indices to the corresponding site the distance is to nearestNeighborDistances.second.first = the site of this index nearestNeighborDistances.second.second the index of this nearestNeighborDistances, i.e. the i in i_dists

bool isCase2(const LocalEnvironment &i_neighbors) const

Checks if these distance, sites vector has some equal elements and is thus subject to case2

void setThisOrder(const std::vector<int> &minimumOrder)

Rearranges distances and sites to the order given in minimumOrder.

example:

minimumOrder[0] = current index which should be first place minimumOrder[1] = current index which should be second place and so on …

This is a slightly non trivial operation since swapping two sites changes the order of the distances in a complex way.

The distances are ordered by: d_12, d_13, d_14, … , d_23, d_24, …

solution:

The algorithm creates a vector of tuples with i, j, distance

the current state is: 1, 2, d_12 1, 3, d_13

which is then mapped to: minOrder.index_of(1), minOrder.index_of(2), d_12 minOrder.index_of(1), minOrder.index_of(3), d_13

where minOrder.index_of(1) = index of 1 in minOrder. this vector is then sorted and the positions will align to the new order.

std::vector<std::tuple<int, int, double>> getDistIndices() const

The distances are ordered by:

d_12, d_13, d_14, … , d_23, d_24, …

return a tuple of the current state: 1, 2, d_12 1, 3, d_13

std::vector<std::tuple<int, int, double>> getDistIndices(const std::vector<int> &indiceOrder) const

The algorithm creates a vector of tuples with i, j, distance

the current state is: 1, 2, d_12 1, 3, d_13

which is then mapped to: indiceOrder.index_of(1), indiceOrder.index_of(2), d_12 indiceOrder.index_of(1), indiceOrder.index_of(3), d_13

where indiceOrder.index_of(1) = index of 1 in indiceOrder. this vector is then sorted and the positions will align to the new order.

std::vector<double> getReorderedDistances(const std::vector<int> &indiceOrder) const

Get the distances if the sites would have been rearranged according to indiceOrder.

Get the distances if the sites would have been rearranged according to indiceOrder

returns a double (distance ) vector

std::vector<int> getReorderedSites(const std::vector<int> &indiceOrder) const

Return the sites if the order would have been as is given in indiceOrder.

Return the sites if the order would have been as is given in indiceOrder

std::tuple<std::vector<double>, std::vector<int>, std::vector<int>> case2_min_indices(const LocalEnvironment &i_neighbor) const

solutions case 2: for each j,k,l.. indices in i_nbr that have i_dists equal: for combination in all_combinations(j,k,l,…): get “getDistIndices” and getReorderedSites take the get_dist_indices and reordered sites that are smallest and use the corresponding combination of indices.

returns min_indices, correspong distances and corresponding sites

void findMinimumIndexPermutation(size_t currentIndexSet, const std::vector<std::vector<int>> &identicalIndices, const std::vector<int> &minimumOrder, std::vector<int> trial_order, std::vector<double> &min_distances, std::vector<int> &min_sites, std::vector<int> &min_indices) const
bool compare_sites_dists(const std::vector<double> &dist1, const std::vector<int> &sites1, const std::vector<double> &dist2, const std::vector<int> &sites2) const

Compare distances and sites if dist1 and sites1 < dists2 and sites2.

compare distances and sites if dist1 and sites1 < dists2 and sites2 (first compare distances, if they are equal compare sites)

Friends

bool operator==(const Cluster &c1, const Cluster &c2)

Comparison operator for equality.

bool operator!=(const Cluster &c1, const Cluster &c2)

Comparison operator for inequality.

bool operator<(const Cluster &c1, const Cluster &c2)

Comparison operator for “smaller than” in the case of sortable clusters.

## ClusterCounts¶

class ClusterCounts

Public Functions

ClusterCounts()
void countLatticeSites(const Structure &structure, const std::vector<std::pair<std::vector<LatticeSite>, std::vector<LatticeSite>>> &latticeNeighbors)

Count clusters given this compact form of lattice neighbors (see ManyBodyNeighborList for more details)

void count(const Structure &structure, const std::vector<LatticeSite> &latticeNeighbors)

The simplest form of counting clusters using the mbnl format

Get the indice of one set of indices and counts this

void count(const Structure &structure, const std::vector<std::vector<LatticeSite>> &latticeSites, const Cluster &cluster, bool orderIntact)

Will count the vectors in latticeNeighbors and assuming these sets of sites are represented by the cluster ‘cluster’.

Parameters
• structure: the structure that will have its clusters counted
• latticeSites: A group of sites, represented by ‘cluster’, that will be counted
• cluster: A cluster used as identification on what sites the clusters belong to
• orderIntact: if true the order of the sites will stay the same otherwise the vector of species being counted will be sorted

void countCluster(const Cluster &cluster, const std::vector<int> &elements, bool orderIntact)

Count cluster only through this function.

void countOrbitList(const Structure &structure, const OrbitList &orbitList, bool orderIntact, bool permuteSites = false)

Counts the clusters in the input structure.

Parameters
• structure: input configuration
• orbitList: orbit list
• orderIntact: if true do not reorder clusters before comparison (i.e., ABC != ACB)
• permuteSites: if true the sites will be permuted according to the correspondin permutations in the orbit

std::unordered_map<Cluster, std::map<std::vector<int>, int>> getClusterCounts() const
size_t size() const

Returns the cluster counts size i.e. the total number of clusters.

void reset()

Reset cluster counts.

void print()

Helpful function that prints the cluster counts

Public Members

std::unordered_map<Cluster, std::map<std::vector<int>, int>> _clusterCounts

## ClusterSpace¶

class ClusterSpace

This class handles the cluster space.

It provides functionality for setting up a cluster space, calculating cluster vectors as well as retrieving various types of associated information.

Public Functions

ClusterSpace()

Constructor.

ClusterSpace(std::vector<std::vector<std::string>> &chemicalSymbols, const OrbitList &orbitList)

This constructor initializes a ClusterSpace object.

Parameters
• chemicalSymbols: vector of allowed chemical symbol for each site
• orbitList: list of orbits for the primitive structure

std::vector<double> getClusterVector(const Structure &structure) const

Returns the cluster vector corresponding to the input structure.

This function calculates and then returns the cluster vector for the input structure in the cluster space.

The first element in the cluster vector will always be one (1) corresponding to the zerolet. The remaining elements of the cluster vector represent averages over orbits (symmetry equivalent clusters) of increasing order and size.

Parameters
• structure: input configuration

std::pair<int, std::vector<int>> getClusterSpaceInfo(const unsigned int)

Returns information concerning the cluster space.

Returns a pair where pair.first is the index of the underlying orbit in _orbitList. and pair.second is the multicomponent vector for the “outerlying” orbit with index index

Parameters
• index: index for the “outerlying” orbit

OrbitList getOrbitList() const

Returns the entire orbit list.

Orbit getOrbit(const size_t index) const

Returns an orbit from the orbit list.

ClusterCounts getNativeClusters(const Structure &structure) const

Returns the native clusters.

std::vector<std::vector<std::vector<int>>> getMultiComponentVectorPermutations(const std::vector<std::vector<int>> &multiComponentVectors, const int orbitIndex) const

Returns the multi-component (MC) vector permutations for each MC vector in the set of input vectors.

This method return the multi-component vector permutations for each multi-component vector.

Example 1: Given multi-component vectors [0, 0], [0, 1] and [1, 1] the returned permutations should be [[1, 0]], [[0, 1],[1, 0]], [1, 1]. i.e. the [0, 1] multi-component vector should count elements with permutations [1, 0] and [1, 0].

Example 2: Given multi-component vectors [0, 0], [0, 1], [1, 0] and [1, 1] the returned permutations will only be the self permutations since the multi-component vectors [0, 1] and [1, 0] will handle the AB vs BA choice.

Return
a vector of a vector of a vector of ints; here the innermost index
Parameters
• multiComponentVectors: multi-component vectors for this orbit
• orbitIndex: index from which to take the allowed permutations

std::vector<double> getCutoffs() const

Returns the cutoff for each order.

Structure getPrimitiveStructure() const

Returns the primitive structure.

std::vector<int> getNumberOfAllowedSpeciesBySite(const Structure &structure, const std::vector<LatticeSite> &latticeSites) const

Returns the number of allowed components for each site.

Returns the number of species allowed on each site of the provided structure.

Return
the number of allowed species for each site
Parameters
• structure: an atomic configuration
• latticeSites: a list of sites

std::vector<std::vector<std::string>> getChemicalSymbols() const

Returns a list of species associated with cluster space as chemical symbols.

size_t getClusterSpaceSize()

Returns the cluster space size, i.e. the length of a cluster vector.

std::vector<std::unordered_map<int, int>> getSpeciesMaps() const

Returns the mapping between atomic numbers and the internal species enumeration scheme for each site.

double evaluateClusterProduct(const std::vector<int> &multiComponentVector, const std::vector<int> &numberOfAllowedSpecies, const std::vector<int> &species, const std::vector<int> &indices) const

Returns the cluster product.

Evaluates the full cluster product of the entire cluster.

Return
the cluster product
Parameters
• multiComponentVector: multi-component vector, each element of the vector gives the index of a cluster function
• numberOfAllowedSpecies: number of species allowed on the sites in this cluster (all sites involved are assumed to have the same number of allowed species)
• species: species that occupy (decorate) the cluster identified by atomic number
• indices: representative lattice indices of the cluster being computed

double evaluateClusterFunction(const int numberOfAllowedSpecies, const int clusterFunction, const int species) const

Returns the default cluster function.

Evaluates the cluster function using the specified parameters.

The cluster functions (also “orthogonal point functions”) are defined as

.. math::

{n}() = {cases} 1 & {if}~n=0 \ -((n+1)/M) & {if n is odd} \ -( n /M) & {if n is even} {cases}

Return
the value of the cluster function
Parameters
• numberOfAllowedSpecies: number of allowed species on the site in question
• clusterFunction: index of cluster function
• species: index of species

void precomputeMultiComponentVectors()

Precomputes permutations and multicomponent vectors of each orbit.

void pruneOrbitList(std::vector<size_t> &indices)

Prunes the orbit list.

This function removes orbits from the underlying orbit list.

Parameters
• indices: list of orbit indices

Public Members

OrbitList _orbitList

Primitive orbit list based on the structure and the global cutoffs.

std::vector<std::vector<std::vector<int>>> _multiComponentVectors

Precomputed multicomponent vectors for each orbit in _orbitlist.

std::vector<std::vector<std::vector<std::vector<int>>>> _sitePermutations

Precomputed site permutations for each orbit in _orbitlist.

## General¶

namespace icet

Functions

double getGeometricalRadius(const std::vector<LatticeSite> &latticeSites, const Structure &structure)

Returns the geometrical radius of a cluster.

This function computes the geometrical radius of a cluster that is defined in terms of lattice sites.

Parameters
• latticeSites: a list of lattice sites
• structure: atomic configuration used to convert information in latticeSites to Cartesian coordinates

Eigen::Vector3d transformPosition(const Eigen::Vector3d &position, const Eigen::Vector3d &translation, const Eigen::Matrix3d &rotation)

Return the transformed position position using the input translation and rotation.

Return the transformed position position using the input translation and rotation whys is there a ‘2’ here?

bool nextCartesianProduct(const std::vector<std::vector<int>> &items, std::vector<int> &currentProduct)

Returns the next cartesian product of currentProduct using the vector of vectors items items[0] is the possible combinations for element n.

std::vector<Eigen::Vector3d> getOffsetPositions(const Structure &structure, const Eigen::Vector3d &offset)

Creates a vector of positions by offsetting the structure’s positions by an offset.

template<typename T>
std::vector<int> getPermutation(const std::vector<T> &v_original, const std::vector<T> &v_permutation)

Find the permutation vector that takes v_permutation to v_original.

template<typename T>
std::vector<T> getPermutedVector(const std::vector<T> &v, const std::vector<int> &indices)

Return the permutation of v using the permutation in indices.

template<typename T>
std::vector<std::vector<T>> getAllPermutations(std::vector<T> v)

Return the permutation of v using the permutation in indices.

## LatticeSite¶

struct LatticeSite

Struct for storing information concerning a lattice site.

This structure provides functionality for handling lattice sites most notably including comparison operators.

Public Functions

LatticeSite()

Empty constructor.

LatticeSite(const size_t index, const Eigen::Vector3d unitcellOffset)

Constructor.

Parameters
• index: site index
• unitcellOffset: offset of site relative to unit cell at origin in units of lattice vectors

size_t index() const

Return index of site.

void setIndex(size_t index)

Set index of site.

Eigen::Vector3d unitcellOffset() const

Return offset relative to unit cell at origin in units of lattice vectors.

void setUnitcellOffset(Eigen::Vector3d offset)

Set offset relative to unit cell at origin in units of lattice vectors.

void addUnitcellOffset(Eigen::Vector3d offset)

Add offset relative to unit cell at origin in units of lattice vectors.

bool operator<(const LatticeSite &other) const

Smaller than operator.

bool operator==(const LatticeSite &other) const

Equality operator.

operator std::string() const

Cast object as string.

void print() const

Write class information to stdout.

Friends

LatticeSite operator+(const LatticeSite &latticeSite, const Eigen::Vector3d &offset)

LatticeSite operator-(const LatticeSite &latticeSite, const Eigen::Vector3d &offset)

Substraction operator.

LatticeSite operator+=(const LatticeSite &latticeSite, const Eigen::Vector3d &offset)

## LocalEnvironment¶

struct LocalEnvironment

Helper structure which is internally used for sorting clusters.

An instance of this structure stores the index and site of the “first” (reference) point in a clusterand with the distances, indices, and sites of its neighbors

For example in the case of a four-point cluster the structure would contain

(index, site)              --> reference point
(distance1, site1, index1) --> neighbor 1
(distance2, site2, index2) --> neighbor 2
(distance3, site3, index3) --> neighbor 3


The structure provides functions for comparing clusters in order to establish and ordering.

Public Functions

LocalEnvironment()

Empty constructor.

LocalEnvironment(const int &index, const int &site, const std::vector<double> &neighborDistances, const std::vector<int> &neighborSites, const std::vector<int> &neighborIndices)

Constructor.

Parameters
• index: index of the reference point of the cluster
• site: site of the reference point of the cluster
• neighborDistances: list of distances to neigbors
• neighborSites: list of sites of neighbors
• neighborIndices: list of indices of neighbors

std::vector<double> getNeighborDistances() const

Returns list of distances to neighbors.

void setNeighborDistances(const std::vector<double> &neighborDistances)

Set list of distances to neighbors.

std::vector<int> getNeighborSites() const

Returns list of sites of neighbors.

void setNeighborSites(const std::vector<int> &sites)

Set list of sites of neighbors.

std::vector<int> getNeighborIndices() const

Return list of indices of neighbors.

void setNeighborIndices(const std::vector<int> &neighborIndices)

Set list of _neighborIndices.

std::vector<int> getClusterIndices() const

Returns indices of all points in the cluster including the reference point.

std::vector<std::vector<int>> getEquivalentIndices() const

Identify which neighbor tuples (distance $$d_i$$, site $$s_i$$) combinations are identical.

This function returns a vector of vectors of indices that identify the neighbor tuples $$(d_i, s_i)$$, for which $$d_i=d_j, s_i=s_j\, \forall\, i,j$$.

For example assuming that $$d_i=d_j, s_i=s_j$$ for $$i,j\in(1,3)$$ and $$d_i=d_j, s_i=s_j$$ for $$i,j\in(2,4)$$, the function will return $$[1, 3], [2, 4]$$.

Return
vector of vectors

operator std::string() const

Cast object as string.

void print() const

Write class information to stdout.

int index() const

Returns index of reference point.

void setIndex(int index)

Set index of reference point.

int site() const

Returns site of reference point.

void setSite(int site)

Set site of reference point.

std::vector<int> neighborSites() const

Returns neighbor sites.

std::vector<double> neighborDistances() const

Returns neighbor distances.

Friends

bool operator<(const LocalEnvironment &locEnv1, const LocalEnvironment &locEnv2)

Smaller than comparison operator.

bool operator==(const LocalEnvironment &locEnv1, const LocalEnvironment &locEnv2)

Equality comparison operator.

## LocalOrbitListGenerator¶

class LocalOrbitListGenerator

This is a small class that has a:

orbit list (from primitive structure) supercell list of unique primitive cell offsets that the supercell span the primToSupercellMap

you can query this object with

/Generate the orbit list from the primitive offset with count i OrbitList getLocalOrbitList(int i);

std::vector<Vector3d> getUniqueOffsets() const;

std::vector<Vector3d> primToSupercellMap() const;

/clears primToSupercellMap and unique offsets void reset();

etc…

Public Functions

LocalOrbitListGenerator()
LocalOrbitListGenerator(const OrbitList &orbitList, const Structure &superCell)
OrbitList getLocalOrbitList(const size_t index)

generate and returns the local orbit list with the input index

OrbitList getLocalOrbitList(const Vector3d &primOffset)

generate and returns the local orbit list with the input offset (require that the offset is in uniquecell offset?)

OrbitList getFullOrbitList()

Generate the full orbit list from this structure.

Generate the complete orbit list (the sum of all local orbit lists)

void clear()
size_t getNumberOfUniqueOffsets() const

Returns the number of unique offsets.

std::unordered_map<LatticeSite, LatticeSite> getMapFromPrimitiveToSupercell() const

Return the primitive lattice neighbor to supercell lattice neigbhor map.

std::vector<Vector3d> getUniquePrimitiveCellOffsets() const

Returns the unique primitive cells.

## ManyBodyNeighborList¶

class ManyBodyNeighborList

Design approach: input pair neighbors and calculate higher order neighbors using set intersection.

Public Functions

ManyBodyNeighborList()
std::vector<std::pair<std::vector<LatticeSite>, std::vector<LatticeSite>>> build(const std::vector<NeighborList> &neighbor_lists, int index, bool saveBothWays)

This will use the neighbor_list to combine all possible neighbors up to the given order. The output will be: std::vector<std::pair<originalNeighbors, manyNeigbhors>> the many body neigbhors can be retrieved by doing: for (const auto nbr : many_bodyNeighborIndices) { std::vector<std::pair<int,Vector3d>> neighbors = nbr.first; // this are the first orignal neighbors for(const auto manynbr : nbr.second) { many_body_neigbhor = neighbors; many_body_neigbhor.append(manynbr); } }

this means that if originalNeigbhors.size() == 2 then for each lattice site in manyNeigbhors you can combine it with originalNeigbhors to get all triplets that have these first two original neighbors (lattice indices)

saveBothWays : bool if true then both i,j,k and j,i,k etc.. will be saved otherwise only i,j,k will be saved if i < j < k

void combineToHigherOrder(const NeighborList &nl, std::vector<std::pair<std::vector<LatticeSite>, std::vector<LatticeSite>>> &many_bodyNeighborIndex, const std::vector<LatticeSite> &Ni, std::vector<LatticeSite> &currentOriginalNeighbrs, bool saveBothWays, const size_t maxOrder)

This will use the permutationmatrix together with the neighbor_list to construct the distinct and indistinct sets of points

The output will be std::vector<std::vector<std::vector<LatticeSite>>> the next outer vector contains the set of indistinct set of lattice neighbors.

Algorithm

The algorithm will work by taking the first column of permutation matrix: col1 = permutation_matrix[:,0]

and it will take Ni (lattice neighbors of i) and find the intersection of Ni and col1, intersection(Ni, col1) = Ni_pm all j in Ni_c1 are then within the cutoff of site i, then depending on the order all the pairs/triplets will be constructed from the lattice neighbors in Ni_pm.

This will be repeated for all the sites in the neighbor_list. In the end all the pair/triplet terms will have been generated from col1.

Then you will take the first vector<LatticeSites> and find the rows of these LatNbrs in col1 of the permutation matrix. then you traverse through all the columns in the permutation matrix. These vector<latticeNeighbors> are then indistinct from the original. Note that here a validity check is made to ensure that atleast one LatticeNeigbhor originate in the original lattice (unitcell offset = [0,0,0]) otherwise we are including a “ghost cluster”.

The new vector<latticeNeighbors> found when traversing the columns are likely to have been found from the combinations in Ni_pm and these must then be removed/overlooked when moving to the next vector<LatticeSite>.

std::vector<LatticeSite> getIntersection(const std::vector<LatticeSite> &Ni, const std::vector<LatticeSite> &Nj)
void translateAllNi(std::vector<LatticeSite> &Ni, const Vector3d &unitCellOffset) const

Offsets all indice, offsets pairs in Ni with the input offset, e.g: For all j in Ni: offset j.offset with “unitCellOffset”

size_t getNumberOfSites() const

Get size of _latticeNeighbors

This can be used in conjunction with getNumberOfSites(int index) and ManyBodyNeighborList::getSites To loop over possible many_body neighbors

size_t getNumberOfSites(const unsigned int index) const

Get number of manybodies one can make from _latticeNeighbors[index].

std::vector<LatticeSite> getSites(const unsigned int &firstIndex, const unsigned int &secondIndex) const

Return the many_body neighbor at “firstIndex” and “secondIndex ” in _latticeNeighbors and _latticeNeighbors[firstIndex] respectively

void addSinglet(const int index, std::vector<std::pair<std::vector<LatticeSite>, std::vector<LatticeSite>>> &many_bodyNeighborIndices) const

Adds singlet from the index to many_bodyNeighborIndices.

void addPairs(const int index, const NeighborList &neighborList, std::vector<std::pair<std::vector<LatticeSite>, std::vector<LatticeSite>>> &many_bodyNeighborIndices, bool saveBothWays) const

Add all pairs originating from index using neighbor_list.

## NeighborList¶

class NeighborList

Class for maintaining a neighbor list.

This class provides functionality for building and storing a (conventional) pair-wise neighbor list (as opposed to the specialized many-body neighbor list defined by ManyBodyNeighborList).

See
ManyBodyNeighborList

Public Functions

NeighborList(const double cutoff)

Initialize a neighbor list instance.

Parameters
• cutoff: cutoff to be used for constructing the neighbor list.

void build(const Structure &conf)

Build a neighbor list based on the given structure.

This function builds a neighbor list for the given structure.

Parameters
• structure: atomic configuration

void update(const Structure&)

Update a neighbor list based on the given structure.

bool isNeighbor(const size_t index1, const size_t index2, const Vector3d offset) const

Check if two sites are neighbors.

This function returns True (False) if two sites identified by their respective indices are (not) neighbors of each other.

Parameters
• index1: first site
• index2: second site
• offset: \

std::vector<LatticeSite> getNeighbors(size_t index) const

Returns list of neighbors.

This function returns a vector of lattice sites that identify the neighbors of site in question.

Return
vector of LatticeSite objects
Parameters
• index: index of site in structure for which neighbor list was build

size_t size() const

Returns size of neighbor list.

double cutoff() const

Returns cutoff radius used for building the neighbor list.

## Orbit¶

class Orbit

Class Orbit

contains equivalent vector<LatticeSites> contains a sorted Cluster for representation

Can be compared to other orbits

Public Functions

Orbit(const Cluster &cluster)
void addEquivalentSites(const std::vector<LatticeSite> &latNbrs, bool sort = false)

Adds a group sites that are equivalent to the ones in this orbit.

void addEquivalentSites(const std::vector<std::vector<LatticeSite>> &LatticeSites, bool sort = false)

size_t size() const

Returns number of equivalent sites in this orbit.

double radius() const

Returns the radius of the representative cluster in this orbit.

Cluster getRepresentativeCluster() const

Returns the sorted, representative cluster for this orbit.

std::vector<std::vector<LatticeSite>> getEquivalentSites() const

Returns equivalent sites.

std::vector<std::vector<LatticeSite>> getPermutedEquivalentSites() const

Returns equivalent sites.

std::vector<LatticeSite> GetSitesOfIndex(unsigned int index) const

Returns the equivalent sites at position index.

std::vector<LatticeSite> getSitesWithPermutation(unsigned int index) const

Returns the equivalent sites at position index by using the permutation to rep. cluster.

void setEquivalentSites(const std::vector<std::vector<LatticeSite>> &equivalentSites)

Sets the equivalent sites.

void sortOrbit()
unsigned int getClusterSize() const

Returns the number of bodies of the cluster that represent this orbit.

std::vector<std::vector<int>> getPermutationsOfEquivalentSites() const

Return the equivalent sites permutations.

void setEquivalentSitesPermutations(std::vector<std::vector<int>> &permutations)

Assigns the equivalent sites permutations.

void setAllowedSitesPermutations(std::set<std::vector<int>> &permutations)

Assigns the allowed sites permutations.

std::set<std::vector<int>> getAllowedSitesPermutations() const

Gets the allowed sites permutations.

std::vector<LatticeSite> getRepresentativeSites() const

Returns the representative sites of this orbit (if any equivalentSites permutations exists it is to these sites they refer to).

int getNumberOfDuplicates(int verbosity = 0) const

Returns the number of exactly equal sites in equivalent sites vector This is used among other things to debug orbits when duplicates are not expected

Returns the number of exactly equal sites in equivalent sites vector

This is used among other things to debug orbits when duplicates is not expected

Orbit &operator+=(const Orbit &orbit_rhs)

Appends an orbit to this orbit.

std::vector<std::vector<int>> getMultiComponentVectors(const std::vector<int> &Mi_local) const

Returns the relevant multicomponent vectors of this orbit given the number of allowed components.

Returns the inequivalent MC vectors for this orbit.

Parameters
• Mi_local: : Vector of the number of allowed sites

std::vector<std::vector<int>> getAllPossibleMultiComponentVectorPermutations(const std::vector<int> &Mi_local) const

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

bool contains(const std::vector<LatticeSite> sites, bool sorted) const

Returns true if the input sites exists in _equivalentSites, order doesn’t matter if sorted= false.

Check if this orbit contains a set of sites in its equivalent sites vector.

Return
true if the sites exist in equivalent sites.
Parameters
• sites: the sites that will be looked for.
• sorted: if true the order of sites is irrelevant

void removeSitesWithIndex(const size_t indexRemove, bool onlyConsiderZeroOffset)

Removes all elements i in equivalent sites if any sites in _equivalentSites[i] have the input index.

Removes sets of sites in equivalent sites for which any site in the set has an index equal to indexToRemove.

Parameters
• indexToRemove: the index to look for
• onlyConsiderZeroOffset: if true remove only sites with zero offset

void removeSitesNotWithIndex(const size_t index, bool onlyConsiderZeroOffset)

Removes all elements i in equivalent sites if no sites in _equivalentSites[i] have the input index.

Removes sets of sites in equivalent sites for which no site in the set has an index equal to index.

Parameters
• index: the index to look for
• onlyConsiderZeroOffset: if true only look for sites with zero offset

void removeSites(std::vector<LatticeSite> sites)

Remove a specific set of sites with corresponding equivalent site permutation.

Removes a specific set of sites in this orbit and the corresponding site permutation.

Parameters
• sites: vector of sites that will be removed, order of sites is irrelevant

Public Members

std::vector<std::vector<LatticeSite>> _equivalentSites

Container of equivalent sites for this orbit.

Cluster _representativeCluster

Representative sorted cluster for this orbit.

Friends

bool operator==(const Orbit &orbit1, const Orbit &orbit2)

Comparison operator for automatic sorting in containers.

bool operator<(const Orbit &orbit1, const Orbit &orbit2)

Comparison operator for automatic sorting in containers.

Orbit operator+(const Orbit &orbit, const Eigen::Vector3d &offset)

Creates a copy of this orbit and translates all LatticeSite offsets in equivalent sites. This will also transfer any existing permutations directly, which should be fine since an offset does not change permutations to the prototype sites.

## OrbitList¶

class OrbitList

container for a sorted list of orbits.

Instances of OrbitList serve as a containers for a list of orbits and provide associated functionality.

Public Functions

OrbitList()

Empty constructor.

OrbitList(const Structure &structure, const std::vector<std::vector<LatticeSite>> &permutationMatrix, const std::vector<NeighborList> &neighbor_lists)

Constructs orbit list from a set of neighbor lists, a permutation matrix, and a structure.

This constructor generates an orbit list for the given (supercell) structure from a set of neighbor lists and a permutation map.

Parameters
• neighbor_lists: list of neighbor lists
• permutationMatrix: permutation matrix
• structure: (supercell) structure for which to generate orbit list

void addOrbit(const Orbit &orbit)

Parameters
• orbit: orbit to add to orbit list

OrbitList &operator+=(const OrbitList &rhs_ol)

Provides the “+=” operator for adding orbit lists. First assert that they have the same number of orbits or that this is empty and then add equivalent sites of orbit i of rhs to orbit i to ->this

Orbit getOrbit(unsigned int) const

Returns a copy of the orbit of the given index.

Returns a copy of the orbit at the given index.

Return
copy of orbit
Parameters
• index:

void addClusterToOrbitList(const Cluster &cluster, const std::vector<LatticeSite> &sites, std::unordered_map<Cluster, int> &clusterIndexMap)

Adds cluster to orbit list, if cluster exists add sites if not create a new orbit.

Orbit getSuperCellOrbit(const Structure &superCell, const Vector3d &cellOffset, const unsigned int, std::unordered_map<LatticeSite, LatticeSite> &primToSuperMap) const

Returns an orbit in the given (supercell) structure.

This function returns the orbit for a supercell that is associated with a given orbit in the primitive structure.

Parameters
• superCell: input structure
• cellOffset: offset by which to translate the orbit
• orbitIndex: index of orbit in list of orbits
• primToSuperMap: map from sites in the primitive cell to sites in the supercell

OrbitList getLocalOrbitList(const Structure &superCell, const Vector3d &cellOffset, std::unordered_map<LatticeSite, LatticeSite> &primToSuperMap) const

Returns the local orbit list for a site.

Returns a “local” orbitList by offsetting each site in the primitive cell by an offset.

Parameters
• superCell: supercell structure
• cellOffset: offset to be applied to sites
• primToSuperMap: map from primitive to supercell

void addPermutationMatrixColumns(std::vector<std::vector<std::vector<LatticeSite>>> &latticeSites, std::unordered_set<std::vector<int>, VectorHash> &taken_rows, const std::vector<LatticeSite> &lat_nbrs, const std::vector<int> &pm_rows, const std::vector<std::vector<LatticeSite>> &permutationMatrix, const std::vector<LatticeSite> &col1, bool add) const

From all columns in permutation matrix add all the vector<LatticeSites> from pm_rows When taking new columns update taken_rows accordingly

void clear()

Clears the orbit list.

void sort()

Sorts the orbit list.

void print(int verbosity) const

Prints information about the orbit list.

This function prints information about the orbit list.

Parameters
• verbosity: control verbosity of information

size_t size() const

Returns the number of orbits.

unsigned int getNumberOfNBodyClusters(unsigned int) const

Returns the number of orbits which are made up of a certain number of bodies.

Parameters
• nbody: number of bodies for which to filter

std::vector<LatticeSite> getColumn1FromPM(const std::vector<std::vector<LatticeSite>> &permutationMatrix, bool sortIt = true) const

Parameters
• permutationMatrix: permutation matrix
• sortIt: if true (default) the first column will be sorted

std::vector<int> findRowsFromCol1(const std::vector<LatticeSite> &col1, const std::vector<LatticeSite> &latticeSites, bool sortIt = true) const

This function searches for lattice sites in the first column of the permutation matrix and returns the corresponding rows.

Parameters
• sortIt: if true the first column will be sorted

bool validCluster(const std::vector<LatticeSite> &latticeSites) const

This function returns true if the cluster includes at least on site from the unit cell at the origin, i.e. its unitcell offset is zero.

Parameters
• latticeSites: list of sites to check

void addOrbitsFromPM(const Structure &structure, const std::vector<std::vector<std::vector<LatticeSite>>> &latticeSites)

This function adds the latticeSites container found in the constructor to the orbits. Each outer vector is an orbit and the inner vectors are identical sites

void addOrbitFromPM(const Structure &structure, const std::vector<std::vector<LatticeSite>> &equivalent_sites)

Adds these equivalent sites as an orbit to orbit list.

void checkEquivalentClusters() const

Debug function to check that all equivalent sites in every orbit give the same sorted cluster.

std::vector<LatticeSite> translateSites(const std::vector<LatticeSite> &latticeSites, const unsigned int) const

Takes all lattice neighbors in vector latticeSites and subtract the unitcelloffset of site latticeSites[index].

std::vector<std::vector<LatticeSite>> getSitesTranslatedToUnitcell(const std::vector<LatticeSite> &latticeSites, bool sortit = true) const

This function will take a list of lattice sites and for each site outside the unitcell will translate it inside the unitcell and translate the other sites with the same translation.

This translation will give rise to equivalent sites that sometimes are not found by using the set of crystal symmetries given by spglib.

An added requirement to this is that this function should not give rise to any sites in non-periodic directions.

Parameters
• latticeSites: list of lattice sites
• sortIt: if true sort the translated sites

std::vector<std::pair<std::vector<LatticeSite>, std::vector<int>>> getMatchesInPM(const std::vector<std::vector<LatticeSite>> &translatedSites, const std::vector<LatticeSite> &col1) const

Returns the first set of translated sites that exists in col1 of permutationmatrix.

void transformSiteToSupercell(LatticeSite &site, const Structure &superCell, std::unordered_map<LatticeSite, LatticeSite> &primToSuperMap) const

Transforms a site from the primitive structure to a given supercell. This involves finding a map from the site in the primitive cell to the supercell. If no map is found mapping is attempted based on the position of the site in the supercell.

Parameters
• structure: supercell structure
• primToSuperMap: map from primitive to supercell

void addPermutationInformationToOrbits(const std::vector<LatticeSite> &col1, const std::vector<std::vector<LatticeSite>> &permutationMatrix)

Adds the permutation information to the orbits.

This function adds permutation related information to the orbits.

Algorithm

For each orbit:

1. Take representative sites
2. Find the rows these sites belong to (also find the unit cell offsets equivalent sites??)
3. Get all columns for these rows, i.e the sites that are directly equivalent, call these p_equal.
4. Construct all possible permutations for the representative sites, call these p_all
5. Construct the intersect of p_equal and p_all, call this p_allowed_permutations.
6. Get the indice version of p_allowed_permutations and these are then the allowed permutations for this orbit.
7. Take the sites in the orbit: site exist in p_all?: those sites are then related to representative_sites through the permutation else: loop over permutations of the sites: does the permutation exist in p_all?: that permutation is then related to rep_sites through that permutation else: continue

std::vector<std::vector<LatticeSite>> getAllColumnsFromRow(const std::vector<int> &rows, const std::vector<std::vector<LatticeSite>> &permutationMatrix, bool includeTranslatedSites, bool sortIt) const

Returns all columns from the given rows in permutation matrix.

Parameters
• includeTranslatedSites: If true it will also include the equivalent sites found from the rows by moving each site into the unitcell.

bool isRowsTaken(const std::unordered_set<std::vector<int>, VectorHash> &taken_rows, std::vector<int> rows) const

Returns true if rows_sort exists in taken_rows.

std::vector<std::vector<LatticeSite>> getAllColumnsFromSites(const std::vector<LatticeSite> &sites, const std::vector<LatticeSite> &col1, const std::vector<std::vector<LatticeSite>> &permutationMatrix) const

Finds and returns sites in col1 along with their unit cell translated indistinguishable sites.

Will find the sites in col1, extract all columns along with their unit cell translated indistinguishable sites.

bool isSitesPBCCorrect(const std::vector<LatticeSite> &sites) const

Checks that the lattice neighbors do not have any unitcell offsets in a non-periodic direction.

Checks that the lattice neighbors do not have any unitcell offsets in a pbc=false direction.

void removeSitesContainingIndex(const int index, bool onlyConsiderZeroOffset)

Removes from each orbit all sites in equivalent sites that involve the given site.

This function will loop over all orbits in the list and remove from each orbit the sites that match the given index.

Parameters
• index: the index for which to check
• onlyConsiderZeroOffset: if true only sites with zero offset will be removed

void removeSitesNotContainingIndex(const int index, bool onlyConsiderZeroOffset)

Removes from each orbit all sites in equivalent sites that do not involve the given site.

This function will loop over all orbits in the list and remove from each orbit the sites that do _not match the given index.

Parameters
• index: the index for which to check
• onlyConsiderZeroOffset: if true only sites with zero offset will be removed

std::vector<LatticeSite> getFirstColumnOfPermutationMatrix() const

Returns the first column of the permutation matrix used to construct the orbit list.

std::vector<std::vector<LatticeSite>> getPermutationMatrix() const

Returns the permutation matrix used to construct the orbit list.

void subtractSitesFromOrbitList(const OrbitList &orbitList)

Removes all equivalent sites that exist both in this orbit list and the input orbit list.

Removes from each orbit a specific set of sites in this orbit and the corresponding site permutation.

Parameters
• sites: the list of sites that will be removed; the order of sites is irrelevant.

void removeOrbit(const size_t index)

Removes an orbit identified by its index.

This function removes an orbit identified by index from the orbit list.

Parameters
• index: index of the orbit in question

void removeInactiveOrbits(const Structure &structure)

Removes all orbits that have inactive sites.

Removes all orbits that have inactive sites.

Parameters
• structure: the structure containining the number of allowed species on each lattice site

std::vector<Orbit> getOrbits() const

Returns the orbits in this orbit list.

Structure getPrimitiveStructure() const

Returns the primitive structure.

void setPrimitiveStructure(const Structure &primitive)

Sets primitive structure.

Public Members

std::vector<Orbit> _orbits

Contains all the orbits in the orbit list.

## PeriodicTable¶

namespace PeriodicTable

Variables

std::map<std::string, int> strInt
std::map<int, std::string> intStr

## PermutationMatrix¶

class PermutationMatrix

Public Functions

PermutationMatrix(const std::vector<Eigen::Vector3d> &translations, const std::vector<Eigen::Matrix3d> &rotations)
void build(const Eigen::Matrix<double, Eigen::Dynamic, 3, Eigen::RowMajor> &positions)

Build the permutationmap usng the input positions.

Will create all the permuted positions from these positions and the current rotational/translational symmetries.

: Think about pruning positions that fall outside cell if pbc is false : Relate positions to indices : Think about possibility to sort permutationmap (both row-wise and col-wise?) : Think about possibility to only add permutations that are bigger/smaller with motivation of removing duplicates.

std::vector<std::vector<Eigen::Vector3d>> getPermutedPositions() const
std::pair<std::vector<std::vector<int>>, std::vector<Eigen::Vector3d>> getIndexedPermutedPositions()

Returns indices for unique positions as well as the representative positions, same indices share the same position

## Structure¶

class Structure

Class for storing a 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.

Public Functions

Structure()

Default constructor.

Structure(const Eigen::Matrix<double, Dynamic, 3, RowMajor> &positions, const std::vector<std::string> &chemicalSymbols, const Eigen::Matrix3d &cell, const std::vector<bool> &pbc, double tolerance)

Initializes an icet Structure instance.

Parameters
• positions: list of positions in Cartesian coordinates
• chemicalSymbols: list of chemical symbols
• cell: cell metric
• pbc: periodic boundary conditions
• tolerance: numerical tolerance imposed when testing for equality of positions and distances

double getDistance(const size_t index1, const size_t index2, const Vector3d offset1, const Vector3d offset2) const

Returns distance vector between two sites.

This function computes the distance between two sites.

Parameters
• index1: index of the first site
• index2: index of the second site
• offset1: offset of site 1 relative to origin in units of lattice vectors
• offset2: offset of site 2 relative to origin in units of lattice vectors

Vector3d getPosition(const LatticeSite &latticeNeighbor) const

Return the position of a site in Cartesian coordinates.

This function returns the position of a site.

Return
a 3-dimensional position vector
Parameters
• latticeNeighbor: site for which to obtain the position

Vector3d getPositionByIndex(const size_t &index) const

Return the position of a site in Cartesian coordinates.

This function returns the position of a specific site in Cartesian coordinates.

Parameters
• index: index of the site

int getAtomicNumber(const size_t index) const

Returns atomic number of site.

This function returns the atomic number of a site.

Return
atomic number
Parameters
• site: index of site

std::vector<size_t> getUniqueSites() const

Returns the list of unique sites.

void setUniqueSites(const std::vector<size_t> &sites)

Set list of unique sites.

This function sets the symmetrically distinct sites associated with the structure. It requires a vector as input the length of which must match the number of positions.

Parameters
• sites: list of integers

size_t getUniqueSite(const size_t i) const

Returns a unique site.

This function returns the index of a unique site from the list of unique sites.

Return
index of unique site
Parameters
• i: index of site

int findSiteByPosition(const Vector3d &position) const

Returns index of site that matches the given position.

This function returns the index of the site the position of which matches the input position to the tolerance specified for this structure.

Return
index of site; -1 = failed to find a match.
Parameters
• position: position to match in Cartesian coordinates

LatticeSite findLatticeSiteByPosition(const Vector3d &position) const

Return LatticeSite object that matches the given position.

This function returns the LatticeSite object the position of which matches the input position to the tolerance specified for this structure.

The algorithm commences by extracting the fractional position. From the fractional position the unitcell offset is taken by rounding the fractional coordinates to the nearest integer. By subtracting the unitcell offset from the fractional position and taking the dot product with the cell the position relative to the primitive cell is found. The index is found by searching for the remainder position in structure. If no index is found a runtime_error is thrown.

Return
LatticeSite object
Parameters
• position: position to match in Cartesian coordinates

std::vector<LatticeSite> findLatticeSitesByPositions(const std::vector<Vector3d> &positions) const

Return list of LatticeSite objects that matche a given list of positions.

This function returns a list ofLatticeSite object the position of each matches the respective entry in the list of input positions to the tolerance specified for this structure. Internally this function uses Structure::findLatticeSiteByPosition.

Return
list of LatticeSite objects
Parameters
• positions: list of position to match in Cartesian coordinates

size_t size() const

Returns the size of the structure, i.e., the number of sites.

void setPositions(const Eigen::Matrix<double, Dynamic, 3> &positions)

Set the atomic positions.

Eigen::Matrix<double, Dynamic, 3, RowMajor> getPositions() const

Returns positions.

void setAtomicNumbers(const std::vector<int> &atomicNumbers)

Set atomic numbers.

std::vector<int> getAtomicNumbers() const

Returns atomic numbers.

void setChemicalSymbols(const std::vector<std::string> &chemicalSymbols)

Set atomic numbers via chemical symbols.

std::vector<std::string> getChemicalSymbols() const

Returns chemical symbols.

bool hasPBC(const int k) const

Returns periodic boundary condition along direction k.

std::vector<bool> getPBC() const

Returns periodic boundary conditions.

void setPBC(const std::vector<bool> pbc)

Set periodic boundary conditions.

void setCell(const Eigen::Matrix<double, 3, 3> &cell)

Set the cell metric.

Eigen::Matrix<double, 3, 3> getCell() const

Returns the cell metric.

void setNumberOfAllowedSpecies(const std::vector<int> &numbersOfAllowedSpecies)

Set allowed components for each site by vector.

This function allows one to specify the number of components that are allowed on each lattice site via a vector. This can be employed to construct “parallel” cluster expansions such as in (A,B) on site #1 with (C,D) on site #2.

Parameters
• numbersOfAllowedSpecies: list with the number of components allowed on each site

void setNumberOfAllowedSpecies(const int numberOfAllowedSpecies)

Set allowed components for all sites to the same value.

This function allows one to specify the number of components that are allowed on each lattice site via a scalar. This can be employed to construct “parallel” cluster expansions such as in (A,B) on site #1 with (C,D) on site #2.

Parameters
• numberOfAllowedSpecies: number of components allowed

int getNumberOfAllowedSpeciesBySite(const size_t index) const

Returns number of allowed components on each site.

This function returns the number of components allowed on a given site.

Return
the number of the allowed components
Parameters
• index: index of the site

std::vector<int> getNumberOfAllowedSpeciesBySites(const std::vector<LatticeSite> &sites) const

Returns number of allowed components on each site.

This function returns the a vector with number of components allowed on each site index

Return
the list of number of allowed components for each site
Parameters
• indices: indices of sites

void setTolerance(double tolerance)

Set tolerance applied when comparing positions.

double getTolerance() const

Returns tolerance applied when comparing positions.

Public Members

std::vector<int> _atomicNumbers

List of atomic numbers.