openmaterials.ai / codes / smol
smol: cluster expansions and Monte Carlo on lattices
Builds generalized cluster expansions on pymatgen structures, fits them to first-principles energies and samples canonical and semigrand canonical ensembles by Monte Carlo.
What it is and how it works
Energy as a function of occupancy
In H(sigma) = sum over beta of m_beta J_beta Theta_beta(sigma), correlation functions over symmetry-equivalent clusters multiply fitted coefficients. The function set may be a basis or redundant (Barroso-Luque 2022).
smol.cofe
Site function sets (polynomial, trigonometric, indicator) and cluster orbits from a disordered pymatgen structure with species, charges or vacancies (Barroso-Luque 2022).
Extra interaction terms
An optional electrostatic pair potential for ionic structures improves training convergence. Other pair or strain terms fit the same slot (Barroso-Luque 2022).
smol.moca
Monte Carlo in canonical and semigrand canonical ensembles. Proposals, ensembles, traces and kernels are separate objects. Updates run in Cython (Barroso-Luque 2022).
Fitting
Coefficients come from regularized linear regression, for instance lasso on the l1 norm of the ECIs with the penalty tuned by fivefold cross-validation (Xie 2024).
Materials Project stack
The only cluster expansion package built on pymatgen, so FireWorks, atomate and database tools slot in around it (Barroso-Luque 2022).
What people do with it
- 0.5 meVRMSE per atom, Ag-Li gamma-brass expansionXie 2024
- 1,000,000Metropolis steps per T at or below 500 KXie 2024
Ag-Li free energies for anode-free cells
Cluster expansions for BCC, FCC and gamma-brass (RMSE 3.3, 1.5 and 0.5 meV/atom), canonical MC and thermodynamic integration give free energies. Four phases stable at 200 K, two at 300 K. Xie 2024
Paddlewheel effect in Li3PS4
Low-energy Li/vacancy orderings of alpha and beta Li3PS4 also came from smol cluster expansion Monte Carlo. NEB puts a 120 degree PS4 rotation above 1 eV and a Li hop in beta at 0.112 eV. Jun 2024
How it is used
Define the lattice model
A disordered pymatgen Structure with allowed species per site, cutoffs per cluster size.
Compute training data
Enumerate orderings, relax with DFT, collect energies as the fitting targets.
Fit the expansion
Build the feature matrix in smol.cofe, fit ECIs by regularized regression, check CV error.
Sample
Run canonical or semigrand Monte Carlo in smol.moca over temperature and composition.
Integrate
Average energy, heat capacity, free energy by thermodynamic integration, ground states.
What smol is
smol fits cluster expansions to first-principles energies of configurations on a lattice and samples them by Monte Carlo. It is used for configurational thermodynamics of alloys and ionic conductors. On the map it serves the quantities it fits and samples.
WebsiteOn the mapAll codesLicense: BSD-3-Clause
In more detail
Formalism
A configuration is a string of occupation variables, one per site of an N-site supercell, and any lattice model is a sum of cluster functions over subsets of sites. smol writes a symmetry-invariant model as H(sigma) = sum over beta of m_beta J_beta Theta_beta(sigma), with crystallographic multiplicities m_beta, coefficients J_beta and correlation functions Theta_beta that average cluster product functions over orbits of symmetry-equivalent clusters. Unlike the classical cluster expansion, the set of correlation functions need not be a basis: any complete set spanning the invariant subspace, redundant or not, is allowed (Barroso-Luque 2022).
Design and fitting
smol is pure Python with a few Cython components, object oriented along the mathematical abstractions, and lean in dependencies, with structure handling and regression from other packages. It is the only cluster expansion package built on pymatgen, which supplies structures and symmetries and links it to FireWorks and atomate. Against the C++ packages ATAT and CASM and the Python package icet, its stated aim is fast development of new methodology (Barroso-Luque 2022). Xie 2024 fitted coefficients by lasso with the penalty from fivefold cross-validation on 64, 134 and 96 training structures for BCC, FCC and gamma-brass Ag-Li, reaching RMSE of 3.3, 1.5 and 0.5 meV/atom with smol and sparse-lm.
Sampling and thermodynamics
smol.moca samples canonical and semigrand canonical ensembles with interchangeable proposal, ensemble, trace and kernel objects (Barroso-Luque 2022). Xie 2024 annealed Ag-Li cells from 10000 K to 20 K with 250,000 to 1,000,000 Metropolis steps per temperature and integrated the average energy over beta for the configurational free energy, adding Phonopy phonon terms. At 200 K four phases are stable, at 300 K only FCC Ag and the BCC solid solution. Jun 2024 drew low-energy Li/vacancy orderings of Li3PS4 from smol Monte Carlo for its local occupancy analysis.
What it computes on the map
2 quantities, drawn by tier with the data flow between them. Dashed boxes are intermediate quantities. Select one for its formula and the other codes that compute it.
Embed this submap
<iframe src="https://openmaterials.ai/m/c56731602651/80000000000000000000000001?embed=1" title="smol on the OpenMaterials map" width="100%" height="480" loading="lazy" style="border:1px solid #EBEBEB;border-radius:6px"></iframe>
Each quantity with the interface the representation records.
- ConfigurationalEnergyClusterExpansion.predict / ExpansionProcessor.compute_property (cofe/expansion.py:259-288)ev
- PotentialClusterExpansion (cofe/expansion.py:159 coefs; :172-183 ECI); load/save cluster_expansion.json
References
The code
The papers that describe the code; cite them when you use it.
- L. Barroso-Luque, J. H. Yang, F. Xie et al., smol: A Python package for cluster expansions and beyond, Journal of Open Source Software, 2022. doi.org/10.21105/joss.04504
Applications
Highly cited studies that cite the code, with a few picked by hand.
- P. Zhong, S. Gupta, B. Deng et al., Effect of Cation Disorder on Lithium Transport in Halide Superionic Conductors, ACS Energy Letters, 2024. doi.org/10.1021/acsenergylett.4c00799
- F. Xie, M. S. Diallo, H. Kim et al., The Microscopic Mechanism of Lithiation and Delithiation in the Ag/C Buffer Layer for AnodeāFree SolidāState Batteries, Advanced Energy Materials, 2024. doi.org/10.1002/aenm.202302960
- K. Jun, B. Lee, R. L. Kam et al., The nonexistence of a paddlewheel effect in superionic conductors, Proceedings of the National Academy of Sciences, 2024. doi.org/10.1073/pnas.2316493121
How to cite
L. Barroso-Luque, J. H. Yang, F. Xie, et al., smol: A Python package for cluster expansions and beyond, J. Open Source Softw. 7, 4504 (2022)