pulsatrix::EmbeddingModule Class Reference

Embedding lookup table, rank-2 input (N, L) of float-encoded indices -> rank-3 output (N, L, embedding_dim). Structurally unlike every other module in this codebase: forward is a pure selection (row copy), with no arithmetic mixing across input features. More...

#include <embedding_module.hpp>

Inheritance diagram for pulsatrix::EmbeddingModule:

Collaboration diagram for pulsatrix::EmbeddingModule:

Public Member Functions
	EmbeddingModule (int64_t num_embeddings, int64_t embedding_dim, DeviceBackend *backend)
	Constructs an embedding table with a zero-initialized weight matrix.
Tensor	backward (const Tensor &grad_output) override
	Scatter-adds grad_output into the corresponding rows of weight_grad_.
OpType	op_type () const override
	Embedding per charter's closed OpType set.
void	set_weight (std::initializer_list< float > values)
	Overwrites the weight 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.
const Tensor &	weight () const
const Tensor &	weight_grad () const
Tensor	propagate_relevance (const Tensor &relevance_out, const LRPRuleConfig &config) override
	Sum-over-embedding-dimension LRP relevance aggregation (Arras et al. 2017).
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).
Public Member Functions inherited from pulsatrix::Module
virtual	~Module ()=default
Tensor	forward (const Tensor &input)
	Runs this module's forward computation.
virtual std::optional< DeviceType >	compute_device () const
	The device this module computes on, so forward() can reject an input on another device before any kernel sees it (roadmap FND-8).
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 bool	supports_lrp_rule (LRPRule rule) const
	Whether propagate_relevance() implements rule (no silent fallback: callers such as ExplainerContext::relevance_pass() throw rather than run a module on a rule it does not implement).
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 – per-position row copy from weight_.

Detailed Description

Embedding lookup table, rank-2 input (N, L) of float-encoded indices -> rank-3 output (N, L, embedding_dim). Structurally unlike every other module in this codebase: forward is a pure selection (row copy), with no arithmetic mixing across input features.

Note

Float-indices design decision: Tensor is float-only (no integer tensor type exists anywhere in this codebase). Each input element is resolved to an index via round-to-nearest (std::llround, not truncation – a caller passing 2.9999999f due to float round-trip from an integer source should not silently land on index 2), then bounds-checked against [0, num_embeddings). This is a genuinely new pattern in this codebase, not reused from any existing module.

propagate_relevance sums relevance over the embedding dimension per (n, l) position (Arras et al. 2017, "Explaining Recurrent Neural Network Predictions in Sentiment Analysis" – already cited in this charter for RNN/LSTM): a token's total relevance is the sum of its embedding vector's per-dimension relevance values – there is no further "input" beneath a discrete token id to redistribute to. Conserves exactly by construction.

backward() uses scatter-add gradient accumulation (the first module in this codebase needing it – LinearModule/Conv2DModule's gradients are dense-matmul sums, not index-selected accumulation): multiple (n, l) positions referencing the same row each contribute additively into that row of weight_grad_. Gradient w.r.t. the input indices themselves is undefined (discrete, non-differentiable) – backward() returns an all-zero tensor matching the input shape, matching every mainstream framework's nn.Embedding behavior.

Constructor & Destructor Documentation

EmbeddingModule()

pulsatrix::EmbeddingModule::EmbeddingModule	(	int64_t	num_embeddings,
		int64_t	embedding_dim,
		DeviceBackend *	backend
	)

Constructs an embedding table with a zero-initialized weight matrix.

Parameters

num_embeddings	Number of rows (vocabulary size).
embedding_dim	Row width.
backend	Backend to allocate/compute through. Not owned; must outlive this module.

Exceptions

std::invalid_argument

if num_embeddings <= 0 or embedding_dim <= 0 – external boundary (construction arguments can originate from Phase 5's Python bindings with no upstream validation).

Member Function Documentation

backward()

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

overridevirtual

Scatter-adds grad_output into the corresponding rows of weight_grad_.

Parameters

grad_output

Gradient w.r.t. this module's output. Must be (N, L, embedding_dim) matching the most recent forward() call's output shape.

Returns

An all-zero tensor matching the cached input shape (N, L) – gradient w.r.t. discrete indices is undefined; this module never claims otherwise.

Exceptions

std::logic_error	if forward() has never been called.
std::invalid_argument	if grad_output's shape doesn't match the cached forward output shape.

Note

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

Implements pulsatrix::Module.

forward_impl()

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

overrideprotectedvirtual

The actual forward computation – per-position row copy from weight_.

Exceptions

std::invalid_argument

if input isn't rank-2 (N, L), or any element round-resolves to an index outside [0, num_embeddings).

Note

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

Implements pulsatrix::Module.

named_parameters()

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

inlineoverridevirtual

Embedding per charter's closed OpType set.

Implements pulsatrix::Module.

propagate_relevance()

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

overridevirtual

Sum-over-embedding-dimension LRP relevance aggregation (Arras et al. 2017).

Parameters

relevance_out	Relevance at this module's output. Must be (N, L, embedding_dim) matching the most recent forward() call's output shape.
config	Unused – this rule has no tunable parameter.

Returns

Relevance at this module's input, shape (N, L): relevance_out summed over the embedding dimension at each (n, l) position. Conserves exactly by construction.

Exceptions

std::logic_error	if forward() has never been called.
std::invalid_argument	if relevance_out's shape doesn't match the cached forward output shape.

Implements pulsatrix::Module.

set_weight() [1/2]

void pulsatrix::EmbeddingModule::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::EmbeddingModule::set_weight

(

std::initializer_list< float >

values

)

Overwrites the weight buffer – test/initialization use only.

weight()

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

inline

weight_grad()

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

inline

---

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

• include/pulsatrix/embedding_module.hpp