wolfgpu.tile_packer

Author: HECE - University of Liege, Stéphane Champailler, Pierre Archambeau Date: 2024

Copyright (c) 2024 University of Liege. All rights reserved.

This script and its content are protected by copyright law. Unauthorized copying or distribution of this file, via any medium, is strictly prohibited.

Module Contents

class wolfgpu.tile_packer.TilePackingMode(*args, **kwds)

Bases: enum.Enum

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

• attribute access:

>>> Color.RED
<Color.RED: 1>

• value lookup:

>>> Color(1)
<Color.RED: 1>

• name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

REGULAR = 1

TRANSPARENT = 3

wolfgpu.tile_packer._unpack_and_deshuffle_array(a: numpy.ndarray, shape: tuple, height: int, width: int, active_tiles: numpy.ndarray, tile_size: int, tile_indirection_map: numpy.ndarray) → numpy.ndarray

class wolfgpu.tile_packer.TilePacker(nap: numpy.array, tile_size: int, mode: TilePackingMode = TilePackingMode.REGULAR)

_tile_size

_mode

_original_nap

_active_tiles_ndx

_nb_active_tiles

_packed_nb_tiles_x

_packed_nb_tiles_y

_tile_indirection_map

tile_reversed_indirection_map()

tile_indirection_map()

The tile indirection map. Its shape is (nb_tiles_y,nb_tiles_x,2) (so it’s defined in term of the original, non-tiled domain). The z-axis contains the indirected coordinates of the bottom-left corner of the tile denoted by the x and y axis values. For example, if you have the tile coordinates (t_i, t_j), then map[t_i, t_j, :] is a 2-tuple containing the coordinates (in meshes) of the bottom-left corner of that tile, on the tiled, packed domain.

Note that the (i,j) is (horizontal, vertical) coordinates but the indirection matrix is (vertical horizontal). FIXME That’s completely awkward. I should keep (j,i) as (vert, horiz)

mode() → TilePackingMode

packed_size()

Size of the arrays after padding them and packing them in tiles, expressed in meshes. Size is a (width, height) tuple.

Note that this size can be very different than the actual computation domain size (because tiles are heavily reorganized).

packed_size_in_tiles()

Size of the arrays after padding them and packing them in tiles, expressed in tiles. Size is a (width, height) tuple.

Note that this size can be very different than the actual computation domain size.

size_in_tiles()

Size of the (original, non packed, non tiled) computation domain, in tiles. Note that we count full tiles. So if one dimension of the domain is not a multiple of the tile size, then we round upwards.

Size is a (width, height) tuple.

tile_size() → int

The tile size. Note that tiles are squared.

unpack_array(a: numpy.ndarray) → numpy.ndarray

De-shuffle and un-pad an array of tiles that was shuffled and padded.

_unpad_array(a: numpy.array) → numpy.array

Undo _pad_array_to_tiles.

_pad_array_to_tiles(a: numpy.array, neutral_values) → numpy.array

Make an array fit in a given number of tiles (on x and y axis). After this, the array’s dimensions are multiple of the tile_size.

Parameters:

neutral_values – The value used to pad.

pack_array(a: numpy.array, neutral_values=None, debug=False) → numpy.array

Reorganize an array by moving tiles around to follow the ordering given by self._tile_indirection_map The array is resized in order to be just as large as needed to hold the active tiles plus the “empty” tile.

Note: the packed array has the same dtype as :param a:

neutral_values: value to fill the empty tile with.

unpack_subarray_xy_view(packed_array, x1, y1, x2, y2)

Extract a rectangular subarray from a packed tile array and return it as a regular array.

Parameters:

• packed_array – The packed array from which to extract the subarray.

• x1 – The left (inclusive) coordinate of the region to extract (in user/original domain coordinates).

• y1 – The top (inclusive) coordinate of the region to extract (in user/original domain coordinates).

• x2 – The right (exclusive) coordinate of the region to extract (in user/original domain coordinates).

• y2 – The bottom (exclusive) coordinate of the region to extract (in user/original domain coordinates).

Returns:

The unpacked subarray corresponding to the requested region.

Return type:

numpy.ndarray

unpack_subarray_matrix_view(packed_array, i1, j1, i2, j2)

Extract a rectangular subarray from a packed tile array and return it as a regular array.

Parameters:

• packed_array – The packed array from which to extract the subarray.

• i1 – The left (inclusive) coordinate of the region to extract (in matrix convention).

• j1 – The top (inclusive) coordinate of the region to extract (in matrix convention).

• i2 – The right (exclusive) coordinate of the region to extract (in matrix convention).

• j2 – The bottom (exclusive) coordinate of the region to extract (in matrix convention).

Returns:

The unpacked subarray corresponding to the requested region.

Return type:

numpy.ndarray

unpack_subarrays_xy_view(packed_array, xys: dict[str, tuple[int, int, int, int]]) → dict[str, numpy.ndarray]

Extract multiple rectangular subarrays from a packed tile array and return them as regular arrays.

Parameters:

• packed_array – The packed array from which to extract the subarrays.

• xys – A dictionary where each key is a label and each value is a tuple of four integers representing the coordinates (x1, y1, x2, y2) of the region to extract (in user/original domain coordinates).

Returns:

A dictionary of unpacked subarrays corresponding to the requested regions.

Return type:

dict[str, numpy.ndarray]

_pad_subarray_to_tiles(a: numpy.array, i1: int, j1: int, neutral_values) → numpy.array

Make an array fit in a given number of tiles (on x and y axis). After this, the array’s dimensions are multiple of the tile_size.

Parameters:

• a – The subarray to pad.

• i1 – The top coordinate of the subarray in the original domain.

• j1 – The left coordinate of the subarray in the original domain.

• neutral_values – The value used to pad.

pack_subarray(packed_array, new_subarray, i1, j1)

Update the packed_array with a rectangular region of a regular new_array.

Parameters:

• packed_array – The packed array to update.

• new_subarray – The regular array containing the new data to insert.

• i1 – The left indice of the region to update - packed_array[i1,j1] == new_subarray[0,0] - in matrix convention.

• j1 – The top indice of the region to update - packed_array[i1,j1] == new_subarray[0,0] - in matrix convention.

Returns:

The original packed array with the updated subarray.

Return type:

numpy.ndarray

pack_subarrays(packed_array, new_subarrays: dict[str, tuple[numpy.ndarray, tuple[int, int]]]) → numpy.ndarray

Update the packed_array with multiple rectangular regions of regular new_arrays.

Parameters:

• packed_array – The packed array to update.

• new_subarrays – A dictionary where each key is a label and each value is a regular array containing the new data to insert and the position (i1, j1).

• neutral_values – value to fill the empty tile with.

Returns:

The original packed array with the updated subarrays.

Return type:

numpy.ndarray

get_ij_packed_from_ij_domain(i: int, j: int) → tuple[int, int]

Get the packed array coordinates (i_packed, j_packed) corresponding to the original domain coordinates (i, j).

Parameters:

• i – The horizontal coordinate in the original domain.

• j – The vertical coordinate in the original domain.

Returns:

A tuple (i_packed, j_packed) representing the coordinates in the packed array.

Return type:

tuple[int, int]

get_ijs_packed_from_ijs_domain(ijs: tuple[numpy.ndarray]) → tuple[numpy.ndarray]

Get the packed array coordinates for multiple points corresponding to the original domain coordinates.

Parameters:

ijs – A tuple of two Numpy arrays (each of shape (N,)) where the first array contains i coordinates and the second array contains j coordinates in the original domain.

The ijs is like a np.where result: first row is i’s, second row is j’s.

Returns:

A tuple of two Numpy arrays (each of shape (N,)) where the first array contains i_packed coordinates and the second array contains j_packed coordinates in the packed array.

Return type:

tuple[np.ndarray]