dscribe.kernels package¶

Submodules¶

dscribe.kernels.averagekernel module¶

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class dscribe.kernels.averagekernel.AverageKernel(metric, gamma=None, degree=3, coef0=1, kernel_params=None, normalize_kernel=True)[source]¶

Bases: dscribe.kernels.localsimilaritykernel.LocalSimilarityKernel

Used to compute a global similarity of structures based on the average similarity of local atomic environments in the structure. More precisely, returns the similarity kernel K as:

\[K(A, B) = \frac{1}{N M}\sum_{ij} C_{ij}(A, B)\]

where \(N\) is the number of atoms in structure \(A\), \(M\) is the number of atoms in structure \(B\) and the similarity between local atomic environments \(C_{ij}\) has been calculated with the pairwise metric (e.g. linear, gaussian) defined by the parameters given in the constructor.

Parameters

metric (string or callable) – The pairwise metric used for calculating the local similarity. Accepts any of the sklearn pairwise metric strings (e.g. “linear”, “rbf”, “laplacian”, “polynomial”) or a custom callable. A callable should accept two arguments and the keyword arguments passed to this object as kernel_params, and should return a floating point number.
gamma (float) – Gamma parameter for the RBF, laplacian, polynomial, exponential chi2 and sigmoid kernels. Interpretation of the default value is left to the kernel; see the documentation for sklearn.metrics.pairwise. Ignored by other kernels.
degree (float) – Degree of the polynomial kernel. Ignored by other kernels.
coef0 (float) – Zero coefficient for polynomial and sigmoid kernels. Ignored by other kernels.
kernel_params (mapping of string to any) – Additional parameters (keyword arguments) for kernel function passed as callable object.
normalize_kernel (boolean) – Whether to normalize the final global similarity kernel. The normalization is achieved by dividing each kernel element \(K_{ij}\) with the factor \(\sqrt{K_{ii}K_{jj}}\)

get_global_similarity(localkernel)[source]¶

Computes the average global similarity between two structures A and B.

Parameters: localkernel (np.ndarray) – NxM matrix of local similarities between structures A and B, with N and M atoms respectively.
Returns: Average similarity between the structures A and B.
Return type: float

dscribe.kernels.localsimilaritykernel module¶

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class dscribe.kernels.localsimilaritykernel.LocalSimilarityKernel(metric, gamma=None, degree=3, coef0=1, kernel_params=None, normalize_kernel=True)[source]¶

Bases: abc.ABC

An abstract base class for all kernels that use the similarity of local atomic environments to compute a global similarity measure.

Parameters

metric (string or callable) – The pairwise metric used for calculating the local similarity. Accepts any of the sklearn pairwise metric strings (e.g. “linear”, “rbf”, “laplacian”, “polynomial”) or a custom callable. A callable should accept two arguments and the keyword arguments passed to this object as kernel_params, and should return a floating point number.
gamma (float) – Gamma parameter for the RBF, laplacian, polynomial, exponential chi2 and sigmoid kernels. Interpretation of the default value is left to the kernel; see the documentation for sklearn.metrics.pairwise. Ignored by other kernels.
degree (float) – Degree of the polynomial kernel. Ignored by other kernels.
coef0 (float) – Zero coefficient for polynomial and sigmoid kernels. Ignored by other kernels.
kernel_params (mapping of string to any) – Additional parameters (keyword arguments) for kernel function passed as callable object.
normalize_kernel (boolean) – Whether to normalize the final global similarity kernel. The normalization is achieved by dividing each kernel element \(K_{ij}\) with the factor \(\sqrt{K_{ii}K_{jj}}\)

create(x, y=None)[source]¶

Creates the kernel matrix based on the given lists of local features x and y.

Parameters

x (iterable) – A list of local feature arrays for each structure.
y (iterable) – An optional second list of features. If not specified it is assumed that y=x.

Returns

The pairwise global similarity kernel K[i,j] between the given structures, in the same order as given in the input, i.e. the similarity of structures i and j is given by K[i,j], where features for structure i and j were in features[i] and features[j] respectively.

abstract get_global_similarity(localkernel)[source]¶

Computes the global similarity between two structures A and B.

Parameters: localkernel (np.ndarray) – NxM matrix of local similarities between structures A and B, with N and M atoms respectively.
Returns: Global similarity between the structures A and B.
Return type: float

get_pairwise_matrix(X, Y=None)[source]¶

Calculates the pairwise similarity of atomic environments with scikit-learn, and the pairwise metric configured in the constructor.

Parameters

X (np.ndarray) – Feature vector for the atoms in structure A
Y (np.ndarray) – Feature vector for the atoms in structure B

Returns

NxM matrix of local similarities between structures A: and B, with N and M atoms respectively.

Return type

np.ndarray

dscribe.kernels.rematchkernel module¶

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class dscribe.kernels.rematchkernel.REMatchKernel(alpha=0.1, threshold=1e-06, metric='linear', gamma=None, degree=3, coef0=1, kernel_params=None, normalize_kernel=True)[source]¶

Bases: dscribe.kernels.localsimilaritykernel.LocalSimilarityKernel

Used to compute a global similarity of structures based on the regularized-entropy match (REMatch) kernel of local atomic environments in the structure. More precisely, returns the similarity kernel K as:

\[ \begin{align}\begin{aligned}\DeclareMathOperator*{\argmax}{argmax} K(A, B) &= \mathrm{Tr} \mathbf{P}^\alpha \mathbf{C}(A, B)\\\mathbf{P}^\alpha &= \argmax_{\mathbf{P} \in \mathcal{U}(N, N)} \sum_{ij} P_{ij} (1-C_{ij} +\alpha \ln P_{ij})\end{aligned}\end{align} \]

where the similarity between local atomic environments \(C_{ij}\) has been calculated with the pairwise metric (e.g. linear, gaussian) defined by the parameters given in the constructor.

For reference, see:

“Comparing molecules and solids across structural and alchemical space”, Sandip De, Albert P. Bartók, Gábor Csányi and Michele Ceriotti, Phys. Chem. Chem. Phys. 18, 13754 (2016), https://doi.org/10.1039/c6cp00415f

Parameters

alpha (float) – Parameter controlling the entropic penalty. Values close to zero approach the best-match solution and values towards infinity approach the average kernel.
threshold (float) – Convergence threshold used in the Sinkhorn-algorithm.
metric (string or callable) – The pairwise metric used for calculating the local similarity. Accepts any of the sklearn pairwise metric strings (e.g. “linear”, “rbf”, “laplacian”, “polynomial”) or a custom callable. A callable should accept two arguments and the keyword arguments passed to this object as kernel_params, and should return a floating point number.
gamma (float) – Gamma parameter for the RBF, laplacian, polynomial, exponential chi2 and sigmoid kernels. Interpretation of the default value is left to the kernel; see the documentation for sklearn.metrics.pairwise. Ignored by other kernels.
degree (float) – Degree of the polynomial kernel. Ignored by other kernels.
coef0 (float) – Zero coefficient for polynomial and sigmoid kernels. Ignored by other kernels.
kernel_params (mapping of string to any) – Additional parameters (keyword arguments) for kernel function passed as callable object.
normalize_kernel (boolean) – Whether to normalize the final global similarity kernel. The normalization is achieved by dividing each kernel element \(K_{ij}\) with the factor \(\sqrt{K_{ii}K_{jj}}\)

get_global_similarity(localkernel)[source]¶

Computes the REMatch similarity between two structures A and B.

Parameters: localkernel (np.ndarray) – NxM matrix of local similarities between structures A and B, with N and M atoms respectively.
Returns: REMatch similarity between the structures A and B.
Return type: float

Module contents¶

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.