pymatgen.analysis.chemenv.utils.func_utils module

This module contains some utility functions and classes that are used in the chemenv package.

class AbstractRatioFunction(function, options_dict=None)[source]

Bases: object

Abstract class for all ratio functions

Constructor for AbstractRatioFunction

Parameters

function – Ration function name.
options_dict – Dictionary containing the parameters for the ratio function.

ALLOWED_FUNCTIONS: dict[str, list] = {}[source]

evaluate(value)[source]

Evaluate the ratio function for the given value.

Parameters: value – Value for which ratio function has to be evaluated.
Returns: Ratio function corresponding to the value.

classmethod from_dict(dd)[source]

Construct ratio function from dict.

Parameters: dd – Dict representation of the ratio function
Returns: Ratio function object.

setup_parameters(options_dict)[source]

Set up the parameters for this ratio function.

Parameters: options_dict – Dictionary containing the parameters for the ratio function.
Returns: None.

class CSMFiniteRatioFunction(function, options_dict=None)[source]

Bases: pymatgen.analysis.chemenv.utils.func_utils.AbstractRatioFunction

Concrete implementation of a series of ratio functions applied to the continuous symmetry measure (CSM).

Uses “finite” ratio functions.

See the following reference for details: ChemEnv: a fast and robust coordination environment identification tool, D. Waroquiers et al., Acta Cryst. B 76, 683 (2020).

Constructor for AbstractRatioFunction

Parameters

function – Ration function name.
options_dict – Dictionary containing the parameters for the ratio function.

ALLOWED_FUNCTIONS: dict[str, list] = {'power2_decreasing_exp': ['max_csm', 'alpha'], 'smootherstep': ['lower_csm', 'upper_csm'], 'smoothstep': ['lower_csm', 'upper_csm']}[source]

fractions(data)[source]

Get the fractions from the CSM ratio function applied to the data.

Parameters: data – List of CSM values to estimate fractions.
Returns: Corresponding fractions for each CSM.

mean_estimator(data)[source]

Get the weighted CSM using this CSM ratio function applied to the data.

Parameters: data – List of CSM values to estimate the weighted CSM.
Returns: Weighted CSM from this ratio function.

power2_decreasing_exp(vals)[source]

Get the evaluation of the ratio function f(x)=exp(-a*x)*(x-1)^2.

The CSM values (i.e. “x”), are scaled to the “max_csm” parameter. The “a” constant correspond to the “alpha” parameter.

Parameters: vals – CSM values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the CSM values.

ratios(data)[source]

Get the fractions from the CSM ratio function applied to the data.

Parameters: data – List of CSM values to estimate fractions.
Returns: Corresponding fractions for each CSM.

smootherstep(vals)[source]

Get the evaluation of the smootherstep ratio function: f(x)=6*x^5-15*x^4+10*x^3.

The CSM values (i.e. “x”), are scaled between the “lower_csm” and “upper_csm” parameters.

Parameters: vals – CSM values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the CSM values.

smoothstep(vals)[source]

Get the evaluation of the smoothstep ratio function: f(x)=3*x^2-2*x^3.

The CSM values (i.e. “x”), are scaled between the “lower_csm” and “upper_csm” parameters.

Parameters: vals – CSM values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the CSM values.

class CSMInfiniteRatioFunction(function, options_dict=None)[source]

Bases: pymatgen.analysis.chemenv.utils.func_utils.AbstractRatioFunction

Concrete implementation of a series of ratio functions applied to the continuous symmetry measure (CSM).

Uses “infinite” ratio functions.

See the following reference for details: ChemEnv: a fast and robust coordination environment identification tool, D. Waroquiers et al., Acta Cryst. B 76, 683 (2020).

Constructor for AbstractRatioFunction

Parameters

function – Ration function name.
options_dict – Dictionary containing the parameters for the ratio function.

ALLOWED_FUNCTIONS: dict[str, list] = {'power2_inverse_decreasing': ['max_csm'], 'power2_inverse_power2_decreasing': ['max_csm']}[source]

fractions(data)[source]

Get the fractions from the CSM ratio function applied to the data.

Parameters: data – List of CSM values to estimate fractions.
Returns: Corresponding fractions for each CSM.

mean_estimator(data)[source]

Get the weighted CSM using this CSM ratio function applied to the data.

Parameters: data – List of CSM values to estimate the weighted CSM.
Returns: Weighted CSM from this ratio function.

power2_inverse_decreasing(vals)[source]

Get the evaluation of the ratio function f(x)=(x-1)^2 / x.

The CSM values (i.e. “x”), are scaled to the “max_csm” parameter. The “a” constant correspond to the “alpha” parameter.

Parameters: vals – CSM values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the CSM values.

power2_inverse_power2_decreasing(vals)[source]

Get the evaluation of the ratio function f(x)=(x-1)^2 / x^2.

The CSM values (i.e. “x”), are scaled to the “max_csm” parameter. The “a” constant correspond to the “alpha” parameter.

Parameters: vals – CSM values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the CSM values.

ratios(data)[source]

Get the fractions from the CSM ratio function applied to the data.

Parameters: data – List of CSM values to estimate fractions.
Returns: Corresponding fractions for each CSM.

class DeltaCSMRatioFunction(function, options_dict=None)[source]

Bases: pymatgen.analysis.chemenv.utils.func_utils.AbstractRatioFunction

Concrete implementation of a series of ratio functions applied to differences of continuous symmetry measures (DeltaCSM).

Uses “finite” ratio functions.

See the following reference for details: ChemEnv: a fast and robust coordination environment identification tool, D. Waroquiers et al., Acta Cryst. B 76, 683 (2020).

Constructor for AbstractRatioFunction

Parameters

function – Ration function name.
options_dict – Dictionary containing the parameters for the ratio function.

ALLOWED_FUNCTIONS: dict[str, list] = {'smootherstep': ['delta_csm_min', 'delta_csm_max']}[source]

smootherstep(vals)[source]

Get the evaluation of the smootherstep ratio function: f(x)=6*x^5-15*x^4+10*x^3.

The DeltaCSM values (i.e. “x”), are scaled between the “delta_csm_min” and “delta_csm_max” parameters.

Parameters: vals – DeltaCSM values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the DeltaCSM values.

class RatioFunction(function, options_dict=None)[source]

Bases: pymatgen.analysis.chemenv.utils.func_utils.AbstractRatioFunction

Concrete implementation of a series of ratio functions.

Constructor for AbstractRatioFunction

Parameters

function – Ration function name.
options_dict – Dictionary containing the parameters for the ratio function.

ALLOWED_FUNCTIONS: dict[str, list] = {'inverse_smootherstep': ['lower', 'upper'], 'inverse_smoothstep': ['lower', 'upper'], 'power2_decreasing_exp': ['max', 'alpha'], 'power2_inverse_decreasing': ['max'], 'power2_inverse_power2_decreasing': ['max'], 'smootherstep': ['lower', 'upper'], 'smoothstep': ['lower', 'upper']}[source]

inverse_smootherstep(vals)[source]

Get the evaluation of the “inverse” smootherstep ratio function: f(x)=1-(6*x^5-15*x^4+10*x^3).

The values (i.e. “x”), are scaled between the “lower” and “upper” parameters.

Parameters: vals – Values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the values.

inverse_smoothstep(vals)[source]

Get the evaluation of the “inverse” smoothstep ratio function: f(x)=1-(3*x^2-2*x^3).

The values (i.e. “x”), are scaled between the “lower” and “upper” parameters.

Parameters: vals – Values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the values.

power2_decreasing_exp(vals)[source]

Get the evaluation of the ratio function f(x)=exp(-a*x)*(x-1)^2.

The values (i.e. “x”), are scaled to the “max” parameter. The “a” constant correspond to the “alpha” parameter.

Parameters: vals – Values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the values.

power2_inverse_decreasing(vals)[source]

Get the evaluation of the ratio function f(x)=(x-1)^2 / x.

The values (i.e. “x”), are scaled to the “max” parameter.

Parameters: vals – Values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the values.

power2_inverse_power2_decreasing(vals)[source]

Get the evaluation of the ratio function f(x)=(x-1)^2 / x^2.

The values (i.e. “x”), are scaled to the “max” parameter.

Parameters: vals – Values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the values.

smootherstep(vals)[source]

Get the evaluation of the smootherstep ratio function: f(x)=6*x^5-15*x^4+10*x^3.

The values (i.e. “x”), are scaled between the “lower” and “upper” parameters.

Parameters: vals – Values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the values.

smoothstep(vals)[source]

Get the evaluation of the smoothstep ratio function: f(x)=3*x^2-2*x^3.

The values (i.e. “x”), are scaled between the “lower” and “upper” parameters.

Parameters: vals – Values for which the ratio function has to be evaluated.
Returns: Result of the ratio function applied to the values.