pulsatrix 1.1.0
Loading...
Searching...
No Matches
module.hpp
Go to the documentation of this file.
1
5#pragma once
6
7#include <optional>
8#include <stdexcept>
9#include <string>
10#include <utility>
11#include <vector>
12
13#include "pulsatrix/assert.hpp"
17#include "pulsatrix/node.hpp"
18#include "pulsatrix/op_type.hpp"
19#include "pulsatrix/tensor.hpp"
20
21namespace pulsatrix {
22
28
38 std::string name;
40};
41
47 std::string name;
49};
50
51class Module;
52
58 std::string name;
59 Module* module;
60};
61
78class Module {
79public:
80 virtual ~Module() = default;
81
93 [[nodiscard]] Tensor forward(const Tensor& input) {
94 if (input.numel() <= 0) {
95 throw std::invalid_argument("Module::forward: input must not be empty");
96 }
97 if (const std::optional<DeviceType> device = compute_device()) {
98 require_device(input, *device, "Module::forward");
99 }
100 return forward_impl(input);
101 }
102
111 [[nodiscard]] virtual std::optional<DeviceType> compute_device() const { return std::nullopt; }
112
131 [[nodiscard]] std::pair<Tensor, NodeId> forward_traced(const Tensor& input, NodeId input_node,
132 ComputationGraph& graph, Autograd& autograd) {
133 Tensor output = forward(input);
134 NodeId node_id = graph.add_node(op_type(), output.shape(), std::nullopt, {input_node});
135 autograd.register_backward(node_id, [this](const Tensor& grad_output) { return this->backward(grad_output); });
136 return {std::move(output), node_id};
137 }
138
145 [[nodiscard]] virtual Tensor propagate_relevance(const Tensor& relevance_out, const LRPRuleConfig& config) = 0;
146
155 [[nodiscard]] virtual bool supports_lrp_rule(LRPRule rule) const { return rule == LRPRule::Epsilon; }
156
168 [[nodiscard]] virtual Tensor backward(const Tensor& grad_output) = 0;
169
176 [[nodiscard]] virtual OpType op_type() const = 0;
177
187 [[nodiscard]] virtual std::vector<NamedParamRef> named_parameters() { return {}; }
188
195 [[nodiscard]] virtual std::vector<NamedBufferRef> named_buffers() { return {}; }
204 [[nodiscard]] virtual std::vector<NamedModuleRef> named_children() { return {}; }
205
217 [[nodiscard]] virtual std::vector<ParamRef> parameters() {
218 std::vector<ParamRef> params;
219 for (const NamedParamRef& p : named_parameters()) {
220 params.push_back(p.ref);
221 }
222 return params;
223 }
224
236 void set_requires_grad(bool requires_grad, const std::string& prefix = "") {
237 if (prefix.empty()) {
238 // parameters(), not named_parameters(): also reaches a legacy module that has no names.
239 for (ParamRef p : parameters()) {
240 p.value->set_requires_grad(requires_grad);
241 }
242 return;
243 }
244 std::vector<Tensor*> selected;
245 for (const NamedParamRef& p : named_parameters()) {
246 if (p.name == prefix || p.name.rfind(prefix + ".", 0) == 0) {
247 selected.push_back(p.ref.value);
248 }
249 }
250 if (selected.empty()) {
251 throw std::invalid_argument("Module::set_requires_grad: no parameter named or under '" + prefix + "'");
252 }
253 for (Tensor* value : selected) {
254 value->set_requires_grad(requires_grad);
255 }
256 }
257
271 virtual void set_training(bool training) { training_ = training; }
272
274 [[nodiscard]] bool is_training() const { return training_; }
275
284 virtual void release_activations() {}
285
286protected:
288 [[nodiscard]] virtual Tensor forward_impl(const Tensor& input) = 0;
289
290private:
291 bool training_ = true;
292};
293
301inline void append_named_parameters(std::vector<NamedParamRef>& out, const std::string& prefix, Module& child) {
302 std::vector<NamedParamRef> named = child.named_parameters();
303 if (named.empty()) {
304 std::vector<ParamRef> plain = child.parameters();
305 for (size_t i = 0; i < plain.size(); ++i) {
306 named.push_back({std::to_string(i), plain[i]});
307 }
308 }
309 for (NamedParamRef& p : named) {
310 out.push_back({prefix + "." + p.name, p.ref});
311 }
312}
313
318inline std::vector<NamedModuleRef> NamedModules(Module& root) {
319 std::vector<NamedModuleRef> out;
320 for (const NamedModuleRef& child : root.named_children()) {
321 out.push_back(child);
322 for (const NamedModuleRef& below : NamedModules(*child.module)) {
323 out.push_back({child.name + "." + below.name, below.module});
324 }
325 }
326 return out;
327}
328
330inline void release_tensor(Tensor& t) { t = Tensor(Shape({0}), t.backend(), t.device()); }
331
333inline void append_named_buffers(std::vector<NamedBufferRef>& out, const std::string& prefix, Module& child) {
334 for (NamedBufferRef& b : child.named_buffers()) {
335 out.push_back({prefix + "." + b.name, b.value});
336 }
337}
338
339} // namespace pulsatrix
PULSATRIX_ASSERT – debug-only invariant check for programmer errors, distinct from throw (used for ca...
Reverse-mode autodiff – walks a ComputationGraph backward, accumulating gradients via per-node backwa...
Computes gradients by walking a ComputationGraph in reverse topological order.
Definition autograd.hpp:36
void register_backward(NodeId id, BackwardFn fn)
Registers how to compute this node's input gradient from its output gradient.
Owns every Node in a computation graph and exposes read access for graph-walking code (autograd's bac...
Definition computation_graph.hpp:27
NodeId add_node(OpType op_type, Shape shape, std::optional< std::string > label=std::nullopt, std::vector< NodeId > parent_ids={})
Adds a node to the graph and wires it to its parents.
Base class for every layer type (LinearModule, Conv2DModule, activations, ...).
Definition module.hpp:78
virtual std::vector< NamedBufferRef > named_buffers()
This module's buffers: state a checkpoint must save that no optimizer updates.
Definition module.hpp:195
virtual std::vector< ParamRef > parameters()
This module's trainable parameters and their gradients, for an optimizer to update uniformly across m...
Definition module.hpp:217
virtual Tensor propagate_relevance(const Tensor &relevance_out, const LRPRuleConfig &config)=0
Computes this module's contribution to LRP relevance propagation.
virtual std::vector< NamedParamRef > named_parameters()
This module's trainable parameters, each with its hierarchical name – the one place a module declares...
Definition module.hpp:187
void set_requires_grad(bool requires_grad, const std::string &prefix="")
Freezes (false) or unfreezes (true) parameters by name (roadmap FND-2).
Definition module.hpp:236
virtual OpType op_type() const =0
This module's operation-category tag, for ComputationGraph node tagging.
virtual void set_training(bool training)
Sets this module's training/eval mode. Defaults to training (matches every mainstream framework's Mod...
Definition module.hpp:271
Tensor forward(const Tensor &input)
Runs this module's forward computation.
Definition module.hpp:93
virtual Tensor forward_impl(const Tensor &input)=0
The actual forward computation. Called by forward() after precondition checks.
bool is_training() const
Whether this module is currently in training mode.
Definition module.hpp:274
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(),...
Definition module.hpp:131
virtual Tensor backward(const Tensor &grad_output)=0
Computes the gradient w.r.t. this module's input, given the gradient w.r.t. its output....
virtual bool supports_lrp_rule(LRPRule rule) const
Whether propagate_relevance() implements rule (no silent fallback: callers such as ExplainerContext::...
Definition module.hpp:155
virtual ~Module()=default
virtual std::vector< NamedModuleRef > named_children()
This module's direct sub-modules, each under the prefix its parameters carry in named_parameters(),...
Definition module.hpp:204
virtual void release_activations()
Frees the tensors forward() kept for backward() and the relevance passes; containers release their ch...
Definition module.hpp:284
virtual std::optional< DeviceType > compute_device() const
The device this module computes on, so forward() can reject an input on another device before any ker...
Definition module.hpp:111
An N-dimensional shape. A plain aggregate of dimensions with no invariant beyond "non-negative dimens...
Definition shape.hpp:24
N-dimensional tensor. Owns its data buffer exclusively; a DeviceBackend* is injected (not owned) – th...
Definition tensor.hpp:29
DeviceType device() const
Which device this tensor's buffer conceptually resides on.
Definition tensor.hpp:122
DeviceBackend * backend() const
The backend that owns this tensor's buffer. Not owned by the Tensor.
Definition tensor.hpp:130
int64_t numel() const
Total element count – shape().numel().
Definition tensor.hpp:116
const Shape & shape() const
This tensor's shape.
Definition tensor.hpp:113
Owns and exposes graph structure – the interpretability substrate every explainer (Phase 2+) walks.
Selects which LRP rule variant a Module::propagate_relevance() call uses.
Definition acquisition_functions.hpp:16
size_t NodeId
Stable identifier for a Node within its owning ComputationGraph.
Definition node.hpp:18
void require_device(const Tensor &t, DeviceType expected, const char *where)
Throws unless t lives on expected – the check every module and loss runs on the tensors handed to it ...
Definition tensor.hpp:285
void append_named_parameters(std::vector< NamedParamRef > &out, const std::string &prefix, Module &child)
Appends child's named parameters to out, each renamed to prefix.name – the one step every container's...
Definition module.hpp:301
OpType
The op-type tag a Node carries. Charter Part 2 §3: nodes are tagged by a small closed set of op types...
Definition op_type.hpp:19
LRPRule
The LRP rule family a module applies. Semantics follow Zennit 1.0.0 exactly (Anders et al....
Definition lrp_rule_config.hpp:21
void release_tensor(Tensor &t)
Frees t's buffer: it becomes an empty tensor on the same backend and device.
Definition module.hpp:330
std::vector< NamedModuleRef > NamedModules(Module &root)
Every module under root, depth first with each parent before its children, named by their full dotted...
Definition module.hpp:318
void append_named_buffers(std::vector< NamedBufferRef > &out, const std::string &prefix, Module &child)
Appends child's named buffers to out, each renamed to prefix.name.
Definition module.hpp:333
Computation graph node – op type, shape, optional label, parent/child edges.
Closed set of operation categories every graph Node is tagged with.
Configuration for LRP relevance propagation: which rule a module applies and its hyperparameters....
Definition lrp_rule_config.hpp:72
Module state that is saved with a model but never trained, such as BatchNorm's running statistics,...
Definition module.hpp:46
std::string name
Definition module.hpp:47
Tensor * value
Definition module.hpp:48
A sub-module with its dot-separated name relative to the module that reported it, the same prefix its...
Definition module.hpp:57
std::string name
Definition module.hpp:58
A parameter together with its hierarchical, dot-separated name relative to the module that reported i...
Definition module.hpp:37
std::string name
Definition module.hpp:38
ParamRef ref
Definition module.hpp:39
A trainable parameter and its accumulated gradient, as owned by some Module.
Definition module.hpp:24
Tensor * value
Definition module.hpp:25
Tensor * grad
Definition module.hpp:26
N-dimensional tensor – owns a buffer via DeviceBackend*, RAII (Rule of Five).