Skip to content

Pulsatrix

Pulsatrix

CI

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