quickpaver.get_rlg_perm_mat#

quickpaver.get_rlg_perm_mat(grid: RectilinearGrid, n: int, axis: int, sub_selection: ndarray[tuple[Any, ...], dtype[int64]]) → csc_array[source]#

Build a sparse forward-neighbour permutation matrix along one grid axis.

The returned matrix maps values from owner cells to their forward neighbours along the selected axis. For each valid owner/neighbour pair, the matrix contains one non-zero coefficient:

mat[neighbour_index, owner_index] = 1

Therefore, if field is a flattened grid-cell array, then mat @ field gives an array where each forward neighbour receives the value of its owner cell. Cells without a valid backward owner along the selected axis remain zero.

Parameters:

  • grid (RectilinearGrid) – Rectilinear grid defining the shape, indexing convention, and total number of grid cells.

  • n (int) – Number of cells along the selected axis. This is usually one of grid.nx, grid.ny, or grid.nz depending on axis.

  • axis (int) –

    Axis along which the forward-neighbour permutation is built:

    • 0 for the x-axis,

    • 1 for the y-axis,

    • 2 for the z-axis.

  • sub_selection (NDArrayInt) – Flattened grid-cell indices to keep. Owner and neighbour cells must both belong to this selection to be connected in the permutation matrix.

Returns:

Sparse permutation matrix with shape (grid.n_grid_cells, grid.n_grid_cells) in CSC format.

Return type:

csc_array

Notes

If n < 2, no forward neighbour exists along the selected axis and an empty sparse matrix is returned.

The grid uses the flattened numbering convention:

node_number = ix + iy * grid.nx + iz * grid.ny * grid.nx

This matrix is not a full permutation matrix in the strict algebraic sense when boundary cells or cells outside sub_selection are present, because some rows and columns may contain only zeros.

On this page