Reference on kuibit.tensor

The tensor module provides abstractions to work with tensorial containers and similar.

The main object defined here is Tensor, which is a that acts as container for any object BaseNumerical, as in TimeSeries, or UniformGridData. Tensor behaves as one would expect them to behave: they are high-level interfaces that support all the mathematical operations. Tensor also inherit the attributes from their contained object. For example, if the Tensor contains TimeSeries, the tensor will dynamically acquire all the methods in such class.

In pratice, the main way to use Tensor objects is through its derived classes Vector and Matrix, which implement all those features one might expect from vector calculus.

Consider the following usage example:

import numpy as np

from kuibit.timeseries import TimeSeries
from kuibit.tensor import Vector

# Fake some data that describe the x, y position of two black holes
times = np.linspace(0, 2 * np.pi, 100)

bh1_x = np.sin(times)
bh1_y = np.cos(times)

# Not really realistic, but it is fake data
bh2_x = np.sin(2 * times)
bh2_y = np.cos(2 * times)

bh1_centroid = Vector([TimeSeries(times, bh1_x), TimeSeries(times, bh1_y)])
bh2_centroid = Vector([TimeSeries(times, bh2_x), TimeSeries(times, bh2_y)])

# If we want to compute vx, vy
bh1_velocity = bh_centroid.differentiated()  # This is a Vector

# For the distance with another
distance = bh1_centroid - bh2_centroid  # This is a Vector

# The magnitude of the distance
distance = distance.norm()   # This is a TimeSeries

class kuibit.tensor.Matrix(data)

Represents a matrix in the mathematical sense.

It can be used with series, or grid data, or anything that is derived from BaseNumerical.

This abstraction is useful for matrix operations: for example, taking the determinant.

All the operations are component-wise, and the matrix inherits all the methods available to the base object.

Construct the Tensor by checking and processing the data.

The data is flattened out and it shape is saved. The shape here is defined as the number of elements of the tensor along each dimension. For example, for a vector it would only by its length.

Parameters:

data (Nested list of data derived from BaseNumerical.) – Representation of the tensor as nested lists.

class kuibit.tensor.Tensor(data)

Represents a mathematical hyper-matrix (a Tensor) in N dimensions.

At the moment, it is only used as a base class for Vector and Matrix. So, the class is currently not intended for direct use (as it does not have a lot of features). This class is not fully flashed out for the general case. It is here mostly as a stub for the two subclasses that are below. Implementing a generic tensor class is not trivial and it left as an exercise to the reader.

This class implements the basic infrastrucutre used by Vector and Matrix. In particular, it fullfills the requirements set by BaseNumerical and it implements a method to broadcast attributes from the contained objects to the container itself.

All the operations are applied component-wise. So, for example, a tensor times a tensor is going to be a tensor with the same shape and elements multiplied. Reductions return NumPy arrays.

..note:

 For efficicency of implmentation, data is sotred without hierarchy
(i.e., "flattened out"). Therefore, the operations that require
reconstructing the structure have some small overhead. When, possible
work with flattened data.

Construct the Tensor by checking and processing the data.

The data is flattened out and it shape is saved. The shape here is defined as the number of elements of the tensor along each dimension. For example, for a vector it would only by its length.

Parameters:

data (Nested list of data derived from BaseNumerical.) – Representation of the tensor as nested lists.

copy()

Return a deep copy of the object.

Returns:

Deep copy

Return type:

Tensor

property data

Return the data with its tensorial structure.

For example, if this was a Matrix, the return value would be a list of lists.

Note, this operation is not free! Data is stored flat, so recomputing the structure has some overhead.

Returns:

Data structured according to self.shape

Return type:

Nested lists

property flat_data: List[_T]

Return the data in the tensor as a flat list.

Returns:

List with all the data

Return type:

List of type.

classmethod from_shape_and_flat_data(shape, flat_data)

Create a new Tensor from flat data and shape.

No checks are performed.

Return type:

Tensor[TypeVar(_T, bound= BaseNumerical)]

property shape: Tuple[int, ...]

Return the shape of the Tensor.

The shape is defined as the number of elements in each dimension.

Returns:

Shape of the tensor.

Return type:

Tuple of ints

property type: type

Return the type of the contained object.

Returns:

Type of the object, a class derived from BaseNumerical

Return type:

type

class kuibit.tensor.Vector(data)

Represents a vector in the mathematical sense.

It can be used with series, or grid data, or anything that is derived from BaseNumerical.

This abstraction is useful for vector operations: for example, taking the cross/dot products between two vectors.

All the operations are component-wise, and the vector inherits all the methods available to the base object.

Construct the Tensor by checking and processing the data.

The data is flattened out and it shape is saved. The shape here is defined as the number of elements of the tensor along each dimension. For example, for a vector it would only by its length.

Parameters:

data (Nested list of data derived from BaseNumerical.) – Representation of the tensor as nested lists.

dot(other)

Return the dot product with another vector.

Parameters:

other (Vector) – Other vector in the dot product.

Returns:

Dot product

Return type:

Same as self.type

norm()

Return the norm of the vector.

Returns:

Norm of the vector

Return type:

Same as self.type