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	Compare with another Eigenvalues value.
len(e)	Returns the number of stored values.
np.asarray(e)	Convert to a NumPy array with np.asarray(e).

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.