src.linalg package

Submodules

src.linalg.covariance module

class src.linalg.covariance.Covariance

Bases: func[CovarianceMatrix, CovarianceMatrices], ABC

classmethod global_func(centered_x_pts, weights=None, md=None)

Computes the global covariance matrix from centered data points.

Parameters:

  • centered_x_pts (DenseArray) – Centered data points with shape (m, p), where m is the number of samples and p is the feature dimension.

  • weights (BaseArray | None) – Optional weight array of shape (m,) to compute a weighted covariance. If None, computes the unweighted covariance. (default: None).

  • md (Metadata | None) – Metadata to attach to the returned CovarianceMatrix.

Returns:

A CovarianceMatrix representing the global covariance structure.

Return type:

CovarianceMatrix

classmethod local(x_pts, mean_pts=None, weights=None, needs_means=True, needs_norm=True, in_place_norm=False, bsize=None)

Lazily computes the local covariance on all x_pts centered on mean_pts. If there are multiple mean points, computes covariance for each.

Parameters:

  • x_pts (Points) – The neighborhood to calculate covariance with.

  • mean_pts (DenseArray | None) – Optional center for the covariance calculation. If there are multiple mean points, computes covariance for each. If None, each point is treated as its own center. (default: None)

  • weights (BaseArray | None) – Optional weight matrix to calculate weighted covariance with. (default: None).

  • needs_means (bool) – Whether x_pts is centered. (default: True)

  • needs_norm (bool) – Whether the weights need to be normalized. (default: True)

  • in_place_norm (bool) – If needs_norm, whether to do the weight normalization in-place. (default: False)

  • bsize (int | None) – Optional batch size to divide the covariance calculation. (default: None).

Returns:

The desired covariance matrices in a CovarianceMatrices object.

Return type:

CovarianceMatrices

classmethod local_func(x_pts, mean_pts, weights, needs_means, md=None)

Computes the local covariance on all x_pts centered on mean_pts. If there are multiple mean points, computes covariance for each.

Parameters:

  • x_pts (DenseArray) – The neighborhood to calculate covariance with.

  • mean_pts (DenseArray) – The center for the covariance calculation. If there are multiple mean points, computes covariance for each.

  • weights (BaseArray | None) – Optional weight matrix to calculate weighted covariance with.

  • needs_means (bool) – Whether x_pts is centered.

  • md (Metadata | None) – Optional metadata to include in return CovarianceMatrices. (default: None).

Returns:

Matrix where covariance matrices are joined along axis 0.

Return type:

CovarianceMatrices

classmethod local_iter(x_pts, mean_pts=None, weights=None, needs_means=True, needs_norm=True, in_place_norm=False, bsize=None)

Computes the local covariance in a batched manner on all x_pts centered on mean_pts. If there are multiple mean points, computes covariance for each.

Parameters:

  • x_pts (Points) – The neighborhood to calculate covariance with.

  • mean_pts (DenseArray | None) – Optional center for the covariance calculation. If there are multiple mean points, computes covariance for each. If None, each point is treated as its own center. (default: None)

  • weights (BaseArray | None) – Optional weight matrix to calculate weighted covariance with. (default: None).

  • needs_means (bool) – Whether x_pts is centered. (default: True)

  • needs_norm (bool) – Whether the weights need to be normalized. (default: True)

  • in_place_norm (bool) – If needs_norm, whether to do the weight normalization in-place. (default: False)

  • bsize (int | None) – Optional batch size to divide the covariance calculation. (default: None).

Returns:

Iterator that gives the desired covariance matrices.

Return type:

Iterator[CovarianceMatrices]

class src.linalg.covariance.CovarianceMatrices(*args, **metadata)

Bases: CovarianceMatrixMixin, DenseArray

Container class for multiple covariance matrices.

Extends DenseArray with a fixed third dimension for stacking covariance matrices along axis 0.

Parameters:
fixed_ndim: int = 3
class src.linalg.covariance.CovarianceMatrix(*args, **metadata)

Bases: CovarianceMatrixMixin, DenseArray

Container class for a single Dense covariance matrix.

Parameters:
class src.linalg.covariance.CovarianceMatrixMixin(*args, **metadata)

Bases: GeometryMatrixMixin, ABC

Abstract mixin class for covariance matrices.

Provides a common interface for covariance-related matrix objects.

Parameters:

src.linalg.func module

class src.linalg.func.func

Bases: ABC, Generic[GlobalType, LocalType]

Abstract base class for functions that produce both global and local outputs.

Subclasses must implement global_func, local_func, and local_iter to define how to compute global and local structures. The package helper aggregates local outputs into a single object.

Parameters:

  • GlobalType – Type returned by global_func.

  • LocalType – Type returned by local_func and local_iter.

abstractmethod classmethod global_func(*args, **kwargs)

Computes the global object for the function.

Parameters:

  • args (Any) – Positional arguments specific to the subclass implementation.

  • kwargs (Any) – Keyword arguments specific to the subclass implementation.

Returns:

A global object of type GlobalType.

Return type:

GlobalType

global_type: Type
abstractmethod classmethod local_func(*args, **kwargs)

Computes a local object for the function.

Parameters:

  • args (Any) – Positional arguments specific to the subclass implementation.

  • kwargs (Any) – Keyword arguments specific to the subclass implementation.

Returns:

A local object of type LocalType.

Return type:

LocalType

abstractmethod classmethod local_iter(*args, **kwargs)

Iterates over local computations in a batched manner.

Parameters:

  • args (Any) – Positional arguments specific to the subclass implementation.

  • kwargs (Any) – Keyword arguments specific to the subclass implementation.

Returns:

An iterable of local objects of type LocalType.

Return type:

Iterable[LocalType]

local_type: Type
classmethod package(*args, output_cls, bsize=None, **kwargs)

Aggregates all local computations into a single object based on the object’s concat_with_metadata method.

Parameters:

  • args (Any) – Positional arguments forwarded to local_iter.

  • output_cls (Type[LocalType]) – The output class used to aggregate local objects.

  • bsize (int | None) – Optional batch size for chunked iteration. (default: None).

  • kwargs (Any) – Keyword arguments forwarded to local_iter.

Returns:

A concatenated LocalType object with metadata.

Return type:

LocalType

src.linalg.rmetric module

class src.linalg.rmetric.RMetric

Bases: func[RMetricSystem, RMetricSystems], ABC

classmethod global_func(x_pts, lap, ncomp=None, dual=True, md=None)

Compute the global Riemannian metric decomposition from data embeddings and a Laplacian vector.

Parameters:

  • x_pts (Embedding) – Input data embedding.

  • lap (DenseArray) – Laplacian vector or equivalent weight vector.

  • ncomp (int | None) – Number of eigencomponents to retain. If None, keep all. (default: None).

  • dual (bool) – If True, return the dual metric. If False, return the inverse. (default: True).

  • md (Metadata | None) – Optional metadata to merge with x_pts metadata. If None, inherits from x_pts. (default: None)

Returns:

An RMetricSystems object containing eigenvalues and eigenvectors.

Return type:

RMetricSystem

classmethod local(x_pts, lap, ncomp=None, mean_pts=None, dual=True, bsize=None)

Lazily computes the local Riemannian metric decomposition on all x_pts centered on mean_pts. If there are multiple mean points, computes metrics for each.

Parameters:

  • x_pts (Embedding) – Input data embedding.

  • lap (LaplacianMatrix) – Laplacian weights for local neighborhoods.

  • ncomp (int | None) – Number of eigencomponents to retain. If None, keep all. (default: None).

  • mean_pts (DenseArray | None) – Optional local mean points. If None, defaults to each data point. (default: None).

  • dual (bool) – If True, return the dual metric. If False, return the inverse. (default: True).

  • bsize (int | None) – Optional batch size for dividing the computation. (default: None).

Returns:

The desired local Riemannian metric in an RMetricSystems object.

Return type:

RMetricSystems

classmethod local_func(x_pts, mean_pts, lap, ncomp, dual, md=None)

Computes the local Riemannian metric decomposition using uncentered data and affinity weights.

Parameters:

  • x_pts (Embedding) – Input data embedding.

  • mean_pts (DenseArray) – Local mean points for each neighborhood.

  • lap (LaplacianMatrix) – Laplacian weights for local neighborhoods.

  • ncomp (int | None) – Number of eigencomponents to retain. If None, keep all. (default: None).

  • dual (bool) – If True, return the dual metric. If False, return the inverse. (default: True).

  • md (Metadata | None) – Metadata to include in the return RMetricSystems.

Returns:

The desired local Riemannian metric in an RMetricSystems object.

Return type:

RMetricSystems

classmethod local_iter(x_pts, lap, ncomp=None, mean_pts=None, dual=True, bsize=None)

Computes the local Riemannian metric decomposition in a batched manner on all x_pts centered on mean_pts. If there are multiple mean points, computes metrics for each.

Parameters:

  • x_pts (Embedding) – Input data embedding.

  • lap (LaplacianMatrix) – Laplacian weights for local neighborhoods.

  • ncomp (int | None) – Number of eigencomponents to retain. If None, keep all. (default: None).

  • mean_pts (DenseArray | None) – Optional local mean points. If None, defaults to each data point. (default: None).

  • dual (bool) – If True, return the dual metric. If False, return the inverse. (default: True).

  • bsize (int | None) – Optional batch size for dividing the computation. (default: None).

Returns:

Iterator that yields RMetricSystems objects per batch.

Return type:

Iterator[RMetricSystems]

class src.linalg.rmetric.RMetricSystem(iterable, **kwargs)

Bases: EigenSystem

Container class for a single Riemannian metric eigensystem.

Parameters:

  • iterable (Iterable[Any])

  • kwargs (Any)

Return type:

Eigen

class src.linalg.rmetric.RMetricSystems(iterable, **kwargs)

Bases: EigenSystem

Container class for multiple Riemannian metric eigensystems. Index 0 is an array of eigenvalue arrays. Index 1 is an array of eigenvector matrices.

Parameters:

  • iterable (Iterable[Any])

  • kwargs (Any)

Return type:

Eigen

fixed_value_ndim: int = 2
fixed_value_type

alias of DenseArray

fixed_vector_ndim: int = 3
fixed_vector_type

alias of DenseArray

Module contents

class src.linalg.Covariance

Bases: func[CovarianceMatrix, CovarianceMatrices], ABC

classmethod global_func(centered_x_pts, weights=None, md=None)

Computes the global covariance matrix from centered data points.

Parameters:

  • centered_x_pts (DenseArray) – Centered data points with shape (m, p), where m is the number of samples and p is the feature dimension.

  • weights (BaseArray | None) – Optional weight array of shape (m,) to compute a weighted covariance. If None, computes the unweighted covariance. (default: None).

  • md (Metadata | None) – Metadata to attach to the returned CovarianceMatrix.

Returns:

A CovarianceMatrix representing the global covariance structure.

Return type:

CovarianceMatrix

classmethod local(x_pts, mean_pts=None, weights=None, needs_means=True, needs_norm=True, in_place_norm=False, bsize=None)

Lazily computes the local covariance on all x_pts centered on mean_pts. If there are multiple mean points, computes covariance for each.

Parameters:

  • x_pts (Points) – The neighborhood to calculate covariance with.

  • mean_pts (DenseArray | None) – Optional center for the covariance calculation. If there are multiple mean points, computes covariance for each. If None, each point is treated as its own center. (default: None)

  • weights (BaseArray | None) – Optional weight matrix to calculate weighted covariance with. (default: None).

  • needs_means (bool) – Whether x_pts is centered. (default: True)

  • needs_norm (bool) – Whether the weights need to be normalized. (default: True)

  • in_place_norm (bool) – If needs_norm, whether to do the weight normalization in-place. (default: False)

  • bsize (int | None) – Optional batch size to divide the covariance calculation. (default: None).

Returns:

The desired covariance matrices in a CovarianceMatrices object.

Return type:

CovarianceMatrices

classmethod local_func(x_pts, mean_pts, weights, needs_means, md=None)

Computes the local covariance on all x_pts centered on mean_pts. If there are multiple mean points, computes covariance for each.

Parameters:

  • x_pts (DenseArray) – The neighborhood to calculate covariance with.

  • mean_pts (DenseArray) – The center for the covariance calculation. If there are multiple mean points, computes covariance for each.

  • weights (BaseArray | None) – Optional weight matrix to calculate weighted covariance with.

  • needs_means (bool) – Whether x_pts is centered.

  • md (Metadata | None) – Optional metadata to include in return CovarianceMatrices. (default: None).

Returns:

Matrix where covariance matrices are joined along axis 0.

Return type:

CovarianceMatrices

classmethod local_iter(x_pts, mean_pts=None, weights=None, needs_means=True, needs_norm=True, in_place_norm=False, bsize=None)

Computes the local covariance in a batched manner on all x_pts centered on mean_pts. If there are multiple mean points, computes covariance for each.

Parameters:

  • x_pts (Points) – The neighborhood to calculate covariance with.

  • mean_pts (DenseArray | None) – Optional center for the covariance calculation. If there are multiple mean points, computes covariance for each. If None, each point is treated as its own center. (default: None)

  • weights (BaseArray | None) – Optional weight matrix to calculate weighted covariance with. (default: None).

  • needs_means (bool) – Whether x_pts is centered. (default: True)

  • needs_norm (bool) – Whether the weights need to be normalized. (default: True)

  • in_place_norm (bool) – If needs_norm, whether to do the weight normalization in-place. (default: False)

  • bsize (int | None) – Optional batch size to divide the covariance calculation. (default: None).

Returns:

Iterator that gives the desired covariance matrices.

Return type:

Iterator[CovarianceMatrices]

class src.linalg.RMetric

Bases: func[RMetricSystem, RMetricSystems], ABC

classmethod global_func(x_pts, lap, ncomp=None, dual=True, md=None)

Compute the global Riemannian metric decomposition from data embeddings and a Laplacian vector.

Parameters:

  • x_pts (Embedding) – Input data embedding.

  • lap (DenseArray) – Laplacian vector or equivalent weight vector.

  • ncomp (int | None) – Number of eigencomponents to retain. If None, keep all. (default: None).

  • dual (bool) – If True, return the dual metric. If False, return the inverse. (default: True).

  • md (Metadata | None) – Optional metadata to merge with x_pts metadata. If None, inherits from x_pts. (default: None)

Returns:

An RMetricSystems object containing eigenvalues and eigenvectors.

Return type:

RMetricSystem

classmethod local(x_pts, lap, ncomp=None, mean_pts=None, dual=True, bsize=None)

Lazily computes the local Riemannian metric decomposition on all x_pts centered on mean_pts. If there are multiple mean points, computes metrics for each.

Parameters:

  • x_pts (Embedding) – Input data embedding.

  • lap (LaplacianMatrix) – Laplacian weights for local neighborhoods.

  • ncomp (int | None) – Number of eigencomponents to retain. If None, keep all. (default: None).

  • mean_pts (DenseArray | None) – Optional local mean points. If None, defaults to each data point. (default: None).

  • dual (bool) – If True, return the dual metric. If False, return the inverse. (default: True).

  • bsize (int | None) – Optional batch size for dividing the computation. (default: None).

Returns:

The desired local Riemannian metric in an RMetricSystems object.

Return type:

RMetricSystems

classmethod local_func(x_pts, mean_pts, lap, ncomp, dual, md=None)

Computes the local Riemannian metric decomposition using uncentered data and affinity weights.

Parameters:

  • x_pts (Embedding) – Input data embedding.

  • mean_pts (DenseArray) – Local mean points for each neighborhood.

  • lap (LaplacianMatrix) – Laplacian weights for local neighborhoods.

  • ncomp (int | None) – Number of eigencomponents to retain. If None, keep all. (default: None).

  • dual (bool) – If True, return the dual metric. If False, return the inverse. (default: True).

  • md (Metadata | None) – Metadata to include in the return RMetricSystems.

Returns:

The desired local Riemannian metric in an RMetricSystems object.

Return type:

RMetricSystems

classmethod local_iter(x_pts, lap, ncomp=None, mean_pts=None, dual=True, bsize=None)

Computes the local Riemannian metric decomposition in a batched manner on all x_pts centered on mean_pts. If there are multiple mean points, computes metrics for each.

Parameters:

  • x_pts (Embedding) – Input data embedding.

  • lap (LaplacianMatrix) – Laplacian weights for local neighborhoods.

  • ncomp (int | None) – Number of eigencomponents to retain. If None, keep all. (default: None).

  • mean_pts (DenseArray | None) – Optional local mean points. If None, defaults to each data point. (default: None).

  • dual (bool) – If True, return the dual metric. If False, return the inverse. (default: True).

  • bsize (int | None) – Optional batch size for dividing the computation. (default: None).

Returns:

Iterator that yields RMetricSystems objects per batch.

Return type:

Iterator[RMetricSystems]