Skip to content

geometric_expansion

Bases: transformation

The geometric patch based expansion function.

It performs the data expansion based on geometric patch shapes, where each attribute (or the attributes selected ones by the packing strategy) is expanded into a patch. This class inherits from the base data transformation class, and also implements the abstract methods in that class.

...

Notes

Formally, given a data instance \(\mathbf{x}\) and its underlying grid structure, we can extract a set of patches denoted as \(\mathcal{P} = \{{p}_1, {p}_2, \cdots {p}_{|\mathcal{P}|}\}\). For simplicity, we use the notation \(\mathbf{p}_i = \mathbf{x}(p_i) \in {R}^p\) to represent the attribute elements covered by patch \({p}_i \in \mathcal{P}\) from the input data instance vector \(\mathbf{x}\).

The geometric expansion function proposes to expand the input data instance with these patches as follows:

\[
    \begin{equation}
    \kappa(\mathbf{x}) = \left[ \mathbf{p}_1, \mathbf{p}_2, \cdots, \mathbf{p}_{|\mathcal{P}|} \right] \in {R}^{d},
    \end{equation}
\]

where the expansion output vector dimension is \(d = |\mathcal{P}| \times p\).

The patches in set \(\mathcal{P}\) can have different shapes, such as cuboid, cylinder and sphere. The size of the patch set \(\mathcal{P}\) is determined by both the input grid shape, the patch shape and the packing strategies.

Attributes:

Name Type Description
name str, default = 'geometric_expansion'

Name of the expansion function.
grid grid, default = None

The input data instance underlying grid structure.
grid_configs dict, default = None

The grid detailed configurations.
h int, default = None

The height of the grid structure.
w int, default = None

The width of the grid structure.
d int, default = None

The depth of the grid structure.
patch Union[cuboid, cylinder, sphere], default = None

The patch shape of the data segments to be compressed.
patch_configs dict, default = None

The patch detailed configurations.
packing_strategy str, default = None

The packing strategy to be used.
cd_h int, default = None

The patch center distance along the height dimension.
cd_w int, default = None

The patch center distance along the width dimension.
cd_d int, default = None

The patch center distance along the depth dimension.

Methods:

Name Description
__init__

It performs the initialization of the expansion function.
get_grid_shape

It returns the shape of the grid structure.
get_grid_size

It returns the size of the grid structure.
get_patch_size

It returns the size of the patch structure.
get_patch_num

It returns the number of patches in the input data vector.
get_grid_shape_after_packing

It returns the shape of the grid structure after packing, i.e., the patch center coordinates.
calculate_D

It calculates the expansion space dimension d based on the input dimension parameter m.
forward

It implements the abstract forward method declared in the base transformation class.
Source code in tinybig/expansion/geometric_expansion.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
class geometric_expansion(transformation):
    r"""
        The geometric patch based expansion function.

        It performs the data expansion based on geometric patch shapes, where each attribute (or the attributes selected ones by the packing strategy) is expanded into a patch.
        This class inherits from the base data transformation class, and also implements the abstract methods in that class.

        ...

        Notes
        ----------
        Formally, given a data instance $\mathbf{x}$ and its underlying grid structure, we can extract a set of patches denoted as $\mathcal{P} = \{{p}_1, {p}_2, \cdots {p}_{|\mathcal{P}|}\}$.
        For simplicity, we use the notation $\mathbf{p}_i = \mathbf{x}(p_i) \in {R}^p$ to represent the attribute elements covered by patch ${p}_i \in \mathcal{P}$ from the input data instance vector $\mathbf{x}$.

        The geometric expansion function proposes to expand the input data instance with these patches as follows:

        $$
            \begin{equation}
            \kappa(\mathbf{x}) = \left[ \mathbf{p}_1, \mathbf{p}_2, \cdots, \mathbf{p}_{|\mathcal{P}|} \right] \in {R}^{d},
            \end{equation}
        $$

        where the expansion output vector dimension is $d = |\mathcal{P}| \times p$.

        The patches in set $\mathcal{P}$ can have different shapes, such as cuboid, cylinder and sphere.
        The size of the patch set $\mathcal{P}$ is determined by both the input grid shape, the patch shape and the packing strategies.

        Attributes
        ----------
        name: str, default = 'geometric_expansion'
            Name of the expansion function.
        grid: grid, default = None
            The input data instance underlying grid structure.
        grid_configs: dict, default = None
            The grid detailed configurations.
        h: int, default = None
            The height of the grid structure.
        w: int, default = None
            The width of the grid structure.
        d: int, default = None
            The depth of the grid structure.
        patch: Union[cuboid, cylinder, sphere], default = None
            The patch shape of the data segments to be compressed.
        patch_configs: dict, default = None
            The patch detailed configurations.
        packing_strategy: str, default = None
            The packing strategy to be used.
        cd_h: int, default = None
            The patch center distance along the height dimension.
        cd_w: int, default = None
            The patch center distance along the width dimension.
        cd_d: int, default = None
            The patch center distance along the depth dimension.

        Methods
        ----------
        __init__
            It performs the initialization of the expansion function.

        get_grid_shape
            It returns the shape of the grid structure.

        get_grid_size
            It returns the size of the grid structure.

        get_patch_size
            It returns the size of the patch structure.

        get_patch_num
            It returns the number of patches in the input data vector.

        get_grid_shape_after_packing
            It returns the shape of the grid structure after packing, i.e., the patch center coordinates.

        calculate_D
            It calculates the expansion space dimension d based on the input dimension parameter m.

        forward
            It implements the abstract forward method declared in the base transformation class.

    """

    def __init__(
        self,
        name: str = 'geometric_expansion',
        grid: grid_structure = None,
        grid_configs: dict = None,
        h: int = None, w: int = None, d: int = None,
        patch: Union[cuboid, cylinder, sphere] = None,
        patch_configs: dict = None,
        packing_strategy: str = None,
        cd_h: int = None, cd_w: int = None, cd_d: int = None,
        *args, **kwargs
    ):
        """
            The initialization method of the geometric expansion function.

            It initializes the geometric expansion function based on
            the provided geometric grid (or its configuration or its size)
            and the patch shape (or the patch configuration) of the data segments to be compressed,
            and the packing strategy (or the patch center distances).

            Parameters
            ----------
            name: str, default = 'geometric_expansion'
                Name of the expansion function.
            grid: grid, default = None
                The input data instance underlying grid structure.
            grid_configs: dict, default = None
                The grid detailed configurations.
            h: int, default = None
                The height of the grid structure.
            w: int, default = None
                The width of the grid structure.
            d: int, default = None
                The depth of the grid structure.
            patch: Union[cuboid, cylinder, sphere], default = None
                The patch shape of the data segments to be compressed.
            patch_configs: dict, default = None
                The patch detailed configurations.
            packing_strategy: str, default = None
                The packing strategy to be used.
            cd_h: int, default = None
                The patch center distance along the height dimension.
            cd_w: int, default = None
                The patch center distance along the width dimension.
            cd_d: int, default = None
                The patch center distance along the depth dimension.

            Returns
            ----------
            transformation
                The geometric expansion function.
        """
        super().__init__(name=name, *args, **kwargs)

        self.interdependence = geometric_interdependence(
            b=0, m=0, interdependence_type='attribute', interdependence_matrix_mode='padding',
            grid=grid, grid_configs=grid_configs, h=h, w=w, d=d,
            patch=patch, patch_configs=patch_configs,
            packing_strategy=packing_strategy, cd_h=cd_h, cd_w=cd_w, cd_d=cd_d,
            normalization=False, require_data=False, require_parameters=False,
        )

    def get_grid_shape(self):
        """
            The grid shape retrieval function.

            It returns the shape of the grid structure.

            Returns
            -------
            tuple | list
                The shape of the grid structure.
        """
        return self.interdependence.get_grid_shape()

    def get_grid_size(self, across_universe: bool = False):
        """
            The grid shape retrieval function.

            It returns the size of the grid structure.

            Parameters
            ----------
            across_universe: bool, default = False
                The boolean tag indicating the grid size across universe or not.

            Returns
            -------
            int
                The size of the grid structure.
        """
        return self.interdependence.get_grid_size(across_universe=across_universe)

    def get_patch_size(self):
        """
            The patch shape retrieval function.

            It returns the size of the patch structure.

            Returns
            -------
            int
                The size of the patch structure.
        """
        return self.interdependence.get_patch_size()

    def get_patch_num(self, across_universe: bool = False):
        """
            The patch shape number function.

            It returns the number of patches existing in the input data vector.

            Parameters
            ----------
            across_universe: bool, default = False
                The boolean tag indicating the patch size across universe or not.

            Returns
            -------
            int
                The number of patches existing in the input data vector.
        """
        return self.interdependence.get_patch_num(across_universe=across_universe)

    def get_grid_shape_after_packing(self):
        """
            The shape of the grid structure after packing.

            It returns the shape of the grid structure after packing.

            Returns
            -------
            tuple | list
                The shape of the grid structure after packing.
        """
        return self.interdependence.get_grid_shape_after_packing()

    def calculate_D(self, m: int):
        r"""
            The expansion dimension calculation method.

            It calculates the intermediate expansion space dimension based on the input dimension parameter m.
            For the geometric expansion function, the expansion space dimension is determined by
            the grid shape, patch shape and packing strategy.

            The expansion output vector dimension is $d = |\mathcal{P}| \times p$,
            where $\mathcal{P}$ is the patch set in the input and $p$ is the patch size.

            Parameters
            ----------
            m: int
                The dimension of the input space.

            Returns
            -------
            int
                The dimension of the expansion space.
        """
        assert m == self.get_grid_size(across_universe=True)
        return self.interdependence.get_patch_num(across_universe=True) * self.get_patch_size()

    def forward(self, x: torch.Tensor, device: str = 'cpu', *args, **kwargs) -> torch.Tensor:
        r"""
            The forward method of the geometric expansion function.

            It performs the geometric data expansion of the input data and returns the expansion result.

            Formally, given a data instance $\mathbf{x}$ and its underlying grid structure, we can extract a set of patches denoted as $\mathcal{P} = \{{p}_1, {p}_2, \cdots {p}_{|\mathcal{P}|}\}$.
            For simplicity, we use the notation $\mathbf{p}_i = \mathbf{x}(p_i) \in {R}^p$ to represent the attribute elements covered by patch ${p}_i \in \mathcal{P}$ from the input data instance vector $\mathbf{x}$.

            The geometric expansion function proposes to expand the input data instance with these patches as follows:

            $$
                \begin{equation}
                \kappa(\mathbf{x}) = \left[ \mathbf{p}_1, \mathbf{p}_2, \cdots, \mathbf{p}_{|\mathcal{P}|} \right] \in {R}^{d},
                \end{equation}
            $$

            where the expansion output vector dimension is $d = |\mathcal{P}| \times p$.

            Parameters
            ----------
            x: torch.Tensor
                The input data vector.
            device: str, default = 'cpu'
                The device of the input data vector.

            Returns
            -------
            torch.Tensor
                The expansion result.
        """
        b, m = x.shape
        x = self.pre_process(x=x, device=device)

        expansion = self.interdependence(x, device=device)
        expansion = expansion.view(b, self.get_patch_num(), -1)
        expansion = expansion.permute(0, 2, 1).reshape(b, -1)

        assert expansion.shape == (b, self.calculate_D(m=m))
        return self.post_process(x=expansion, device=device)

__init__(name='geometric_expansion', grid=None, grid_configs=None, h=None, w=None, d=None, patch=None, patch_configs=None, packing_strategy=None, cd_h=None, cd_w=None, cd_d=None, *args, **kwargs)

The initialization method of the geometric expansion function.

It initializes the geometric expansion function based on the provided geometric grid (or its configuration or its size) and the patch shape (or the patch configuration) of the data segments to be compressed, and the packing strategy (or the patch center distances).

Parameters:

Name Type Description Default
name str

Name of the expansion function.

 'geometric_expansion'
grid grid

The input data instance underlying grid structure.

 None
grid_configs dict

The grid detailed configurations.

 None
h int

The height of the grid structure.

 None
w int

The width of the grid structure.

 None
d int

The depth of the grid structure.

 None
patch Union[cuboid, cylinder, sphere]

The patch shape of the data segments to be compressed.

 None
patch_configs dict

The patch detailed configurations.

 None
packing_strategy str

The packing strategy to be used.

 None
cd_h int

The patch center distance along the height dimension.

 None
cd_w int

The patch center distance along the width dimension.

 None
cd_d int

The patch center distance along the depth dimension.

 None

Returns:

Type Description
transformation

The geometric expansion function.
Source code in tinybig/expansion/geometric_expansion.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def __init__(
    self,
    name: str = 'geometric_expansion',
    grid: grid_structure = None,
    grid_configs: dict = None,
    h: int = None, w: int = None, d: int = None,
    patch: Union[cuboid, cylinder, sphere] = None,
    patch_configs: dict = None,
    packing_strategy: str = None,
    cd_h: int = None, cd_w: int = None, cd_d: int = None,
    *args, **kwargs
):
    """
        The initialization method of the geometric expansion function.

        It initializes the geometric expansion function based on
        the provided geometric grid (or its configuration or its size)
        and the patch shape (or the patch configuration) of the data segments to be compressed,
        and the packing strategy (or the patch center distances).

        Parameters
        ----------
        name: str, default = 'geometric_expansion'
            Name of the expansion function.
        grid: grid, default = None
            The input data instance underlying grid structure.
        grid_configs: dict, default = None
            The grid detailed configurations.
        h: int, default = None
            The height of the grid structure.
        w: int, default = None
            The width of the grid structure.
        d: int, default = None
            The depth of the grid structure.
        patch: Union[cuboid, cylinder, sphere], default = None
            The patch shape of the data segments to be compressed.
        patch_configs: dict, default = None
            The patch detailed configurations.
        packing_strategy: str, default = None
            The packing strategy to be used.
        cd_h: int, default = None
            The patch center distance along the height dimension.
        cd_w: int, default = None
            The patch center distance along the width dimension.
        cd_d: int, default = None
            The patch center distance along the depth dimension.

        Returns
        ----------
        transformation
            The geometric expansion function.
    """
    super().__init__(name=name, *args, **kwargs)

    self.interdependence = geometric_interdependence(
        b=0, m=0, interdependence_type='attribute', interdependence_matrix_mode='padding',
        grid=grid, grid_configs=grid_configs, h=h, w=w, d=d,
        patch=patch, patch_configs=patch_configs,
        packing_strategy=packing_strategy, cd_h=cd_h, cd_w=cd_w, cd_d=cd_d,
        normalization=False, require_data=False, require_parameters=False,
    )

calculate_D(m)

The expansion dimension calculation method.

It calculates the intermediate expansion space dimension based on the input dimension parameter m. For the geometric expansion function, the expansion space dimension is determined by the grid shape, patch shape and packing strategy.

The expansion output vector dimension is \(d = |\mathcal{P}| \times p\), where \(\mathcal{P}\) is the patch set in the input and \(p\) is the patch size.

Parameters:

Name Type Description Default
m int

The dimension of the input space.

 required

Returns:

Type Description
int

The dimension of the expansion space.
Source code in tinybig/expansion/geometric_expansion.py 
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
def calculate_D(self, m: int):
    r"""
        The expansion dimension calculation method.

        It calculates the intermediate expansion space dimension based on the input dimension parameter m.
        For the geometric expansion function, the expansion space dimension is determined by
        the grid shape, patch shape and packing strategy.

        The expansion output vector dimension is $d = |\mathcal{P}| \times p$,
        where $\mathcal{P}$ is the patch set in the input and $p$ is the patch size.

        Parameters
        ----------
        m: int
            The dimension of the input space.

        Returns
        -------
        int
            The dimension of the expansion space.
    """
    assert m == self.get_grid_size(across_universe=True)
    return self.interdependence.get_patch_num(across_universe=True) * self.get_patch_size()

forward(x, device='cpu', *args, **kwargs)

The forward method of the geometric expansion function.

It performs the geometric data expansion of the input data and returns the expansion result.

Formally, given a data instance \(\mathbf{x}\) and its underlying grid structure, we can extract a set of patches denoted as \(\mathcal{P} = \{{p}_1, {p}_2, \cdots {p}_{|\mathcal{P}|}\}\). For simplicity, we use the notation \(\mathbf{p}_i = \mathbf{x}(p_i) \in {R}^p\) to represent the attribute elements covered by patch \({p}_i \in \mathcal{P}\) from the input data instance vector \(\mathbf{x}\).

The geometric expansion function proposes to expand the input data instance with these patches as follows:

\[
    \begin{equation}
    \kappa(\mathbf{x}) = \left[ \mathbf{p}_1, \mathbf{p}_2, \cdots, \mathbf{p}_{|\mathcal{P}|} \right] \in {R}^{d},
    \end{equation}
\]

where the expansion output vector dimension is \(d = |\mathcal{P}| \times p\).

Parameters:

Name Type Description Default
x Tensor

The input data vector.

 required
device str

The device of the input data vector.

 'cpu'

Returns:

Type Description
Tensor

The expansion result.
Source code in tinybig/expansion/geometric_expansion.py 
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
def forward(self, x: torch.Tensor, device: str = 'cpu', *args, **kwargs) -> torch.Tensor:
    r"""
        The forward method of the geometric expansion function.

        It performs the geometric data expansion of the input data and returns the expansion result.

        Formally, given a data instance $\mathbf{x}$ and its underlying grid structure, we can extract a set of patches denoted as $\mathcal{P} = \{{p}_1, {p}_2, \cdots {p}_{|\mathcal{P}|}\}$.
        For simplicity, we use the notation $\mathbf{p}_i = \mathbf{x}(p_i) \in {R}^p$ to represent the attribute elements covered by patch ${p}_i \in \mathcal{P}$ from the input data instance vector $\mathbf{x}$.

        The geometric expansion function proposes to expand the input data instance with these patches as follows:

        $$
            \begin{equation}
            \kappa(\mathbf{x}) = \left[ \mathbf{p}_1, \mathbf{p}_2, \cdots, \mathbf{p}_{|\mathcal{P}|} \right] \in {R}^{d},
            \end{equation}
        $$

        where the expansion output vector dimension is $d = |\mathcal{P}| \times p$.

        Parameters
        ----------
        x: torch.Tensor
            The input data vector.
        device: str, default = 'cpu'
            The device of the input data vector.

        Returns
        -------
        torch.Tensor
            The expansion result.
    """
    b, m = x.shape
    x = self.pre_process(x=x, device=device)

    expansion = self.interdependence(x, device=device)
    expansion = expansion.view(b, self.get_patch_num(), -1)
    expansion = expansion.permute(0, 2, 1).reshape(b, -1)

    assert expansion.shape == (b, self.calculate_D(m=m))
    return self.post_process(x=expansion, device=device)

get_grid_shape()

The grid shape retrieval function.

It returns the shape of the grid structure.

Returns:

Type Description
tuple | list

The shape of the grid structure.
Source code in tinybig/expansion/geometric_expansion.py 
162
163
164
165
166
167
168
169
170
171
172
173
def get_grid_shape(self):
    """
        The grid shape retrieval function.

        It returns the shape of the grid structure.

        Returns
        -------
        tuple | list
            The shape of the grid structure.
    """
    return self.interdependence.get_grid_shape()

get_grid_shape_after_packing()

The shape of the grid structure after packing.

It returns the shape of the grid structure after packing.

Returns:

Type Description
tuple | list

The shape of the grid structure after packing.
Source code in tinybig/expansion/geometric_expansion.py 
224
225
226
227
228
229
230
231
232
233
234
235
def get_grid_shape_after_packing(self):
    """
        The shape of the grid structure after packing.

        It returns the shape of the grid structure after packing.

        Returns
        -------
        tuple | list
            The shape of the grid structure after packing.
    """
    return self.interdependence.get_grid_shape_after_packing()

get_grid_size(across_universe=False)

The grid shape retrieval function.

It returns the size of the grid structure.

Parameters:

Name Type Description Default
across_universe bool

The boolean tag indicating the grid size across universe or not.

 False

Returns:

Type Description
int

The size of the grid structure.
Source code in tinybig/expansion/geometric_expansion.py 
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
def get_grid_size(self, across_universe: bool = False):
    """
        The grid shape retrieval function.

        It returns the size of the grid structure.

        Parameters
        ----------
        across_universe: bool, default = False
            The boolean tag indicating the grid size across universe or not.

        Returns
        -------
        int
            The size of the grid structure.
    """
    return self.interdependence.get_grid_size(across_universe=across_universe)

get_patch_num(across_universe=False)

The patch shape number function.

It returns the number of patches existing in the input data vector.

Parameters:

Name Type Description Default
across_universe bool

The boolean tag indicating the patch size across universe or not.

 False

Returns:

Type Description
int

The number of patches existing in the input data vector.
Source code in tinybig/expansion/geometric_expansion.py 
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
def get_patch_num(self, across_universe: bool = False):
    """
        The patch shape number function.

        It returns the number of patches existing in the input data vector.

        Parameters
        ----------
        across_universe: bool, default = False
            The boolean tag indicating the patch size across universe or not.

        Returns
        -------
        int
            The number of patches existing in the input data vector.
    """
    return self.interdependence.get_patch_num(across_universe=across_universe)

get_patch_size()

The patch shape retrieval function.

It returns the size of the patch structure.

Returns:

Type Description
int

The size of the patch structure.
Source code in tinybig/expansion/geometric_expansion.py 
193
194
195
196
197
198
199
200
201
202
203
204
def get_patch_size(self):
    """
        The patch shape retrieval function.

        It returns the size of the patch structure.

        Returns
        -------
        int
            The size of the patch structure.
    """
    return self.interdependence.get_patch_size()