|
pulsatrix 1.1.0
|
Wraps an ordered chain of Modules, running them via Module::forward_traced to build a real ComputationGraph and Autograd backward wiring – graph-native explainers (Missions 2-3) use graph()/backward_pass()/activation(); surrogate explainers (Phase 3) would use only forward_pass(), per the charter's stated interface segregation. More...
#include <explainer_context.hpp>
Public Member Functions | |
| ExplainerContext (std::vector< Module * > modules) | |
| Constructs a context over an ordered module chain. | |
| Tensor | forward_pass (const Tensor &input) |
| Runs the full module chain forward, building a fresh graph and caching every node's activation value as it goes. | |
| Tensor | forward_pass_with_patch (const Tensor &input, NodeId patch_node_id, const Tensor &patch_value) |
| Runs the full module chain forward, substituting patch_value for the natural output of the module that produces patch_node_id – the causal-intervention (activation patching) primitive. | |
| Tensor | backward_pass (const Tensor &output_grad) |
| Runs Autograd::backward from the most recent forward_pass()'s output node. | |
| Tensor | relevance_pass (const Tensor &output_relevance, const LRPRuleConfig &config) |
| Propagates LRP relevance from the network output back to the input through every module's own propagate_relevance(), in reverse order – the relevance counterpart of backward_pass(), and what LRP::explain() runs. | |
| Tensor | relevance_pass (const Tensor &output_relevance, const std::vector< LRPRuleConfig > &configs) |
relevance_pass() with a per-module rule choice: configs[i] is handed to the i-th module (forward order) – e.g. LRP composites (lrp.hpp). | |
| Tensor | relevance_pass_through (const Tensor &relevance, const std::vector< LRPRuleConfig > &configs, size_t begin, size_t end) |
relevance_pass() through modules [begin, end) only, in reverse: relevance is the relevance at node end (module end - 1's output), and the result is the relevance at node begin. Splitting a pass at a node lets a caller change the relevance there and continue, as Concept Relevance Propagation does (concept_relevance.hpp). | |
| const std::vector< Module * > & | modules () const |
| The module chain, in forward order (not owned). | |
| const ComputationGraph & | graph () const |
| The current graph (from the most recent forward_pass() call). | |
| const Tensor & | activation (NodeId id) const |
| The cached activation value at a node, from the most recent forward_pass(). | |
| const Tensor & | gradient (NodeId id) const |
| The cached gradient at a node, from the most recent backward_pass() call. | |
| ActivationSnapshot | activation_snapshot () const |
| Captures the current activation cache into a self-contained ActivationSnapshot. | |
| Tensor | logit_lens (NodeId node_id) const |
| The "logit lens": runs the chain's final module – its read-out head – on the cached activation at node_id, answering "what would the network predict if this
layer's representation were already final?". | |
| Tensor | attention_weights (NodeId node_id) const |
| The "attention lens": the per-head attention pattern produced by the attention layer at node_id during the most recent forward pass – "what did each head
attend to", keyed by node id rather than by a direct module reference. | |
| CircuitGraph | build_circuit_graph (const Tensor &input) |
| Builds a CircuitGraph for this chain at the given input: every node scored by how much zeroing it changes the network's output, plus the chain's edges. | |
| std::optional< std::string > | layer_label (NodeId id) const |
| Passthrough to Node::label() – e.g. a layer name, for debugging/display. | |
Wraps an ordered chain of Modules, running them via Module::forward_traced to build a real ComputationGraph and Autograd backward wiring – graph-native explainers (Missions 2-3) use graph()/backward_pass()/activation(); surrogate explainers (Phase 3) would use only forward_pass(), per the charter's stated interface segregation.
|
inlineexplicit |
Constructs a context over an ordered module chain.
| modules | The network, in forward-pass order. Not owned; each must outlive this ExplainerContext. |
| std::invalid_argument | if modules is empty or contains a nullptr – external boundary (campaign_exai_dl_library_adversarial_hardening.md, Mission 2, finding 5): without this check, a nullptr element was an unconditional null-pointer dereference on the next forward_pass() call. |
The cached activation value at a node, from the most recent forward_pass().
| id | Node id. Must have been produced by the most recent forward_pass() call. |
|
inline |
Captures the current activation cache into a self-contained ActivationSnapshot.
The "attention lens": the per-head attention pattern produced by the attention layer at node_id during the most recent forward pass – "what did each head attend to", keyed by node id rather than by a direct module reference.
| node_id | Node whose attention pattern is returned. Must come from the most recent forward pass and must name a node whose op_type() is OpType::Attention. |
| std::invalid_argument | if node_id lies outside the node range the most recent forward pass produced (including the case where no forward pass has run yet, so there are no nodes at all), or if it names a node that is not an attention layer – both external boundaries (caller-supplied node id), hence throw rather than PULSATRIX_ASSERT, matching logit_lens and forward_pass_with_patch rather than activation()'s older pattern, so the behavior is identical in Debug and Release. |
Runs Autograd::backward from the most recent forward_pass()'s output node.
| output_grad | Gradient w.r.t. the chain's output. |
| std::logic_error | if the most recent forward pass was a forward_pass_with_patch() call. A patched activation is a constant substitution, not a differentiable function of the input, yet Module::forward_traced registers each module's ordinary backward closure regardless – so without this guard Autograd::backward() would return a perfectly plausible gradient taken through a link that does not exist in the computation it claims to differentiate. Rejected loudly rather than answered wrongly, the same principle as Phase 1.5's device guards; classified external boundary (a caller-sequencing mistake, like the constructor's checks) so it is a throw and behaves identically in Debug and Release. Re-arm with an ordinary forward_pass() – the guard is per-call history, not a permanent latch. |
|
inline |
Builds a CircuitGraph for this chain at the given input: every node scored by how much zeroing it changes the network's output, plus the chain's edges.
| input | Input the circuit is built at. A circuit graph is input-conditional – ablation importance is "how much does this node matter *for this input*", not a property of the weights alone. |
Runs the full module chain forward, building a fresh graph and caching every node's activation value as it goes.
| input | Input to the first module in the chain. |
|
inline |
Runs the full module chain forward, substituting patch_value for the natural output of the module that produces patch_node_id – the causal-intervention (activation patching) primitive.
| input | Input to the first module in the chain. |
| patch_node_id | Node whose activation is overridden. Node ids are assigned deterministically per forward pass: 0 is the input node, then one per module in chain order, so a node id captured from an earlier pass over this same context names the same logical layer here. |
| patch_value | Value substituted at that node. Must have the same shape as the node's natural (unpatched) output. |
| std::invalid_argument | if patch_node_id exceeds the largest node id this forward pass produces, or if patch_value's shape differs from the target node's natural output shape – both external boundaries (caller-supplied), hence throw rather than PULSATRIX_ASSERT, consistent with the constructor. |
The cached gradient at a node, from the most recent backward_pass() call.
| id | Node id. Must have accumulated a gradient during the most recent backward_pass() call (i.e. lie on the path between the seeded output and the input). |
|
inline |
The current graph (from the most recent forward_pass() call).
|
inline |
Passthrough to Node::label() – e.g. a layer name, for debugging/display.
The "logit lens": runs the chain's final module – its read-out head – on the cached activation at node_id, answering "what would the network predict if this layer's representation were already final?".
| node_id | Node whose cached activation is projected through the head. Must come from the most recent forward pass, and its activation's shape must match what the head actually consumed in that pass. |
| std::invalid_argument | if node_id has no cached activation (an id no forward pass produced, or no forward pass has run yet), or if that activation's shape differs from the head's actual input shape in the most recent forward pass – both external boundaries (caller-supplied node id), hence throw rather than PULSATRIX_ASSERT, matching forward_pass_with_patch and the constructor, and so the behavior is identical in Debug and Release. |
|
inline |
The module chain, in forward order (not owned).
|
inline |
Propagates LRP relevance from the network output back to the input through every module's own propagate_relevance(), in reverse order – the relevance counterpart of backward_pass(), and what LRP::explain() runs.
| output_relevance | Relevance at the network output, same shape as the most recent forward_pass()'s output. |
| config | LRP rule configuration handed to every module. |
| std::logic_error | if the most recent forward pass was forward_pass_with_patch(), for the same reason backward_pass() refuses: the modules' cached state would describe a computation the input did not produce. |
| std::invalid_argument | if a module does not implement config.rule (Module::supports_lrp_rule()) – checked for every module before any propagation; the rule is never silently replaced by epsilon. |
|
inline |
relevance_pass() with a per-module rule choice: configs[i] is handed to the i-th module (forward order) – e.g. LRP composites (lrp.hpp).
| std::invalid_argument | if configs.size() != number of modules, or a module does not implement its rule; std::logic_error as for the uniform overload. |
|
inline |
relevance_pass() through modules [begin, end) only, in reverse: relevance is the relevance at node end (module end - 1's output), and the result is the relevance at node begin. Splitting a pass at a node lets a caller change the relevance there and continue, as Concept Relevance Propagation does (concept_relevance.hpp).
| std::invalid_argument | if configs.size() != number of modules, begin > end or end is past the last module, or a module in the range does not implement its rule; std::logic_error as relevance_pass() does. |