capytaine.tools.block_circulant_matrices module

Implementation of block circulant matrices to be used for optimizing resolution with symmetries.

class capytaine.tools.block_circulant_matrices.BlockCirculantMatrix(blocks: Sequence[ArrayLike])

Bases: object

Data-sparse representation of a block matrix of the following form

( a d c b ) ( b a d c ) ( c b a d ) ( d c b a )

where a, b, c and d are matrices of the same shape.

Parameters:

blocks (Sequence of matrix-like, can be also a ndarray of shape (nb_blocks, n, n, …)) – The first column of blocks [a, b, c, d, …] Each block should have the same shape.

block_diagonalize() → BlockDiagonalMatrix

matvec(other)

solve(b: ndarray) → ndarray

class capytaine.tools.block_circulant_matrices.BlockDiagonalMatrix(blocks: Sequence[ArrayLike])

Bases: object

Data-sparse representation of a block matrix of the following form

( a 0 0 0 ) ( 0 b 0 0 ) ( 0 0 c 0 ) ( 0 0 0 d )

where a, b, c and d are matrices of the same shape.

Parameters:

blocks (iterable of matrix-like) – The blocks [a, b, c, d, …]

solve(b: ndarray) → ndarray

class capytaine.tools.block_circulant_matrices.LUDecomposedBlockCirculantMatrix(bcm: BlockCirculantMatrix, *, overwrite_a: bool = False)

Bases: object

solve(b: ndarray) → ndarray

class capytaine.tools.block_circulant_matrices.LUDecomposedBlockDiagonalMatrix(bdm: BlockDiagonalMatrix, *, overwrite_a: bool = False)

Bases: object

LU decomposition of a BlockDiagonalMatrix, stored as the LU decomposition of each block.

solve(b: ndarray) → ndarray

class capytaine.tools.block_circulant_matrices.LUDecomposedMatrix(A: ndarray[tuple[Any, ...], dtype[_ScalarT]], *, overwrite_a: bool = False)

Bases: object

solve(b: ndarray) → ndarray

class capytaine.tools.block_circulant_matrices.NestedBlockCirculantMatrix(blocks: Sequence[ArrayLike])

Bases: object

Data-sparse representation of a block matrix of the following form

( a b | e d | c f ) ( b a | f c | d e ) ( —————— ) ( c f | a b | e d ) ( d e | b a | f c ) ( —————— ) ( e d | c f | a b ) ( f c | d e | b a )

where a, b, c, d, e and f are matrices of the same shape, that is a block circulant matrix (here of size 3x3, but arbitrary outer sizes are supported), where diagonal blocks are 2x2 block circulant matrices and off-diagonal blocks have subblocks in common.

Reordering the lines and columns, this matrix is equivalent to the following shape

( a e c | b d f ) ( c a e | f b d ) ( e c a | d f b ) ( —————– ) ( b f d | a c e ) ( d b f | e a c ) ( f d b | c e a )

that is a 2x2 block matrix of block circulant matrices, the block circulant matrices of the bottom row being the transpose of the block circulant matrices of the top row.

In the 2x2x2x2 limit case, the matrix is a nested block circulant matrix

( a b | c d ) ( b a | d c ) ( ———– ) ( c d | a b ) ( d c | b a )

The 4x4x2x2 pattern reads

( a b | g d | e f | c h ) ( b a | h c | f e | d g ) ( —–|------|——|----- ) ( c h | a b | g d | e f ) ( d g | b a | h c | f e ) ( -----|——|------|—– ) ( e f | c h | a b | g d ) ( f e | d g | b a | h c ) ( —–|------|——|—– ) ( g d | e f | c h | a b ) ( h c | f e | d g | b a )

Parameters:

blocks (Sequence of matrix-like, can be also a ndarray of shape (nb_blocks, n, n, …)) – The first column of blocks [a, b, c, d, …] Each block should have the same shape, and the number of blocks should be even.

block_diagonalize() → BlockDiagonalMatrix

matvec(other)

solve(b: ndarray) → ndarray

to_BlockCirculantMatrix()

Convert to a BlockCirculantMatrix with combined macro-blocks.

The NestedBlockCirculantMatrix with blocks [a, b, c, d, e, f, …] (where nb_blocks = 2*n) is converted to a BlockCirculantMatrix with n macro-blocks.

Each macro-block i (for i in 0..n-1) is a 2x2 arrangement of the original blocks: - For i=0: [[blocks[0], blocks[1]], [blocks[1], blocks[0]]] - For i>0: [[blocks[2*i], blocks[2*n-2*i+1]], [blocks[2*i+1], blocks[2*n-2*i]]]

capytaine.tools.block_circulant_matrices.circular_permutation(l: List, i: int) → List

capytaine.tools.block_circulant_matrices.ending_dimensions_at_the_beginning(a)

Transform an array of shape (…, n, m) into (n, m, …). Invert of leading_dimensions_at_the_end

capytaine.tools.block_circulant_matrices.has_been_lu_decomposed(A)

capytaine.tools.block_circulant_matrices.leading_dimensions_at_the_end(a)

Transform an array of shape (n, m, …) into (…, n, m). Invert of leading_dimensions_at_the_end

capytaine.tools.block_circulant_matrices.lu_decompose(A: ndarray | BlockDiagonalMatrix | NestedBlockCirculantMatrix | BlockCirculantMatrix, *, overwrite_a: bool = False)