build_nonlinear_model

Command-line usage

usage: cell build_nonlinear_model [-h] [-ccalc-filepath ccalc.pickle]
                                  [-xp-filepath xp.npz] [-mof model.pickle]
                                  [-rm None] [-sm None] [-thr None] [-nt None]
                                  [-weights-filepath None] [-std] [-ts None]
                                  [-rs 42] [-sh]
                                  property_name [selection_must_include]

positional arguments:
  property_name         Property to be modelled. Must be present in the
                        StructuresSet object.
  selection_must_include
                        [[]]

options:
  -h, --help            show this help message and exit
  -ccalc-filepath ccalc.pickle
                        Path to the pickle file of a serialized
                        CorrelationsCalculator object.
  -xp-filepath xp.npz   Path to the npz file of a serialized correlation
                        matrix (from compute_comat).
  -mof, --model-filepath model.pickle
                        Path to serialize the created Model object.
  -rm, --regression-model None
                        Dictionary of estimator options.
  -sm, --selection-model None
                        Dictionary of estimator options for feature selection
                        model (e.g. LASSO).
  -thr, --selection-threshold None
                        Threshold to interactions.
  -nt, --nonlinear-transformation None
                        Dictionary of nonlinear transformation settings.
  -weights-filepath None
                        Sample weights for fitting and evaluating the weighted
                        MSE.
  -std, --standardize   Standardize the input data.
  -ts, --test-size None
                        Fraction of samples to reserve as a hold-out test set.
                        If not provided or <= 0, no split is performed.
  -rs, --random-state 42
                        Random seed used for the optional train/test split.
  -sh, --shuffle        Shuffle samples before the optional train/test split.

Arguments and behavior

clusterx.cli.build_nonlinear_model.build_nonlinear_model(property_name, ccalc_filepath='ccalc.pickle', xp_filepath='xp.npz', model_filepath='model.pickle', regression_model=None, selection_model=None, selection_threshold=None, selection_must_include=[], nonlinear_transformation=None, weights_filepath=None, standardize=False, test_size=None, random_state=42, shuffle=False)

Build and serialize a nonlinear cluster expansion (CE) model.

This function constructs a nonlinear model for a given property based on a precomputed correlation matrix and correlation calculator. It combines optional nonlinear transformations, feature selection, and regression estimators to fit and evaluate a CE model. The final model is serialized to disk.

The function is designed to be invoked both from the command line and programmatically.

Parameters:
property_namestr

Name of the property to be modeled. Must exist in the StructuresSet object used in correlation computations.

ccalc_filepathstr, optional

Path to the pickle file of a serialized CorrelationsCalculator object. Default is "ccalc.pickle".

xp_filepathstr, optional

Path to the .npz file containing the serialized correlation matrix (as produced by compute_comat). Default is "xp.npz".

model_filepathstr, optional

Path to serialize the resulting Model object. Default is "model.pickle".

regression_modeldict, optional

Dictionary specifying the regression estimator configuration, with keys "module", "class", and "args". Defaults to {"module": "sklearn.linear_model", "class": "LinearRegression", "args": {}}.

selection_modeldict, optional

Dictionary specifying a feature selection model, typically a LASSO variant. Defaults to {"module": "sklearn.linear_model", "class": "LassoCV", "args": {"alphas": 10, "cv": 10}}.

selection_thresholdfloat, optional

Threshold applied to the selected interactions for filtering.

selection_must_includelist of int, optional

List of feature indices that must always be included in the model.

nonlinear_transformationdict, optional

Dictionary specifying the nonlinear transformation settings. Defaults to {"module": "sklearn.preprocessing", "class": "PolynomialFeatures", "args": {"degree": 1, "include_bias": False}}.

weights_filepathstr, optional

Path to an .npz file containing sample weights for fitting and evaluating the weighted mean squared error (MSE).

standardizebool, optional

Whether to standardize the input data prior to fitting. Default is False.

test_sizefloat, optional

Fraction of samples reserved for a final hold-out test set. If None or <= 0, no split is performed.

random_stateint, optional

Random seed for the optional train/test split.

shufflebool, optional

Whether to shuffle before splitting.

Returns:
None

The trained model is serialized to the specified model_filepath.

Notes

  • The function prints progress and diagnostic information to stdout.

  • If weights_filepath is provided, weighted regression is performed.

  • Model summaries are printed for both the selector and regressor stages.

Examples

Run from command line:

$ clusterx build-nonlinear-model energy --ccalc ccalc.pickle               --xp xp.npz --model model.pickle --standardize

Or use programmatically:

build_nonlinear_model(
    property_name="energy",
    ccalc_filepath="ccalc.pickle",
    xp_filepath="xp.npz",
    regression_model={"class": "Ridge", "args": {"alpha": 1.0}},
    standardize=True
)