Rename tensor to blockarray and BlockTensor to BlockArray

Also tried to update documentation to no longer refer to BlockTensor

Author: jon-deng

README.md

@@ -1,15 +1,15 @@
-# BlockTensor
+# BlockArray
 
-BlockTensor is a package for working with tensors logically partitioned into blocks (or subtensors) in a nested format. For example, block matrices and block vectors can be created as:
+BlockArray is a package for working with tensors logically partitioned into blocks (or subtensors) in a nested format. For example, block matrices and block vectors can be created as:
 ```python
-from blocktensor.tensor import BlockTensor
-from blocktensor.linalg import mult_mat_vec
+from BlockArray.tensor import BlockArray
+from BlockArray.linalg import mult_mat_vec
 
 # model the block vector
 # [x0, x1]
 # where x0 = np.array([1, 2, 3])
 # x1 = np.array([4, 5])
-x = BlockTensor([np.array([1, 2, 3]), np.array([4, 5])])
+x = BlockArray([np.array([1, 2, 3]), np.array([4, 5])])
 
 # model the block matrix
 # [[A00, A01],
@@ -29,7 +29,7 @@ A10 = np.array(
 A11 = np.array(
     [[1, 2],
      [3, 4]])
-A = BlockTensor([[A00, A01], [A10, A11]])
+A = BlockArray([[A00, A01], [A10, A11]])
 
 # Basic math operations
 y = mult_mat_vec(2*A, x)

blocktensor/tensor.py blocktensor/blockarray.pyblocktensor/tensor.py renamed to blocktensor/blockarray.py

@@ -39,12 +39,12 @@ def _block_shape(array: larr.LabelledArray):
 
 def validate_subtensor_shapes(array: larr.LabelledArray, bshape):
     """
-    Validate subtensors in a BlockTensor have a valid shape
+    Validate subtensors in a BlockArray have a valid shape
 
     array :
         The block array containing the subtensors
     shape :
-        The target block shape of the BlockTensor
+        The target block shape of the BlockArray
     """
     # Subtensors are valid along an axis at a certain block if:
     # all subtensors in the remaining dimensions have the same shape along that
@@ -69,13 +69,13 @@ def validate_subtensor_shapes(array: larr.LabelledArray, bshape):
                 valid_bsizes = [bsize == _bsize for _bsize in ascblock_sizes]
                 assert all(valid_bsizes)
 
-class BlockTensor:
+class BlockArray:
     """
     An n-dimensional block tensor object
 
-    `BlockTensor` has two main attributes: an underlying `LabelledArray` that stores the subtensors in an n-d layout and a `bshape` attributes that stores the shape of the blocks along each axis.
+    `BlockArray` has two main attributes: an underlying `LabelledArray` that stores the subtensors in an n-d layout and a `bshape` attributes that stores the shape of the blocks along each axis.
 
-    For example, consider a `BlockTensor` `A` with the block shape `((10, 5), (2, 4))`.
+    For example, consider a `BlockArray` `A` with the block shape `((10, 5), (2, 4))`.
     This represents a matrix with blocks of size 10 and 5 along the rows, and blocks of size 2 and 4 along the columns. Subtensors of `A` would then have shapes:
         `A[0, 0].shape == (10, 2)`
         `A[0, 1].shape == (10, 4)`
@@ -316,7 +316,7 @@ def __rtruediv__(self, other):
     ## Numpy ufunc interface
     def __array_ufunc__(ufunc, method, *inputs, **kwargs):
         for btensor in inputs:
-            if not isinstance(btensor, BlockTensor):
+            if not isinstance(btensor, BlockArray):
                 raise TypeError(
                     f"ufunc {ufunc} cannot be called with inputs" +
                     ", ".join([f"{type(input)}" for input in inputs])
@@ -329,24 +329,24 @@ def __array_ufunc__(ufunc, method, *inputs, **kwargs):
         ret_shape = inputs[0].shape
         ret_labels = inputs[0].labels
 
-        return BlockTensor(subtensors_out, ret_shape, ret_labels)
+        return BlockArray(subtensors_out, ret_shape, ret_labels)
 
 def validate_elementwise_binary_op(a, b):
     """
-    Validates if BlockTensor inputs are applicable
+    Validates if BlockArray inputs are applicable
     """
     assert a.bshape == b.bshape
 
-def _elementwise_binary_op(op: Callable[[T, T], T], a: BlockTensor, b: BlockTensor):
+def _elementwise_binary_op(op: Callable[[T, T], T], a: BlockArray, b: BlockArray):
     """
-    Compute elementwise binary operation on BlockTensors
+    Compute elementwise binary operation on BlockArrays
 
     Parameters
     ----------
     op: function
         A function with signature func(a, b) -> c, where a, b, c are vector of
         the same shape
-    a, b: BlockTensor
+    a, b: BlockArray
     """
     validate_elementwise_binary_op(a, b)
     array = tuple([op(ai, bi) for ai, bi in zip(a.subtensors_flat, b.subtensors_flat)])
@@ -364,13 +364,13 @@ def _elementwise_binary_op(op: Callable[[T, T], T], a: BlockTensor, b: BlockTens
 power = functools.partial(_elementwise_binary_op, operator.pow)
 
 
-def _elementwise_unary_op(op: Callable[[T], T], a: BlockTensor):
+def _elementwise_unary_op(op: Callable[[T], T], a: BlockArray):
     """
-    Compute elementwise unary operation on a BlockTensor
+    Compute elementwise unary operation on a BlockArray
 
     Parameters
     ----------
-    a: BlockTensor
+    a: BlockArray
     """
     array = larr.LabelledArray([op(ai) for ai in a.subtensors_flat], a.shape, a.labels)
     return type(a)(array)
@@ -385,9 +385,9 @@ def scalar_mul(alpha, a):
 def scalar_div(alpha, a):
     return _elementwise_unary_op(lambda subvec: subvec/alpha, a)
 
-def to_ndarray(block_tensor: BlockTensor):
+def to_ndarray(block_tensor: BlockArray):
     """
-    Convert a BlockTensor object to a ndarray object
+    Convert a BlockArray object to a ndarray object
     """
     # .bsize (block size) is the resulting shape of the monolithic array
     ret_array = np.zeros(block_tensor.mshape)

blocktensor/h5utils.py

@@ -1,5 +1,5 @@
 """
-Utilities for reading/writing BlockTensor objects to hdf5
+Utilities for reading/writing BlockArray objects to hdf5
 """
 
 import h5py

blocktensor/mat.py

@@ -5,12 +5,11 @@
 
 import itertools
 import numpy as np
-from blocktensor.tensor import BlockTensor
+from blocktensor.blockarray import BlockArray
 from petsc4py import PETSc
 
 from . import subops as gops
 from .labelledarray import LabelledArray, flatten_array
-from .tensor import BlockTensor
 
 # pylint: disable=no-member
 
@@ -366,7 +365,7 @@ def convert_bmat_to_petsc(bmat):
     barray = LabelledArray(mats, bmat.shape, bmat.labels)
     return BlockMatrix(barray)
 
-class BlockMatrix(BlockTensor):
+class BlockMatrix(BlockArray):
     """
     Represents a block matrix with blocks indexed by keys
     """

blocktensor/ufunc.py

@@ -7,7 +7,7 @@
 import numpy as np
 
 from . import types
-from .tensor import BlockTensor
+from .blockarray import BlockArray
 
 Signature = Tuple[str, ...]
 Signatures = List[Signature]
@@ -204,7 +204,7 @@ def recursive_concatenate(arrays: types.FlatArray, shape: types.Shape, axes: typ
 
 def apply_ufunc(ufunc: np.ufunc, method: str, *inputs, **kwargs):
     """
-    Apply a ufunc on sequence of BlockTensor inputs
+    Apply a ufunc on sequence of BlockArray inputs
     """
     if method != '__call__':
         raise ValueError(f"ufunc method {method} is not supported")
@@ -258,7 +258,7 @@ def apply_ufunc(ufunc: np.ufunc, method: str, *inputs, **kwargs):
 
             subtensors_out.append(ufunc(*subtensor_ins, **kwargs))
 
-        outputs.append(BlockTensor(subtensors_out, shape_out, labels_out))
+        outputs.append(BlockArray(subtensors_out, shape_out, labels_out))
 
     if len(outputs) == 1:
         return outputs[0]

blocktensor/vec.py

@@ -10,7 +10,7 @@
 from petsc4py import PETSc
 
 from . import subops as gops
-from .tensor import BlockTensor
+from .blockarray import BlockArray
 from .mat import BlockMatrix
 
 ## pylint: disable=no-member
@@ -94,7 +94,7 @@ def norm(a):
     """Return the 2-norm of a vector"""
     return dot(a, a)**0.5
 
-class BlockVector(BlockTensor):
+class BlockVector(BlockArray):
     """
     Represents a block vector with blocks indexed by labels
     """
@@ -138,8 +138,8 @@ def __setitem__(self, key, value):
         value : array_like or BlockVector
         """
         _array = self[key]
-        if isinstance(_array, BlockTensor):
-            if isinstance(value, BlockTensor):
+        if isinstance(_array, BlockArray):
+            if isinstance(value, BlockArray):
                 for subvec, subvec_value in zip(_array, value):
                     gops.set_vec(subvec, subvec_value)
             else:

docs/source/intro.rst

@@ -2,11 +2,11 @@
 Introduction
 ************
 
-This package provides a ``BlockTensor`` object that makes it easier to work with tensors that are logically divided into multiple blocks or subtensors.
-The basic usage of the ``BlockTensor`` is illustrated below for the case of a block matrix and block vector::
+This package provides a ``BlockArray`` object that makes it easier to work with tensors that are logically divided into multiple blocks or subtensors.
+The basic usage of the ``BlockArray`` is illustrated below for the case of a block matrix and block vector::
 
     import numpy as np
-    from blocktensor.tensor import BlockTensor
+    from blocktensor.tensor import BlockArray
 
     # `A` is a block representation of the matrix
     # [[1, 2, 3],
@@ -24,15 +24,15 @@ The basic usage of the ``BlockTensor`` is illustrated below for the case of a bl
         [[7, 8]])
     A11 = np.array(
         [[9]])
-    A = BlockTensor([[A00, A01], [A10, A11]], labels=(('a', 'b'), ('a', 'b')))
+    A = BlockArray([[A00, A01], [A10, A11]], labels=(('a', 'b'), ('a', 'b')))
 
 
     # `X` is a block representation of the vector
     # [1, 2, 3]
     # the first block is labelled 'a' and the second 'b'
     X0 = np.array([1, 2])
     X1 = np.array([3])
-    X = BlockTensor([X0, X1], labels=(('a', 'b'),))
+    X = BlockArray([X0, X1], labels=(('a', 'b'),))
 
 In the above example, the matrix ``A`` is represented by 2 row blocks (with corresponding submatrix row sizes 2 and 1) and 2 column blocks (with corresponding submatrix column sizes 2 and 1) while the vector ``X`` is represented with two row blocks (with corresponding subvector sizes 2 and 1).
 Blocks of ``A`` and ``X`` are also labelled; labels are useful to organize blocks since blocks often represent different different systems.
@@ -47,9 +47,9 @@ Indexing block tensors works similarly to indexing in ``numpy`` with some additi
         * ``tensor[0]`` returns subtensor ``a``
         * ``tensor[-1]`` returns subtensor ``c``
     * range of indices by slice
-        * ``tensor[0:2]`` returns a ``BlockTensor`` with subtensors ``(a, b)``
-        * ``tensor[:]`` returns the same ``BlockTensor`` as ``tensor``
+        * ``tensor[0:2]`` returns a ``BlockArray`` with subtensors ``(a, b)``
+        * ``tensor[:]`` returns the same ``BlockArray`` as ``tensor``
     * range of indices by list of single indices
-        * ``tensor[['a', 'b']]`` returns a ``BlockTensor`` with subtensors ``(a, b)``
-        * ``tensor[[0, 1]]`` returns a ``BlockTensor`` with subtensors ``(a, b)``
-        * ``tensor[[0, -1]]`` returns a ``BlockTensor`` with subtensors ``(a, c)``
+        * ``tensor[['a', 'b']]`` returns a ``BlockArray`` with subtensors ``(a, b)``
+        * ``tensor[[0, 1]]`` returns a ``BlockArray`` with subtensors ``(a, b)``
+        * ``tensor[[0, -1]]`` returns a ``BlockArray`` with subtensors ``(a, c)``

tests/test_tensor.py tests/test_blockarray.pytests/test_tensor.py renamed to tests/test_blockarray.py

@@ -4,28 +4,28 @@
 
 import numpy as np
 
-import blocktensor.tensor as btensor
+import blocktensor.blockarray as ba
 
 
 a = np.ones((4, 4))
 b = np.ones((4, 2))
 c = np.ones((2, 4))
 d = np.ones((2, 2))
-A = btensor.BlockTensor([[a, b], [c, d]])
+A = ba.BlockArray([[a, b], [c, d]])
 
 a = 2 * np.ones((4, 4))
 b = 2 * np.ones((4, 2))
 c = 2 * np.ones((2, 4))
 d = 2 * np.ones((2, 2))
-B = btensor.BlockTensor([[a, b], [c, d]])
+B = ba.BlockArray([[a, b], [c, d]])
 
 
 def _test_elementwise_binary_op(sub_op, a, b, block_op=None):
     """
     Test a generic element-wise binary operation
 
     This should test whether a operation applied across each block gives the
-    same result as an equivalent operation on the BlockTensors
+    same result as an equivalent operation on the BlockArrays
     """
     if block_op is None:
         block_op = sub_op
@@ -51,7 +51,7 @@ def test_div():
     _test_elementwise_binary_op(lambda x, y: x/y, A, B)
 
 def test_power():
-    _test_elementwise_binary_op(lambda x, y: x**y, A, B, btensor.power)
+    _test_elementwise_binary_op(lambda x, y: x**y, A, B, ba.power)
 
 def test_bshape():
     print(f"A.bshape = {A.bshape}")

tests/test_ufuncutils.py

@@ -1,6 +1,6 @@
 
 import numpy as np
-from blocktensor import ufunc, tensor as btensor
+from blocktensor import blockarray as btensor, ufunc
 
 SIGNATURE = '(i,j),(j,k)->(i, k)'
 
@@ -57,7 +57,7 @@ def test_recursive_concatenate():
     b = np.ones((4, 2))
     c = np.ones((2, 4))
     d = np.ones((2, 2))
-    A = btensor.BlockTensor([[a, b], [c, d]])
+    A = btensor.BlockArray([[a, b], [c, d]])
 
     ufunc.recursive_concatenate(A.subtensors_flat, A.shape, A.dims)
 
@@ -66,13 +66,13 @@ def test_apply_ufunc():
     b = np.ones((4, 2))
     c = np.ones((2, 4))
     d = np.ones((2, 2))
-    A = btensor.BlockTensor([[a, b], [c, d]])
+    A = btensor.BlockArray([[a, b], [c, d]])
 
     a = np.ones((4, 4))
     b = np.ones((4, 2))
     c = np.ones((2, 4))
     d = np.ones((2, 2))
-    B = btensor.BlockTensor([[a, b], [c, d]])
+    B = btensor.BlockArray([[a, b], [c, d]])
 
     # C = ufuncutils.apply_ufunc(np.add, '__call__', *[A, B])
     # print(C.shape)

tests/test_vec.py

@@ -4,7 +4,7 @@
 from blocktensor import mat as bmat
 from blocktensor import linalg as bla
 from blocktensor import vec as bvec
-from blocktensor import tensor as btensor
+from blocktensor import blockarray as btensor
 
 # pylint: disable=unused-import
 # pylint: disable=missing-function-docstring