Fold#

classtorch.nn.modules.fold.Fold(output_size,kernel_size,dilation=1,padding=0,stride=1)[source]#

Combines an array of sliding local blocks into a large containing tensor.

Consider a batchedinput tensor containing sliding local blocks,e.g., patches of images, of shape$(N,C\times \prod (\text{kernel\_size}),L)$(N,C×∏(kernel_size),L),where$N$N is batch dimension,$C\times \prod (\text{kernel\_size})$C×∏(kernel_size)is the number of values within a block (a block has$\prod (\text{kernel\_size})$∏(kernel_size)spatial locations each containing a$C$C-channeled vector), and$L$L is the total number of blocks. (This is exactly thesame specification as the output shape ofUnfold.) Thisoperation combines these local blocks into the largeoutput tensorof shape$(N,C,\text{output\_size}[0],\text{output\_size}[1],\dots )$(N,C,output_size[0],output_size[1],…)by summing the overlapping values. Similar toUnfold, thearguments must satisfy

$$L=\prod _d\lfloor \frac{\text{output\_size}[d]+2\times \text{padding}[d]-\text{dilation}[d]\times (\text{kernel\_size}[d]-1)-1}{\text{stride}[d]}+1\rfloor ,$$L=d∏​⌊stride[d]output_size[d]+2×padding[d]−dilation[d]×(kernel_size[d]−1)−1​+1⌋,

where$d$d is over all spatial dimensions.

• output_size describes the spatial shape of the large containingtensor of the sliding local blocks. It is useful to resolve the ambiguitywhen multiple input shapes map to same number of sliding blocks, e.g.,withstride>0.

Thepadding,stride anddilation arguments specifyhow the sliding blocks are retrieved.

• stride controls the stride for the sliding blocks.

• padding controls the amount of implicit zero-paddings on bothsides forpadding number of points for each dimension beforereshaping.

• dilation controls the spacing between the kernel points; also known as the à trous algorithm.It is harder to describe, but thislink has a nice visualization of whatdilation does.

Parameters

• output_size (int ortuple) – the shape of the spatial dimensions of theoutput (i.e.,output.sizes()[2:])

• kernel_size (int ortuple) – the size of the sliding blocks

• dilation (int ortuple,optional) – a parameter that controls thestride of elements within theneighborhood. Default: 1

• padding (int ortuple,optional) – implicit zero padding to be added onboth sides of input. Default: 0

• stride (int ortuple) – the stride of the sliding blocks in the inputspatial dimensions. Default: 1

• Ifoutput_size,kernel_size,dilation,padding orstride is an int or a tuple of length 1 thentheir values will be replicated across all spatial dimensions.

• For the case of two output spatial dimensions this operation is sometimescalledcol2im.

Note

Fold calculates each combined value in the resultinglarge tensor by summing all values from all containing blocks.Unfold extracts the values in the local blocks bycopying from the large tensor. So, if the blocks overlap, they are notinverses of each other.

In general, folding and unfolding operations are related asfollows. ConsiderFold andUnfold instances created with the sameparameters:

>>>fold_params=dict(kernel_size=...,dilation=...,padding=...,stride=...)>>>fold=nn.Fold(output_size=...,**fold_params)>>>unfold=nn.Unfold(**fold_params)

Then for any (supported)input tensor the followingequality holds:

fold(unfold(input))==divisor*input

wheredivisor is a tensor that depends only on the shapeand dtype of theinput:

>>>input_ones=torch.ones(input.shape,dtype=input.dtype)>>>divisor=fold(unfold(input_ones))

When thedivisor tensor contains no zero elements, thenfold andunfold operations are inverses of eachother (up to constant divisor).

Warning

Currently, only unbatched (3D) or batched (4D) image-like output tensors are supported.

Shape:

• Input:$(N,C\times \prod (\text{kernel\_size}),L)$(N,C×∏(kernel_size),L) or$(C\times \prod (\text{kernel\_size}),L)$(C×∏(kernel_size),L)

• Output:$(N,C,\text{output\_size}[0],\text{output\_size}[1],\dots )$(N,C,output_size[0],output_size[1],…)or$(C,\text{output\_size}[0],\text{output\_size}[1],\dots )$(C,output_size[0],output_size[1],…) as described above

Examples:

>>>fold=nn.Fold(output_size=(4,5),kernel_size=(2,2))>>>input=torch.randn(1,3*2*2,12)>>>output=fold(input)>>>output.size()torch.Size([1, 3, 4, 5])

extra_repr()[source]#

Return the extra representation of the module.

Return type

str

forward(input)[source]#

Runs the forward pass.

Return type

Tensor