Cluster Expansion¶

Optional dependency

ClusterExpansion requires the ce extra.

uvpip

uv add "materialsframework[ce]"

pip install "materialsframework[ce]"

ClusterExpansion ¶

ClusterExpansion(
    symprec: float = 1e-05,
    position_tolerance: float | None = None,
    is_relaxed: bool = True,
    fit_method: Literal[
        "ardr",
        "bayesian-ridge",
        "elasticnet",
        "lasso",
        "least-squares",
        "omp",
        "rfe",
        "ridge",
        "split-bregman",
    ] = "ardr",
    standardize: bool = True,
    validation_method: Literal[
        "shuffle-split", "k-fold"
    ] = "k-fold",
    n_splits: int = 10,
    check_condition: bool = True,
    seed: int = 42,
    verbose: bool = False,
    calculator: BaseCalculator | None = None,
)

A class to handle cluster expansion calculations.

Initialize the ClusterExpansion instance.

Parameters:

Name	Type	Description	Default
`symprec`	`float`	Symmetry precision for structure analysis. Defaults to 1e-5.	`1e-05`
`position_tolerance`	`float \| None`	Tolerance for atomic position comparison. Defaults to None.	`None`
`is_relaxed`	`bool`	Whether the input structures are relaxed. Defaults to True.	`True`
`fit_method`	`Literal['ardr', 'bayesian-ridge', 'elasticnet', 'lasso', 'least-squares', 'omp', 'rfe', 'ridge', 'split-bregman']`	Method used for fitting the cluster expansion. Defaults to "ardr".	`'ardr'`
`standardize`	`bool`	Whether to standardize the data before fitting. Defaults to True.	`True`
`validation_method`	`Literal['shuffle-split', 'k-fold']`	Method used for validation of the model. Defaults to "k-fold".	`'k-fold'`
`n_splits`	`int`	Number of splits for cross-validation. Defaults to 10.	`10`
`check_condition`	`bool`	Whether to check the condition number of the fit. Defaults to True.	`True`
`seed`	`int`	Random seed for reproducibility. Defaults to 42.	`42`
`verbose`	`bool`	Whether to print detailed output during relaxation and fitting. Defaults to False.	`False`
`calculator`	`BaseCalculator \| None`	Calculator for energy and property calculations. Defaults to None.	`None`

calculator `property` ¶

calculator: BaseCalculator

Returns the calculator used for energy and force calculations.

If the calculator instance is not already initialized, this method returns the default calculator.

Returns:

Name	Type	Description
`BaseCalculator`	`BaseCalculator`	The calculator object used for force and energy calculations.

fit ¶

fit(
    structures: list[Structure] | SQLite3Database,
    primitive_structure: Atoms,
    cutoffs: list[float],
    chemical_symbols: list[str] | list[list[str]],
    properties: list[str],
    fit_property: str = "mixing_energy",
)

Fit the cluster expansion model using the provided structures and calculator.