src.utils.ptransf.receptive_field_hierarchical_sg

Classes

ReceptiveFieldHierarchicalSG(**kwargs)

class src.utils.ptransf.receptive_field_hierarchical_sg.ReceptiveFieldHierarchicalSG(**kwargs)

Author:

Alberto M. Esmoris Pena

Class representing a hierarchical receptive field based on sparse grids.

A hierarchical receptive field is a special type of receptive field because it is composed of many receptive fields organized in a hierarchical manner.

See ReceptiveField and HierarchicalSGPreProcessorPP.

Variables:

• size (float) – The size of the cell. Note that 3D cells are voxels with the same length for each edge.

• w (np.ndarray of int) – The size of the submanifold convolutional window. It is given as a half size in terms of number of cells. For example, \(w_t\) means that the submanifold convolutional window at depth \(t\) will consider the active cell in the center, \(w_t\) cells backward, and \(w_t\) cells forward. If the dimensionality of the space is \(n_x\), the number of cells in a submanifold convolutional window will be given by \((2w_t + 1)^{n_x}\). Note that any submanifold convolution has a stride or step size of one.

• wD (np.ndarray of int) – The size of the downsampling convolutional window. It is given as a size in terms of number of cells. For example, \(w^D_t\) means that the downsampling convolutional window at depth \(t\) will consist of \((w^D_t)^{n_x}\) cells for a \(n_x\)-dimensional space.

• sD (np.ndarray of int) – The step size or stride for the downsampling convolutional window. The downsampling window will move \(s^D_t\) cells along the \(t\) sparse grid to generate the cells of the \(t+1\)-th sparse grid in the hierarchy.

• wU (np.ndarray of int) – The size of the upsampling convolutional window. It is given as a size in terms of number of cells. For example, math:w^U_t means that the upsampling convolutional window at depth \(t\) will consist of \((w^U_t)^{n_x}\) for a \(n_x\)-dimensional space.

• sU (np.ndarray of int) – The step size or stride for the upsampling convolutional window. The upsampling window will move \(s^U_t\) cells along the \(t+1\) sparse grid to generate the cells of the \(t\)-th sparse grid in the hierarchy.

• h (list of tuple of np.ndarray) – A list of 2-tuples, each tuple represents the \(h_t\) map at depth \(t\) by storing the vector of keys (first element of the tuple) and the vector of values (second element of the tuple). The \(h_t(i)\) value can be understood as the sequential index representing the active cell that corresponds to the cell index \(i\) in the sparse grid at depth \(t\).

• hD ((list or np.ndarray) of int) – The downsampling indexing. The \(h^D_{ti}\) value can be understood as the index of the min vertex (e.g., the lower-left-backward for a 3D grid) for the convolutional window in the sparse grid at depth \(t\) that generates the value for the \(i\)-th active cell in the sparse grid at depth \(t+1\).

• hU ((list or np.ndarray) of int) – The upsampling indexing. The \(h^U_{ti}\) value can be understood as the index of the min vertex (e.g., the lower-left-backward for a 3D grid) for the convolutional window in the sparse grid at depth \(t+1\) that generates the value for the \(i\)-th active cell in the sparse grid at depth \(t\).

• n (np.ndarray of int) – The axis-wise number of partitions for each sparse grid of the hierarchy.

• A (np.ndarray) – The min point of the sparse grid at the first level of the hierarchy.

• S (list of np.ndarray of int, or None) – The dense submanifold neighbor tables. S[t] has shape \((R_t + 1) \times (2 w_t + 1)^3\) and gives, for each active cell at depth \(t\), the one-based sequential indices of the cells in its submanifold convolutional window (row 0 is the ground row, all zeros). None when the pre-processor was not asked to compute neighbor tables.

• D (list of np.ndarray of int, or None) – The dense downsampling neighbor tables. D[t] has shape \((R_{t+1} + 1) \times (w^D_t)^3\) and is defined for \(t \in [0, t^* - 1)\). None when not requested.

• U (list of np.ndarray of int, or None) – The dense upsampling neighbor tables. U[t] has shape \((R_t + 1) \times (w^U_t)^3\) and is defined for \(t \in [0, t^* - 1)\). None when not requested.

__init__(**kwargs)

Initialize/instantiate a hierarchical SG receptive field object.

Parameters:

kwargs – The key-word specification to instantiate the ReceptiveFieldHierarchicalSG.

Keyword Arguments:

• size (float) – The size of the cell (note that 3D cells are voxels with the same length for each edge.)

• w (list of int) – The size of the submanifold convolutional window. Note that this size is interpreted differently from the others. It applies twice, one for each direction along each axis.

• wD (list of int) – The size of the downsampling convolutional window.

• sD (list of int) – The step size or stride for the downsampling convolutions.

• wU (list of int) – The size of the upsampling convolutional window.

• sU (list of int) – The step size or stride for the upsampling convolutions.

fit(X, x=None, structure_float_type=<class 'numpy.float64'>, id=None)

Fit the receptive field to represent the given points by constructing a hierarchy of sparse grids such that the first one has as active cells those in which there is at least one point from the input structure space.

Parameters:

• X – The input structure space matrix of \(m\) points in a \(n_x\)-dimensional space (for now, typically \(n_x=3\)).

• x – The center point used to define the origin of the receptive field. Note that this parameter is ignored by the hierarchical sparse grid because it does not explicitly generate structure spaces nor centers the sparse grids in the hierarchy.

• x – Not used by

• structure_float_type – The decimal type for the structure space. Note that this parameter is ignored by the hierarchical sparse grid because it does not explicitly generate structure spaces.

• id – See ReceptiveField.fit().

Returns:

The fitted receptive field itself (for fluent programming).

Return type:

ReceptiveFieldHierarchicalSG

get_submanifold_maps()

Obtain the submanifold maps from the cell index (key, domain) to its corresponding sequential active cell index (value, codomain).

Returns:

The submanifold maps.

Return type:

list of tf.lookup.StaticHashTable

get_downsampling_vectors()

Obtain the downsampling vector for each depth connecting the min vertex of the convolutional window with its corresponding cell in the downsampled sparse grid.

Returns:

The downsampling vectors.

Return type:

list of np.ndarray of int

get_upsampling_vectors()

Obtain the upsampling vector for each depth connecting the min vertex of the convolutional window with its corresponding cell in the upsampled sparse grid.

Returns:

The upsampling vectors.

Return type:

list of np.ndarray of int

get_num_partitions()

Obtain the number of axis-wise partitions for each sparse grid in the hierarchy.

Returns:

The number of axis-wise partitions for each sparse grid in the hierarchy.

Return type:

np.ndarray of int

get_min_point()

Obtain the min point/vertex of the first sparse grid in the hierarchy.

Returns:

The min vertex of the first sparse grid.

Return type:

np.ndarray

get_max_depth()

Obtain the max depth of the hierarchy.

Returns:

The max depth of the hierarchy.

Return type:

int

get_submanifold_windows()

Obtain the submanifold convolutional window.

Returns:

The submanifold convolutional window.

Return type:

int

get_downsampling_windows()

Obtain the downsampling convolutional window.

Returns:

The downsampling convolutional window.

Return type:

int

get_upsampling_windows()

Obtain the upsampling convolutional window.

Returns:

The upsampling convolutional window.

Return type:

int

get_submanifold_neighbor_tables()

Obtain the dense submanifold neighbor tables (per depth).

Each table \(\pmb{S}_t\) has shape \((R_t + 1) \times (2 w_t + 1)^3\) where \(R_t\) is the number of active cells at depth \(t\). Row 0 is reserved as the ground row (all zeros); row \(v \in [1, R_t]\) contains the one-based sequential indices of each cell in the submanifold convolutional window centered on the \(v\)-th active cell, in z-inner / y-middle / x-outer ordering.

Returns:

List of length max_depth, one table per depth.

Return type:

list of np.ndarray of int, or None if the pre-processor did not opt in to neighbor table generation.

get_downsampling_neighbor_tables()

Obtain the dense downsampling neighbor tables (per depth).

Each table \(\pmb{D}_t\) has shape \((R_{t+1} + 1) \times (w^D_t)^3\) and contains the one-based sequential indices in depth \(t\) of the cells in the downsampling window whose min vertex is the corresponding active cell at depth \(t + 1\). Defined for \(t \in [0, t^* - 1)\).

Returns:

List of length max_depth - 1, one table per depth.

Return type:

list of np.ndarray of int, or None if the pre-processor did not opt in to neighbor table generation.

get_upsampling_neighbor_tables()

Obtain the dense upsampling neighbor tables (per depth).

Each table \(\pmb{U}_t\) has shape \((R_t + 1) \times (w^U_t)^3\) and contains the one-based sequential indices in depth \(t + 1\) of the cells in the upsampling window whose min vertex is the corresponding active cell at depth \(t\). Defined for \(t \in [0, t^* - 1)\).

Returns:

List of length max_depth - 1, one table per depth.

Return type:

list of np.ndarray of int, or None if the pre-processor did not opt in to neighbor table generation.

compute_active_centroids(t)

Compute the centroid for each active cell of the sparse grid at depth \(t \in \mathbb{Z}_{\geq 0}\) the hierarchy.

This method assumes a 3D structure space so each centroid can be computed from the index of the active cell \(k\) such that:

\[\begin{split}\left\{\begin{array}{ll} x(k) =& \left[(k \mod n_z) + \dfrac{1}{2}\right] s + A_x \\ y(k) =& \left[ \left(\left\lfloor\dfrac{k}{n_z}\right\rfloor \mod n_y\right) + \dfrac{1}{2} \right] s + A_y \\ z(k) =& \left[ \left\lfloor\dfrac{k}{n_y n_z}\right\rfloor + \dfrac{1}{2} \right] s + A_z \end{array}\right.\end{split}\]

Where \(n_x, n_y, n_z\) represent the number of partitions along the \(x, y, z\) axis for the sparse grid at depth \(t\) and \(A = (A_x, A_y, A_z)\) represent the min vertex of the first sparse grid in the hierarchy.

NOTE that the centroids of sparse grids after the first depth will not respect the original scale.

Returns:

Each cell represented as a centroid.

Return type:

np.ndarray

get_submanifold_map_as_dict(t, without_ground=False)

Obtain the submanifold map \(h_t\) at depth \(t\) as a python dictionary.

Parameters:

• t (int) – The depth of the submanifold map that must be obtained.

• without_ground (bool) – Whether the values (sequential indices of active cells) must be corrected to avoid accounting for the ground value (True) or not (False). The ground value is a convenience so the HSG receptive field can be used inside a neural network. It assumes the feature space matrix is expanded with a new row at the beginning that contains the ground value (0). However, the original submanifold map is not aware of this. If without_ground is True then this method will revert the returned submanifold map (as dictionary) so it does not consider the ground value.

Returns:

The submanifold map at depth \(t\) as a dictionary.

Return type:

dict