torch_fem.sparse

SparseMatirx 

class SparseMatrix(edata, row, col, shape)[source]

Bases: Module

coo format sparse matrix

Parameters:

edata (torch.Tensor) – 1D float tensor of shape \([|\mathcal E|]\), where \(|\mathcal E|\) is the number of edges the edge data
row (torch.Tensor) – 1D int tensor of shape \([|\mathcal E|]\), where \(|\mathcal E|\) is the number of edges the row indices
col (torch.Tensor) – 1D int tensor of shape \([|\mathcal E|]\), where \(|\mathcal E|\) is the number of edges the column indices
shape (Tuple[int, int]) – the shape of the sparse matrix of the first two dim, e.g. (3, 4)

edata

1D float tensor of shape \([|\mathcal E|]\), where \(|\mathcal E|\) is the number of edges the edge data

Type:: torch.Tensor

row

1D int tensor of shape \([|\mathcal E|]\), where \(|\mathcal E|\) is the number of edges the row indices

Type:: torch.Tensor

col

1D int tensor of shape \([|\mathcal E|]\), where \(|\mathcal E|\) is the number of edges the column indices

Type:: torch.Tensor

shape

the shape of the sparse matrix of the first two dim, e.g. (3, 4)

Type:: Tuple[int, int]

hash_layout

it will be used to check if two sparse matrices have the same layout, the hash of the layout of the sparse matrix

Type:: str

property edges

Returns:: the edge indices of shape \([2, |\mathcal E|]\), where \(|\mathcal E|\) is the number of edges
Return type:: torch.Tensor

elementwise_operation(func, obj)[source]

Elementwise operation with another sparse matrix or a tensor or a scalar If the object is a sparse matrix, the edges of the two sparse matrices should be the same

Parameters:

func (Callable[[torch.Tensor, torch.Tensor], torch.Tensor]) – the elementwise operation
obj (SparseMatrix or torch.Tensor or int or float) – the object to be elementwise operated with

Returns:

result – the result of the elementwise operation

Return type:

SparseMatrix

solve(x, backend=None)[source]

Parameters:

x (torch.Tensor) – the dense tensor of shape [a] or [a,h] to be solved with the sparse matrix
backend (str, optional) – the backend to solve the sparse matrix, can be None, "torch", "scipy" or "torch_scipy", default None

Returns:

the result of the solution of shape [b] or [b,h]

Return type:

torch.Tensor

requires_grad_(requires_grad: bool = True)[source]

Parameters:: requires_grad (bool, optional) – whether the sparse matrix requires gradient, default True
Returns:: the sparse matrix with requires_grad set to requires_grad
Return type:: SparseMatrix

transpose()[source]: tranpose the sparse matrix

\[A = A^\top\]

sqrt()[source]: element-wise square root

\[A_{ij} = \sqrt{A_{ij}}\]

reciprocal()[source]: element-wise reciprocal

\[A_{ij} = \frac{1}{A_{ij}}\]

degree(axis=0)[source]

how many non-zero element in each row/column - axis = 0

\[\sum_{j}\mathbb{1}_{A_{ij} \neq 0}\]

axis = 1

\[\sum_{i}\mathbb{1}_{A_{ij} \neq 0}\]

Parameters:: axis (int, optional) – the axis to sum, can be 0 or 1, default 0
Returns:: the degree of shape \([n_{\text{row}}]\) or \([n_{\text{col}}]\)
Return type:: torch.Tensor

sum(axis=None)[source]

sum of all non-zero elements

axis = None

\[\sum_{ij}A_{ij}\]
axis = 0

\[\sum_{j}A_{ij}\]
axis = 1

\[\sum_{i}A_{ij}\]

Parameters:: axis (int, optional) – the axis to sum, can be None, 0 or 1, default None
Returns:: the sum of shape \([]\) or \([n_\text{row}]\) or \([n_\text{col}]\)
Return type:: torch.Tensor

clone()[source]: The cloned sparse matrix will share clone gradient with the original sparse matrix :returns: the cloned sparse matrix :rtype: torch_fem.sparse.SparseMatrix

property T

Returns:: the transpose of the sparse matrix
Return type:: torch_fem.sparse.SparseMatrix

property requires_grad

Returns:: whether the sparse matrix requires gradient or not
Return type:: bool

property dtype

Returns:: the dtype of the sparse matrix
Return type:: torch.dtype

property device

Returns:: the device of the sparse matrix
Return type:: torch.device

property grad

Returns:: if the sparse matrix requires gradient, return the grad for each element of the sparse matrix, otherwise return None
Return type:: torch_fem.sparse.SparseMatrix or None

property grad_fn

Returns:: if the sparse matrix requires gradient, return the grad_fn for each element of the sparse matrix, otherwise return None
Return type:: torch.autograd.Function or None

property nnz

Returns:: the number of non-zero elements
Return type:: int

property layout_mask

Returns:: the mask of the layout, where the non-zero elements are 1, otherwise 0
Return type:: torch.Tensor

type(dtype)[source]

Returns:: the sparse matrix with dtype set to dtype
Return type:: torch_fem.sparse.SparseMatrix

detach()[source]

Returns:: the sparse matrix with requires_grad set to False
Return type:: torch_fem.sparse.SparseMatrix

to_scipy_coo()[source]

Returns:: the scipy.sparse.coo_matrix of the sparse matrix
Return type:: scipy.sparse.coo_matrix

to_sparse_coo()[source]: Turn the sparse matrix into a torch.sparse_coo_tensor, the gradient will be lost :returns: the torch.sparse_coo_tensor of the sparse matrix :rtype: torch.sparse_coo_tensor

to_dense()[source]: Turn the sparse matrix into a dense matrix, the gradient will be maintained :returns: the dense tensor of the sparse matrix :rtype: torch.Tensor

has_same_layout(obj)[source]

Parameters:: obj (SparseMatrix or str) – the object to be compared with, if it is a str, it will be compared with the layout_hash of the sparse matrix
Returns:: whether the two sparse matrices have the same layout
Return type:: bool

static from_sparse_coo(matrix)[source]

Parameters:: matrix (torch.sparse_coo_tensor) – the sparse matrix to be converted
Returns:: the sparse matrix converted from the torch.sparse_coo_tensor
Return type:: torch_fem.sparse.SparseMatrix

static from_block_coo(edata, row, col, shape)[source]

Each element in a sparse matrix is a block matrix

Parameters:

edata (torch.Tensor) – 3D float tensor of shape \([|\mathcal E|, C, C]\), where \(|\mathcal E|\) is the number of edges, \(C\) is the size of the block data the block data
row (torch.Tensor) – 1D int tensor of shape \([|\mathcal E|]\), where \(|\mathcal E|\) is the number of edges the row indices
col (torch.Tensor) – 1D int tensor of shape \([|\mathcal E|]\), where \(|\mathcal E|\) is the number of edges the column indices
shape (Tuple[int, int]) – the shape of the sparse matrix of the first two dim

Returns:

the sparse matrix converted from the block coo format of shape

Return type:

torch_fem.sparse.SparseMatrix

static from_dense(tensor)[source]

Parameters:: tensor (torch.Tensor) – the dense tensor to be converted
Returns:: the sparse matrix converted from the dense tensor
Return type:: torch_fem.sparse.SparseMatrix

Examples

>>> SparseMatrix.from_dense(torch.eye(3))
SparseMatrix(
    edata: tensor([1., 1., 1.])
    row  : tensor([0, 1, 2])
    col  : tensor([0, 1, 2])
    shape: (3, 3)
)

static random(m, n, density=0.1, device='cpu', dtype=torch.float32)[source]

randomly generate a sparse matrix :param m: the number of rows :type m: int :param n: the number of cols :type n: int :param density: the density of the sparse matrix, default 0.1 :type density: float, optional :param device: the device of the sparse matrix, default cpu :type device: str, optional :param dtype: the dtype of the sparse matrix, default torch.float :type dtype: torch.dtype, optional

Returns:: the sparse matrix of shape \([m,n]\) with density density and dtype dtype
Return type:: torch_fem.sparse.SparseMatrix

static random_layout(m, n, density=0.1, device='cpu')[source]

randomly generate a sparse matrix layout :param m: the number of rows :type m: int :param n: the number of cols :type n: int :param density: the density of the sparse matrix, default 0.1 :type density: float, optional :param device: the device of the sparse matrix, default cpu :type device: str, optional

Returns:: the layout of the sparse matrix of shape \([m,n]\) with density density and dtype dtype
Return type:: Tuple[torch.Tensor, torch.Tensor, Tuple[int, int]]

static random_from_layout(layout, device='cpu', dtype=torch.float32)[source]

randomly generate a sparse matrix from a layout :param layout: the layout of the sparse matrix :type layout: Tuple[torch.Tensor, torch.Tensor, Tuple[int, int]] :param device: the device of the sparse matrix, default cpu :type device: str, optional :param dtype: the dtype of the sparse matrix, default torch.float :type dtype: torch.dtype, optional

Returns:: the sparse matrix of shape \([m,n]\) with density density and dtype dtype
Return type:: torch_fem.sparse.SparseMatrix

static eye(n, value=1.0, device='cpu', dtype=torch.float32)[source]

generate a sparse identity matrix :param n: the number of rows and columns :type n: int :param value: the value of the diagonal elements, default 1. :type value: float, optional :param device: the device of the sparse matrix, default cpu :type device: str, optional :param dtype: the dtype of the sparse matrix, default torch.float :type dtype: torch.dtype, optional

Returns:: the sparse matrix of shape \([n,n]\) with value value and dtype dtype
Return type:: torch_fem.sparse.SparseMatrix

Examples

>>> SparseMatrix.eye(3).to_dense()
tensor([[1., 0., 0.],
        [0., 1., 0.],
        [0., 0., 1.]])

static full(m, n, value=1.0, device='cpu', dtype=torch.float32)[source]

generate a dense matrix filled with a value :param m: the number of rows :type m: int :param n: the number of columns :type n: int :param value: the value of the diagonal elements, default 1. :type value: float, optional :param device: the device of the sparse matrix, default cpu :type device: str, optional :param dtype: the dtype of the sparse matrix, default torch.float :type dtype: torch.dtype, optional

Returns:: the dense tensor of shape \([n,n]\) with value value and dtype dtype
Return type:: torch_fem.sparse.SparseMatrix

static combine_vector(matrices, axis=0)[source]

Combine sparse matrices into a sparse matrix

Parameters:

matrices (List[torch_fem.sparse.SparseMatrix]) – the sparse matrices to be combined
axis (int, optional) – the axis to combine, can be 0 or 1, default 0

Returns:

the combined sparse matrix

Return type:

torch_fem.sparse.SparseMatrix

Examples

>>> SparseMatrix.combine_vector([
...     SparseMatrix.eye(3), SparseMatrix.eye(3)
... ]).to_dense()
tensor([[1., 0., 0.],
        [0., 1., 0.],
        [0., 0., 1.],
        [1., 0., 0.],
        [0., 1., 0.],
        [0., 0., 1.]])

static combine_matrix(matrices)[source]

Parameters:

matrices (List[List[torch_fem.sparse.SparseMatrix or None or float or int]]) – the sparse matrices to be combined
axis (int, optional) – the axis to combine, can be 0 or 1, default 0

Returns:

the combined sparse matrix

Return type:

torch_fem.sparse.SparseMatrix

Examples

>>> SparseMatrix.combine_matrix([
...     [SparseMatrix.eye(3), SparseMatrix.eye(3)],
...     [SparseMatrix.eye(3), SparseMatrix.eye(3)]
... ]).to_dense()
tensor([[1., 0., 0., 1., 0., 0.],
        [0., 1., 0., 0., 1., 0.],
        [0., 0., 1., 0., 0., 1.],
        [1., 0., 0., 1., 0., 0.],
        [0., 1., 0., 0., 1., 0.],
        [0., 0., 1., 0., 0., 1.]])

static combine(matrices)[source]

the dispatch function for :attr:combine_vector and :attr:combine_matrix

Parameters:: matrices (List[torch_fem.sparse.SparseMatrix or List[torch_fem.sparse.SparseMatrix or None or float or int]]) – the sparse matrices to be combined
Returns:: the combined sparse matrix
Return type:: torch_fem.sparse.SparseMatrix

torch_fem.sparse

SparseMatirx

SparseMatirx 