quickpaver.get_rlg_spatial_grad_mat#

quickpaver.get_rlg_spatial_grad_mat(grid: RectilinearGrid, n: int, axis: int, sub_selection: ndarray[tuple[Any, ...], dtype[int64]], which: Literal['forward', 'backward', 'both'] = 'both') → csc_array[source]#

Build a sparse spatial-gradient matrix along one grid axis.

The matrix approximates a finite-volume gradient-like operator along the selected axis. For each valid owner-neighbour cell pair, the matrix adds a positive contribution on the owner cell and a negative contribution on the neighbouring cell:

mat[owner_index, owner_index] += interface_area / cell_volume

mat[owner_index, neighbour_index] -= interface_area / cell_volume

If field is a flattened grid-cell array, then mat @ field returns the directional difference between owner and neighbour values, scaled by the corresponding interface-area-to-volume ratio.

Parameters:

  • grid (RectilinearGrid) – Rectilinear grid defining the cell dimensions, 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 gradient matrix is assembled:

    • 0 for the x-axis,

    • 1 for the y-axis,

    • 2 for the z-axis.

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

  • which (Literal["forward", "backward", "both"], optional) –

    Difference scheme to assemble:

    • "forward" uses owner cells and their forward neighbours.

    • "backward" uses owner cells and their backward neighbours.

    • "both" combines forward and backward contributions.

    By default "both".

Returns:

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

Return type:

csc_array

Raises:

ValueError – If which is not one of "forward", "backward", or "both".

Notes

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

The coefficient magnitude is computed as:

interface_area / cell_volume

with the interface area selected according to axis:

  • x-axis: grid.gamma_ij_x_m2

  • y-axis: grid.gamma_ij_y_m2

  • z-axis: grid.gamma_ij_z_m2

The flattened grid-cell numbering convention is:

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