Eigenvectors

SUMMARY

A set of orthonormal eigenvectors.

from telekinesis import datatypes
eigenvectors = datatypes.Eigenvectors([[1.0, 0.0], [0.0, 1.0]])

API Reference

Complete API documentation for Eigenvectors, including parameters, attributes, and methods.

View Reference →

Parameters

Parameter	Type	Default	Description
data	np.ndarray | list | tuple	Required	Array-like data of shape (N, N): square, non-empty, dtype in the allowlist below. Columns are the eigenvectors.
atol	float | None	None	Keyword-only. Absolute tolerance for the orthonormality check (V^T V ≈ I). If None, computed as 100 * eps(dtype) * sqrt(N).
rtol	float	0.0	Keyword-only. Relative tolerance for the same check. Since the reference matrix is the identity, rtol has no effect on its zero entries.

Raises

Exception	Condition
TypeError	data can't be converted into a uniform array (e.g. ragged nested lists)
ValueError	The resulting dtype isn't in the allowlist below
ValueError	data isn't 2-D
ValueError	data isn't square
ValueError	data is empty (0x0)
ValueError	data contains a non-finite value (NaN/Inf)
ValueError	data's columns aren't orthonormal within atol/rtol

Supported Dtypes

Inherited unchanged from Array:

Category	Dtypes
Boolean	bool
Signed / unsigned integer	int8…int64, uint8…uint64
Floating-point	float16, float32, float64

object, structured, datetime64, and complex (complex64/complex128) dtypes are not supported — Array itself only accepts bool/int/uint/float.

Attributes

Attribute	Type	Description
data	np.ndarray	The wrapped (N, N) array; column k is the k-th eigenvector. Reading it returns a copy.
shape	tuple[int, int]	(N, N).
ndim	int	Always 2.
dtype	np.dtype	Dtype of the array as constructed — not forced to float32.
size	int	N * N.

Methods

Method	Type	Description
Eigenvectors.coerce(value)	Eigenvectors	Converts array-like data into an Eigenvectors. Accepts a np.ndarray, list, or tuple. If value is already an Eigenvectors, it is returned unchanged; otherwise it goes through the same checks as constructing one directly, including the orthonormality check with default tolerances.
to_numpy(copy=True)	np.ndarray	Returns the eigenvectors as a plain array. With the default copy=True you get an independent copy; pass copy=False to get a direct reference to the internal array instead, so mutating it also mutates the Eigenvectors.
copy()	Eigenvectors	Returns a new, independent Eigenvectors with the same data, re-validated using the default orthonormality tolerances.
check_orthonormality(data, atol=None, rtol=0.0)	bool	Checks whether an arbitrary square array's columns are orthonormal, not just this instance's own data — useful for validating a candidate matrix before building an Eigenvectors from it. atol defaults to a tolerance scaled to data's own dtype and size; rtol defaults to 0.0. data must be square, 2-D, and non-empty.
is_orthonormal(atol=None, rtol=0.0)	bool	Checks whether this instance's own data is orthonormal, using the same atol/rtol tolerance and defaults as check_orthonormality.

Operators

Operation	Behavior
v1 == v2	True only if other is also an Eigenvectors with the same dtype, shape, and values (NaN counts as equal to NaN here). False for anything else.
len(v)	N (number of rows, equal to the number of columns).
np.asarray(v)	Returns a copy of data as an np.ndarray; NumPy functions accept an Eigenvectors directly.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("eigenvectors_example", spawn=True)
datatypes.visualize(eigenvectors, entity_path="/eigenvectors", label="Eigenvectors")

Example

"""Demonstrates the Telekinesis Eigenvectors datatype."""

import time

import numpy as np
import rerun as rr
from loguru import logger

from telekinesis import datatypes

def eigenvectors_example():
    """Demonstrate creation, inspection, operations, visualization, and serialization."""

    # ======================= Create ============================================
    matrix = np.array([[2.0, 1.0], [1.0, 2.0]], dtype=np.float64)
    _, eigenvector_data = np.linalg.eigh(matrix)
    eigenvectors = datatypes.Eigenvectors(eigenvector_data)
    logger.info(f"Created Eigenvectors: {eigenvectors}")

    noisy_eigenvectors = datatypes.Eigenvectors(eigenvector_data + 1e-10, atol=1e-6)
    logger.info(f"Created Eigenvectors with relaxed tolerance: {noisy_eigenvectors}")

    # ======================= Inspect ===========================================
    logger.info(f"shape={eigenvectors.shape}")
    logger.info(f"size={eigenvectors.size}")
    logger.info(f"ndim={eigenvectors.ndim}")
    logger.info(f"dtype={eigenvectors.dtype}")
    logger.info(f"data={eigenvectors.data}")

    # ======================= Operations =========================================
    _, new_eigenvector_data = np.linalg.eigh(np.array([[5.0, 2.0], [2.0, 5.0]], dtype=np.float64))
    eigenvectors.data = new_eigenvector_data
    logger.info(f"Updated Eigenvectors: {eigenvectors}")

    eigenvectors_copy = eigenvectors.copy()
    logger.info(f"Copied Eigenvectors: {eigenvectors_copy}")

    eigenvectors_numpy = eigenvectors.to_numpy(copy=True)
    logger.info(f"NumPy Eigenvectors:\n{eigenvectors_numpy}")

    numpy_eigenvectors = np.asarray(eigenvectors)
    logger.info(f"NumPy array via __array__:\n{numpy_eigenvectors}")

    logger.info(f"is_orthonormal={eigenvectors.is_orthonormal()}")
    logger.info(f"check_orthonormality={eigenvectors.check_orthonormality(eigenvectors.data)}")

    # ======================= Visualize =========================================
    rr.init("eigenvectors_example", spawn=True)
    datatypes.visualize(eigenvectors, entity_path="/eigenvectors")

    # ======================= Serialize / Deserialize ===========================
    start = time.perf_counter()
    serialized = datatypes.serialize(eigenvectors)
    serialization_ms = (time.perf_counter() - start) * 1000

    start = time.perf_counter()
    deserialized = datatypes.deserialize(serialized)["param_0"]
    deserialization_ms = (time.perf_counter() - start) * 1000

    logger.info(f"Deserialized Eigenvectors: {deserialized}")
    logger.info(f"Round-trip successful: {eigenvectors == deserialized}")
    logger.info(f"Serialization time: {serialization_ms:.3f} ms")
    logger.info(f"Deserialization time: {deserialization_ms:.3f} ms")


if __name__ == "__main__":
    eigenvectors_example()

See also Eigenvalues and Array.