Eigenvalues

SUMMARY

A collection of eigenvalues.

from telekinesis import datatypes
eigenvalues = datatypes.Eigenvalues([1.0, 2.0])

API Reference

Complete API documentation for Eigenvalues, 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 >= 1, with a dtype in the allowlist below.

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 (this also rules out complex input, since Eigenvalues requires real-valued eigenvalues)
ValueError	data isn't 1-D
ValueError	data is empty (size == 0)
ValueError	data contains a non-finite value (NaN/Inf)

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, so complex input is rejected before Eigenvalues's own real-valued check ever runs.

Attributes

Attribute	Type	Description
data	np.ndarray	The wrapped 1-D array, shape (N,). Reading it returns a copy, so mutating the result doesn't affect the Eigenvalues.
shape	tuple[int]	(N,).
ndim	int	Always 1.
dtype	np.dtype	Dtype of the array as constructed — not forced to float32.
size	int	N.
condition_number	float	max|λ| / min|λ| over the stored eigenvalues. Only meaningful for a non-singular matrix — a near-zero eigenvalue makes it arbitrarily large. Raises ZeroDivisionError if any eigenvalue's magnitude is exactly 0 (singular matrix).

Methods

Method	Type	Description
Eigenvalues.coerce(value)	Eigenvalues	Converts array-like data into an Eigenvalues. Accepts a np.ndarray, list, or tuple. If value is already an Eigenvalues, it is returned unchanged; otherwise it goes through the same checks as constructing one directly.
to_numpy(copy=True)	np.ndarray	Returns the eigenvalues 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 Eigenvalues.
copy()	Eigenvalues	Returns a new, independent Eigenvalues with the same data.
is_positive_semidefinite(atol=None)	bool	Checks whether every eigenvalue is non-negative, within a small tolerance atol for floating-point noise. Useful for confirming a matrix is a valid covariance or Gram matrix. atol defaults to a value scaled to the data's precision.
is_positive_definite(atol=None)	bool	Checks whether every eigenvalue is strictly positive, within the same tolerance atol as is_positive_semidefinite. Useful for confirming a matrix is invertible and well-conditioned.

Operators

Operation	Behavior
e1 == e2	True only if other is also an Eigenvalues with the same dtype, shape, and values (NaN counts as equal to NaN here). False for anything else.
len(e)	Number of stored eigenvalues, N.
np.asarray(e)	Returns a copy of data as an np.ndarray; NumPy functions accept an Eigenvalues directly.

Visualization

import rerun as rr

# Your code block
# ....

rr.init("eigen_value_example", spawn=True)
datatypes.visualize(eigenvalues, entity_path="/eigenvalues", label="Eigen value")

Example

"""Demonstrates the Telekinesis Eigenvalues datatype."""

import time

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

from telekinesis import datatypes

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

    # ======================= Create ============================================
    matrix = np.array([[2.0, 1.0], [1.0, 2.0]], dtype=np.float32)
    eigenvalue_data, _ = np.linalg.eigh(matrix)
    eigenvalues = datatypes.Eigenvalues(eigenvalue_data)
    logger.info(f"Created Eigenvalues: {eigenvalues}")

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

    # ======================= Operations =========================================
    new_eigenvalue_data, _ = np.linalg.eigh(np.array([[5.0, 2.0], [2.0, 5.0]], dtype=np.float32))
    eigenvalues.data = new_eigenvalue_data
    logger.info(f"Updated Eigenvalues: {eigenvalues}")

    eigenvalues_copy = eigenvalues.copy()
    logger.info(f"Copied Eigenvalues: {eigenvalues_copy}")

    eigenvalues_numpy = eigenvalues.to_numpy(copy=True)
    logger.info(f"NumPy Eigenvalues: {eigenvalues_numpy}")

    numpy_eigenvalues = np.asarray(eigenvalues)
    logger.info(f"NumPy array via __array__: {numpy_eigenvalues}")
    logger.info(f"Spectral radius (max |eigenvalue|): {np.max(np.abs(eigenvalues))}")

    logger.info(f"is_positive_semidefinite={eigenvalues.is_positive_semidefinite()}")
    logger.info(f"is_positive_definite={eigenvalues.is_positive_definite()}")

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

    # ======================= Serialize / Deserialize ===========================
    start = time.perf_counter()
    serialized = datatypes.serialize(eigenvalues)
    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 Eigenvalues: {deserialized}")
    logger.info(f"Round-trip successful: {eigenvalues == deserialized}")
    logger.info(f"Serialization time: {serialization_ms:.3f} ms")
    logger.info(f"Deserialization time: {deserialization_ms:.3f} ms")


if __name__ == "__main__":
    eigenvalues_example()

See also Eigenvectors and Array.