ichor.core.models.kernels package

Subpackages

Submodules

ichor.core.models.kernels.constant module

class ConstantKernel(name: str, value: float, active_dims: ndarray | None)

Bases: Kernel

Implements constant kernel, which scales by a constant factor when used in a kernel product or modifies the mean of the Gaussian process when used in a kernel sum

R(x)

helper method to return symmetric square matrix x_train, x_train covariance matrix K(X, X)

k(xi, xj)

Calculates covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

A covariance matrix of shape (n, m)

property params
r(xi, x)

helper method to return x_test, x_train covariance matrix K(X*, X)

write_str() → str

ichor.core.models.kernels.distance module

class Distance

Bases: object

static euclidean_distance(x1: ndarray, x2: ndarray) → ndarray

Calculates distance matrix between data points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second marix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

The distance matrix of shape (n, m)

static squared_euclidean_distance(x1: ndarray, x2: ndarray) → ndarray

Calculates squared distance matrix between data points, uses array broadcasting and distance trick

Note

See the following websites for how array broadcasting and the distance trick work: https://medium.com/@souravdey/l2-distance-matrix-vectorization-trick-26aa3247ac6c https://stackoverflow.com/a/37903795

Note

Does not support batches (when x1 or x2 are 3D arrays)

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second marix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

The squared distance matrix of shape (x1.shape[0], x2.shape[0])

ichor.core.models.kernels.kernel module

class CompositeKernel(k1: Kernel, k2: Kernel)

Bases: Kernel, ABC

property nkernel: int
property params: ndarray
write_str() → str

Used to write out kernel info to model file

class Kernel(name: str, active_dims: ndarray | None = None)

Bases: ABC

Base class for all kernels that implements dunder methods for addition or multiplication of separate kernels

R(x_train: ndarray) → ndarray

helper method to return symmetric square matrix x_train, x_train covariance matrix K(X, X)

property active_dims
abstract k(x1: ndarray, x2: ndarray) → ndarray

Calculates covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

A covariance matrix of shape (n, m)

property nkernel: int
abstract params() → ndarray
r(x_train: ndarray, x_test: ndarray) → ndarray

helper method to return x_test, x_train covariance matrix K(X*, X)

property true_lengthscales

These are the true lengthscale values. Typically the kernel equations are written with these values (l) instead of theta (see the kernel cookbook or Rasmussen and Williams for examples.

abstract write_str()
class KernelProd(k1: Kernel, k2: Kernel)

Bases: CompositeKernel

Kernel multiplication implementation

R(x)

helper method to return symmetric square matrix x_train, x_train covariance matrix K(X, X)

k(xi, xj)

Calculates covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

A covariance matrix of shape (n, m)

property name: str
property params
r(xi, x)

helper method to return x_test, x_train covariance matrix K(X*, X)

class KernelSum(k1: Kernel, k2: Kernel)

Bases: CompositeKernel

Kernel addition implementation

R(x)

helper method to return symmetric square matrix x_train, x_train covariance matrix K(X, X)

k(xi, xj)

Calculates covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

A covariance matrix of shape (n, m)

property name: str
r(xi, x)

helper method to return x_test, x_train covariance matrix K(X*, X)

ichor.core.models.kernels.mixed_kernel_with_derivatives module

class MixedKernelWithDerivatives(name: str, rbf_thetas: ndarray, periodic_thetas: ndarray, rbf_dimensions: ndarray, periodic_dimensions: ndarray)

Bases: Kernel

Implementation of the mixed kernel, where the rbf dimensions are used for non-cyclic dimensions and the periodic kernel is used for cyclic dimensions (phi dimensions).

Also adds first and second derivatives of the mixed kernel which are used to train on the total system energy with gradient information.

The data is assumed to be uscaled, i.e. the original data. The period length array is set for all the dimensions even though it is only used for the periodic dimensions to vectorize the operations. The period length is set to be 2 * math.pi for all dimensions, as this is the optimal value for the ALF phi features.

Note

Need to use kernel_instance.double() in torch implementation to get the exact same results as this, torch defaults to float32 for some reason.

Also, unlike the torch version, there is no need to permute the rows and columns of the covariance matrix because the weights vector that is in the .model files with gradient information is written to be in the order of all weights for energies (alpha) followed by all weights for derivatives (beta) instead.

k(x1: ndarray, x2: ndarray) → ndarray

Calculates RBF covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

The RBF covariance matrix of shape (n, m)

property lengthscale: ndarray

Returns a 1D array of lengtshcales for both RBF and periodic which are ordered correctly (i.e. first 3 lengthscales are RBF ones, then it repeats RBF RBF Periodic)

property lengthscales
property ndims
property params: ndarray
property periodic_lengthscales

Note that the lengthscales are already squared for the periodic kernel. But still, thetas are defined to be 1/(2l). (where l here is the already squared true lengthscale)

property rbf_lengthscales
write_str() → str

ichor.core.models.kernels.periodic_kernel module

class PeriodicKernel(name: str, thetas: ndarray, period_length: ndarray, active_dims: ndarray | None = None)

Bases: Kernel

Implemtation of the Periodic Kernel.

Parameters:

  • lengthscale – np.ndarray of n_features array of lengthscales

  • period – np.ndarray of n_features array of period lengths

Note

Lengthscales is typically n_features long because we want a separate lengthscale for each dimension. The periodic kernel is going to be used for phi features because these are the features we know can be cyclic. The period of the phi angle is always \(2\pi\), however this period can change if there is normalization or standardization applied to features. The new period then becomes the distance between where \(\pi\) and \(-\pi\) land after the features are scaled. Because the period can vary for individual phi angles for standardization, it is still passed in as an array that is n_features long.

R(x_train: ndarray) → ndarray

helper method to return symmetric square matrix x_train, x_train Periodic covariance matrix K(X, X)

k(x1: ndarray, x2: ndarray) → ndarray

Calculates Periodic covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

The periodic covariance matrix of shape (n, m)

property lengthscales

Note that the lengthscales are already squared for the periodic kernel. But still, thetas are defined to be 1/(2l). (where l here is the already squared true lengthscale)

property params
r(x_test: ndarray, x_train: ndarray) → ndarray

helper method to return x_test, x_train Periodic covariance matrix K(X*, X)

write_str() → str

ichor.core.models.kernels.rbf module

class RBF(name: str, thetas: ndarray, active_dims: ndarray | None = None)

Bases: Kernel

Implementation of Radial Basis Function (RBF) kernel When each dimension has a separate lengthscale, this is also called the RBF-ARD kernel. Note that we use thetas instead of true lengthscales.

\[\theta = \frac{1}{2l^2}\]

where l is the lengthscale value.

k(x1: ndarray, x2: ndarray) → ndarray

Calculates RBF covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

The RBF covariance matrix of shape (n, m)

property lengthscales
property params
write_str() → str

ichor.core.models.kernels.rbf_cyclic module

class RBFCyclic(name: str, thetas: ndarray, active_dims: ndarray | None = None)

Bases: Kernel

Implemtation of Radial Basis Function (RBF) kernel with cyclic feature correction for phi angle feature

Note

Cyclic correction is applied only for our phi angles (phi is the azimuthal angle measured in the xy plane).

If we have unstandardized(original) features, we have to apply this correction only when the distance between two phi angles is greater than pi

\[\begin{split}\phi_1 - \phi_2 = \left \{ \begin{aligned} &\phi_1 - \phi_2, && \text{if}\ \phi_1 - \phi_2 \leq \pi \\ & 2\pi - (\phi_1 - \phi_2), && \text{if}\ (\phi_1 - \phi_2) \geq \pi \end{aligned} \right \}\end{split}\]

If we have standardized features (where we have subtracted the feature mean and divided by the feature standard deviation), we have to apply a correction only when the distance is greater than pi/sigma where sigma is the standard deviation of the particular feature in the training data.

\[\begin{split}\hat \phi_1 - \hat \phi_2 = \left \{ \begin{aligned} &\hat \phi_1 - \hat \phi_2, && \text{if}\ \hat \phi_1 - \hat \phi_2 \leq \frac{\pi}{\sigma} \\ & \frac{2\pi}{\sigma} - (\hat \phi_1 - \hat \phi_2), && \text{if}\ (\hat \phi_1 - \hat \phi_2) \geq \frac{\pi}{\sigma} \end{aligned} \right \}\end{split}\]
k(x1: ndarray, x2: ndarray) → ndarray

Calcualtes cyclic RBF covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second marix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

The cyclic RBF covariance matrix matrix of shape (n, m)

mask
property params
write_str() → str

Module contents

class ConstantKernel(name: str, value: float, active_dims: ndarray | None)

Bases: Kernel

Implements constant kernel, which scales by a constant factor when used in a kernel product or modifies the mean of the Gaussian process when used in a kernel sum

R(x)

helper method to return symmetric square matrix x_train, x_train covariance matrix K(X, X)

k(xi, xj)

Calculates covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

A covariance matrix of shape (n, m)

property params
r(xi, x)

helper method to return x_test, x_train covariance matrix K(X*, X)

write_str() → str
class Kernel(name: str, active_dims: ndarray | None = None)

Bases: ABC

Base class for all kernels that implements dunder methods for addition or multiplication of separate kernels

R(x_train: ndarray) → ndarray

helper method to return symmetric square matrix x_train, x_train covariance matrix K(X, X)

property active_dims
abstract k(x1: ndarray, x2: ndarray) → ndarray

Calculates covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

A covariance matrix of shape (n, m)

property nkernel: int
abstract params() → ndarray
r(x_train: ndarray, x_test: ndarray) → ndarray

helper method to return x_test, x_train covariance matrix K(X*, X)

property true_lengthscales

These are the true lengthscale values. Typically the kernel equations are written with these values (l) instead of theta (see the kernel cookbook or Rasmussen and Williams for examples.

abstract write_str()
class MixedKernelWithDerivatives(name: str, rbf_thetas: ndarray, periodic_thetas: ndarray, rbf_dimensions: ndarray, periodic_dimensions: ndarray)

Bases: Kernel

Implementation of the mixed kernel, where the rbf dimensions are used for non-cyclic dimensions and the periodic kernel is used for cyclic dimensions (phi dimensions).

Also adds first and second derivatives of the mixed kernel which are used to train on the total system energy with gradient information.

The data is assumed to be uscaled, i.e. the original data. The period length array is set for all the dimensions even though it is only used for the periodic dimensions to vectorize the operations. The period length is set to be 2 * math.pi for all dimensions, as this is the optimal value for the ALF phi features.

Note

Need to use kernel_instance.double() in torch implementation to get the exact same results as this, torch defaults to float32 for some reason.

Also, unlike the torch version, there is no need to permute the rows and columns of the covariance matrix because the weights vector that is in the .model files with gradient information is written to be in the order of all weights for energies (alpha) followed by all weights for derivatives (beta) instead.

k(x1: ndarray, x2: ndarray) → ndarray

Calculates RBF covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

The RBF covariance matrix of shape (n, m)

property lengthscale: ndarray

Returns a 1D array of lengtshcales for both RBF and periodic which are ordered correctly (i.e. first 3 lengthscales are RBF ones, then it repeats RBF RBF Periodic)

property lengthscales
property ndims
property params: ndarray
property periodic_lengthscales

Note that the lengthscales are already squared for the periodic kernel. But still, thetas are defined to be 1/(2l). (where l here is the already squared true lengthscale)

property rbf_lengthscales
write_str() → str
class PeriodicKernel(name: str, thetas: ndarray, period_length: ndarray, active_dims: ndarray | None = None)

Bases: Kernel

Implemtation of the Periodic Kernel.

Parameters:

  • lengthscale – np.ndarray of n_features array of lengthscales

  • period – np.ndarray of n_features array of period lengths

Note

Lengthscales is typically n_features long because we want a separate lengthscale for each dimension. The periodic kernel is going to be used for phi features because these are the features we know can be cyclic. The period of the phi angle is always \(2\pi\), however this period can change if there is normalization or standardization applied to features. The new period then becomes the distance between where \(\pi\) and \(-\pi\) land after the features are scaled. Because the period can vary for individual phi angles for standardization, it is still passed in as an array that is n_features long.

R(x_train: ndarray) → ndarray

helper method to return symmetric square matrix x_train, x_train Periodic covariance matrix K(X, X)

k(x1: ndarray, x2: ndarray) → ndarray

Calculates Periodic covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

The periodic covariance matrix of shape (n, m)

property lengthscales

Note that the lengthscales are already squared for the periodic kernel. But still, thetas are defined to be 1/(2l). (where l here is the already squared true lengthscale)

property params
r(x_test: ndarray, x_train: ndarray) → ndarray

helper method to return x_test, x_train Periodic covariance matrix K(X*, X)

write_str() → str
class RBF(name: str, thetas: ndarray, active_dims: ndarray | None = None)

Bases: Kernel

Implementation of Radial Basis Function (RBF) kernel When each dimension has a separate lengthscale, this is also called the RBF-ARD kernel. Note that we use thetas instead of true lengthscales.

\[\theta = \frac{1}{2l^2}\]

where l is the lengthscale value.

k(x1: ndarray, x2: ndarray) → ndarray

Calculates RBF covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

The RBF covariance matrix of shape (n, m)

property lengthscales
property params
write_str() → str
class RBFCyclic(name: str, thetas: ndarray, active_dims: ndarray | None = None)

Bases: Kernel

Implemtation of Radial Basis Function (RBF) kernel with cyclic feature correction for phi angle feature

Note

Cyclic correction is applied only for our phi angles (phi is the azimuthal angle measured in the xy plane).

If we have unstandardized(original) features, we have to apply this correction only when the distance between two phi angles is greater than pi

\[\begin{split}\phi_1 - \phi_2 = \left \{ \begin{aligned} &\phi_1 - \phi_2, && \text{if}\ \phi_1 - \phi_2 \leq \pi \\ & 2\pi - (\phi_1 - \phi_2), && \text{if}\ (\phi_1 - \phi_2) \geq \pi \end{aligned} \right \}\end{split}\]

If we have standardized features (where we have subtracted the feature mean and divided by the feature standard deviation), we have to apply a correction only when the distance is greater than pi/sigma where sigma is the standard deviation of the particular feature in the training data.

\[\begin{split}\hat \phi_1 - \hat \phi_2 = \left \{ \begin{aligned} &\hat \phi_1 - \hat \phi_2, && \text{if}\ \hat \phi_1 - \hat \phi_2 \leq \frac{\pi}{\sigma} \\ & \frac{2\pi}{\sigma} - (\hat \phi_1 - \hat \phi_2), && \text{if}\ (\hat \phi_1 - \hat \phi_2) \geq \frac{\pi}{\sigma} \end{aligned} \right \}\end{split}\]
k(x1: ndarray, x2: ndarray) → ndarray

Calcualtes cyclic RBF covariance matrix from two sets of points

:paramparam: x1 np.ndarray of shape n x ndimensions:

First matrix of n points

:paramparam: x2 np.ndarray of shape m x ndimensions:

Second marix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray

The cyclic RBF covariance matrix matrix of shape (n, m)

mask
property params
write_str() → str