pulsatrix::Conv2DModule Class Reference

2D convolution, batched (input/output are rank-4: N x channels x H x W) – migrated from the original unbatched (rank-3) scope by campaign_exai_dl_library_batch_dimension_support. Stride 1, no padding, no dilation – deferred until a real use case needs them, same pattern as LinearModule's original unbatched scope cut. More...

#include <conv2d_module.hpp>

Inheritance diagram for pulsatrix::Conv2DModule:

Collaboration diagram for pulsatrix::Conv2DModule:

Public Member Functions
	Conv2DModule (int64_t in_channels, int64_t out_channels, int64_t kernel_h, int64_t kernel_w, DeviceBackend *backend, int64_t stride=1, int64_t padding=0)
	Constructs a conv layer with zero-initialized kernel/bias.
int64_t	stride () const
	Step between windows along both axes.
int64_t	padding () const
	Zero padding on every side, along both axes.
Tensor	backward (const Tensor &grad_output) override
	Computes gradients w.r.t. input, kernel, and bias.
OpType	op_type () const override
	Conv per charter's closed OpType set.
void	set_kernel (std::initializer_list< float > values)
	Overwrites the kernel buffer – test/initialization use only.
void	set_bias (std::initializer_list< float > values)
	Overwrites the bias buffer – test/initialization use only.
void	set_kernel (const std::vector< float > &values)
	Vector overload for runtime-sized sources – see Tensor's own vector ctor.
void	set_bias (const std::vector< float > &values)
	Vector overload for runtime-sized sources – see Tensor's own vector ctor.
const Tensor &	kernel () const
const Tensor &	bias () const
const Tensor &	kernel_grad () const
const Tensor &	bias_grad () const
Tensor	propagate_relevance (const Tensor &relevance_out, const LRPRuleConfig &config) override
	Epsilon-rule LRP relevance propagation.
bool	supports_lrp_rule (LRPRule) const override
	Implements every LRPRule.
std::vector< NamedParamRef >	named_parameters () override
	This module's trainable parameters, each with its hierarchical name – the one place a module declares its parameters (roadmap FND-1).
std::optional< DeviceType >	compute_device () const override
	Where this layer computes, so forward() rejects an input on another device (FND-8).
Public Member Functions inherited from pulsatrix::Module
virtual	~Module ()=default
Tensor	forward (const Tensor &input)
	Runs this module's forward computation.
std::pair< Tensor, NodeId >	forward_traced (const Tensor &input, NodeId input_node, ComputationGraph &graph, Autograd &autograd)
	Runs forward() while also registering a ComputationGraph node (tagged with this module's op_type(), parented to input_node) and wiring an Autograd backward function that reuses this module's own backward() – the opt-in traced/explainable path, per Phase 2 Mission 0.
virtual std::vector< ParamRef >	parameters ()
	This module's trainable parameters and their gradients, for an optimizer to update uniformly across module types.
void	set_requires_grad (bool requires_grad, const std::string &prefix="")
	Freezes (false) or unfreezes (true) parameters by name (roadmap FND-2).
virtual void	set_training (bool training)
	Sets this module's training/eval mode. Defaults to training (matches every mainstream framework's Module default).
bool	is_training () const
	Whether this module is currently in training mode.

Protected Member Functions
Tensor	forward_impl (const Tensor &input) override
	The actual forward computation (im2col + gemm + per-channel bias add).

Detailed Description

2D convolution, batched (input/output are rank-4: N x channels x H x W) – migrated from the original unbatched (rank-3) scope by campaign_exai_dl_library_batch_dimension_support. Stride 1, no padding, no dilation – deferred until a real use case needs them, same pattern as LinearModule's original unbatched scope cut.

Note

Implemented via im2col + gemm per campaign Decision 3 (see campaign_exai_dl_library_phase1_core_layers_training.md) rather than a dedicated DeviceBackend::conv2d primitive – Phase 1.5's cuDNN integration will need its own conv path anyway, so a CPU-side primitive now would likely be thrown away, not reused.

Batching implemented as a per-example loop over the existing unbatched im2col/gemm/ col2im pipeline (each output column of the im2col matrix is independent of every other, so this is exactly equivalent to a single larger gemm with the Q axis extended to N*Q – the per-example loop is the simpler, correctness-first choice; see campaign recon's noted alternative), not a new backend primitive.

Constructor & Destructor Documentation

Conv2DModule()

pulsatrix::Conv2DModule::Conv2DModule	(	int64_t	in_channels,
		int64_t	out_channels,
		int64_t	kernel_h,
		int64_t	kernel_w,
		DeviceBackend *	backend,
		int64_t	stride = 1,
		int64_t	padding = 0
	)

Constructs a conv layer with zero-initialized kernel/bias.

Parameters

in_channels	Input channel count.
out_channels	Output channel count.
kernel_h	Kernel height.
kernel_w	Kernel width.
backend	Backend to compute through. Not owned; must outlive this module.
stride	Step between windows, the same along both axes. Defaults to 1.
padding	Zeros added on every side of the input, along both axes. Defaults to 0. Output size is (H + 2*padding - kernel_h) / stride + 1, like torch.nn.Conv2d (roadmap FND-6: VGG and ResNet need both).

Exceptions

std::invalid_argument

if stride < 1 or padding < 0.

Member Function Documentation

backward()

Tensor pulsatrix::Conv2DModule::backward ( const Tensor &  grad_output )

overridevirtual

Computes gradients w.r.t. input, kernel, and bias.

Parameters

grad_output

Gradient w.r.t. this module's output. Must match the shape of the most recent forward() call's output.

Returns

Gradient w.r.t. this module's input.

Note

Must be called after forward() – uses the input/im2col cached from that call.

Device-generic: runs on Cpu, Cuda or Hip tensors (GPU-native-kernels Mission 4).

Exceptions

std::logic_error

if forward() has never been called – see campaign_exai_dl_library_adversarial_hardening.md, finding 12.

Implements pulsatrix::Module.

bias()

const Tensor & pulsatrix::Conv2DModule::bias ( ) const

inline

bias_grad()

const Tensor & pulsatrix::Conv2DModule::bias_grad ( ) const

inline

compute_device()

std::optional< DeviceType > pulsatrix::Conv2DModule::compute_device ( ) const

inlineoverridevirtual

Where this layer computes, so forward() rejects an input on another device (FND-8).

Reimplemented from pulsatrix::Module.

forward_impl()

Tensor pulsatrix::Conv2DModule::forward_impl ( const Tensor &  input )

overrideprotectedvirtual

The actual forward computation (im2col + gemm + per-channel bias add).

Note

Device-generic: runs on Cpu, Cuda or Hip tensors (GPU-native-kernels Mission 4).

Exceptions

std::invalid_argument

if input isn't rank-4 (N, in_channels, H, W), its channel count doesn't match in_channels_, or the kernel is larger than the padded input (kernel_h_ > H + 2*padding, likewise W) – see campaign_exai_dl_library_adversarial_hardening.md, findings 1 and 6.

Implements pulsatrix::Module.

kernel()

const Tensor & pulsatrix::Conv2DModule::kernel ( ) const

inline

kernel_grad()

const Tensor & pulsatrix::Conv2DModule::kernel_grad ( ) const

inline

named_parameters()

std::vector< NamedParamRef > pulsatrix::Conv2DModule::named_parameters ( )

inlineoverridevirtual

This module's trainable parameters, each with its hierarchical name – the one place a module declares its parameters (roadmap FND-1).

Returns

{name, {value, grad}} entries pointing directly at this module's own members, in a fixed order. Names are unique within the module tree. Default: empty (a parameterless module like ReluModule needs no override).

Note

Override this, not parameters(): saving, loading, freezing by name and optimizer parameter groups all key on these names.

Reimplemented from pulsatrix::Module.

op_type()

OpType pulsatrix::Conv2DModule::op_type ( ) const

inlineoverridevirtual

Conv per charter's closed OpType set.

Implements pulsatrix::Module.

padding()

int64_t pulsatrix::Conv2DModule::padding ( ) const

inline

Zero padding on every side, along both axes.

propagate_relevance()

Tensor pulsatrix::Conv2DModule::propagate_relevance ( const Tensor &  relevance_out, const LRPRuleConfig &  config  )

overridevirtual

Epsilon-rule LRP relevance propagation.

Parameters

relevance_out	Relevance at this module's output. Shape (N, out_channels, out_h, out_w).
config	Selects epsilon.

Returns

Relevance at this module's input, shape (N, in_channels, H, W).

Note

Structurally the same rule as LinearModule's, applied independently per output position via the im2col representation (each output position/channel pair is a "virtual Linear neuron" over its own receptive-field patch), then col2im'd back to input space – which sums relevance from every output position that touched a given input pixel, the same overlap-handling backward() already needed for gradients. Bias is excluded from z, same rationale as LinearModule. Must be called after forward().

Device-generic: runs on Cpu, Cuda or Hip tensors (GPU-native-kernels Mission 4).

config.rule selects Epsilon (default, as above), Gamma, AlphaBeta or ZBox: the LinearModule formulas (Zennit 1.0.0) applied in patch space, where each output position is K @ patch + b, then folded back with col2im. Epsilon with config.epsilon_bias_in_denominator uses z = K @ patch + b (Zennit's Epsilon).

Exceptions

std::logic_error	if forward() has never been called – see campaign_exai_dl_library_adversarial_hardening.md, finding 12.
std::invalid_argument	if config's rule parameters are invalid (AlphaBeta needs alpha, beta >= 0 and alpha - beta == 1).

Implements pulsatrix::Module.

set_bias() [1/2]

void pulsatrix::Conv2DModule::set_bias

(

const std::vector< float > &

values

)

Vector overload for runtime-sized sources – see Tensor's own vector ctor.

set_bias() [2/2]

void pulsatrix::Conv2DModule::set_bias

(

std::initializer_list< float >

values

)

Overwrites the bias buffer – test/initialization use only.

set_kernel() [1/2]

void pulsatrix::Conv2DModule::set_kernel

(

const std::vector< float > &

values

)

Vector overload for runtime-sized sources – see Tensor's own vector ctor.

set_kernel() [2/2]

void pulsatrix::Conv2DModule::set_kernel

(

std::initializer_list< float >

values

)

Overwrites the kernel buffer – test/initialization use only.

stride()

int64_t pulsatrix::Conv2DModule::stride ( ) const

inline

Step between windows along both axes.

supports_lrp_rule()

bool pulsatrix::Conv2DModule::supports_lrp_rule ( LRPRule  ) const

inlineoverridevirtual

Implements every LRPRule.

Reimplemented from pulsatrix::Module.

---

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

• include/pulsatrix/conv2d_module.hpp