pulsatrix 1.1.0
Loading...
Searching...
No Matches
pulsatrix::HiddenStateTap Class Reference

An identity intervention that keeps the hidden states it sees and adds a gradient to the one flowing back through it: the way to train a CausalLM on a loss of a layer's output. More...

#include <layer_student.hpp>

Inheritance diagram for pulsatrix::HiddenStateTap:
Collaboration diagram for pulsatrix::HiddenStateTap:

Public Member Functions

 HiddenStateTap (DeviceBackend *backend)
 
Tensor forward_at (const Tensor &hidden, int64_t start, int64_t prompt_length) override
 The edit for hidden states covering positions [start, start + L) of a sequence whose prompt is prompt_length positions long. forward(x) is forward_at(x, 0, L). Cached generation calls it once on the prompt and then once per new token, each a later start.
 
Tensor backward (const Tensor &grad_output) override
 grad_output plus the gradient given to add_gradient(), if any, which is then dropped.
 
Tensor propagate_relevance (const Tensor &relevance_out, const LRPRuleConfig &config) override
 Computes this module's contribution to LRP relevance propagation.
 
bool supports_lrp_rule (LRPRule) const override
 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).
 
OpType op_type () const override
 This module's operation-category tag, for ComputationGraph node tagging.
 
std::optional< DeviceType > compute_device () const override
 The device this module computes on, so forward() can reject an input on another device before any kernel sees it (roadmap FND-8).
 
void release_activations () override
 Frees the tensors forward() kept for backward() and the relevance passes; containers release their children too. Inference that only needs the output calls it after each forward, so a deep model holds one layer's activations at a time (a 1024-token ESM-2 650M pass otherwise keeps over 10 GB of them).
 
const Tensor & hidden () const
 The last forward()'s hidden states, (N, L, hidden_size).
 
void add_gradient (const Tensor &gradient)
 A gradient for the next backward() to add, the hidden states' shape.
 
- 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< NamedParamRef > named_parameters ()
 This module's trainable parameters, each with its hierarchical name – the one place a module declares its parameters (roadmap FND-1).
 
virtual std::vector< NamedBufferRef > named_buffers ()
 This module's buffers: state a checkpoint must save that no optimizer updates.
 
virtual std::vector< NamedModuleRef > named_children ()
 This module's direct sub-modules, each under the prefix its parameters carry in named_parameters(), in the same order (TRN-7: how ApplyLora() finds a model's Linear layers). Default: none. NamedModules() walks the whole tree.
 
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.
 

Additional Inherited Members

- Protected Member Functions inherited from pulsatrix::ResidualIntervention
Tensor forward_impl (const Tensor &hidden) override
 The actual forward computation. Called by forward() after precondition checks.
 

Detailed Description

An identity intervention that keeps the hidden states it sees and adds a gradient to the one flowing back through it: the way to train a CausalLM on a loss of a layer's output.

Note
Each forward() replaces the kept states; add_gradient() applies to the next backward() only. Relevance passes through unchanged.

Constructor & Destructor Documentation

◆ HiddenStateTap()

pulsatrix::HiddenStateTap::HiddenStateTap ( DeviceBackend *  backend)
explicit

Member Function Documentation

◆ add_gradient()

void pulsatrix::HiddenStateTap::add_gradient ( const Tensor &  gradient)

A gradient for the next backward() to add, the hidden states' shape.

Exceptions
std::invalid_argumentfor another shape or device, std::logic_error before a forward().

◆ backward()

Tensor pulsatrix::HiddenStateTap::backward ( const Tensor &  grad_output)
overridevirtual

grad_output plus the gradient given to add_gradient(), if any, which is then dropped.

Implements pulsatrix::Module.

◆ compute_device()

std::optional< DeviceType > pulsatrix::HiddenStateTap::compute_device ( ) const
inlineoverridevirtual

The device this module computes on, so forward() can reject an input on another device before any kernel sees it (roadmap FND-8).

Returns
std::nullopt (the default) skips the check: a container whose layers check their own inputs, or a user module written before this existed. Every in-tree layer returns its device; EmbeddingModule doesn't, because it reads its indices through their own backend and so accepts them from any device.

Reimplemented from pulsatrix::Module.

◆ forward_at()

Tensor pulsatrix::HiddenStateTap::forward_at ( const Tensor &  hidden,
int64_t  start,
int64_t  prompt_length 
)
overridevirtual

The edit for hidden states covering positions [start, start + L) of a sequence whose prompt is prompt_length positions long. forward(x) is forward_at(x, 0, L). Cached generation calls it once on the prompt and then once per new token, each a later start.

Implements pulsatrix::ResidualIntervention.

◆ hidden()

const Tensor & pulsatrix::HiddenStateTap::hidden ( ) const

The last forward()'s hidden states, (N, L, hidden_size).

Exceptions
std::logic_errorbefore a forward().

◆ op_type()

OpType pulsatrix::HiddenStateTap::op_type ( ) const
inlineoverridevirtual

This module's operation-category tag, for ComputationGraph node tagging.

Returns
This module's OpType (see op_type.hpp's closed set).
Note
Added in Phase 2 Mission 0 alongside backward() – lets graph-wiring code tag nodes generically through a Module* rather than switching on concrete subclass.

Implements pulsatrix::Module.

◆ propagate_relevance()

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

Computes this module's contribution to LRP relevance propagation.

Parameters
relevance_outRelevance at this module's output.
configSelects the LRP rule variant.
Returns
Relevance at this module's input.

Implements pulsatrix::Module.

◆ release_activations()

void pulsatrix::HiddenStateTap::release_activations ( )
overridevirtual

Frees the tensors forward() kept for backward() and the relevance passes; containers release their children too. Inference that only needs the output calls it after each forward, so a deep model holds one layer's activations at a time (a 1024-token ESM-2 650M pass otherwise keeps over 10 GB of them).

Note
Until the next forward(), backward() and relevance calls are invalid. The default has nothing to free.

Reimplemented from pulsatrix::Module.

◆ supports_lrp_rule()

bool pulsatrix::HiddenStateTap::supports_lrp_rule ( LRPRule  rule) const
inlineoverridevirtual

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).

Note
Default: only LRPRule::Epsilon, the rule every module implements. Overridden by LinearModule / Conv2DModule (all rules), by parameter-free pass-through modules whose relevance rule does not read the config at all, and by SequentialModule (all layers).

Reimplemented from pulsatrix::Module.


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