pulsatrix 1.1.0
Loading...
Searching...
No Matches
lrp.hpp
Go to the documentation of this file.
1
5#pragma once
6
7#include <cstdint>
8#include <functional>
9#include <memory>
10#include <stdexcept>
11#include <string>
12#include <utility>
13#include <vector>
14
22#include "pulsatrix/tensor.hpp"
23
24namespace pulsatrix {
25
27enum class LRPSeed {
33 OneHot
34};
35
44struct LRPTarget {
45 std::vector<int64_t> targets;
46 std::vector<int64_t> contrasts = {};
48};
49
59using LRPComposite = std::function<LRPRuleConfig(size_t layer_index, const Module& module)>;
60
70namespace lrp_composite {
71
72namespace detail {
73inline bool is_conv(const Module& module) { return dynamic_cast<const Conv2DModule*>(&module) != nullptr; }
74inline LRPRuleConfig zennit_epsilon(float epsilon) {
75 LRPRuleConfig config{epsilon};
76 config.epsilon_bias_in_denominator = true;
77 return config;
78}
79inline LRPRuleConfig alpha_beta(float alpha, float beta, float epsilon) {
80 LRPRuleConfig config{epsilon};
81 config.rule = LRPRule::AlphaBeta;
82 config.alpha = alpha;
83 config.beta = beta;
84 return config;
85}
86} // namespace detail
87
90inline LRPRuleConfig epsilon_with_conv(float epsilon, const LRPRuleConfig& conv) {
91 LRPRuleConfig config = detail::zennit_epsilon(epsilon);
92 config.conv_rule = std::make_shared<const LRPRuleConfig>(conv);
93 return config;
94}
95
98inline LRPComposite epsilon_plus(float epsilon = 1e-6f) {
99 return [epsilon](size_t, const Module& module) {
100 const LRPRuleConfig zplus = detail::alpha_beta(1.0f, 0.0f, epsilon);
101 return detail::is_conv(module) ? zplus : epsilon_with_conv(epsilon, zplus);
102 };
103}
104
107inline LRPComposite epsilon_alpha2_beta1(float epsilon = 1e-6f) {
108 return [epsilon](size_t, const Module& module) {
109 const LRPRuleConfig ab = detail::alpha_beta(2.0f, 1.0f, epsilon);
110 return detail::is_conv(module) ? ab : epsilon_with_conv(epsilon, ab);
111 };
112}
113
125inline LRPComposite epsilon_gamma_box(float low, float high, float gamma = 0.25f, float epsilon = 1e-6f) {
126 auto first_conv_seen = std::make_shared<bool>(false);
127 return [=](size_t layer_index, const Module& module) {
128 if (layer_index == 0) {
129 *first_conv_seen = false;
130 }
131 if (!detail::is_conv(module)) {
132 LRPRuleConfig gamma_rule{epsilon};
133 gamma_rule.rule = LRPRule::Gamma;
134 gamma_rule.gamma = gamma;
135 return epsilon_with_conv(epsilon, gamma_rule);
136 }
137 LRPRuleConfig config{epsilon};
138 if (!*first_conv_seen) {
139 *first_conv_seen = true;
140 config.rule = LRPRule::ZBox;
141 config.low = low;
142 config.high = high;
143 } else {
144 config.rule = LRPRule::Gamma;
145 config.gamma = gamma;
146 }
147 return config;
148 };
149}
150
151} // namespace lrp_composite
152
168class LRP {
169public:
171 [[nodiscard]] static const ExplainerCapabilities& capabilities() { return ExplainerCapabilitiesOf("LRP"); }
172
174 explicit LRP(LRPRuleConfig config = LRPRuleConfig{}) : config_(config) {}
175
180 explicit LRP(LRPComposite composite, std::string name = "custom")
181 : config_(), composite_(std::move(composite)), composite_name_(std::move(name)) {
182 if (!composite_) {
183 throw std::invalid_argument("LRP: composite must not be empty");
184 }
185 }
186
188 [[nodiscard]] static LRP epsilon_plus(float epsilon = 1e-6f) {
189 return LRP(lrp_composite::epsilon_plus(epsilon), "epsilon_plus");
190 }
192 [[nodiscard]] static LRP epsilon_gamma_box(float low, float high, float gamma = 0.25f, float epsilon = 1e-6f) {
193 return LRP(lrp_composite::epsilon_gamma_box(low, high, gamma, epsilon), "epsilon_gamma_box");
194 }
196 [[nodiscard]] static LRP epsilon_alpha2_beta1(float epsilon = 1e-6f) {
197 return LRP(lrp_composite::epsilon_alpha2_beta1(epsilon), "epsilon_alpha2_beta1");
198 }
199
201 [[nodiscard]] Attribution explain(ExplainerContext& ctx, const Tensor& input, int64_t target_index,
202 DeviceBackend* backend) const {
203 return explain(ctx, input, LRPTarget{{target_index}}, backend);
204 }
205
218 [[nodiscard]] Attribution explain(ExplainerContext& ctx, const Tensor& input, const LRPTarget& target,
219 DeviceBackend* backend) const {
220 float relevance_out_sum = 0.0f;
221 Tensor seed_tensor = seed_relevance(ctx, input, target, backend, &relevance_out_sum);
222 const std::vector<LRPRuleConfig> configs = rule_configs(ctx);
223 std::string rules;
224 for (size_t i = 0; i < configs.size(); ++i) {
225 rules += (i == 0 ? "" : ",") + lrp_rule_name(configs[i].rule);
226 }
227 Tensor relevance = ctx.relevance_pass(seed_tensor, configs);
228 const float relevance_in_sum =
229 relevance.backend()->sum(relevance.data(), static_cast<size_t>(relevance.numel()));
230
231 return Attribution{"lrp",
232 std::move(relevance),
233 {{"rule", composite_ ? "composite:" + composite_name_ : lrp_rule_name(config_.rule)},
234 {"rules", rules},
235 {"epsilon", std::to_string(config_.epsilon)},
236 {"seed", target.seed == LRPSeed::OutputValue ? "output_value" : "one_hot"},
237 {"targets", join(target.targets)},
238 {"contrasts", join(target.contrasts)},
239 {"relevance_out_sum", std::to_string(relevance_out_sum)},
240 {"relevance_in_sum", std::to_string(relevance_in_sum)}}};
241 }
242
250 [[nodiscard]] Tensor seed_relevance(ExplainerContext& ctx, const Tensor& input, const LRPTarget& target, DeviceBackend* backend,
251 float* relevance_out_sum = nullptr) const {
252 Tensor output = ctx.forward_pass(input);
253 if (output.rank() != 2) {
254 throw std::invalid_argument("LRP::explain: network output must be rank-2 (N, num_classes)");
255 }
256 const int64_t N = output.shape().dim(0);
257 const int64_t C = output.shape().dim(1);
258 const std::vector<int64_t> targets = per_row(target.targets, N, C, "targets");
259 const std::vector<int64_t> contrasts =
260 target.contrasts.empty() ? std::vector<int64_t>{} : per_row(target.contrasts, N, C, "contrasts");
261 for (size_t n = 0; n < contrasts.size(); ++n) {
262 if (contrasts[n] == targets[n]) {
263 throw std::invalid_argument(
264 "LRP::explain: a row's contrast equals its target (the seed would be zero)");
265 }
266 }
267
268 // Seed on the host, then upload: valid whatever device the output lives on.
269 std::vector<float> y;
270 if (target.seed == LRPSeed::OutputValue) {
271 y.resize(static_cast<size_t>(N * C));
272 output.backend()->copy(y.data(), output.data(), y.size() * sizeof(float),
275 }
276 auto seed_value = [&](int64_t n, int64_t c) {
277 return target.seed == LRPSeed::OutputValue ? y[static_cast<size_t>(n * C + c)] : 1.0f;
278 };
279 std::vector<float> seed(static_cast<size_t>(N * C), 0.0f);
280 float out_sum = 0.0f;
281 for (int64_t n = 0; n < N; ++n) {
282 const int64_t t = targets[static_cast<size_t>(n)];
283 seed[static_cast<size_t>(n * C + t)] = seed_value(n, t);
284 out_sum += seed_value(n, t);
285 if (!contrasts.empty()) {
286 const int64_t c = contrasts[static_cast<size_t>(n)];
287 seed[static_cast<size_t>(n * C + c)] = -seed_value(n, c);
288 out_sum -= seed_value(n, c);
289 }
290 }
291 if (relevance_out_sum != nullptr) *relevance_out_sum = out_sum;
292 return Tensor(output.shape(), backend, seed, output.device());
293 }
294
296 [[nodiscard]] std::vector<LRPRuleConfig> rule_configs(const ExplainerContext& ctx) const {
297 std::vector<LRPRuleConfig> configs;
298 configs.reserve(ctx.modules().size());
299 for (size_t i = 0; i < ctx.modules().size(); ++i) {
300 configs.push_back(composite_ ? composite_(i, *ctx.modules()[i]) : config_);
301 }
302 return configs;
303 }
304
306 [[nodiscard]] const LRPRuleConfig& config() const { return config_; }
307
309 [[nodiscard]] const LRPComposite& composite() const { return composite_; }
310
311private:
312 // Expands a 1-entry list to N rows and validates every index against C classes.
313 static std::vector<int64_t> per_row(const std::vector<int64_t>& indices, int64_t N, int64_t C,
314 const char* what) {
315 if (indices.size() != 1 && static_cast<int64_t>(indices.size()) != N) {
316 throw std::invalid_argument(std::string("LRP::explain: ") + what +
317 " must have 1 entry or one per row of the output");
318 }
319 std::vector<int64_t> rows(static_cast<size_t>(N));
320 for (int64_t n = 0; n < N; ++n) {
321 const int64_t index = indices.size() == 1 ? indices[0] : indices[static_cast<size_t>(n)];
322 if (index < 0 || index >= C) {
323 throw std::invalid_argument(std::string("LRP::explain: ") + what + " index out of range");
324 }
325 rows[static_cast<size_t>(n)] = index;
326 }
327 return rows;
328 }
329
330 static std::string join(const std::vector<int64_t>& v) {
331 std::string out;
332 for (size_t i = 0; i < v.size(); ++i) {
333 out += (i == 0 ? "" : ",") + std::to_string(v[i]);
334 }
335 return out;
336 }
337
338 LRPRuleConfig config_;
339 LRPComposite composite_;
340 std::string composite_name_;
341};
342
343} // namespace pulsatrix
First-class explanation result type – values, method, and metadata together.
2D convolution, batched (input/output are rank-4: N x channels x H x W) – migrated from the original ...
Definition conv2d_module.hpp:31
Vendor-agnostic compute/memory backend. CPUBackend, CUDABackend (Phase 1.5), and HIPBackend (Phase 1....
Definition device_backend.hpp:248
virtual float sum(const float *in, size_t n)=0
sum_i in[i], returned to the host. Same reduction order as dot(). Synchronizes.
virtual void copy(void *dst, const void *src, size_t bytes, CopyDirection dir)=0
Copies bytes between buffers.
Wraps an ordered chain of Modules, running them via Module::forward_traced to build a real Computatio...
Definition explainer_context.hpp:67
Tensor forward_pass(const Tensor &input)
Runs the full module chain forward, building a fresh graph and caching every node's activation value ...
Definition explainer_context.hpp:95
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 propaga...
Definition explainer_context.hpp:234
const std::vector< Module * > & modules() const
The module chain, in forward order (not owned).
Definition explainer_context.hpp:306
Whole-model LRP: runs the forward pass, seeds relevance at the chosen output(s), and propagates it to...
Definition lrp.hpp:168
static const ExplainerCapabilities & capabilities()
What it answers and needs: its ExplainerCatalog() entry.
Definition lrp.hpp:171
LRP(LRPRuleConfig config=LRPRuleConfig{})
Uniform rule: every module applies config.
Definition lrp.hpp:174
static LRP epsilon_alpha2_beta1(float epsilon=1e-6f)
Zennit EpsilonAlpha2Beta1 preset (lrp_composite::epsilon_alpha2_beta1).
Definition lrp.hpp:196
LRP(LRPComposite composite, std::string name="custom")
Per-layer rules from a composite; name is reported as "composite:<name>".
Definition lrp.hpp:180
Tensor seed_relevance(ExplainerContext &ctx, const Tensor &input, const LRPTarget &target, DeviceBackend *backend, float *relevance_out_sum=nullptr) const
The first half of explain(): runs the forward pass and builds the relevance it seeds at the output,...
Definition lrp.hpp:250
std::vector< LRPRuleConfig > rule_configs(const ExplainerContext &ctx) const
The rule each of ctx's modules applies, in forward order, as explain() uses them.
Definition lrp.hpp:296
static LRP epsilon_plus(float epsilon=1e-6f)
Zennit EpsilonPlus preset (lrp_composite::epsilon_plus).
Definition lrp.hpp:188
static LRP epsilon_gamma_box(float low, float high, float gamma=0.25f, float epsilon=1e-6f)
Zennit EpsilonGammaBox preset (lrp_composite::epsilon_gamma_box).
Definition lrp.hpp:192
const LRPComposite & composite() const
The composite, or an empty function for a uniform-rule LRP.
Definition lrp.hpp:309
Attribution explain(ExplainerContext &ctx, const Tensor &input, const LRPTarget &target, DeviceBackend *backend) const
Explains the given target(s) / contrast(s).
Definition lrp.hpp:218
Attribution explain(ExplainerContext &ctx, const Tensor &input, int64_t target_index, DeviceBackend *backend) const
Explains target_index for every row, OutputValue seed.
Definition lrp.hpp:201
const LRPRuleConfig & config() const
The uniform config (default-constructed when this LRP uses a composite).
Definition lrp.hpp:306
Base class for every layer type (LinearModule, Conv2DModule, activations, ...).
Definition module.hpp:78
int64_t dim(size_t index) const
Size of a single dimension.
Definition shape.hpp:93
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
int64_t rank() const
Number of dimensions – shape().rank().
Definition tensor.hpp:119
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
const float * data() const
Raw buffer access. nullptr iff numel() == 0.
Definition tensor.hpp:167
2D convolution – implemented via im2col + DeviceBackend::gemm (no new backend primitive).
Abstract interface isolating vendor-specific memory/compute operations from Tensor/ComputationGraph.
What each explainer answers: the nine question categories (Liao, Gruen and Miller,...
Stable interface every explainer gets, regardless of type (charter Part 2 SS2).
Dense/fully-connected layer – the reference Module implementation.
Selects which LRP rule variant a Module::propagate_relevance() call uses.
LRPRuleConfig alpha_beta(float alpha, float beta, float epsilon)
Definition lrp.hpp:79
bool is_conv(const Module &module)
Definition lrp.hpp:73
LRPRuleConfig zennit_epsilon(float epsilon)
Definition lrp.hpp:74
LRPComposite epsilon_gamma_box(float low, float high, float gamma=0.25f, float epsilon=1e-6f)
Zennit EpsilonGammaBox: ZBox(low, high) for the first Conv2D layer (lowest index),...
Definition lrp.hpp:125
LRPRuleConfig epsilon_with_conv(float epsilon, const LRPRuleConfig &conv)
Epsilon for this module, and conv for every Conv2D inside it (residual blocks, sequences): Zennit's b...
Definition lrp.hpp:90
LRPComposite epsilon_alpha2_beta1(float epsilon=1e-6f)
Zennit EpsilonAlpha2Beta1: Epsilon for Linear, AlphaBeta(2, 1) for Conv2D, nested ones included.
Definition lrp.hpp:107
LRPComposite epsilon_plus(float epsilon=1e-6f)
Zennit EpsilonPlus: Epsilon for Linear, ZPlus (AlphaBeta 1, 0) for Conv2D, including convolutions ins...
Definition lrp.hpp:98
Definition acquisition_functions.hpp:16
LRPSeed
How LRP seeds relevance at the target output.
Definition lrp.hpp:27
const ExplainerCapabilities & ExplainerCapabilitiesOf(std::string_view name)
The catalog entry named name.
std::string lrp_rule_name(LRPRule rule)
Lower-case rule name ("epsilon", "gamma", "alpha_beta", "zbox") for messages/metadata.
Definition lrp_rule_config.hpp:50
@ AlphaBeta
Alpha-beta rule (Bach et al. 2015) with alpha - beta == 1; alpha 1, beta 0 is ZPlus.
std::function< LRPRuleConfig(size_t layer_index, const Module &module)> LRPComposite
Per-layer LRP rule choice: maps (top-level module index in forward order, module) to the LRPRuleConfi...
Definition lrp.hpp:59
An explanation result: the raw attribution values, the method that produced them, and any relevant me...
Definition attribution.hpp:23
One explainer's declaration: what it answers and what it needs.
Definition explainer_capabilities.hpp:99
Configuration for LRP relevance propagation: which rule a module applies and its hyperparameters....
Definition lrp_rule_config.hpp:72
float epsilon
Stabilizer added to every rule's denominator: z + epsilon * sign(z), sign(0) = +1.
Definition lrp_rule_config.hpp:74
std::shared_ptr< const LRPRuleConfig > conv_rule
The rule every Conv2DModule applies, wherever it sits, in place of this config (KS-9)....
Definition lrp_rule_config.hpp:110
bool epsilon_bias_in_denominator
Epsilon rule only, honoured by LinearModule / Conv2DModule: include the bias in the denominator,...
Definition lrp_rule_config.hpp:92
LRPRule rule
Which rule to apply.
Definition lrp_rule_config.hpp:76
What LRP explains: one target class (and optionally one contrast class) per row of the network's (N,...
Definition lrp.hpp:44
std::vector< int64_t > contrasts
Definition lrp.hpp:46
LRPSeed seed
Definition lrp.hpp:47
std::vector< int64_t > targets
Definition lrp.hpp:45
N-dimensional tensor – owns a buffer via DeviceBackend*, RAII (Rule of Five).