Pulsatrix¶
Pulsatrix is a C++17 deep learning library built around explainability. Every layer implements Layer-wise Relevance Propagation (LRP) next to its forward and backward pass, so any network you build can explain its own predictions. On the tested MLP, CNN and attention models, the LRP results match the Zennit and LXT reference libraries to float32 precision, and the heatmaps of torchvision's pretrained ResNet18 and VGG16 match Zennit's.
New here? Start with Getting Started to build the library and run your first example, then try a recipe.
What's in the library¶
Deep Learning Modules and Layers: tensors, autograd and
optimizers; linear, convolution, normalization and pooling layers; RNN/LSTM/GRU, attention,
TransformerBlock, Mamba, RetNet and RWKV; VAE, GAN and diffusion building blocks; and
torchvision's ResNet and VGG, which load the published ImageNet weights. The
training stack has AdamW with parameter groups, learning-rate schedules, gradient clipping,
token-accurate gradient accumulation and parameter freezing. Models save and load as
safetensors or as checkpoints with optimizer state; PyTorch .pt/.pth files convert to
safetensors with a safe converter; and set_seed makes runs reproducible. Runs on CPU, CUDA or
HIP/ROCm.
Data Loading, Transformation & Validation: Dataset and
DataLoader with readers for CSV, images, text, audio and video frames, plus dataset
statistics and outlier checks. Tokenizers load from a Hugging Face tokenizer.json and return
offsets back into the text, and token scores can be merged into word scores.
Language Models: load Llama, SmolLM2, Qwen2/2.5, Qwen3 and Gemma 3 models
from the Hugging Face Hub, generate text, and explain each prediction per token or per word with
AttnLRP. Logits, token ids and explanations are checked against transformers, tokenizers
and LXT, and pulsatrix_explain_text turns a prompt into an explanation figure in one command.
Protein Language Models: load ESM-2 protein language models (8M to 650M parameters) from the Hugging Face Hub, read their per-residue representations and attention maps, score mutations zero-shot, predict contacts and check them against PDB and mmCIF structures, and explain their predictions.
Interpretability: explain a trained model's predictions.
- Layer-wise Relevance Propagation: Epsilon, Gamma, AlphaBeta and ZBox rules, Zennit's composite presets, and AttnLRP/MambaLRP for attention and state-space layers. AttnLRP matches LXT on real language models.
- Model-agnostic explainers: KernelSHAP, LIME, partial dependence, ICE and ALE, sensitivity analysis, Anchors, a global surrogate tree, prototypes and ProtoDash.
- Gradient-based explainers: Saliency, Integrated Gradients, Grad-CAM, counterfactuals, and pertinent negatives and positives (CEM).
- Checking an explanation: deletion and insertion curves (with ROAD), the model-parameter randomization test, sensitivity to small and adversarial perturbations, sparseness and complexity, and a random-model baseline that shows whether an explanation depends on what the model learned.
- Planning and reporting: name the question and the reason, and pulsatrix picks the explainers, runs the checks the reason requires, and reports what the explanation does and doesn't support.
- Performance: accuracy, log loss, the Brier score, calibration with a reliability diagram, the error on each slice of the data, tested against the rest, uncertainty from Monte Carlo dropout and deep ensembles, and conformal prediction sets and intervals with a coverage guarantee.
Reinforcement Learning: CartPole environments, replay and rollout buffers, and DQN, REINFORCE, A2C, PPO and SAC. Each algorithm's tests train it to a fixed score on CartPole.
Mechanistic Interpretability: look inside a network. - Read activations with hooks, patch them, and apply the logit lens. - Compare and describe representations: CKA, RSA, SVCCA and mutual nearest neighbors across layers and models; anisotropy, effective rank and intrinsic dimension; PCA plots, and export for UMAP and t-SNE. - Measure the shape of a layer with persistent homology: its clusters, loops and voids, with certified error bars, significance tests, and RTD to compare two layers' topology. - Test for named concepts with linear probes and their controls, and with TCAV. - Find features with sparse autoencoders (TopK, BatchTopK, Matryoshka, JumpReLU), block-sparse featurizers and transcoders, and evaluate them against random-model baselines. - Steer a model, with a report that shows whether the steering is real. - Diff a model against its fine-tune with crosscoders. - Decompose a network's weights into mechanisms (SPD, VPD). - Trace attribution graphs of a language model's prediction through transcoder features, for Neuronpedia's viewer.
Each method reports what it found on real models, including what didn't work. The section also covers GFlowNets.
Neuro-Symbolic Reasoning: differentiable fuzzy logic you can train with gradient descent, and a Datalog engine that traces relevance from a logical conclusion back into a neural network.
Evolutionary Computation: genetic algorithms, NSGA-II, NEAT, Evolution Strategies, CMA-ES, Population Based Training and E-GAN.
Hyperparameter Optimization: grid and random search, Bayesian optimization (Gaussian process and TPE), and early stopping with Successive Halving, Hyperband and ASHA.
Visualization: versioned JSON documents for explanations,
heatmaps, token relevance, circuit graphs and training logs; dependency-free SVG charts
(including token and word relevance for text), interactive HTML pages with hover, zoom and
export, attribution graphs for Neuronpedia's and circuit-tracer's viewers, and the
pulsatrix_svg tool; notebooks and reports written as .ipynb or
HTML from C++; and, optionally, native Dear ImGui + ImPlot windows with a live training dashboard and a
token relevance view.
LLM Agents (optional): talk to Claude or to a local model served by
llama-server, vLLM or Ollama from C++, with streaming and retries, and let it call your
functions as tools. A tool registry checks each input against its JSON Schema before your
function runs. No Python or SDK; turn it on with -DPULSATRIX_ENABLE_ORCHESTRATOR=ON.
System Monitoring: log CPU/GPU utilization, memory and temperatures while you train.
GPU Profiling and Benchmarks: per-op GPU kernel
times with scripts/profile_hip.sh, and pulsatrix_bench for step time, explanation time and
LRP conservation, with an A/B comparison between two builds.
Python bindings: Tensor, the core layers, LRP and the other explainers, and seeding from
Python. See Getting Started.
Everything is implemented in C++ with no Python dependency at runtime, and covered by about 3,050 CPU tests (3,150 with the HIP backend) that run in CI on Windows and Linux.
More resources¶
- Using pulsatrix in your project:
cmake --installandfind_package(pulsatrix). - Customization: add your own layers, metrics sinks or device backends.
- API Reference: the Doxygen reference for every class and function.
- Examples: demo programs on GitHub.