quickpaver.conservative_upsample#

quickpaver.conservative_upsample(array: ndarray[tuple[Any, ...], dtype[float64]], factor: int) → ndarray[tuple[Any, ...], dtype[float64]][source]#

Upsample a 2D extensive array while preserving its total sum.

Each input cell is expanded into a factor x factor block. The original cell value is evenly distributed over the refined cells by dividing each duplicated value by factor ** 2. As a result, the sum of the output array is equal to the sum of the input array, up to floating-point precision.

Parameters:

  • array (NDArrayFloat) – Two-dimensional array to upsample. Values are interpreted as extensive quantities attached to grid cells.

  • factor (int) – Integer upsampling factor applied along both array axes. Each input cell becomes a square block of shape (factor, factor) in the output. Must be greater than or equal to 1.

Returns:

Conservatively upsampled array with shape (array.shape[0] * factor, array.shape[1] * factor).

Return type:

NDArrayFloat

Raises:

ValueError – If factor is smaller than 1.

Notes

This function is appropriate for extensive quantities whose total value must be conserved during refinement, such as volume, mass, surface area, or energy.

For intensive quantities, where the original value should simply be repeated over refined cells, use duplicative_upsample().