The Model class

Objects of this class comprise represent a cluster expansion model

Initialization and methods

class clusterx.model.Model(*args, **kwargs)

Model class

Model class to manage property estimation based on correlations and ECIs.

Parameters:
corrcCorrelationsCalculator, optional

The correlations calculator corresponding to the optimal model.

property_namestr or list of str, optional

The name of the property/properties to be queried in StructureSet.

estimatorobject, optional

An estimator object to predict property values. Alternatively, ECIs can be set.

ecisList[float], optional

Effective cluster interactions (multiplied by multiplicities). Overrides estimator.

filepathstr, optional

Path to a serialized model file (.json or .pickle). If provided, all other arguments are ignored.

standardizebool, default False

If True, standardizes input using sklearn.preprocessing.StandardScaler.

get_all_errors(sset, srtd=False)

Return absolute errors of every structure in a structures set.

Parameters:
ssetStructuresSet

the errors are calculated for every structure in the structures set

srtdbool, default False

if True the output errors are sorted from smallest to largest.

Returns:
ndarray

structured numpy array with fields:

[('index','<i4'), ('error','<f4')]

i.e., every element of the array contains a tuple with an integer, the structure index and a float, the absolute error

get_correlations(structure: Structure, reduce_structure: bool = False, flag=None)

Return global correlations, optionally streaming through reduced neighborhoods.

The reduced structure must first be initialized with init_reduced_model and Structure.init_reduced_structure, as in reduced Monte Carlo. This path uses model-sized accumulators and only reduced-cell orbit geometry, independent of the full supercell size. It works for nonlinear models because correlations are accumulated before applying the estimator.

get_correlations_calculator()

Return correlations calculator of the Model object

get_cv_score(sset, property_name_single, params=None)

Get leave-one-out cross-validation score over structures set.

Parameters:
paramsdict

Parameters to pass to the fit method of the estimator.

get_ecis()

Return array of effective cluster interactions (ECIs) of the model

get_errors(sset, property_name_single)

Compute RMSE, MAE and MaxAE for model in structures set.

get_parent_lattice()

Return parent lattice of the cluster expansion model.

invalidate_prediction_cache()

Discard folded coefficients after modifying a fitted estimator in place.

Estimator/step replacement and refits replacing final coef_/intercept_ are detected automatically. Call this after editing fitted arrays in place or changing transformer/selector settings with set_params(). Starting a MonteCarlo run through reset_mc() also clears the cache.

predict(structure: Structure, reduce_structure: bool = False, flag=None)

Predict property with the optimal cluster expansion model.

Parameters:
structureStructure

structure object to calculate property to.

reduce_structurebool, default False

If true, use reduced structure to predict, only works for diagonal supercell transformation.

flagdict or None

it flags whether the member corrc correlationsCalculator computed orbits from scratch. This can be useful to konw, in order to serialize the model instance to accelerate next property predictions

Example usage:

model = Model(filepath="myfilepath.pickle")
model.predict(structure,flag={})
if  flag["computed_orbits_from_scratch"]:
   print("INFO: correlations calculator computed orbits from scrach.")
   model.serialize(filepath="myfilepath.pickle")
predict_correlations_diff(structure: Structure, index: int, old_sigma: int, new_sigma: int, reduce_structure: bool = False)

Return difference in correlations when changing sigma from old_sigma to new_sigma at index in structure.

For documentation on paremeters, see predict_flip.

predict_correlations_swap(structure: Structure, i: int, j: int, reduce_structure: bool = False) → ArrayLike

Return difference in correlations when swapping sigmas at indices i and j in structure.

For documentation on paremeters, see predict_swap.

predict_flip(structure: Structure, index: int, old_sigma: int, new_sigma: int, reduce_structure: bool = False)

Predict property change by flipping a species.

Structure object remains unchanged This direct difference path assumes an affine model.

Parameters:
structureStructure

structure object to calculate property difference to.

indexint

index of the atom to be substituted

new_sigmaint, default None
reduce_structurebool, default False

If true, use reduced structure to predict flip energy, only works for diagonal supercell transformation.

predict_on_correlations(correlations: array)

Using calculated correlations, return a prediction.

predict_partial(structure: Structure, index: int, divide_n_body: bool = False)

Predict property using only the correlations around site index. This uses all correlations of all clusters that include this site.

Notes

only works for diagonal super cells. It is an additive energy contribution only for affine models.

predict_swap(structure, i, j, reduce_structure: bool = False)

Predict property difference with the optimal cluster expansion model.

This direct difference path assumes an affine model.

Parameters:
structureStructure

structure object to calculate property difference to.

iint

index of first atom position has been swapped

jint

index of second atom position has been swapped

report_errors(sset)

Report fit and CV scores

Parameters:
ssetStructuresSet

the scores are computed for the give structures set

serialize(filepath=None, fmt=None, db_name=None)

Write cluster expansion model to Json database

Parameters:
filepathstr

Name of the file to store the Model instance. It can contain the relative or absolute path. If not given, and if db_name (deprecated) is None, filepathh is set to “cemodel.pickle” and fmt is overriden (set to pickle).

fmtstr

It can take the values "pickle" or "json". So far, object can only be re-initiated from a "pickle" file, therefore this is the preferred format. If not given, it is inferred from the filepathh.

db_name(DEPRECATED) str

Name of the json file containing the database