integrated_gradients.hpp

Go to the documentation of this file.

 
#pragma once
 
#include <stdexcept>
#include <string>
#include <vector>
 
#include "pulsatrix/assert.hpp"
#include "pulsatrix/attribution.hpp"
#include "pulsatrix/device_backend.hpp"
#include "pulsatrix/explainer_context.hpp"
#include "pulsatrix/saliency.hpp"
#include "pulsatrix/tensor.hpp"
 
namespace pulsatrix {
 
class IntegratedGradients {
public:
    [[nodiscard]] Attribution explain(ExplainerContext& ctx, const Tensor& input, const Tensor& baseline,
                                       int64_t target_index, int64_t steps, DeviceBackend* backend) const {
        // External boundary (Mission 2, finding 15 systemic sweep) -- escalated from
        // PULSATRIX_ASSERT-only.
        if (steps <= 0) {
            throw std::invalid_argument("IntegratedGradients::explain: steps must be positive");
        }
        if (input.numel() != baseline.numel()) {
            throw std::invalid_argument("IntegratedGradients::explain: input and baseline must have the same numel");
        }
 
        Saliency saliency;
        DeviceBackend* input_backend = explainer_detail::backend_beside(input, backend);
        Tensor accumulated_grad(input.shape(), input_backend, input.device());  // zero-initialized
 
        const std::vector<float> input_values = input.to_host_vector();
        const std::vector<float> baseline_values = baseline.to_host_vector();
        const auto numel = static_cast<size_t>(input.numel());
 
        std::vector<float> interpolated_values(numel);
        for (int64_t k = 1; k <= steps; ++k) {
            float alpha = static_cast<float>(k) / static_cast<float>(steps);
            for (size_t i = 0; i < numel; ++i) {
                interpolated_values[i] = baseline_values[i] + alpha * (input_values[i] - baseline_values[i]);
            }
            Tensor interpolated(input.shape(), input_backend, interpolated_values, input.device());
 
            Attribution step = saliency.explain(ctx, interpolated, target_index, backend);
            accumulated_grad.accumulate(step.values);
        }
 
        const std::vector<float> accumulated = accumulated_grad.to_host_vector();
        std::vector<float> ig(numel);
        for (size_t i = 0; i < numel; ++i) {
            float avg_grad = accumulated[i] / static_cast<float>(steps);
            ig[i] = (input_values[i] - baseline_values[i]) * avg_grad;
        }
        Tensor ig_values(input.shape(), input_backend, ig, input.device());
 
        return Attribution{"integrated_gradients", std::move(ig_values),
                            {{"steps", std::to_string(steps)}, {"target_index", std::to_string(target_index)}}};
    }
};
 
}  // namespace pulsatrix