tce-lib: Tensor Cluster Expansion Library

• tce-lib is an open-source software library that implements tensor cluster expansion to model multicomponent solids and alloys with high efficiency.
• It leverages tensor contractions using precomputed topology tensors and one-hot encoded configuration tensors, eliminating costly cluster enumeration.
• tce-lib supports scalable, high-throughput simulations on parallel architectures, accurately reproducing energy differences and statistical properties.

tce-lib is an open-source software library that implements the tensor cluster expansion (TCE), an adaptable and general formalism for cluster expansion modeling of multicomponent solids. The TCE framework re-casts conventional cluster expansions as tensor contractions between precomputed topology tensors and one-hot encoded configuration tensors, eliminating the need for cluster enumeration and enabling efficient computation on massively parallel architectures. tce-lib facilitates rapid evaluation of correlation functions, energy differences, and statistical averages, supporting both traditional alloy modeling tasks and large-scale atomistic simulations.

1. Tensor Cluster Expansion: Formal Definition and Motivation

The tensor cluster expansion (TCE) represents a re-formulation of the standard cluster expansion (CE) technique used in the simulation of materials with multiple atomic components (Jeffries et al., 4 Sep 2025). Standard CE expresses the total energy of a configuration as a linear combination of correlation functions (cluster counts) weighted by effective cluster interactions. These correlation functions are usually obtained by iterating over all symmetrically equivalent clusters in a reference lattice.

TCE instead expresses correlation functions as tensor contractions involving:

• A one-hot encoded configuration tensor $X$: for $N$ lattice sites and $m$ atomic types, $X_{i\alpha} = 1$ if site $i$ is occupied by atomic type $\alpha$, zero otherwise.
• Topology tensors $A$ (for pair interactions) and $B$ (for higher-order clusters): $A_{ij}^{(n)}$ flags $n$-th neighbor pairs, $B_{ijk}^{(n)}$ flags valid triplets or higher cliques.

The two-body and three-body correlation functions are, respectively:

$$N_{\alpha\beta}^{(n)} = \sum_{i,j} A_{ij}^{(n)} X_{i\alpha} X_{j\beta}$$

$$M_{\alpha\beta\gamma}^{(n)} = \sum_{i,j,k} B_{ijk}^{(n)} X_{i\alpha} X_{j\beta} X_{k\gamma}$$

This multilinear formulation generalizes to any lattice symmetry or dimensionality and enables direct mapping to high-performance tensor computation kernels.

2. Implementation Architecture in tce-lib

tce-lib operationalizes the TCE formalism through optimized sparse–dense tensor contraction routines. The main ingredients and workflow are as follows:

• Preprocessing: Generation of topology tensors $A$ and $B$, which encode lattice connectivity for all cluster orders and interaction ranges of interest.
• Configuration encoding: Site occupations are mapped to a tensor $X$, structured to support vectorization and batched processing.
• Mixed contraction: Correlation functions are calculated using sparse contraction libraries (e.g., opt-einsum, specialized CUDA kernels), allowing rapid summation over relevant clusters without explicit enumeration.

Energy evaluations, feature vector updates, and local changes are computed as:

$$H_{\rm eff}(X) = \sum_{n} \frac{1}{2!}\epsilon_{\alpha\beta}^{(n)} A_{ij}^{(n)} X_{i\alpha} X_{j\beta} + \sum_{n} \frac{1}{3!}\zeta_{\alpha\beta\gamma}^{(n)} B_{ijk}^{(n)} X_{i\alpha} X_{j\beta} X_{k\gamma}$$

(Eq. 3, (Jeffries et al., 4 Sep 2025))

For local updates,

$$\Delta H_{\rm eff} = H_{\rm eff}(X') - H_{\rm eff}(X) = \mathbf{j} \cdot [\mathbf{t}(X') - \mathbf{t}(X)]$$

where $\mathbf{t}(X)$ is the vector of all contracted cluster counts.

3. Computational Efficiency and Parallelization

By casting cluster counts as tensor contractions, tce-lib avoids per-cluster loops and achieves highly regular memory access patterns. This approach enables efficient utilization of parallel computing resources (GPUs, TPUs, etc.), supporting:

• Linear scaling with system size for global property evaluations.
• Nearly $\mathcal{O}(1)$ cost for local energy difference calculations, achieved by restricting contractions to sites affected by configuration changes.
• Batched processing for high-throughput ensemble simulations.

The design is particularly suited to modeling systems with large supercells and many atomic components, as seen in high-entropy alloys and complex solution phases.

4. Application to Materials Simulation: Alloy Examples

tce-lib has been applied to fit CE models for TaW and CoNiCrFeMn alloys, representative of binary and multi-component solid solutions.

TaW Binary Alloy

• A CE model fitted to Ta$_{1-x}$W$_x$ DFT data using TCE.
• Enthalpy of mixing $$\Delta H_{\mathrm{mix}}(x) = E(x) - x E_{\mathrm{W}} - (1-x) E_{\mathrm{Ta}}$$ computed via Monte Carlo simulation shows close agreement with DFT benchmarks.

CoNiCrFeMn High-Entropy Alloy

• TCE-fitted CE model based on surrogate simulations with MEAM potentials.
• Cowley short-range order parameters $$\chi_{\alpha\beta} = 1 - p_{\alpha\beta}/((2-\delta_{\alpha\beta})x_\alpha x_\beta)$$, where $p_{\alpha\beta}$ is the probability of finding species $\alpha,\beta$ as nearest neighbors, and $x_\alpha$ is the atomic fraction.
• MC/MD simulations with tce-lib reproduce full SRO parameter sets, accurately capturing chemical ordering trends.

Quantitative agreement with ground truth data (DFT, MC/MD) is observed for both energy and statistical measures, with cross-validation residuals below 10 meV/atom for enthalpy predictions.

5. Mathematical Formalism and Local Energy Updates

TCE’s linear operator structure enables compact mathematical representation of both energy and statistical moment calculations. The effective Hamiltonian is:

$H_{\rm eff}(X) = \mathbf{j} \cdot \mathbf{t}(X)$

Given two configurations $X$ and $X'$ differing only on a subset of sites, the energy difference is:

$$\Delta H_{\rm eff} = \mathbf{j} \cdot [\mathbf{t}(X') - \mathbf{t}(X)]$$

Most entries in $[\mathbf{t}(X') - \mathbf{t}(X)]$ are zero, enabling rapid updates through focused contraction limited to affected sites. This principle is critical for algorithms that require frequent local moves, such as kinetic Monte Carlo and atomistic MD/MC hybrid simulations.

6. Significance for Alloy Modeling and Atomistic Simulation

The tce-lib approach offers several key advantages:

• Extension to arbitrary and exotic lattice geometries, including low-symmetry structures, enabled by the topology tensor abstraction.
• Efficient large-scale simulation capability due to high computational throughput and $\mathcal{O}(1)$ local update performance.
• Accurate reproduction of both thermodynamic and statistical properties (enthlapy, SRO parameters) validated against underlying quantum mechanical and atomistic benchmarks.

These features support the rapid development and deployment of high-fidelity CE models for a broad class of multi-component materials, including high-entropy alloys and related solution phases.

7. Validation and Limitations

Comparison with ground truth DFT and MC/MD data demonstrates that tce-lib’s TCE formalism is both efficient and accurate (Jeffries et al., 4 Sep 2025). MC simulation results for TaW show enthalpy curves in close agreement with DFT. SRO parameters for CoNiCrFeMn match those produced by independent MC/MD validation runs. When Cr segregation is present (i.e., negative $\chi_{\mathrm{CrCr}}$), the prediction tracks quantitatively.

A plausible implication is that, while tce-lib generalizes CE to arbitrary lattices and supports parallel hardware execution, accuracy is ultimately contingent on the quality of cluster interactions fitted and the completeness of topology tensors employed. Users needing higher-order or non-standard interactions may require further topology tensor specification.

---

In summary, tce-lib generalizes the cluster expansion framework into a scalable, high-performance tensor-contraction approach. By leveraging precomputed topology tensors and one-hot encoded site configurations, the library achieves efficient, accurate property calculations for multicomponent alloys and complex solids, validated by close agreement with ab initio and atomistic simulation data (Jeffries et al., 4 Sep 2025).