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] = {}
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']}
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)

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']}
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)

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']}
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']}
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.