# espei.parameter_selection package¶

## espei.parameter_selection.model_building module¶

Building candidate models

espei.parameter_selection.model_building.build_candidate_models(configuration, features)

Return a dictionary of features and candidate models

Parameters
• configuration (tuple) – Configuration tuple, e.g. ((‘A’, ‘B’, ‘C’), ‘A’)

• features (dict) – Dictionary of {str: list} of generic features for a model, not considering the configuration. For example: {‘CPM_FORM’: [sympy.S.One, v.T, v.T**2, v.T**3]}

Returns

Dictionary of {feature: [candidate_models])

Return type

dict

Notes

Currently only works for binary and ternary interactions.

Candidate models match the following spec: 1. Candidates with multiple features specified will have 2. orders of parameters (L0, L0 and L1, …) have the same number of temperatures

Note that high orders of parameters with multiple temperatures are not required to contain all the temperatures of the low order parameters. For example, the following parameters can be generated L0: A L1: A + BT

espei.parameter_selection.model_building.build_feature_sets(temperature_features, interaction_features)

Return a list of broadcasted features

Parameters
• temperature_features (list) – List of temperature features that will become a successive_list, such as [TlogT, T-1, T2]

• interaction_features (list) – List of interaction features that will become a successive_list, such as [YS, YS*Z, YS*Z**2]

Returns

Return type

list

Notes

This allows two sets of features, e.g. [TlogT, T-1, T2] and [YS, YS*Z, YS*Z**2] and generates a list of feature sets where the temperatures and interactions are broadcasted successively.

Generates candidate feature sets like: L0: A + BT, L1: A L0: A , L1: A + BT

but not lists that are not successive: L0: A + BT, L1: Nothing, L2: A L0: Nothing, L1: A + BT

There’s still some debate whether it makes sense from an information theory perspective to add a L1 B term without an L0 B term. However this might be more representative of how people usually model thermodynamics.

Does not distribute multiplication/sums or make assumptions about the elements of the feature lists. They can be strings, ints, objects, tuples, etc..

The number of features (related to the complexity) is a geometric series. For $N$ temperature features and $M$ interaction features, the total number of feature sets should be $N*(1-N**M)/(1-N)$. If $N=1$, then there are $M$ total feature sets.

espei.parameter_selection.model_building.make_successive(xs)

Return a list of successive combinations

Parameters

xs (list) – List of elements, e.g. [X, Y, Z]

Returns

List of combinations where each combination include all the preceding elements

Return type

list

Examples

>>> make_successive(['W', 'X', 'Y', 'Z'])
[['W'], ['W', 'X'], ['W', 'X', 'Y'], ['W', 'X', 'Y', 'Z']]


## espei.parameter_selection.redlich_kister module¶

Tools for construction Redlich-Kister polynomials used in parameter selection.

espei.parameter_selection.redlich_kister.calc_interaction_product(site_fractions)

Calculate the interaction product for sublattice configurations

Parameters

site_fractions (list) – List of sublattice configurations. Sites on each sublattice be in order with respect to the elements in the sublattice. The list should be 3d of (configurations, sublattices, values)

Returns

List of interaction products, Z, for each sublattice

Return type

list

Examples

>>> # interaction product for an (A) configuration
>>> calc_interaction_product([[1.0]])
[1.0]
>>> # interaction product for [(A,B), (A,B)(A)] configurations that are equal
>>> calc_interaction_product([[[0.5, 0.5]], [[0.5, 0.5], 1]])
[0.0, 0.0]
>>> # interaction product for an [(A,B)] configuration
>>> calc_interaction_product([[[0.1, 0.9]]])
[-0.8]
>>> # interaction product for an [(A,B)(A,B)] configuration
>>> calc_interaction_product([[[0.2, 0.8], [0.4, 0.6]]])
[0.12]
>>> # ternary case, (A,B,C) interaction
>>> calc_interaction_product([[[0.333, 0.333, 0.334]]])
[[0.333, 0.333, 0.334]]
>>> # ternary 2SL case, (A,B,C)(A) interaction
>>> calc_interaction_product([[[0.333, 0.333, 0.334], 1.0]])
[[0.333, 0.333, 0.334]]

espei.parameter_selection.redlich_kister.calc_site_fraction_product(site_fractions)

Calculate the site fraction product for sublattice configurations

Parameters

site_fractions (list) – List of sublattice configurations. The list should be 3d of (configurations, sublattices, values)

Returns

List of site fraction products, YS, for each sublattice

Return type

list

Examples

>>> # site fraction product for an (A,B)(A) configuration
>>> calc_site_fraction_product([[[0.2, 0.8], 1.0]])
[0.16...]
>>> # site fraction product for [(A,B)(A), (A,B)(A)] configurations
>>> calc_site_fraction_product([[[0.2, 0.8], 1.0], [[0.3, 0.7], 1.0]])
[0.16..., 0.21]
>>> # site fraction product for [(A,B)(A,B)] configurations
>>> calc_site_fraction_product([[[0.2, 0.8], [0.4, 0.6]]])
[0.0384...]
>>> # ternary case, (A,B,C) interaction
>>> calc_site_fraction_product([[[0.25, 0.25, 0.5]]])
[0.03125]


## espei.parameter_selection.selection module¶

Fit, score and select models

espei.parameter_selection.selection.fit_model(feature_matrix, data_quantities, ridge_alpha, weights=None)

Return model coefficients fit by scikit-learn’s LinearRegression

Parameters
• feature_matrix (ndarray) – (M*N) regressor matrix. The transformed model inputs (y_i, T, P, etc.)

• data_quantities (ndarray) – (M,) response vector. Target values of the output (e.g. HM_MIX) to reproduce.

• ridge_alpha (float) – Value of the $alpha$ hyperparameter used in ridge regression. Defaults to 1.0e-100, which should be degenerate with ordinary least squares regression. For now, the parameter is applied to all features.

Returns

List of model coefficients of shape (N,)

Return type

list

Notes

Solve Ax = b. x are the desired model coefficients. A is the ‘feature_matrix’. b corrresponds to ‘data_quantities’.

espei.parameter_selection.selection.score_model(feature_matrix, data_quantities, model_coefficients, feature_list, weights, aicc_factor=None, rss_numerical_limit=1e-16)

Use the AICc to score a model that has been fit.

Parameters
• feature_matrix (ndarray) – (M*N) regressor matrix. The transformed model inputs (y_i, T, P, etc.)

• data_quantities (ndarray) – (M,) response vector. Target values of the output (e.g. HM_MIX) to reproduce.

• model_coefficients (list) – List of fitted model coefficients to be scored. Has shape (N,).

• feature_list (list) – Polynomial coefficients corresponding to each column of ‘feature_matrix’. Has shape (N,). Purely a logging aid.

• aicc_factor (float) – Multiplication factor for the AICc’s parameter penalty.

• rss_numerical_limit (float) – Anything with an absolute value smaller than this is set to zero.

Returns

A model score

Return type

float

Notes

Solve Ax = b, where ‘feature_matrix’ is A and ‘data_quantities’ is b.

The likelihood function is a simple least squares with no regularization. The form of the AIC is valid under assumption all sample variances are random and Gaussian, model is univariate. It is assumed the model here is univariate with T.

espei.parameter_selection.selection.select_model(candidate_models, ridge_alpha, weights, aicc_factor=None)

Select a model from a series of candidates by fitting and scoring them

Parameters
• candidate_models (list) – List of tuples of (features, feature_matrix, data_quantities)

• ridge_alpha (float) – Value of the $alpha$ hyperparameter used in ridge regression. Defaults to 1.0e-100, which should be degenerate with ordinary least squares regression. For now, the parameter is applied to all features.

• aicc_factor (float) – Multiplication factor for the AICc’s parameter penalty.

Returns

Tuple of (feature_list, model_coefficients) for the highest scoring model

Return type

tuple

## espei.parameter_selection.ternary_parameters module¶

Build fittable models for ternary parameter selection

espei.parameter_selection.ternary_parameters.build_ternary_feature_matrix(prop, candidate_models, desired_data)

Return an MxN matrix of M data sample and N features.

Parameters
• prop (str) – String name of the property, e.g. ‘HM_MIX’

• candidate_models (list) – List of SymPy parameters that can be fit for this property.

• desired_data (dict) – Full dataset dictionary containing values, conditions, etc.

Returns

An MxN matrix of M samples (from desired data) and N features.

Return type

numpy.ndarray

## espei.parameter_selection.utils module¶

Tools used across parameter selection modules

espei.parameter_selection.utils.get_data_quantities(desired_property, fixed_model, fixed_portions, data)
Parameters
• desired_property (str) – String property corresponding to the features that could be fit, e.g. HM, SM_FORM, CPM_MIX

• fixed_model (pycalphad.Model) – Model with all lower order (in composition) terms already fit. Pure element reference state (GHSER functions) should be set to zero.

• fixed_portions (List[sympy.Expr]) – SymPy expressions for model parameters and interaction productions for higher order (in T) terms for this property, e.g. [0, 3.0*YS*v.T]. In [qty]/mole-formula.

• data (List[Dict[str, Any]]) – ESPEI single phase datasets for this property.

Returns

np.ndarray[ – Ravelled data quantities in [qty]/mole-formula

Return type

]

Notes

pycalphad Model parameters (and therefore fixed_portions) are stored as per mole-formula quantites, but the calculated properties and our data are all in [qty]/mole-atoms. We multiply by mole-atoms/mole-formula to convert the units to [qty]/mole-formula.

espei.parameter_selection.utils.shift_reference_state(desired_data, feature_transform, fixed_model, mole_atoms_per_mole_formula_unit)

Shift _MIX or _FORM data to a common reference state in per mole-atom units.

Parameters
• desired_data (List[Dict[str, Any]]) – ESPEI single phase dataset

• feature_transform (Callable) – Function to transform an AST for the GM property to the property of interest, i.e. entropy would be lambda GM: -sympy.diff(GM, v.T)

• fixed_model (pycalphad.Model) – Model with all lower order (in composition) terms already fit. Pure element reference state (GHSER functions) should be set to zero.

• mole_atoms_per_mole_formula_unit (float) – Number of moles of atoms in every mole atom unit.

Returns

Data for this feature in [qty]/mole-formula in a common reference state.

Return type

np.ndarray

Raises

ValueError

Notes

pycalphad Model parameters are stored as per mole-formula quantites, but the calculated properties and our data are all in [qty]/mole-atoms. We multiply by mole-atoms/mole-formula to convert the units to [qty]/mole-formula.