wolfgpu.tile_packer =================== .. py:module:: wolfgpu.tile_packer .. autoapi-nested-parse:: 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 --------------- .. py:class:: TilePackingMode(*args, **kwds) Bases: :py:obj:`enum.Enum` .. autoapi-inheritance-diagram:: wolfgpu.tile_packer.TilePackingMode :parts: 1 :private-bases: 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 - value lookup: >>> Color(1) - name lookup: >>> Color['RED'] Enumerations can be iterated over, and know how many members they have: >>> len(Color) 3 >>> list(Color) [, , ] Methods can be added to enumerations, and members can have their own attributes -- see the documentation for details. .. py:attribute:: REGULAR :value: 1 .. py:attribute:: TRANSPARENT :value: 3 .. py:function:: _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 .. py:class:: TilePacker(nap: numpy.array, tile_size: int, mode: TilePackingMode = TilePackingMode.REGULAR) .. py:attribute:: _tile_size .. py:attribute:: _mode .. py:attribute:: _original_nap .. py:attribute:: _active_tiles_ndx .. py:attribute:: _nb_active_tiles .. py:attribute:: _packed_nb_tiles_x .. py:attribute:: _packed_nb_tiles_y .. py:attribute:: _tile_indirection_map .. py:method:: tile_reversed_indirection_map() .. py:method:: 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) .. py:method:: mode() -> TilePackingMode .. py:method:: 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). .. py:method:: 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. .. py:method:: 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. .. py:method:: tile_size() -> int The tile size. Note that tiles are squared. .. py:method:: unpack_array(a: numpy.ndarray) -> numpy.ndarray De-shuffle and un-pad an array of tiles that was shuffled and padded. .. py:method:: _unpad_array(a: numpy.array) -> numpy.array Undo `_pad_array_to_tiles`. .. py:method:: _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. :param neutral_values: The value used to pad. .. py:method:: 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. .. py:method:: 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. :param packed_array: The packed array from which to extract the subarray. :param x1: The left (inclusive) coordinate of the region to extract (in user/original domain coordinates). :param y1: The top (inclusive) coordinate of the region to extract (in user/original domain coordinates). :param x2: The right (exclusive) coordinate of the region to extract (in user/original domain coordinates). :param y2: The bottom (exclusive) coordinate of the region to extract (in user/original domain coordinates). :return: The unpacked subarray corresponding to the requested region. :rtype: numpy.ndarray .. py:method:: 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. :param packed_array: The packed array from which to extract the subarray. :param i1: The left (inclusive) coordinate of the region to extract (in matrix convention). :param j1: The top (inclusive) coordinate of the region to extract (in matrix convention). :param i2: The right (exclusive) coordinate of the region to extract (in matrix convention). :param j2: The bottom (exclusive) coordinate of the region to extract (in matrix convention). :return: The unpacked subarray corresponding to the requested region. :rtype: numpy.ndarray .. py:method:: 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. :param packed_array: The packed array from which to extract the subarrays. :param 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). :return: A dictionary of unpacked subarrays corresponding to the requested regions. :rtype: dict[str, numpy.ndarray] .. py:method:: _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. :param a: The subarray to pad. :param i1: The top coordinate of the subarray in the original domain. :param j1: The left coordinate of the subarray in the original domain. :param neutral_values: The value used to pad. .. py:method:: pack_subarray(packed_array, new_subarray, i1, j1) Update the packed_array with a rectangular region of a regular new_array. :param packed_array: The packed array to update. :param new_subarray: The regular array containing the new data to insert. :param i1: The left indice of the region to update - packed_array[i1,j1] == new_subarray[0,0] - in matrix convention. :param j1: The top indice of the region to update - packed_array[i1,j1] == new_subarray[0,0] - in matrix convention. :return: The original packed array with the updated subarray. :rtype: numpy.ndarray .. py:method:: 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. :param packed_array: The packed array to update. :param 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). :param neutral_values: value to fill the empty tile with. :return: The original packed array with the updated subarrays. :rtype: numpy.ndarray .. py:method:: 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). :param i: The horizontal coordinate in the original domain. :param j: The vertical coordinate in the original domain. :return: A tuple (i_packed, j_packed) representing the coordinates in the packed array. :rtype: tuple[int, int] .. py:method:: 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. :param 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. :return: 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. :rtype: tuple[np.ndarray]