nz::nodes::calc::Img2ColNode Class Reference

Implements im2col transformation for efficient convolution operations in neural networks. More...

Inheritance diagram for nz::nodes::calc::Img2ColNode:

Collaboration diagram for nz::nodes::calc::Img2ColNode:

Public Member Functions
	Img2ColNode (Node *input, Tensor::size_type kernelHeight, Tensor::size_type kernelWidth, Tensor::size_type stride, Tensor::size_type padding)
	Constructor for the Img2ColNode class.
void	forward () override
	Performs the forward propagation for the Img2ColNode.
void	backward () override
	Performs the backward propagation for the Img2ColNode.
Public Member Functions inherited from nz::nodes::Node
virtual void	print (std::ostream &os) const
	Prints the type, data, and gradient of the node.
void	dataInject (Tensor::value_type *data, bool grad=false) const
	Injects data into a relevant tensor object, optionally setting its gradient requirement.
template<typename Iterator >
void	dataInject (Iterator begin, Iterator end, const bool grad=false) const
	Injects data from an iterator range into the output tensor of the InputNode, optionally setting its gradient requirement.
void	dataInject (const std::initializer_list< Tensor::value_type > &data, bool grad=false) const
	Injects data from a std::initializer_list into the output tensor of the Node, optionally setting its gradient requirement.

Detailed Description

Implements im2col transformation for efficient convolution operations in neural networks.

This node converts (N, C, H, W) input tensors into expanded column matrices (N, 1, Hout*Wout, C*K_h*K_w) following the im2col algorithm, enabling efficient convolution computation through matrix multiplication.

Core functionality and characteristics:

• Convolution Optimization: Unfilters image patches into column matrices for accelerated convolution computation.
• Parameterized Transformation: Supports configurable kernel dimensions, stride, and padding.
• Memory Layout Conversion: Reorganizes spatial data into channel-patch columns.
• Gradient Propagation: Implements inverse col2im operation during backward pass for gradient computation.
• CUDA Acceleration: Optimized GPU implementation for both forward and backward operations.
• Automatic Shape Calculation: Computes output spatial dimensions based on input parameters.

Key implementation aspects:

• Forward Pass: Applies im2col algorithm with zero-padding and window sliding based on parameters.
• Backward Pass: Accumulates gradients using col2im inverse transformation with proper kernel alignment.
• Memory Access Patterns: Optimizes for contiguous memory access in transformed column matrices.
• Parameter Validation: Verifies kernel dimensions don't exceed padded input size.

Typical use cases:

• Accelerating convolutional layer computations through matrix multiplication.
• Implementing custom filter operations requiring explicit patch extraction.
• Converting spatial correlations into channel-wise operations.
• Data augmentation through explicit patch sampling.

Critical considerations:

• Memory Overhead: Generates O(K_h*K_w*C*Hout*Wout) intermediate storage - may require substantial memory.
• Parameter Compatibility: Requires (H + 2*padding - K_h) divisible by stride (similar for width).
• Input Constraints: Strict 4D input tensor requirement (NCHW format).
• Device Consistency: Maintains original tensor device context (CPU/GPU).

Warning

• Excessive kernel sizes or small strides may create prohibitively large intermediate matrices.
• Improper padding/stride combinations may cause dimension calculation errors.

Note

• Output dimensions follow: Hout = (H + 2*padding - K_h)/stride + 1
• The inverse col2im operation in backward pass sums gradients across overlapping patches.
• For dilated convolutions, consider extending kernel parameters with dilation factors.

See also

ConvolutionNode For typical subsequent operation after im2col transformation

Tensor::im2col() Underlying tensor transformation implementation

Usage Example:

// Create input node with batch of 32 RGB images (256x256)
InputNode input({32, 3, 256, 256}, true);
 
// Configure im2col with 7x7 kernel, stride 2, padding 3
Img2ColNode im2col(&input, 7, 7, 2, 3);
im2col.forward();
 
// Resulting shape: (32, 1, 128*128, 3*7*7)
std::cout << "Transformed shape: " << im2col.output->shape() << std::endl;
 
// Backward pass through col2im
im2col.backward();

Author

Mgepahmge (https://github.com/Mgepahmge)

Date

2023/10/17

Definition at line 3729 of file Nodes.cuh.

Constructor & Destructor Documentation

Img2ColNode()

nz::nodes::calc::Img2ColNode::Img2ColNode	(	Node *	input,
		Tensor::size_type	kernelHeight,
		Tensor::size_type	kernelWidth,
		Tensor::size_type	stride,
		Tensor::size_type	padding )

Constructor for the Img2ColNode class.

Parameters

input	A pointer to the input Node. Memory location: host. This is a pointer to an existing Node object, and the constructor only stores the pointer, not making a copy of the object.
kernelHeight	The height of the kernel. Memory location: host. It is a value passed by value, and the constructor stores its copy.
kernelWidth	The width of the kernel. Memory location: host. It is a value passed by value, and the constructor stores its copy.
stride	The stride value for the convolution operation. Memory location: host. It is a value passed by value, and the constructor stores its copy.
padding	The padding value for the convolution operation. Memory location: host. It is a value passed by value, and the constructor stores its copy.

Returns

None

This constructor initializes an Img2ColNode object. It stores the input node pointer, sets the kernel height, width, stride, and padding values. It also calculates the output height and width based on the input tensor's shape, kernel size, stride, and padding. Then, it creates a new Tensor object for the output with the appropriate shape and gradient requirement. Finally, it sets the node type to "Img2Col".

Memory management strategy: The constructor creates a new Tensor object using std::make_shared, which manages the memory automatically. The input node pointer is just stored, and no new memory is allocated for it. Exception handling mechanism: There is no explicit exception handling in this constructor. However, if the std::make_shared call fails to allocate memory for the output Tensor, a std::bad_alloc exception will be thrown.

Exceptions

std::bad_alloc

If memory allocation for the output Tensor fails.

Note

• Ensure that the input node pointer is valid and points to a properly initialized Node object.
• The calculation of output height and width assumes valid values for kernel size, stride, and padding. Incorrect values may lead to unexpected results.
• The time complexity of the constructor is O(1) as all operations are constant time operations.

```cpp
Node* inputNode = new Node();
Img2ColNode img2ColNode(inputNode, 3, 3, 1, 1);
```

Author

Mgepahmge(https://github.com/Mgepahmge)

Date

2024/07/15

Definition at line 605 of file Nodes.cu.

Member Function Documentation

backward()

void nz::nodes::calc::Img2ColNode::backward ( )

overridevirtual

Performs the backward propagation for the Img2ColNode.

Parameters

None

Returns

None

This function conducts the backward propagation of the Img2ColNode. It first checks if the output of the input node requires gradient computation. If so, it calls the iImg2colBackward function, passing in relevant parameters including the gradient of the input node's output, the gradient of the current node's output, output height, output width, the number of input channels, kernel height, kernel width, stride, padding, input height, input width, and batch size. The iImg2colBackward function is responsible for calculating the gradients with respect to the input.

Memory management strategy: The function does not allocate or free any memory directly. It relies on the pre - allocated memory for the gradients of the input and output tensors. The iImg2colBackward function is assumed to write the calculated gradients into the pre - allocated gradient tensors. Exception handling mechanism: There is no explicit exception handling in this function. However, if the iImg2colBackward function encounters problems such as invalid pointers or incorrect input parameters, it may throw an exception.

Note

• Ensure that the gradient tensors of the input and output are properly initialized and have sufficient memory allocated before calling this function.
• The performance of this function depends on the implementation of the iImg2colBackward function. Generally, the time complexity of the iImg2colBackward operation is O(n), where n is the number of elements in the input gradient tensor.

```cpp
Img2ColNode img2ColNode; // Assume img2ColNode is properly initialized
img2ColNode.backward();
```

Author

Mgepahmge(https://github.com/Mgepahmge)

Date

2024/07/15

Implements nz::nodes::Node.

Definition at line 632 of file Nodes.cu.

forward()

void nz::nodes::calc::Img2ColNode::forward ( )

overridevirtual

Performs the forward propagation for the Img2ColNode.

Parameters

None

Returns

None

This function executes the forward propagation of the Img2ColNode. It calls the iImg2col function, passing in the necessary parameters such as the output data pointer, input data pointer, output height, output width, number of input channels, kernel height, kernel width, stride, padding, input height, input width, and batch size. The iImg2col function is responsible for converting the image data into a column - major format, which is useful for performing convolution operations more efficiently.

Memory management strategy: The function does not allocate or free any memory directly. It relies on the memory already allocated for the input and output tensors. The iImg2col function is assumed to write the results directly into the pre - allocated output tensor. Exception handling mechanism: There is no explicit exception handling in this function. However, if the iImg2col function encounters issues such as invalid pointers or incorrect input parameters, it may throw an exception.

Note

• Ensure that the input and output tensors are properly initialized and have sufficient memory allocated before calling this function.
• The performance of this function depends on the implementation of the iImg2col function. In general, the time complexity of the iImg2col operation is O(n), where n is the number of elements in the output tensor.

```cpp
Img2ColNode img2ColNode; // Assume img2ColNode is properly initialized
img2ColNode.forward();
```

Author

Mgepahmge(https://github.com/Mgepahmge)

Date

2024/07/15

Implements nz::nodes::Node.

Definition at line 624 of file Nodes.cu.

---

The documentation for this class was generated from the following files:

• D:/Users/Mgepahmge/Documents/C Program/NeuZephyr/include/NeuZephyr/Nodes.cuh
• D:/Users/Mgepahmge/Documents/C Program/NeuZephyr/src/Nodes.cu