pulsatrix::LinearModule Class Reference

y = x @ W + b, batched (x is (N, in_features), y is (N, out_features)) – migrated from the original unbatched (rank-1) scope by campaign_exai_dl_library_batch_dimension_support (breaking migration to always-batched; a single example is N=1, not a structurally different case). More...

#include <linear_module.hpp>

Inheritance diagram for pulsatrix::LinearModule:

Collaboration diagram for pulsatrix::LinearModule:

Public Member Functions
	LinearModule (int64_t in_features, int64_t out_features, DeviceBackend *backend, DeviceType device)
	Constructs a linear layer with zero-initialized weight/bias.
	LinearModule (int64_t in_features, int64_t out_features, DeviceBackend *backend)
	As above, on backend's own device (backend->device()).
Tensor	backward (const Tensor &grad_output) override
	Computes the gradient w.r.t. this module's input, and accumulates the weight/bias gradients internally (summed across the batch).
OpType	op_type () const override
	Linear per charter's closed OpType set.
void	set_weight (std::initializer_list< float > values)
	Overwrites the weight buffer – test/initialization use only.
void	set_bias (std::initializer_list< float > values)
	Overwrites the bias buffer – test/initialization use only.
void	set_weight (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 &	weight () const
const Tensor &	bias () const
const Tensor &	weight_grad () const
const Tensor &	bias_grad () const
Tensor	propagate_relevance (const Tensor &relevance_out, const LRPRuleConfig &config) override
	Epsilon-rule LRP relevance propagation (Bach et al. 2015), applied independently per example in the batch.
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. Called by forward() after precondition checks.

Detailed Description

y = x @ W + b, batched (x is (N, in_features), y is (N, out_features)) – migrated from the original unbatched (rank-1) scope by campaign_exai_dl_library_batch_dimension_support (breaking migration to always-batched; a single example is N=1, not a structurally different case).

Note

Weight layout is (in_features, out_features), not the more common (out_features, in_features) PyTorch convention – chosen specifically so forward (x @ W) and the weight-gradient step (X^T @ grad_Y) both use DeviceBackend::gemm directly with no transpose of the weight operand. The input-gradient step (grad_Y @ W^T) and the weight-gradient step (X^T @ grad_Y, the batched sum of outer products) read their transposed operand in place through DeviceBackend::gemm_ex – no transposed copy is built.

Weights/biases are owned here as member Tensors, not ComputationGraph nodes. Parameter gradients accumulate via Tensor::accumulate() across backward() calls until something (the optimizer) resets them. Batch-dimension gradient reduction (summing weight/bias gradient contributions across the N examples in a batch) needs no new Tensor primitive – see campaign_exai_dl_library_batch_dimension_support's mission_tensor_shape_foundation.md: weight_grad's reduction falls out of gemm's own k-dimension summation (accumulated in place, beta = 1); bias_grad's is DeviceBackend::column_sums, likewise accumulated in place. Both are device-resident (GPU-native-kernels Mission 1).

Constructor & Destructor Documentation

LinearModule() [1/2]

pulsatrix::LinearModule::LinearModule	(	int64_t	in_features,
		int64_t	out_features,
		DeviceBackend *	backend,
		DeviceType	device
	)

Constructs a linear layer with zero-initialized weight/bias.

Parameters

in_features	Input dimension.
out_features	Output dimension.
backend	Backend to allocate/compute through. Not owned; must outlive this module.
device	Which device every internal Tensor member (weight, bias, gradients, forward-pass caches) is tagged as. Must match whatever device backend actually allocates on, or Tensor's own device-based dispatch (e.g. CopyDirection selection) will be wrong. See campaign_exai_dl_library_phase1_5_cuda_backend.md's Mission 3.

LinearModule() [2/2]

pulsatrix::LinearModule::LinearModule	(	int64_t	in_features,
		int64_t	out_features,
		DeviceBackend *	backend
	)

As above, on backend's own device (backend->device()).

Note

Previously the device defaulted to Cpu, so a LinearModule built on a GPU backend without an explicit tag – e.g. SwiGLUModule's three projections – held Cpu-tagged weights in device memory (GPU-native-kernels Mission 0).

Member Function Documentation

backward()

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

overridevirtual

Computes the gradient w.r.t. this module's input, and accumulates the weight/bias gradients internally (summed across the batch).

Parameters

grad_output

Gradient w.r.t. this module's output. Must be (N, out_features), with N matching the most recent forward() call's batch size.

Returns

Gradient w.r.t. this module's input, shape (N, in_features).

Note

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

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

Exceptions

std::logic_error	if forward() has never been called – see campaign_exai_dl_library_adversarial_hardening.md, finding 12.
std::invalid_argument	if grad_output's rank/shape don't match (N, out_features) for the cached N – external boundary, batch-size-mismatch is a new adversarial case this migration introduces (campaign_exai_dl_library_batch_dimension_support).

Implements pulsatrix::Module.

bias()

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

inline

bias_grad()

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

inline

compute_device()

std::optional< DeviceType > pulsatrix::LinearModule::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::LinearModule::forward_impl ( const Tensor &  input )

overrideprotectedvirtual

The actual forward computation. Called by forward() after precondition checks.

Implements pulsatrix::Module.

named_parameters()

std::vector< NamedParamRef > pulsatrix::LinearModule::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::LinearModule::op_type ( ) const

inlineoverridevirtual

Linear per charter's closed OpType set.

Implements pulsatrix::Module.

propagate_relevance()

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

overridevirtual

Epsilon-rule LRP relevance propagation (Bach et al. 2015), applied independently per example in the batch.

Parameters

relevance_out	Relevance at this module's output. Must be (N, out_features), matching the cached forward() batch size.
config	Selects epsilon. Larger epsilon trades a small amount of conservation for numerical stability when a pre-bias output is near zero.

Returns

Relevance at this module's input, shape (N, in_features).

Note

Uses the pre-bias linear output (x @ W, not x @ W + b) as z_j – bias has no associated input feature to redistribute relevance to, so it is excluded from the rule entirely rather than approximated. This is what makes relevance conservation exact (up to the epsilon stabilizer) rather than merely approximate. Must be called after forward() – uses the cached pre-bias output.

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

config.rule selects Epsilon (default, as above), Gamma, AlphaBeta or ZBox, with Zennit 1.0.0 semantics (see src/lrp_rules.hpp for the formulas). Epsilon with config.epsilon_bias_in_denominator uses z = xW + b instead (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::LinearModule::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::LinearModule::set_bias

(

std::initializer_list< float >

values

)

Overwrites the bias buffer – test/initialization use only.

set_weight() [1/2]

void pulsatrix::LinearModule::set_weight

(

const std::vector< float > &

values

)

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

set_weight() [2/2]

void pulsatrix::LinearModule::set_weight

(

std::initializer_list< float >

values

)

Overwrites the weight buffer – test/initialization use only.

supports_lrp_rule()

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

inlineoverridevirtual

Implements every LRPRule.

Reimplemented from pulsatrix::Module.

weight()

const Tensor & pulsatrix::LinearModule::weight ( ) const

inline

weight_grad()

const Tensor & pulsatrix::LinearModule::weight_grad ( ) const

inline

---

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

• include/pulsatrix/linear_module.hpp