Tools for performing efficient Kronecker product-based matrix operations
Project description
Check out the full documentation and install instructions here :)
Overview
PyKronecker is a library for manipulating matrices which have a Kronecker product structure. Systems involving Kronecker products arise in many areas of applied mathematics and statistics. The aim of this library is to provide a clean interface for dealing with such systems, combining lazy evaluation and algebraic tricks to deliver large savings in terms of both memory and execution time.
Installation
Installation on Windows, OSX and Linux can be performed by running
pip3 install pykronecker
This will install the vanilla version of the library, with support for NumPy arrays only. Linux users have the additional option of installing PyKronecker with Jax support. The benefit of this is significantly faster runtimes, even when working with NumPy arrays only, due to Jax's JIT complier. This can be installed by running
pip3 install pykronecker[jax]
For Linux users with an Nvidia graphics card, PyKronecker is also compatible with the GPU and TPU version of Jax. However, since this relies on CUDA and cuDNN, it is recommended to follow the instructions here to install Jax first.
Usage
The concept of this library is to create instances of a KroneckerOperator
class, which can be broadly treated as if it is a square numpy array. These objects are designed to be used with the @
syntax for matrix multiplication.
Basic operators
KroneckerProduct
Create a KroneckerProduct
from two or more square NumPy/Jax arrays. These can be real or complex valued.
import numpy as np
from pykronecker import KroneckerProduct
A = np.random.normal(size=(5, 5))
B = np.random.normal(size=(6, 6))
C = KroneckerProduct([A, B])
This object can operate on both vectors of shape (5 * 6, )
and tensors of shape (5, 6)
using the @
syntax for matrix multiplication. The returned array will be of the same shape.
x = np.random.normal(size=5 * 6)
X = np.random.normal(size=(5, 6))
print(C @ x)
print(C @ X)
KroneckerSum
A KronekerSum
can be created and used in much the same way.
from pykronecker import KroneckerSum
D = KroneckerSum([A, B])
print(D @ x)
KroneckerDiag
KroneckerDiag
provides support for diagonal matrices, and can be created by passing a tensor of the appropriate size. This creates, in effect, a matrix with the vectorized tensor along the diagonal.
from pykronecker import KroneckerDiag
E = KroneckerDiag(np.random.normal(size=(5, 6)))
print(E @ x)
KroneckerIdentity
Finally, KroneckerIdentity
creates the identity matrix, which can be instantiated by passing another operator of the same size, or the shape of tensors it should act on.
from pykronecker import KroneckerIdentity
I1 = KroneckerIdentity(like=E)
I2 = KroneckerIdentity(tensor_shape=(5, 6))
print(I1 @ x, I2 @ x)
Deriving new operators
All four of these objects can be added or multiplied together arbitrarily to create new composite operators. In this way, they can be treated similarly to literal NumPy arrays.
F = C @ D + C @ E
print(F @ x)
Other possible operations include transposing with .T
, and multiplying/dividing by a scalar.
G = 2 * F.T + E / 5
print(G @ x)
Many basic operators can also be multipled element-wise just as with NumPy arrays.
H = C * D
print(H @ x)
Block operators
We can create block operators by stacking together any mixture of KroneckerOperator
s and/or NumPy arrays.
from pykronecker import KroneckerBlock
# Block of pure KroneckerOperators
M = KroneckerBlock([[C, D],
[E, F]])
print(M @ np.random.normal(size=5 * 6 * 2))
# Block with mixture of KroneckerOperators and ndarrays
N11 = E
N12 = np.ones((5 * 6, 5))
N21 = np.random.normal(size=(5, 5 * 6))
N22 = np.eye(5)
N = KroneckerBlock([[N11, N12],
[N21, N22]])
print(N @ np.random.normal(size=5 * 6 * 2))
Block diagonal matrices can also be created in a similar way
from pykronecker import KroneckerBlockDiag
J = KroneckerBlockDiag([E, F])
print(M @ np.random.normal(size=5 * 6 * 2))
Other features
For operators that are products of KroneckerProduct
s, KroneckerDiag
s, or KroneckerIdentity
s, we can find the inverse with .inv()
.
H = (C @ E).inv()
print(H @ x)
Summing down an axis or over the whole matrix is supported.
print(F.sum(0))
print(F.sum(1))
print(F.sum())
As is conversion to a literal array
print(H.to_array())
Element-wise power operation can be used with **
print(C ** 2)
The matrix diagonal can be found with .diag()
print(C.diag())
Th conjugate transpose with .H
print(C.H)
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pykronecker-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0ba46a78321202177724c5663363ea56088c87207ddf848f6a406984e1ded6bd |
|
MD5 | dec080a87d913992efc6fca2390899c1 |
|
BLAKE2b-256 | 0d154812bc078030bd4e0aed03738d68dc7d2289a1b82410779ad5fc87aa2c32 |