ichor.core.models.kernels package

Subpackages

ichor.core.models.kernels.interpreter package

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 mixed covariance matrix(RBF and periodic): with derivatives from two sets of points
:paramparam: x1 np.ndarray of shape m x ndimensions:: First matrix of n points
:paramparam: x2 np.ndarray of shape n x ndimensions:: Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray: The covariance matrix of shape (m*(ndim+1), n*(ndim+1))

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 mixed covariance matrix(RBF and periodic): with derivatives from two sets of points
:paramparam: x1 np.ndarray of shape m x ndimensions:: First matrix of n points
:paramparam: x2 np.ndarray of shape n x ndimensions:: Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray: The covariance matrix of shape (m*(ndim+1), n*(ndim+1))

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

class RBFKernelWithDerivatives(name: str, rbf_thetas: ndarray, rbf_dimensions: ndarray)

Bases: Kernel

Implementation of the RBF kernel with derivatives, where the rbf dimensions all dimensions.

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.

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

Calculates RBF covariance matrix with derivatives from two sets of points

:paramparam: x1 np.ndarray of shape m x ndimensions:: First matrix of n points
:paramparam: x2 np.ndarray of shape n x ndimensions:: Second matrix of m points, can be identical to the first matrix x1

Returns:

type: np.ndarray: The covariance matrix of shape (m*(ndim+1), n*(ndim+1))

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 rbf_lengthscales

write_str() → str