Utilitaries
Casting
- kerch.utils.cast.capitalize_only_first(val: str) str[source]
This method returns the input string with the first letter capitalized and the rest of the string unchanged.
- kerch.utils.cast.castf(x, dev=None, tensor=True) Tensor | None[source]
Casts the input to a PyTorch float tensor. If the input is a scalar, it is cast to a tensor. The cast can be done to a 1D or a 2D tensor depending on the parameter tensor. If the provided data x has more than 2 dimensions, an error is raised. The default floating type used is
kerch.FTYPE. The None values are not casted and returned as is.- Parameters:
x (float | torch.Tensor | np.ndarray | None) – The input to cast.
dev (Optional[torch.device]) – The device to cast the tensor to. Defaults to None, which corresponds to no device change.
tensor (bool) – If True, the input is cast to a 2D tensor. If False, the input is cast to a 1D tensor.
- Returns:
The input cast to a PyTorch float tensor, with optional device.
- Return type:
torch.Tensor | None
- kerch.utils.cast.casti(x, dev=None, tensor=False) Tensor | None[source]
Casts the input to a PyTorch integer tensor. If the input is a scalar, it is cast to a tensor. The cast can be done to a 1D or a 2D tensor depending on the parameter tensor. If the provided data x has more than 2 dimensions, an error is raised. The default floating type used is
kerch.ITYPE. The None values are not casted and returned as is.- Parameters:
x (int | torch.Tensor | np.ndarray | None) – The input to cast.
dev (Optional[torch.device]) – The device to cast the tensor to. Defaults to None, which corresponds to no device change.
tensor (bool) – If True, the input is cast to a 2D tensor. If False, the input is cast to a 1D tensor.
- Returns:
The input cast to a PyTorch integer tensor, with optional device.
- Return type:
torch.Tensor | None
- kerch.utils.cast.check_representation(representation: str = None, default: str = None, cls=None) str[source]
This model verifies whether the provided representation is valid. If the representation is None and a default value is provided, the default value is returned. If the representation is not None and is not valid, an error is raised. The valid representations are primal and dual.
- Parameters:
representation (str, optional) – The representation to check.
default (str, optional) – Default representation for the case where representation is None.
cls (kerch.feature.Logger, optional) – An instance of
kerch.feature.Loggerto throw the error from, typically the one calling this method. This is optional.
- Returns:
“primal” | “dual”
- Return type:
Decorators
- class kerch.utils.decorators.extend_docstring(method)[source]
Decorator adding the documentation of the provided definition to the decorated definition. This useful for inheriting the documentation.
- kerch.utils.decorators.kwargs_decorator(dict_kwargs)[source]
Decorator that appends the dictionnary of method keyword arguments (kwargs) with additional values provided in dict_kwargs. If a keyword already exists in the original dictionnary, its value is neglected. This is useful for adding default values to the keyword arguments of methods, e.g., constructors. An alternative is to use the kwargs.pop(keyword, default) instead.
- special-members:
- show-inheritance:
Mathematics
- kerch.utils.math.eigs(A, k=None, B=None, psd=True, sym=True)[source]
Eigenvalue decomposition. This method is a wrapper calling other methods depending on the context. In a kernel context, most matrices are symmetric because kernels also are. Hence, they are Hermitian and a faster SVD can be used. Alternatively, all the eigenvalues are not necessarily required and we may thus skip the computation of a full eigendecomposition. The goal of this method is to always choose the most efficient method depending on the context.
- Parameters:
A (torch.Tensor) – Matrix to be decomposed.
k (int, optional) – Number of greatest eigenpairs requested. Defaults to None, which corresponds to computing all of them.
B (torch.Tensor, optional) – Matrix in the case of a generalized eigenvalue problem. Specify None (default) for a classical eigenvalue decomposition.
psd (bool, optional) – Specifies whether the matrix A is positive semi-definite. Defaults to True.
sym (bool, optional) – Specifies whether the matrix A is positive symmetric. Defaults to True.
- Returns:
eigenvalues, eigenvectors.
- Return type:
Tuple[torch.Tensor, torch.Tensor]
Typing
- kerch.utils.type.gpu_available() bool[source]
Returns whether GPU-enhanced computation is possible and configured on this machine.
- kerch.utils.type.set_eps(eps: float)[source]
Sets the generic epsilon value used throughout the toolbox to guarantee stability.
- Parameters:
eps (float) – Default epsilon type to be used.
- kerch.utils.type.set_ftype(type)[source]
Sets the generic floating type
kerch.FTYPEused throughout the package. Typical choices include half precisiontorch.float16, single precisiontorch.float32(default) and double precisiontorch.float64.- Parameters:
type (PyTorch type) – Default floating type to be used.
- kerch.utils.type.set_itype(type)[source]
Sets the generic integer type
kerch.ITYPEused throughout the package. Typical choices include short integerstorch.int16(-32 768 to 32 767), classical integerstorch.int32(-2^31-1 to 2^31, default) and long integerstorch.int64(-2^63-1 to 2^63). We do not advise on using unsigned integers because of their limited support in PyTorch.- Parameters:
type (PyTorch type) – Default integer type to be used.
Tensor
Errors
- exception kerch.utils.errors.BijectionError(*args, **kwargs)[source]
Bases:
KerchErrorError thrown when an inverse is requested from a non-bijective function.
- Parameters:
cls (Instance of
kerch.feature.Logger) – Optional class throwing the exception. This is helpful to add a context to the error message.message (str) – Optional error message.
- exception kerch.utils.errors.ExplicitError(*args, **kwargs)[source]
Bases:
KerchErrorError thrown when an explicit representation is requested and mathematically not available.
- Parameters:
cls (Instance of
kerch.feature.Logger) – Optional class throwing the exception. This is helpful to add a context to the error message.message (str) – Optional error message.
- exception kerch.utils.errors.ImplicitError(*args, **kwargs)[source]
Bases:
KerchErrorError thrown when an implicit representation is requested and mathematically not available.
- Parameters:
cls (Instance of
kerch.feature.Logger) – Optional class throwing the exception. This is helpful to add a context to the error message.message (str) – Optional error message.
- exception kerch.utils.errors.KerchError(cls=None, message='')[source]
Bases:
Exception- Parameters:
cls (Instance of
kerch.feature.Logger) – Optional class throwing the exception. This is helpful to add a context to the error message.message (str) – Optional error message.
- __weakref__
Type:
GetSetDescriptorTypelist of weak references to the object (if defined)
- exception kerch.utils.errors.MultiViewError(*args, **kwargs)[source]
Bases:
KerchErrorError thrown when some operations are requested, but not defined in a multi-view context.
- Parameters:
cls (Instance of
kerch.feature.Logger) – Optional class throwing the exception. This is helpful to add a context to the error message.message (str) – Optional error message.
- exception kerch.utils.errors.NotInitializedError(*args, **kwargs)[source]
Bases:
KerchErrorError thrown when a model is asked to perform some tasks, but is not yet fully initialized.
- Parameters:
cls (Instance of
kerch.feature.Logger) – Optional class throwing the exception. This is helpful to add a context to the error message.message (str) – Optional error message.
- exception kerch.utils.errors.RepresentationError(*args, **kwargs)[source]
Bases:
KerchErrorError thrown when the requested representation is invalid.
- Parameters:
cls (Instance of
kerch.feature.Logger) – Optional class throwing the exception. This is helpful to add a context to the error message.message (str) – Optional error message.