pulsatrix 1.1.0
Loading...
Searching...
No Matches
circuit_tracing.hpp
Go to the documentation of this file.
1
11#pragma once
12
13#include <cstdint>
14#include <string>
15#include <vector>
16
18#include "pulsatrix/tensor.hpp"
20
21namespace pulsatrix {
22
37public:
40
48 void set_layer(int64_t layer, Tensor w_enc, std::vector<float> b_enc, std::vector<float> threshold, std::vector<Tensor> w_dec);
50 void set_output_bias(int64_t layer, std::vector<float> b_dec);
52 void set_skip(int64_t layer, Tensor w_skip);
53
54 [[nodiscard]] int64_t num_layers() const { return L_; }
55 [[nodiscard]] int64_t d_model() const { return d_; }
56 [[nodiscard]] int64_t num_features(int64_t layer) const;
58 [[nodiscard]] int64_t span(int64_t layer) const;
59 [[nodiscard]] bool has_skip(int64_t layer) const;
60
62 [[nodiscard]] std::vector<float> preactivations(int64_t layer, const Tensor& x) const;
64 [[nodiscard]] std::vector<float> encode(int64_t layer, const Tensor& x) const;
71 [[nodiscard]] std::vector<float> reconstruct(int64_t layer, const std::vector<std::vector<float>>& activations, const Tensor* mlp_input) const;
72
74 [[nodiscard]] std::vector<float> encoder_row(int64_t layer, int64_t f) const;
75 [[nodiscard]] std::vector<float> decoder_row(int64_t layer, int64_t f, int64_t out_layer) const;
76 [[nodiscard]] const Tensor& encoder(int64_t layer) const;
77 [[nodiscard]] const Tensor& decoder(int64_t layer, int64_t out_layer) const;
78 [[nodiscard]] const Tensor& skip(int64_t layer) const;
79 [[nodiscard]] DeviceBackend* backend() const { return backend_; }
80
81private:
82 struct Layer {
83 Tensor w_enc;
84 std::vector<float> b_enc, threshold, b_dec;
85 std::vector<Tensor> w_dec;
86 std::vector<Tensor> w_skip;
87 };
88 int64_t L_, d_;
89 DeviceBackend* backend_;
90 std::vector<Layer> layers_;
91};
92
105[[nodiscard]] CrossLayerTranscoder LoadTranscoders(const std::string& directory, int64_t num_layers, DeviceBackend* backend);
106
110 int64_t max_logits = 10;
111 double logit_probability = 0.95;
114 int64_t skip_positions = 1;
116 int64_t batch = 64;
118 double node_threshold = 0.8;
119 double edge_threshold = 0.98;
120 std::string slug = "pulsatrix-clt-graph";
121 std::string scan = "pulsatrix";
122 std::string prompt;
124 std::vector<std::string> prompt_tokens;
125};
126
138 struct Feature {
139 int64_t layer = 0, position = 0, index = 0;
140 float activation = 0;
141 };
142 std::vector<Feature> features;
143 int64_t num_layers = 0, num_positions = 0;
144 std::vector<int64_t> tokens;
146 std::vector<int64_t> logit_tokens;
147 std::vector<double> logit_probabilities;
150 std::vector<double> target_values;
151 std::vector<double> adjacency;
152
153 [[nodiscard]] int64_t num_nodes() const;
154 [[nodiscard]] int64_t error_node(int64_t layer, int64_t position) const;
155 [[nodiscard]] int64_t token_node(int64_t position) const;
156 [[nodiscard]] int64_t logit_node(int64_t k) const;
157};
158
173[[nodiscard]] CircuitTrace TraceCircuit(CausalLM& model, const CrossLayerTranscoder& transcoder, const std::vector<int64_t>& ids,
174 const CircuitTraceOptions& options = {});
175
179 double replacement = 0;
181 double completeness = 0;
182};
184[[nodiscard]] CircuitScores ScoreCircuit(const CircuitTrace& trace);
185
194[[nodiscard]] AttributionGraph ToAttributionGraph(const CircuitTrace& trace, const CircuitTraceOptions& options,
195 const std::vector<std::string>& logit_labels = {});
196
197} // namespace pulsatrix
Attribution graphs in the JSON that Neuronpedia's graph viewer and circuit-tracer's local viewer read...
A Llama-family decoder-only language model built from a Hugging Face config, and loading its Hugging ...
Token embedding, num_hidden_layers pre-norm transformer blocks, a final RMSNorm and a language-model ...
Definition causal_lm.hpp:82
A cross-layer transcoder (CLT) over a model's L MLPs, or a set of per-layer transcoders (PLTs,...
Definition circuit_tracing.hpp:36
void set_skip(int64_t layer, Tensor w_skip)
A linear skip from layer layer's MLP input to its output, (d, d).
std::vector< float > reconstruct(int64_t layer, const std::vector< std::vector< float > > &activations, const Tensor *mlp_input) const
Layer layer's MLP output as the transcoder predicts it, (rows, d) on the host: every earlier layer's ...
std::vector< float > encode(int64_t layer, const Tensor &x) const
The activations: JumpReLU (or ReLU) of the pre-activations.
const Tensor & skip(int64_t layer) const
int64_t num_layers() const
Definition circuit_tracing.hpp:54
DeviceBackend * backend() const
Definition circuit_tracing.hpp:79
void set_output_bias(int64_t layer, std::vector< float > b_dec)
The decoder bias of layer layer's MLP output, d values (zero by default).
std::vector< float > encoder_row(int64_t layer, int64_t f) const
Feature f of layer layer: its encoder row and its decoder into out_layer, d each.
int64_t num_features(int64_t layer) const
std::vector< float > preactivations(int64_t layer, const Tensor &x) const
Pre-activations x W_encᵀ + b_enc, (rows, F) on the host, for x (rows, d).
int64_t span(int64_t layer) const
How many layers layer layer's features write to (1 for a PLT).
bool has_skip(int64_t layer) const
int64_t d_model() const
Definition circuit_tracing.hpp:55
void set_layer(int64_t layer, Tensor w_enc, std::vector< float > b_enc, std::vector< float > threshold, std::vector< Tensor > w_dec)
Sets layer layer's features.
CrossLayerTranscoder(int64_t num_layers, int64_t d_model, DeviceBackend *backend)
const Tensor & decoder(int64_t layer, int64_t out_layer) const
std::vector< float > decoder_row(int64_t layer, int64_t f, int64_t out_layer) const
const Tensor & encoder(int64_t layer) const
Vendor-agnostic compute/memory backend. CPUBackend, CUDABackend (Phase 1.5), and HIPBackend (Phase 1....
Definition device_backend.hpp:248
N-dimensional tensor. Owns its data buffer exclusively; a DeviceBackend* is injected (not owned) – th...
Definition tensor.hpp:29
Definition acquisition_functions.hpp:16
CircuitScores ScoreCircuit(const CircuitTrace &trace)
Circuit-tracer's replacement and completeness scores (graph.py).
CrossLayerTranscoder LoadTranscoders(const std::string &directory, int64_t num_layers, DeviceBackend *backend)
Loads transcoders from a directory in one of the layouts circuit-tracer reads, with bf16/fp16 weights...
AttributionGraph ToAttributionGraph(const CircuitTrace &trace, const CircuitTraceOptions &options, const std::vector< std::string > &logit_labels={})
The graph for Neuronpedia's or circuit-tracer's viewer, pruned as circuit-tracer prunes: nodes by ind...
CircuitTrace TraceCircuit(CausalLM &model, const CrossLayerTranscoder &transcoder, const std::vector< int64_t > &ids, const CircuitTraceOptions &options={})
Runs the model on ids (one sequence) with transcoder in place of its MLPs, and attributes the salient...
An attribution graph as Neuronpedia's schema (graph-schema.json) and circuit-tracer's create_graph_fi...
Definition attribution_graph.hpp:26
Circuit-tracer's scores of a graph.
Definition circuit_tracing.hpp:177
double completeness
Influence-weighted share of each node's incoming attribution that isn't from errors.
Definition circuit_tracing.hpp:181
double replacement
Influence reaching the logits from token embeddings, over that from tokens and errors.
Definition circuit_tracing.hpp:179
Definition circuit_tracing.hpp:107
double edge_threshold
Definition circuit_tracing.hpp:119
double node_threshold
Node and edge pruning (circuit-tracer's defaults). 1 keeps everything.
Definition circuit_tracing.hpp:118
std::vector< std::string > prompt_tokens
One per token, for the viewer; empty: the ids as text.
Definition circuit_tracing.hpp:124
int64_t skip_positions
Positions whose features and errors are left out, from the start (circuit-tracer zeroes the first: BO...
Definition circuit_tracing.hpp:114
std::string scan
Definition circuit_tracing.hpp:121
std::string prompt
Definition circuit_tracing.hpp:122
std::string slug
Definition circuit_tracing.hpp:120
double logit_probability
Definition circuit_tracing.hpp:111
int64_t batch
Targets per frozen backward pass.
Definition circuit_tracing.hpp:116
int64_t max_logits
Logits explained: the most likely, up to this many, until their probabilities sum to logit_probabilit...
Definition circuit_tracing.hpp:110
Definition circuit_tracing.hpp:138
float activation
Definition circuit_tracing.hpp:140
int64_t layer
Definition circuit_tracing.hpp:139
int64_t index
Definition circuit_tracing.hpp:139
int64_t position
Definition circuit_tracing.hpp:139
An attribution graph before pruning: every active feature, error and token, the explained logits,...
Definition circuit_tracing.hpp:137
std::vector< int64_t > logit_tokens
The explained logits' token ids and probabilities.
Definition circuit_tracing.hpp:146
int64_t token_node(int64_t position) const
int64_t num_positions
Definition circuit_tracing.hpp:143
std::vector< double > adjacency
Definition circuit_tracing.hpp:151
std::vector< Feature > features
Definition circuit_tracing.hpp:142
int64_t logit_node(int64_t k) const
std::vector< double > target_values
Each target's value with the frozen model: the pre-activation without b_enc, or the logit minus the m...
Definition circuit_tracing.hpp:150
std::vector< int64_t > tokens
Definition circuit_tracing.hpp:144
int64_t num_layers
Definition circuit_tracing.hpp:143
int64_t num_nodes() const
int64_t error_node(int64_t layer, int64_t position) const
std::vector< double > logit_probabilities
Definition circuit_tracing.hpp:147
N-dimensional tensor – owns a buffer via DeviceBackend*, RAII (Rule of Five).