Lincege

A julia package for computing LINked Cluster Expansions on a GEneral geometry (LINCEGE).

The general pipeline is:

1. Define a unit cell and lattice geometry.
2. Generate all unique clusters up to a desired order using a cluster set and hasher.
3. Build an Expansion from those clusters.
4. Call summation! to populate the NLCE weights.
5. Export results with write_to_json.

See the online documentation for worked examples on the square lattice, Kagome lattice, and Pyrochlore unit cell.

AbstractCluster

Abstract base type for a single cluster — a connected subgraph of the lattice with an associated lattice coefficient used in the NLCE summation.

Subtypes must implement:

• Base.length(c) — number of sites (vertices) in the cluster
• Base.hash(c, h) — the cluster's graph hash (ghash)

AbstractClusterExpansionLattice <: AbstractInfiniteLattice

Abstract base type for lattices where each expansion vertex represents a cluster of physical sites (a unit cell), rather than a single site.

Subtypes must implement all methods of AbstractInfiniteLattice, plus:

• n_site_colors(lattice) — number of distinct site colors in the lattice
• connections(lattice) — mapping from expansion vertices to their constituent lattice vertices

AbstractClusterSet{C<:AbstractCluster, H<:AbstractHasher}

Abstract base type for a collection of unique clusters sharing a common hasher. Clusters that are equivalent under the hasher's symmetry are merged

Subtypes must implement:

• Base.length(cs) — number of stored clusters
• Base.in(c, cs) — membership test
• Base.iterate(cs) / Base.iterate(cs, state) — iteration over clusters
• Base.push!(cs, c) — add a cluster
• Base.pop!(cs, c) — remove and return a cluster
• ghash(cs, c) / ghash(cs, vs) — delegate to the hasher

AbstractExpansion

Abstract base type for an NLCE expansion. Stores the subgraph relationships between clusters and the weight matrix that summation! populates.

Subtypes must implement:

• Base.getindex(e, cluster_id, order) — weight for a cluster at a given order
• Base.length(e) — total number of clusters (including single-site terms)
• add_array!(e, order, per_cluster) — accumulate a per-cluster vector into the weights at order
• order_ids(e, order) — indices of all clusters first appearing at order
• get_subclusters(e, cluster_id) — indices of all strict subclusters of cluster_id
• order_offset(e) — 0 for site expansions, 1 for cluster expansions

AbstractHasher

Abstract base type for cluster hashing. A hasher maps a vertex set to a graph hash, with two vertex sets receiving the same hash if and only if they are equivalent under the symmetry the hasher preserves.

Subtypes must implement:

• ghash(hasher, vs::LatticeVertices) — hash for a Site Expansions
• ghash(hasher, vs::ExpansionVertices) — hash for a Cluster Expansion

AbstractInfiniteLattice <: AbstractLattice

Abstract base type for an infinite lattice used to enumerate clusters.

Subtypes must implement all methods of AbstractLattice, plus:

• n_unique_sites(lattice) — number of translationally-inequivalent sites in the lattice

AbstractLattice

Abstract base type for a lattice geometry.

Subtypes must implement:

• centers(lattice) — vertex set(s) used as DFS roots when generating clusters
• max_order(lattice) — maximum cluster order (number of sites) to generate
• neighbors(lattice, vs) — vertex indices adjacent to the vertex set vs but not in it
• get_coordinates(lattice) — Cartesian coordinate matrix (dim × n_sites)
• get_labels(lattice) — translation labels for each site
• get_site_colors(lattice) — site colors for each site
• bond_matrix(lattice) — integer adjacency matrix encoding bond types

AbstractVertices{V}

Abstract base type for a set of vertices of element type V.

Subtypes must implement:

• vertices(vs) — return the underlying iterable of vertex indices
• Base.collect(vs) — return a sorted Vector{V}
• Base.sort(vs) — return a sorted copy
• Base.intersect(vs1, vs2) — set intersection
• Base.setdiff(vs1, vs2) — set difference
• Base.union(vs1, vs2) — set union (two-argument form)
• Base.in(v, vs) — membership test
• Base.eltype(vs) — element type V

Bond(site1, site2, direction, bond_type)

Bond of given type between two sites along the given direction, in primitive lattice vector notation

Expansion(clusters, lattice, max_order)

Arbitrary expansion of clusters in the NLCE sense, contains the weights necessary to perform the NLCE summation.

ExpansionBond(site1, site2, direction, bond_type)

Bond of given type between two sites inside of the expansion basis, indexed [expansion basis, element number] along the given direction, in primitive lattice vector notation

ExpansionUnitCell(basis, primitive_vectors, site_colors, bonds, expansion_bonds)

Unit cell containing the given information, generally to be used for a cluster expansion. The bonds are between sites in the basis, and the expansion bonds are between the unit cells in the expansion. Coordinates are written [x1 x2 x3 ...; y1 y2 y3 ...; z1 z2 z3 ...;].

NotImplementedError{M}(m)

Exception thrown when a method required for a NLCE is not implemented. Taken directly from Graphs.jl.

SiteExpansionLattice(max_order, unit_cell)

An infinite lattice that contains the information necessary to perform the site expansion utilizing the given unit_cell

UnitCell(basis, primitive_vectors, bonds, site_colors)

Unit cell containing the given information, generally to be used for a site expansion. Coordinates are written [x1 x2 x3 ...; y1 y2 y3 ...; z1 z2 z3 ...;].

IsomorphicClusterSet(lattice)

ClusterSet constructor that initializes a ClusterSet with a hasher that preserves invariance under graph isomorphisms

SymmetricClusterSet(lattice, symmetries)

ClusterSet constructor that initializes a ClusterSet with a hasher that preserves invariance under the given point group symmetries of the lattice.

TranslationClusterSet(lattice)

ClusterSet constructor that initializes a ClusterSet with a hasher that preserves translational invariance

clusters_from_clusters!(new_clusters, old_clusters)

Populates newclusters from the clusters inside oldclusters using the hasher inside the new_clusters ClusterSet

clusters_from_lattice!(clusters, lattice; spawn_depth=3)

Generates all clusters from an infinite lattice up till the given max_order, populates clusters with all the corresponding clusters reduced by the hashing function

summation!(expansion, max_order)

Performs the recursive NLCE summation up till the max_order and populates the given expansion with the resultant weights

Finds the canonical ordering of an edge-unlabeled cluster using Nauty. Returns (nauty_hash, permutation).

Finds the canonical ordering of an edge-labeled cluster using Nauty. Returns (nauty_hash, permutation).

write_to_json(expansion, lattice, clusters, filepath)

Writes an expansion to a JSON file at the given filepath