pulsatrix 1.1.0
Loading...
Searching...
No Matches
pulsatrix Namespace Reference

Namespaces

namespace  datalog
 
namespace  detail
 
namespace  explainer_detail
 Shared helpers for the post-hoc explainers' host boundary.
 
namespace  lrp_composite
 Zennit 1.0.0's composite presets (zennit.composites), mapped onto pulsatrix modules by type: LinearModule = torch Linear, Conv2DModule = torch Conv2d; every other module gets the epsilon rule (the pass-through modules – ReLU, Flatten, Dropout, MaxPool – ignore it, as Zennit's Pass rule / plain gradient does).
 
namespace  orch
 
namespace  param_select
 Common selectors.
 

Classes

struct  AbsorptionOptions
 
struct  AbsorptionResult
 FeatureAbsorption()'s result, on the held-out inputs. More...
 
class  ActivationModule
 y = f(x), elementwise, for one of the backend's activations. No parameters. More...
 
class  ActivationSnapshot
 A copyable, self-contained record of every activation cached during one forward pass, plus the node ids in topological order and each node's op_type/label metadata. More...
 
class  AdamOptimizer
 Adam (Kingma & Ba, 2015): per-parameter moving averages of gradient (m) and squared gradient (v), with bias correction. More...
 
struct  AdamTensorStep
 One parameter tensor's share of DeviceBackend::adam_step_multi (HIP-6): its buffers and its own step's scalars. More...
 
class  AdamWOptimizer
 AdamW (Loshchilov & Hutter, "Decoupled Weight Decay Regularization", arXiv 1711.05101): Adam whose weight decay shrinks the weights directly, w <- (1 - lr * wd) * w, before the Adam step, instead of adding wd * w to the gradient (roadmap TRN-2). More...
 
class  AdaptiveAvgPool2DModule
 Pools a rank-4 (N, C, H, W) input to (N, C, out_h, out_w), as AdaptiveAvgPool2d((out_h, out_w)): ResNet's global pooling is (1, 1), VGG's is (7, 7). More...
 
struct  AddedToken
 A token matched in the raw input before anything else runs, such as <|im_start|>. More...
 
class  Agent
 Base class for anything that maps an observation to an action. More...
 
class  AggregatorModule
 y = (mean(x^p))^(1/p), reduced over the leading (batch/grounding) axis – not the last axis. Rank-agnostic: input shape (N, ...rest) reduces to output shape (...rest) (rank 0 – a scalar – when input is rank 1, i.e. a single formula's groundings with no other axes). More...
 
struct  AgreementOptions
 CompareExplanations()'s settings. More...
 
struct  AgreementReport
 CompareExplanations()'s result. More...
 
struct  AleResult
 First-order accumulated local effects (Apley and Zhu 2020) of one feature. More...
 
struct  Anchor
 FindAnchor()'s result. More...
 
struct  AnchorOptions
 FindAnchor's settings. The defaults are the reference implementation's, except a beam of 2 and epsilon_stop. More...
 
struct  AnchorPredicate
 lower < x[feature] <= upper; a missing side is infinite. More...
 
struct  AnnotatedProtein
 
class  AsciiLowercase
 Lowercases ASCII letters and leaves every other character alone. More...
 
struct  ASHAResult
 The best configuration/metric found, the total epoch budget spent, and how many distinct configurations were ever started (as opposed to promoted). More...
 
struct  AssayResult
 One assay's result. More...
 
struct  AttackOptions
 Settings for Fgsm() and Pgd(). More...
 
struct  AttackResult
 One attack's result. More...
 
struct  AttentionConfig
 Everything that shapes a MultiHeadAttentionModule (LLM-1). More...
 
struct  AttentionHead
 One attention head: layer from 0, head within it from 0. More...
 
class  AttentionTransferLoss
 Attention transfer: mean over examples and positions of (q_s − q_t)², where q is the L2-normalized map mean_c |A_c|^p of each example's features. More...
 
struct  AttnLrpReport
 A model's comparison against an AttnLRP reference file. More...
 
struct  AttnLrpSequenceResult
 One reference sequence's comparison. More...
 
struct  Attribution
 An explanation result: the raw attribution values, the method that produced them, and any relevant metadata (charter Part 2 SS4). More...
 
class  AttributionBarChart
 Draws a horizontal bar chart of an Attribution's top-k features (hc_information_visualization.md SS1/SS5: position-on-shared-axis is the most accurately perceived encoding for magnitude – Cleveland-McGill rank 1 – and horizontal bars read naturally with long feature names). Bar length encodes magnitude; hue (DivergingColormap) encodes sign, never magnitude. Bars start at zero (Tufte lie-factor = 1). More...
 
class  AttributionBeeswarmView
 Draws a beeswarm plot for one feature's attribution values across many samples/predictions – the global "how does the model behave overall" view (hc_information_visualization.md SS5), complementing AttributionBarChart's single-prediction "why this one" view. More...
 
struct  AttributionDocument
 pulsatrix.attribution.v1: an Attribution's values, shape, method and metadata. More...
 
struct  AttributionGraph
 An attribution graph as Neuronpedia's schema (graph-schema.json) and circuit-tracer's create_graph_files describe it. More...
 
struct  AttributionNullReport
 NullModelBaseline() for an explanation of one input. More...
 
class  AttributionWaterfallChart
 Draws a waterfall chart cascading from baseline_value to the final prediction (hc_information_visualization.md SS5: "correct for local explanation with directional attribution... bars cascade from base rate to prediction; color encodes direction; length encodes magnitude"). This is the one bar chart in this module that legitimately does not start at zero – Tufte's lie-factor rule is satisfied relative to baseline_value, the meaningful reference point, not zero. More...
 
class  AudioFolderDataset
 Dataset over a directory tree of the form root_dir/<class_name>/<audio_file.wav>, structurally identical to ImageFolderDataset (Phase 2): sorted subdirectory names are classes, sorted filenames within each are samples, decoded lazily per get() via WavReader. More...
 
class  Autograd
 Computes gradients by walking a ComputationGraph in reverse topological order. More...
 
class  AvgPool2DModule
 Average pooling, rank-4 (N, channels, H, W), matching Conv2DModule's convention. Stride fixed equal to kernel size (non-overlapping windows), no padding, no dilation – same minimal-cut discipline as MaxPool2DModule/Conv2DModule. More...
 
struct  BarSeries
 One feature-importance bar: a label and a signed value (sign carries direction). More...
 
struct  Batch
 One collated batch: one stacked Tensor per Sample field position. More...
 
class  BatchNormFold
 While alive, merges bn's affine map into conv's weights and makes bn an exact identity; on destruction, restores both bit for bit. More...
 
class  BatchNormModule
 y_{n,c,h,w} = gamma_c * (x_{n,c,h,w} - mu_c)/std_c + beta_c, mu_c/std_c computed per channel c over every (n, h, w) element jointly – BatchNorm's defining statistic, and the reason this module didn't exist before campaign_exai_dl_library_batch_dimension_support: it has nothing to compute over without a real batch dimension. Input/output are rank-4 (N, channels, H, W), the same convention Conv2DModule/GroupNormModule already establish. More...
 
class  BCEWithLogitsLoss
 loss = mean( max(x,0) - x*y + log(1 + exp(-|x|)) ), over all N*k elements of a (N, k) logit tensor x against a target tensor y of the same shape. More...
 
struct  BeeswarmPoint
 One beeswarm point: the attribution value (x) and a collision-avoidance vertical offset (y). More...
 
struct  BenchmarkComparison
 One record compared across two builds. More...
 
struct  BenchmarkRecord
 One measured quantity. More...
 
struct  BenchmarkReport
 A run of benchmarks: pulsatrix.benchmark.v1. More...
 
struct  BlockGeometry
 Each block's code geometry over x, from the covariance of its codes on the inputs where it is active: stable rank ‖C‖²_F / ‖C‖²_2, participation ratio (tr C)² / ‖C‖²_F and effective rank (the exponential of the eigenvalues' entropy). The paper finds a block's dimension saturates at the concept's (2 to 4 for DINOv3) however large b is. More...
 
class  BlockSparseFeaturizer
 A block-sparse featurizer: G blocks of b directions in a d-dimensional space. Codes are (N, G·b), block g's in columns [g·b, (g+1)·b), signed; the reconstruction is x̂ = z D, D's rows the atoms. A block is active when its codes aren't all zero, and its norm says how strongly; its coordinates say where on the concept's subspace the input is. More...
 
struct  BlockSparseOptions
 
struct  BootstrapBandResult
 BootstrapBand()'s result. More...
 
struct  BootstrapOptions
 BootstrapBand()'s settings. More...
 
class  BoundedQueue
 Fixed-capacity thread-safe queue with blocking push/pop – the bounded buffer between pulsatrix data-pipeline stages (campaign_exai_dl_library_data_pipeline). Not tied to any Dataset/DataLoader type; deliberately generic. More...
 
class  BpeModel
 Byte-pair encoding: start from characters and apply merges, lowest rank first. More...
 
struct  BpeOptions
 BPE options beyond the vocabulary and merges, as tokenizer.json names them. More...
 
class  ByteFallbackDecoder
 Turns runs of <0x41>-style byte tokens back into text; a run that isn't valid UTF-8 becomes one U+FFFD per byte (Hugging Face's ByteFallback decoder). More...
 
class  ByteLevelDecoder
 Maps byte-level characters back to bytes; invalid UTF-8 becomes U+FFFD, as in Hugging Face. More...
 
class  ByteLevelPostProcessor
 Byte-level post-processing (Hugging Face's ByteLevel post-processor): with trim_offsets, each token's offsets leave out the spaces at its edges. More...
 
class  ByteLevelPreTokenizer
 Byte-level pre-tokenization (Hugging Face's ByteLevel): optionally prepends a space, optionally splits with the GPT-2 regex, then maps every byte to a printable character with GPT-2's table, so BPE runs over characters that stand for bytes. More...
 
class  ByteModel
 Every byte is a token whose id is the byte's value (0..255); the token string is the byte itself. More...
 
class  CachingAllocator
 
class  CalibrationLoss
 BS = mean_n( Σ_k (p[n,k] − y[n,k])² ), y one-hot at target_class[n] – Brier's original multi-class proper scoring rule. More...
 
class  CartPoleEnv
 The classic cart-pole balancing task (Barto, Sutton & Anderson 1983), the same equations OpenAI Gym's own CartPoleEnv implements – cited as the canonical, independently-verifiable reference for this class's correctness tests, not reused as a code or runtime dependency. More...
 
class  CategoricalPolicyAgent
 Samples an action from softmax(policy_network(observation)) – the discrete-action stochastic policy every policy-gradient method in this phase (REINFORCE, A2C, PPO) is built on. More...
 
class  CausalLM
 Token embedding, num_hidden_layers pre-norm transformer blocks, a final RMSNorm and a language-model head (tied to the embedding or its own bias-free Linear): the architecture of Llama, SmolLM2, Qwen2/2.5 and Qwen3. Maps (N, L) token ids to (N, L, vocab) logits. More...
 
struct  CausalLmBatch
 A right-padded training batch. More...
 
class  CausalLMStepModel
 A CausalLM with bidirectional attention (an A2D diffusion model, DIFF-4) as a StepRelevanceModel, with the same rules as EncoderLMStepModel. More...
 
struct  Cav
 A concept activation vector. More...
 
struct  Caveat
 One thing the explanation doesn't support, and why. More...
 
struct  CavOptions
 
class  CenterCropTransform
 Crops the centered (crop_height, crop_width) region of the image. More...
 
struct  Certified
 A computed value and a certified bound on its error, itemized by source: the exact value is within bound() of value. More...
 
class  CharModel
 Every character (code point) is a token, looked up in a character list; unknown characters become the unknown token. More...
 
struct  CheckpointLoadOptions
 Options for LoadCheckpoint(). More...
 
struct  CheckResult
 One check's result. More...
 
struct  ChoiceScores
 Scores of single-token choices after each prompt. Indexed [example][choice]. More...
 
struct  CircuitEdge
 One directed edge of a CircuitGraph, carrying a scalar weight. More...
 
class  CircuitGraph
 A copyable, self-contained circuit graph: every node of one forward pass with an ablation importance score, plus the weighted edges between them. More...
 
struct  CircuitGraphDocument
 pulsatrix.circuit_graph.v1: a CircuitGraph's scored nodes and weighted edges. More...
 
class  CircuitGraphView
 Draws a CircuitGraph as a node-link diagram: node position is topological depth (x-axis), node size and color encode ablation_effect via length/area AND Viridis (unsigned magnitude – never hue-for-magnitude, hc_information_visualization.md SS1), edge thickness encodes weight. Each node is captioned with CircuitNodeDisplayLabel (its own label, else op type + id) above and its ablation effect below. More...
 
struct  CircuitNode
 One node of a CircuitGraph: a computation-graph node plus its importance score. More...
 
struct  CircuitScores
 Circuit-tracer's scores of a graph. More...
 
struct  CircuitTrace
 An attribution graph before pruning: every active feature, error and token, the explained logits, and the full adjacency. More...
 
struct  CircuitTraceOptions
 
struct  CkaMatrix
 CKA between every pair from two lists of representations, such as the layers of two models: values[i * cols + j] compares a[i] with b[j]. More...
 
struct  ClassificationOptions
 EvaluateClassifier()'s settings. More...
 
struct  ClassificationReport
 How well a classifier does on a labeled dataset. More...
 
class  ClusterSampler
 Cluster-weighted sampling, as ESM-2 drew UniRef50: a cluster uniformly, then one of its members uniformly, so large families don't dominate. With every sequence its own cluster, it is uniform sampling with replacement. More...
 
class  CMAES
 RNG-driven ask-tell wrapper: caches the z-samples an Ask() call draws so a matching Tell() call can reuse them without the caller needing to track them. More...
 
struct  CMAESState
 This algorithm's full adaptive state: the search mean, the global step size, and each dimension's own variance (the diagonal of the covariance matrix). More...
 
struct  CocycleEntry
 One simplex of a cocycle with its coefficient. More...
 
struct  CommitmentDeletionCurve
 A prompt-deletion curve against its random baseline. More...
 
struct  CommitmentHop
 One step's relevance pass: what went in and where it landed. More...
 
struct  CommitmentPatchResult
 Step-resolved patching against the relevance relayed through each committed token. More...
 
struct  CommitmentRelevance
 Where the relevance of the explained tokens went. Every vector has one value per position. The ledger balances exactly: value = prompt + mask + leak (+ relayed in CommitmentMode::StepLocal, where it is an endpoint). More...
 
struct  CommitmentTarget
 A generated token to explain. More...
 
struct  CompareOptions
 How CompareBenchmarks decides that a candidate got worse. More...
 
struct  ComponentAlignment
 How well a layer's subcomponents line up with its target weight's rows, the input features (SPD's toy-model measure): for each input feature j, the best cosine over c between subcomponent c's row j, V[j, c] U[c, :], and the target's row j (MMCS), and that subcomponent's norm over the target row's (ML2R). More...
 
class  ComponentLinear
 A LinearModule split into C rank-one subcomponents: W ≈ V U, V (in, C) reading the input and U (C, out) writing the output, so subcomponent c is V[:, c] U[c, :] and its inner activation is h_c = (x V)_c. The bias is the target's, frozen. More...
 
class  Compose
 Eager, ordered list of Transforms applied in sequence – pulsatrix's analogue of torchvision.transforms.Compose. Deliberately simple: no fusion/graph, matching Compose's own upstream design; unlike Python, there is no GIL here for that simplicity to cost anything. More...
 
class  ComputationGraph
 Owns every Node in a computation graph and exposes read access for graph-walking code (autograd's backward pass, Phase 2+ explainers). More...
 
class  ConcatDenoiser
 A Module that reads [x_t, embedding(t), c] as one row, conditioned by concatenation as in tests/diffusion_integration_test.cpp: x_t, then a sinusoidal timestep embedding (SinusoidalTimestepEmbedding), then a fixed conditioning vector such as a one-hot class. Its input relevance is split back into those three parts. More...
 
struct  ConceptMask
 Keep the relevance of these channels at this layer, and zero the rest. More...
 
struct  ConceptMatch
 The feature that best matches one concept. More...
 
class  ConfidenceMeter
 Draws a filled bar whose fill length encodes confidence (position/length, never color alone – hc_information_visualization.md SS1/SS5: "confidence bar/meter... fastest to process"). The exact percentage is always rendered as text alongside the fill – never a color-only encoding (also satisfies WCAG: a colorblind user must be able to read the value without relying on hue). More...
 
struct  ConformalClassifier
 A calibrated conformal classifier. More...
 
struct  ConformalOptions
 CalibrateConformalClassifier()'s settings. More...
 
struct  ConformalRegressor
 A calibrated conformal regressor. More...
 
class  ConjunctionModule
 y = a T b for a selected t-norm T, over two independent fuzzy-truth-valued operand tensors (values intended in [0,1]; out-of-range values are not rejected – see propagate_relevance()'s note and mission_0_tnorm_operators.md's adversarial section). More...
 
struct  ConnectionGene
 One connection in a NEAT genome: an edge between two node IDs, its weight, whether it is currently active, and its historical marking (innovation number). Disabled connections are kept, not removed – NEAT's own design, preserving historical alignment for crossover (a future mission's concern, not built here). More...
 
struct  ConservationResult
 The result of comparing a relevance-propagation step's input and output totals. More...
 
struct  ContactEvaluation
 PrecisionAtL in each of the short, medium and long ranges. More...
 
struct  ContactMap
 A square matrix over a sequence's residue pairs, row-major: predicted contact probabilities, distances, or true contacts. More...
 
struct  ContactMapDocument
 pulsatrix.contact_map.v1: predicted contacts between a sequence's residues, and the true ones when a structure is known. Drawn as one square: predictions above the diagonal, the structure below it, with the best predictions marked right or wrong. More...
 
struct  ContactMapViewOptions
 Options for RenderContactMapSvg. More...
 
struct  ContactOptions
 
struct  ContactPrecisions
 Precision of the top L, L/2 and L/5 pairs, L the sequence length (rounded down). More...
 
class  ContactPredictor
 Contacts from a masked LM's attention, the way ESM predicts them: one forward pass over <cls> + the sequence + <eos>, every head's map turned into ContactFeatures, then combined. Each map is used as its layer finishes, so a pass holds one layer's at a time. Sequences are run one at a time, with no padding. More...
 
class  ContinuousCartPoleEnv
 The cart-pole balancing task with a continuous action: the action is a single force fraction in [-1, 1] rather than a discrete left/right choice. More...
 
class  ContinuousDenoiser
 The noise predictor eps_theta as the explainer sees it, with its conditioning fixed: a forward pass that keeps what the relevance pass needs, and the relevance pass. More...
 
struct  ContinuousSamplerConfig
 
struct  ContinuousTrajectory
 A reverse process, recorded so it can be explained: every state and every noise draw. More...
 
struct  ContrastiveOptions
 CEM's settings. The defaults are the paper's MNIST settings, scaled to its 1,000 steps. More...
 
struct  ContrastiveResult
 A pertinent negative or positive. More...
 
class  Conv2DModule
 2D convolution, batched (input/output are rank-4: N x channels x H x W) – migrated from the original unbatched (rank-3) scope by campaign_exai_dl_library_batch_dimension_support. Stride and zero padding are configurable (the same on both axes); there is no dilation. More...
 
struct  ConvGeometry
 Window geometry for DeviceBackend::im2col / col2im_add: kernel size, stride and zero padding per axis. Defaults are stride 1 and no padding. Passed to kernels by value. More...
 
struct  CounterfactualConstraints
 Which changes are allowed, and how changes are measured. More...
 
struct  CounterfactualDocument
 pulsatrix.counterfactual.v1: an input, its counterfactual, and what reaching the target cost (CFS-5). More...
 
struct  CounterfactualOptions
 Search settings. Defaults suit standardized tabular inputs. More...
 
struct  CounterfactualResult
 A counterfactual and how good it is (the DiCE metrics, for one counterfactual). More...
 
struct  CounterfactualTarget
 What the counterfactual must achieve. More...
 
struct  CoverageReport
 How often the sets or intervals held the truth, and how large they were. More...
 
class  CPUBackend
 CPU-resident DeviceBackend implementation. Reference implementation every other backend (CUDABackend, HIPBackend) is checked for numerical equivalence against. More...
 
class  Crosscoder
 A crosscoder over S sources of the same size d. Its input is the sources side by side, (N, S·d), source s in columns [s·d, (s+1)·d): f = ReLU(Σ_s x^s W_enc^s + b_enc), x̂^s = f W_dec^s + b_dec^s. More...
 
struct  CrosscoderLatentStats
 One latent across two sources a and b. More...
 
struct  CrosscoderOptions
 
class  CrossEntropyLoss
 loss = -log(softmax(logits)[target_class]), combined for numerical stability (subtract the max logit before exponentiating) rather than computing softmax and log separately. More...
 
class  CrossLayerTranscoder
 A cross-layer transcoder (CLT) over a model's L MLPs, or a set of per-layer transcoders (PLTs, a CLT whose features only write to their own layer). More...
 
class  CsvDataset
 Dataset over a CSV file's numeric columns: N named feature columns -> one (1, num_features) Tensor per row, plus one named label column -> one (1,) Tensor. Requires a header row (feature/label columns are resolved by name). More...
 
class  CsvReader
 Minimal RFC-4180-ish CSV parser: comma-delimited, double-quote-quoted fields, "" as an escaped quote,
or \r
line endings. Whole file loaded into memory at once – no streaming/chunked reading in this phase, matching MnistIdxLoader's own whole-file-at-once precedent. More...
 
struct  CsvTable
 One parsed CSV file's contents: raw string cells, row-major, plus an optional header. More...
 
class  CUDABackend
 CUDA-resident DeviceBackend implementation. More...
 
class  DataLoader
 Orchestrates sampling and collation into batches – pulsatrix's DataLoader (PyTorch DataLoader / torch::data::DataLoader analogue). More...
 
struct  DataLoaderOptions
 Configuration for a DataLoader. More...
 
class  Dataset
 Random-access dataset abstraction – pulsatrix's analogue of PyTorch's torch.utils.data.Dataset / LibTorch's torch::data::Dataset (len/__getitem__). Every concrete modality (CsvDataset, MnistDatasetAdapter, future image/text/audio readers) subclasses this; DataLoader depends only on this interface. More...
 
struct  DatasetStatistics
 One Dataset's per-field descriptive statistics. More...
 
class  DatasetStatisticsView
 Draws one histogram per Sample field (small multiples, hc_information_visualization.md SS6) plus a flagged-issue count, using DatasetValidator's existing production API (ComputeStatistics/DetectIssues) – no new core code needed, this is purely a consumer of data that already exists. More...
 
class  DatasetValidator
 Generic data validation over any Dataset implementation – descriptive statistics and missingness/outlier detection only (campaign_exai_dl_library_data_pipeline Decision Point 5: distributional drift detection and bias/fairness metrics are explicitly out of scope, named follow-ups for a future campaign). More...
 
class  DataThreadPool
 Minimal, generic thread pool for CPU-side data pipeline work (fetch, decode, transform, collate stages) – campaign_exai_dl_library_data_pipeline's staged- pipeline backbone alongside BoundedQueue. Deliberately not tied to Dataset/DataLoader types. More...
 
class  Decoder
 Turns token strings back into text. More...
 
struct  DecompositionLoss
 
struct  DecompositionOptions
 
struct  DenoiserRelevance
 Where the network's share of one step landed. More...
 
struct  DescriptionLength
 The paper's minimum description length (Appendix C), in bits per input at distortion δ = distortion_fraction · (mean per-dimension variance of x): More...
 
class  DetailedBalanceLoss
 ‘Δ(s,s’) = log F(s) + log P_F(s'|s) − log F(s') − log P_B(s|s'),loss = Δ(s,s')²-- the per-*transition* credit-assignment alternative toTrajectoryBalanceLoss`'s per-trajectory constraint. More...
 
class  DeviceBackend
 Vendor-agnostic compute/memory backend. CPUBackend, CUDABackend (Phase 1.5), and HIPBackend (Phase 1.6) all implement this contract; Tensor and ComputationGraph depend only on this interface, never on a concrete backend's types. More...
 
struct  DifferentiableClassifier
 A classifier the attacks can differentiate: forward maps an (N, ...) input to (N, C) logits; backward maps a gradient at those logits to the gradient at the input, for the input of the last forward. More...
 
struct  DiffTarget
 Which output both models are asked to explain. More...
 
class  DigitsPreTokenizer
 Splits off numeric characters (Unicode N), one by one or in runs (Hugging Face's Digits). More...
 
class  DisjunctionModule
 y = a S b for a selected t-conorm S, over two independent fuzzy-truth-valued operand tensors (values intended in [0,1]; out-of-range values are not rejected – see conjunction_module.hpp's identical note). More...
 
struct  DistanceMatrix
 The distances between every pair of n points, condensed. More...
 
struct  DistanceOptions
 PairwiseDistances()'s settings. More...
 
class  DistillationLoss
 Distillation loss between a student's and a teacher's logits, (..., classes): every row along the last dimension is one distribution. More...
 
struct  DistillationOptions
 DistillationLoss's settings. More...
 
struct  DiverseCounterfactualOptions
 Settings for FindDiverseCounterfactuals. More...
 
struct  DiverseCounterfactualResult
 A set of counterfactuals and DiCE's set-level metrics (Mothilal et al. 2020). More...
 
struct  DmsVariants
 An assay's measured variants: mutant, DMS_score and DMS_score_bin columns. More...
 
struct  DominantEigenResult
 PowerIteration()'s result. More...
 
struct  DoubleEigenResult
 SymmetricEigenInDouble()'s result. More...
 
class  DQNAgent
 The epsilon-greedy behaviour policy of Mnih et al. 2015: with probability epsilon act uniformly at random, otherwise take argmax_a Q(observation, a). More...
 
class  DQNLoss
 loss = mean_b( (q_values[b, a_b] - targets[b,0])^2 ), where a_b is the action actually taken on transition b – the semi-gradient TD update of Mnih et al. 2015. More...
 
class  DropoutModule
 y = (mask_i ? x_i / (1 - p) : 0) at training time (inverted dropout – scaling happens at training time so eval-time forward needs no rescaling); y = x at eval time or when p == 0. No parameters. More...
 
struct  EffectiveRank
 MeasureEffectiveRank()'s result. More...
 
struct  EigenResult
 SymmetricEigen()'s result. More...
 
class  EmbeddingModule
 Embedding lookup table, rank-2 input (N, L) of float-encoded indices -> rank-3 output (N, L, embedding_dim). Structurally unlike every other module in this codebase: forward is a pure selection (row copy), with no arithmetic mixing across input features. More...
 
class  EncoderBlock
 One encoder layer. Shape (N, L, d_model) -> (N, L, d_model). More...
 
struct  EncoderBlockOptions
 Everything about an EncoderBlock beyond its attention. The defaults are ESM-2's. More...
 
class  EncoderExplainer
 AttnLRP for an ESM-2 EncoderLM: explains a target (EncoderTarget) as relevance on the input residues, with LXT's rules by default (the identity rule on LayerNorm and GELU, the uniform rule at attention's matmuls, epsilon elsewhere), so it matches LXT's AttnLRP. More...
 
class  EncoderLM
 A masked language model: token embeddings (with ESM's token-dropout scaling, when the config has it), pre-LayerNorm encoder layers with rotary attention (EncoderBlock), a final LayerNorm, and the LM head. Shape: token ids (N, L) to logits (N, L, vocab). More...
 
struct  EncoderLMConfig
 The settings of a masked LM, from its Hugging Face config.json. More...
 
class  EncoderLMStepModel
 An EncoderLM as a StepRelevanceModel: one sequence per pass, AttnLRP with config (LXT's rules by default, as EncoderExplainer uses). More...
 
struct  EncoderTarget
 What an explanation explains. Residues are numbered from 0 here. More...
 
struct  Encoding
 The result of encoding one text. More...
 
class  Environment
 Base class for every RL environment (CartPoleEnv, and whatever later phases add). More...
 
struct  ErrorTerm
 One source of error in a Certified value. More...
 
struct  EsmContactHead
 ESM's contact head (EsmContactPredictionHead): a logistic regression over every head's corrected attention map, sigmoid(sum_c weight[c] * f_c(i, j) + bias). Channel c = layer * heads + head, as transformers stacks them. More...
 
struct  ESResult
 Result of a full Evolution Strategies run. More...
 
struct  Example
 One background example. More...
 
struct  ExcludedExplainer
 An explainer that answers the question but can't run on this model. More...
 
struct  ExplainerCapabilities
 One explainer's declaration: what it answers and what it needs. More...
 
class  ExplainerContext
 Wraps an ordered chain of Modules, running them via Module::forward_traced to build a real ComputationGraph and Autograd backward wiring – graph-native explainers (Missions 2-3) use graph()/backward_pass()/activation(); surrogate explainers (Phase 3) would use only forward_pass(), per the charter's stated interface segregation. More...
 
struct  Explanation
 An explanation and what it does and doesn't support (XAI-3). More...
 
struct  ExplanationCheckOptions
 How BuildExplanation() runs the checks. The defaults are the published ones where there is one; each is recorded in Explanation::settings. More...
 
struct  ExplanationPlan
 What ExplanationPlanner::plan() returns. More...
 
class  ExplanationPlanner
 Plans explanations from the explainer catalog. More...
 
struct  ExplanationRequest
 What to explain, why, and what the caller has. More...
 
class  ExplanationScoreCard
 Aggregates, per prediction, a 2x2 panel: top row is "what was shown, how confident was the model" (input label + ConfidenceMeter), bottom row is "how trustworthy is this explanation" (LRP conservation delta + explainer stability), visually separated by a rule (Gestalt proximity grouping – these are two different semantic questions, not one undifferentiated block of numbers). More...
 
struct  ExtractedRule
 One leaf of a crisp tree as a rule. More...
 
struct  FastaRecord
 One FASTA record. More...
 
class  FeatureActivityTracker
 How often each feature fires, and how long since it last did. A feature that hasn't fired in a long window is dead: it no longer learns, and wastes capacity. One that fires on most inputs is dense, usually a sign it encodes a bias, not a feature. More...
 
struct  FeatureDashboardDocument
 pulsatrix.feature_dashboard.v1: one learned feature (for example a sparse autoencoder unit) with its activation statistics and top-activating examples. More...
 
struct  FeatureSensitivity
 How one feature's low and high value move the output, everything else held fixed. More...
 
struct  FeatureSignificance
 One feature's result in UniversalNullTest(). More...
 
class  Featurizer
 A featurizer maps activations x, (N, input_dim), to codes f = encode(x), (N, num_features), and reconstructs x ≈ decode(f) = f D + b: feature i writes along its decoder direction D[i]. More...
 
struct  FeaturizerLoss
 One batch's loss, split into its parts. More...
 
class  FeedForwardModule
 fc2(f(fc1(x))) over the last dimension. Shape (..., d_model) -> (..., d_model). More...
 
struct  FieldStatistics
 Descriptive statistics for one Sample field position, aggregated across a whole Dataset. More...
 
struct  FineTuneConfig
 Training settings. The defaults are the recipe's. More...
 
struct  FitnessMetrics
 All five, as ProteinGym reports them. More...
 
class  FlattenModule
 y = reshape(x, {N, x.numel()/N}), N = x.shape().dim(0). No parameters, no gradient math beyond reshaping. More...
 
class  FuseDecoder
 Concatenates the tokens (Hugging Face's Fuse decoder). More...
 
struct  GAEResult
 ComputeGAE()'s two outputs: the advantage estimate per step and the critic's regression target per step. More...
 
struct  GaussianMixturePrediction
 CombineGaussians()' result: one value per input. More...
 
class  GaussianNLLLoss
 The Gaussian negative log likelihood, for regressors that predict their own noise (Nix and Weigend, 1994; Lakshminarayanan et al., 2017): the network outputs two values per input, a mean mu and s, and its variance is softplus(s) + min_variance, which keeps it positive. More...
 
class  GaussianProcessRegressor
 A fitted (or queryable-before-fitting-throws) Gaussian Process regressor with a squared-exponential kernel: k(x, x') = sigma_f^2 * exp(-||x - x'||^2 / (2 * length_scale^2)), plus additive observation noise (a small noise_variance is also standard GP practice purely as numerical "jitter" to keep the kernel matrix well-conditioned, independent of whether the underlying objective is actually noisy). More...
 
struct  GenerationConfig
 Decoding settings. The defaults decode greedily. Field names follow Hugging Face's GenerationConfig. More...
 
struct  GenerationResult
 A generated continuation. More...
 
class  GeneratorPopulation
 Owns N independently-parameterized generator Modules. More...
 
class  GFlowNetForwardPolicy
 Samples from softmax(mask(policy_network(observation))) – a categorical policy restricted to a caller-supplied set of valid actions at the current state. More...
 
struct  GFlowNetSampledAction
 One sample from GFlowNetForwardPolicy::sample: the chosen action and the log-probability the masked distribution assigned to it. More...
 
struct  GFlowNetTrajectory
 One full sampled trajectory: every state the forward policy acted from, the action taken at each, and the trajectory-level quantities Trajectory Balance (and Detailed Balance/SubTB, in later missions) need. More...
 
struct  GlobalSensitivityProblem
 The input space to explore: which features vary, over which ranges. Every other feature keeps its value from base. More...
 
struct  GoldenReport
 A model's comparison against a golden file. More...
 
struct  GoldenSequenceResult
 One reference sequence's comparison. More...
 
struct  GpuSample
 One GPU's readings within a SystemSample. More...
 
class  GradCAM
 L^c = ReLU(sum_k alpha^c_k * A^k), where alpha^c_k = mean_ij(d(y^c)/d(A^k_ij)) and A is the last OpType::Conv node's activation. More...
 
class  GroupNormModule
 Splits num_channels into num_groups equal-size groups; each group's mean/std is computed over every (channel-in-group, H, W) element jointly, per batch row n, then y_{n,c,h,w} = gamma_c * (x_{n,c,h,w} - mu_{n,g})/std_{n,g} + beta_c, gamma/beta per-channel (shape (num_channels,), not per-group, not per-batch-row). Batched – input/output are rank-4 (N, channels, H, W), migrated from the original unbatched (rank-3) scope by campaign_exai_dl_library_batch_dimension_support, matching Conv2DModule's own (not-yet-migrated) rank-3 convention plus a leading batch dim. H/W are not fixed at construction (only num_groups/num_channels are), so this module accepts any spatial size at forward() time, exactly like Conv2DModule does. More...
 
struct  GrowingSpheresOptions
 Settings for GrowingSpheresCounterfactual. Radii are in units of the constraints' scale. More...
 
class  GRUModule
 Standard GRU recurrence (Cho et al. 2014), h_0 = 0 (zero-initialized, not learnable – the same deliberate scope cut RNNModule/LSTMModule made, and the same thing that makes this module's conservation exact; see the LRP note below): z_t = sigmoid(x_t @ W_xz + h_{t-1} @ W_hz + b_z) (update gate), r_t = sigmoid(x_t @ W_xr + h_{t-1} @ W_hr + b_r) (reset gate), hn_prev_t = h_{t-1} @ W_hn (internal projection, no bias), n_t = tanh(x_t @ W_xn + r_t * hn_prev_t + b_n) (candidate), h_t = (1 - z_t) * h_{t-1} + z_t * n_t. Note the reset gate multiplies the projected previous hidden state hn_prev_t, not h_{t-1} itself – that projection is a distinct cached intermediate, and it is what gives GRU's LRP rule a different shape from LSTM's. Input (N, L, input_size) -> output (N, L, hidden_size), the full hidden-state sequence (matches RNNModule's/LSTMModule's convention). Single layer, no bidirectional/multi-layer/variable-length support. More...
 
struct  H0Result
 ComputeH0()'s result. More...
 
struct  HeadPrecision
 
struct  HeatmapColorScale
 The color-scale range and colormap family a heatmap's values call for. More...
 
struct  HeatmapDocument
 pulsatrix.heatmap.v1: a row-major grid of values with optional axis labels. More...
 
struct  HeatmapGrid
 A row-major 2D grid of unsigned magnitude values, ready for a heatmap plot. More...
 
class  HfCheckpoint
 A Hugging Face checkpoint directory's weights: model.safetensors, or the shards listed by model.safetensors.index.json (IO-5). Shards are memory-mapped, so opening a checkpoint reads only headers, and a tensor's bytes are paged in when it is read. More...
 
struct  HfModelConfig
 A decoder-only language model's config.json, with the values Hugging Face leaves to the model class filled in: every field is what the model actually uses. More...
 
struct  HfRopeScaling
 A rope_scaling (or rope_parameters) entry other than the default. More...
 
class  HiddenStateCosineLoss
 DistilBERT's cosine loss: the mean over kept rows of 1 − cos(s, t), with s and t the student's and teacher's vectors, (..., width); PyTorch's CosineEmbeddingLoss with target 1. More...
 
class  HiddenStateTap
 An identity intervention that keeps the hidden states it sees and adds a gradient to the one flowing back through it: the way to train a CausalLM on a loss of a layer's output. More...
 
class  HintLoss
 FitNets' hint loss: mean((r(student) − teacher)²), with r a learned linear map from the student's feature width to the teacher's. More...
 
class  HIPBackend
 HIP-resident DeviceBackend implementation, targeting AMD GPUs via ROCm. More...
 
struct  HistogramBins
 Equal-width histogram bins: rows.size() == counts.size() + 1 edges. More...
 
class  HorizontalFlipTransform
 Mirrors the image left-right. In-place, no backend needed (same shape). More...
 
struct  HtmlOptions
 Options for every HTML view. More...
 
struct  Hubness
 How unevenly points appear in each other's neighbor lists. More...
 
struct  HyperbandBracket
 One bracket's own (num_configs, initial_budget) trade-off point; s is the bracket index (s_max = most configs/smallest budget, down to s=0 = fewest configs/largest budget, matching the original paper's own naming). More...
 
struct  HyperbandResult
 The best configuration/metric found across every bracket, and the total epoch budget spent summed across all of them. More...
 
class  HyperGridEnv
 An n-dimensional grid: state is an integer coordinate in [0, H-1]^ndim, actions increment one coordinate or stop the episode, reward is concentrated near the grid's corners. More...
 
class  IA3Adapter
 One layer's rescaling vector l: (out) for an output-scaling layer, (in) for a feedforward one. LinearModule owns and drives it; read it through LinearModule::ia3(). More...
 
struct  IA3Config
 Which layers IA³ rescales, PEFT style (see LoRAConfig::target_modules for the matching). More...
 
struct  IceResult
 ICE curves for one feature: curves[i][k] = f(x_i with feature j set to grid[k])[target]. More...
 
class  ImageDecoder
 Decodes an image file into a Tensor – pulsatrix's generalization beyond MnistIdxLoader's IDX-format-only precedent (campaign_exai_dl_library_data_pipeline, Phase 2). Powered by stb_image (public-domain, single-header, vendored via FetchContent – Decision Point 2): supports PNG/JPEG/BMP/GIF/TGA/HDR and more. More...
 
class  ImageFolderDataset
 Dataset over a directory tree of the form root_dir/<class_name>/<image_file>, mirroring torchvision's ImageFolder convention. Class names are the sorted subdirectory names; each class's label is its index in that sorted order. Images are decoded lazily (per get() call) via ImageDecoder. More...
 
class  ImageGridView
 Draws a grid of image samples from a Dataset whose first Sample field is a decoded (1,C,H,W) or (C,H,W) image tensor (e.g. ImageFolderDataset) – the data-loading "preview what you're about to train on" touchpoint. More...
 
class  ImPlotMetricsSink
 A concrete MetricsSink (metrics_sink.hpp's own doc comment names this the expected extension point: "Concrete writers... implement this") that buffers every logged scalar into a per-tag time series, and keeps the latest histogram snapshot per tag, for live rendering by a training dashboard. Zero core changes needed – MetricsSink* is already threaded through every training loop in this codebase (XorNetwork::train_step, MnistConvNet::train_step). More...
 
struct  ImportanceStats
 Causal importance statistics of one layer over inputs. More...
 
struct  Imputation
 How a removed feature is filled in when perturbing an input. More...
 
struct  Individual
 A single candidate solution in a genetic algorithm population. More...
 
class  InnovationTracker
 The global historical-marking registry: the same structural mutation (an identical new connection, or an identical connection-split creating a new node) occurring in different genomes receives the same innovation number / new node ID if it has already been recorded, and a fresh one otherwise. This is the concrete mechanism that lets two differently-shaped genomes' genes be meaningfully aligned by innovation number – NEAT's own defining idea (not built here: crossover itself is a future mission; this class only maintains the registry crossover would eventually consume). More...
 
struct  InputAgreement
 How one input's two attributions compare. More...
 
class  IntegratedGradients
 IG_i(x) = (x_i - baseline_i) * (1/steps) * sum_{k=1}^{steps} d(F(baseline + (k/steps)(x - baseline)))/dx_i – a Riemann-sum approximation of the straight-line path integral from baseline to input. More...
 
struct  IntruderResult
 Intruder dimensions of one weight matrix (Shuttleworth et al., 2024, Definition 3.1). More...
 
class  IterableDataset
 Streaming dataset abstraction for sources with no random access or no known length (sharded files, generators) – pulsatrix's analogue of PyTorch's IterableDataset / tf.data's source-op model. DataLoader treats this and Dataset via a common internal adapter (data_loader.hpp) so both share one fetch/collate path. More...
 
class  JsonValue
 One JSON value: null, a boolean, a number, a string, an array or an object. More...
 
struct  JumpReLUSaeOptions
 
class  JumpReLUSparseAutoencoder
 A JumpReLU sparse autoencoder: z = pre · H(pre - θ) with pre = x W_enc + b_enc, and x̂ = z W_dec + b_dec. Each latent has its own threshold θ > 0, kept as log θ. More...
 
class  KernelSHAP
 Approximates Shapley values via full coalition enumeration + SHAP-kernel-weighted linear regression, reusing fit_weighted_linear_regression for the reduced (n-1)-dimensional problem the efficiency-axiom substitution produces. More...
 
class  KLDivergenceLoss
 Closed-form KL(N(mu, sigma^2) || N(0, I)) for a diagonal Gaussian posterior (Kingma & Welling 2013, arXiv:1312.6114, Appendix B): loss = mean_b( 0.5 * sum_d( mu[b,d]^2 + exp(2*log_sigma[b,d]) - 2*log_sigma[b,d] - 1 ) ) i.e. summed over the latent dimension per example, averaged over the batch – the standard VAE ELBO normalization, matching how the reconstruction term is typically summed-per-example/averaged-over-batch too. More...
 
class  KVCache
 One attention layer's keys and values for the positions processed so far, in buffers allocated once for max_length positions, so generation never reallocates or copies the past. More...
 
struct  LabeledProtein
 A protein with known contacts, to choose heads with. More...
 
struct  LandmarkOptions
 FarthestPointLandmarks()'s settings. Selection stops at whichever limit comes first. More...
 
struct  Landmarks
 FarthestPointLandmarks()'s result. More...
 
struct  LatentScaling
 Latent Scaling (Minder et al., Eq. 4): how much of latent j's b-side decoder direction each source actually needs. For a target Y^m over the inputs where it's computed, β^m = ⟨Y^m d, f⟩ / (|f|² |d|²) with d = d_j^b, the best scale of f d against Y^m. More...
 
struct  LayerIntruders
 IntruderDimensions() for one named layer. More...
 
class  LayerNormModule
 y_{n,i} = gamma_i * (x_{n,i} - mu_n)/std_n + beta_i, mu_n = mean_i(x_{n,i}), std_n = sqrt(var_i(x_{n,i}) + eps), computed independently per batch row n. Batched ((N, num_features)), migrated from the original unbatched (rank-1) scope by campaign_exai_dl_library_batch_dimension_support. More...
 
class  LearnableScalar
 A bare learnable scalar (e.g. a GFlowNet loss's log Z), outside the Module/LRP hierarchy entirely. More...
 
class  LIME
 Fits a locality-weighted linear surrogate around one input: perturb x with Gaussian noise, weight each perturbed sample by an exponential locality kernel pi(z) = exp(-||z-x||^2 / (2*sigma^2)), fit w* = argmin_w sum_i pi_i*(f(z_i) - f(x) - w^T(z_i-x))^2 + l2_lambda*||w||^2 via fit_weighted_linear_regression. More...
 
struct  LinearHead
 A linear head on the model's representations (last_hidden_state): weight . h + bias. More...
 
class  LinearModule
 y = x @ W + b, batched (x is (N, in_features), y is (N, out_features)) – migrated from the original unbatched (rank-1) scope by campaign_exai_dl_library_batch_dimension_support (breaking migration to always-batched; a single example is N=1, not a structurally different case). More...
 
class  LinearProbe
 A linear probe: LinearModule(activation_dim, 1) + BCEWithLogitsLoss, trained on (activation, binary concept label) pairs. High post-training accuracy means the concept is linearly decodable from those activations; chance-level accuracy means it is not (at least not linearly). More...
 
struct  LocalSensitivityResult
 One-at-a-time sensitivity of one output around one input. More...
 
struct  LogOddsBand
 Log-odds errors over the examples whose reference probability is in [lower, upper). More...
 
struct  LogOddsErrorReport
 
class  LoRAAdapter
 One layer's low-rank update: A (in, r) and B (r, out), stored like LinearModule's weight, with x A B as the update. PEFT's lora_A and lora_B are the transposes, (r, in) and (out, r); SaveLoraAdapter() and LoadLoraAdapter() convert. More...
 
struct  LoRAConfig
 LoRA's settings. The defaults are PEFT's LoraConfig's. More...
 
struct  LoraLayerRelevance
 One adapted layer's share of a relevance pass (TRN-8). More...
 
struct  LoReFTConfig
 Where and how large LoReFT's interventions are. More...
 
class  LoReFTIntervention
 One block's LoReFT edit. Parameters, named as pyreft's state dict: More...
 
struct  LossRecovered
 MeasureLossRecovered()'s result: the model's loss three ways. More...
 
class  LRP
 Whole-model LRP: runs the forward pass, seeds relevance at the chosen output(s), and propagates it to the input through every module's own propagate_relevance() rule. More...
 
struct  LRPRuleConfig
 Configuration for LRP relevance propagation: which rule a module applies and its hyperparameters. A module that does not implement the requested rule throws (see Module::supports_lrp_rule()) – the rule is never silently substituted. More...
 
struct  LRPTarget
 What LRP explains: one target class (and optionally one contrast class) per row of the network's (N, num_classes) output. More...
 
class  LRSchedule
 A learning-rate multiplier as a function of the step, with the formulas of Hugging Face transformers' get_{constant,linear,cosine}_schedule_with_warmup. More...
 
class  LRScheduler
 Applies an LRSchedule to an optimizer (SGDOptimizer, AdamOptimizer, AdamWOptimizer): each rate becomes its base rate times the schedule's multiplier, like PyTorch's LambdaLR. More...
 
class  LSTMModule
 Standard 4-gate LSTM recurrence, h_0 = c_0 = 0 (zero-initialized, not learnable – the same deliberate scope cut RNNModule made, and the same thing that makes this module's conservation exact; see the LRP note below): i_t = sigmoid(x_t @ W_xi + h_{t-1} @ W_hi + b_i), f_t = sigmoid(x_t @ W_xf + h_{t-1} @ W_hf + b_f), g_t = tanh(x_t @ W_xg + h_{t-1} @ W_hg + b_g), o_t = sigmoid(x_t @ W_xo + h_{t-1} @ W_ho + b_o), c_t = f_t * c_{t-1} + i_t * g_t, h_t = o_t * tanh(c_t). Input (N, L, input_size) -> output (N, L, hidden_size), the full hidden-state sequence (matches RNNModule's convention). Single layer, no bidirectional/ multi-layer/variable-length/peephole support. More...
 
class  MambaModule
 Core Mamba/S6 selective-scan recurrence (Gu & Dao 2023, arXiv:2312.00752), input (N, L, d_model) -> output (N, L, d_model). More...
 
struct  MaskedDiffusionConfig
 Sampling settings. The defaults fill greedily by confidence. More...
 
struct  MaskedDiffusionResult
 A sampled sequence and how it was produced. More...
 
struct  MaskedDiffusionStep
 One step that filled at least one position (under Remasking, any step). More...
 
struct  MaskedDiffusionWrite
 One position filled at one step. More...
 
struct  MaskedLMBatch
 One collated batch, on the collator's backend. More...
 
class  MaskedLMCollator
 Turns sequences into masked-LM batches as ESM-2 was trained: <cls> + residues + <eos>, cropped to a random window when too long, then each residue picked with probability 0.15; of those, 80% become <mask>, 10% a random amino acid (uniform over the 20 standard ones) and 10% stay. <cls>, <eos> and padding are never picked. Draws come from a seeded portable generator, so a seed gives the same batches on every platform. More...
 
struct  MaskedLMEvaluation
 Masked-LM quality on held-out sequences. More...
 
struct  MaskedLMOptions
 ESM-2's masking (Lin et al. 2023; BERT's 80/10/10). More...
 
class  MaxPool2DModule
 Max pooling, rank-4 (N, channels, H, W), matching Conv2DModule's convention, as PyTorch's MaxPool2d without dilation: out = (n + 2 padding - kernel) / stride + 1. Windows may overlap (stride < kernel), as in ResNet's stem (3x3, stride 2, padding 1); padded positions never win. No dilation or ceil mode. More...
 
struct  MetadataColumn
 One column of per-point metadata: a label, a class, a value as text. More...
 
class  MetaspaceDecoder
 The replacement character back to spaces (Hugging Face's Metaspace decoder). Unless the scheme is Never, every replacement in the first token is dropped, as Hugging Face does, not only the one the pre-tokenizer put in front. More...
 
class  MetaspacePreTokenizer
 Spaces become a replacement character (▁), one is put in front of each piece (or of the text's first piece only), and pieces are optionally split before each one (Hugging Face's Metaspace pre-tokenizer). More...
 
struct  MetricCapability
 Whether one metric can be read on this machine, and from where – or why not. More...
 
struct  MetricRecord
 One recorded metric value: a named tag, its value, and the training step it was logged at (mirrors MetricsSink::log_scalar's own (tag, value, step) shape). More...
 
class  MetricsSink
 Interface the training loop logs scalars/histograms through. Concrete writers (TensorBoard event format, W&B, CSV, ...) implement this; the training loop and Phase 4 validation harness only ever see MetricsSink. More...
 
struct  MimeBundle
 One displayable value in several formats: MIME type to data, richest first. Text formats (text/plain, text/html, image/svg+xml, base64 image/png) are strings; +json formats are JSON objects, as Jupyter's display protocol and nbformat store them. More...
 
class  MnistConvNet
 Conv2D(1,8,5,5) -> ReLU -> Flatten -> Linear(4608,10), trained via CrossEntropyLoss + Adam, one real MNIST image at a time (this library has no batch dimension anywhere, same constraint XorNetwork already works under). More...
 
struct  MnistDataset
 One IDX file pair's contents: parallel images/labels, same length. More...
 
class  MnistDatasetAdapter
 Adapts a pre-loaded MnistDataset (MnistIdxLoader::Load's output) onto the generic Dataset interface – minimal-diff retrofit (campaign_exai_dl_library_data_pipeline, Mission 4): MnistIdxLoader/MnistDataset themselves are unchanged, still exercised directly by mnist_loader_test.cpp; this adapter is purely additive, fulfilling mnist_loader.hpp's own note that a second real dataset is the moment to generalize. More...
 
class  MnistIdxLoader
 Reads MNIST's original IDX-format files directly – no format conversion, no generic Dataset abstraction. MNIST-specific by deliberate scope decision (see plan_mnist_classification_training_example.md's Recon); if a future mission needs a second real dataset, generalize then. More...
 
struct  ModelToken
 One token from a TokenModel: its id and string, and the bytes of the piece it covers. More...
 
struct  ModelTraits
 What the caller has: the model, its inputs and its data. More...
 
class  Module
 Base class for every layer type (LinearModule, Conv2DModule, activations, ...). More...
 
struct  MorrisDocument
 pulsatrix.morris.v1: Morris screening statistics per feature (CFS-4). More...
 
struct  MorrisOptions
 Morris settings. More...
 
struct  MorrisResult
 Morris screening results, one entry per varied feature (SALib's morris.analyze). More...
 
class  MSELoss
 MSE = mean((prediction - target)^2). More...
 
struct  MstEdge
 One edge of a minimum spanning tree. More...
 
class  MultiHeadAttentionModule
 softmax(Q @ K^T / sqrt(head_dim)) @ V, multi-head, with optional RoPE and optional QK-Norm. Shape (N, L, d_model) -> (N, L, d_model). More...
 
struct  Mutation
 One substitution, numbered from 1 as variant tables write it: A23G. More...
 
class  MutationLoss
 Computes one of E-GAN's three named mutation objectives against a discriminator's own raw logit output, and its gradient w.r.t. those logits. Every objective trains the generator to make the discriminator's output move toward the "real" (1) class – they differ only in how that pressure is shaped (saturating vs. non-saturating vs. quadratic). More...
 
struct  MutationMapDocument
 pulsatrix.mutation_map.v1: a score for every substitution, residue by residue, such as a model's log-odds log p(mutant) - log p(wild type) or a deep mutational scan's measurements. More...
 
struct  NamedBufferRef
 Module state that is saved with a model but never trained, such as BatchNorm's running statistics, with its hierarchical name (roadmap IO-2). Named like parameters. More...
 
struct  NamedModuleRef
 A sub-module with its dot-separated name relative to the module that reported it, the same prefix its parameters carry (mha.q_proj, layers.0). More...
 
struct  NamedParamRef
 A parameter together with its hierarchical, dot-separated name relative to the module that reported it (weight, mha.q_proj.bias, 0.weight). More...
 
struct  NEATEvolutionResult
 Result of a full NEAT evolutionary run. More...
 
class  NEATGenome
 A NEAT genome: its node and connection genes, growable via structural mutation. More...
 
class  NegationModule
 y = 1 - x, elementwise. No parameters, no parameter gradients. More...
 
struct  NeighborOptions
 Settings for the neighbor searches. More...
 
struct  Neighbors
 Each query's k nearest points, nearest first. More...
 
class  NfcNormalizer
 Unicode Normalization Form C (canonical composition), keeping offsets. More...
 
class  Node
 A single computation graph node. Owned exclusively by its ComputationGraph (see computation_graph.hpp); parent/child edges here are non-owning raw pointers into nodes the same graph owns. More...
 
struct  NodeGene
 One node in a NEAT genome's topology. More...
 
class  NoiseSchedule
 The DDPM (Ho et al. 2020, arXiv:2006.11239) linear variance schedule plus the two tensor operations defined directly on top of it – closed-form forward noising and the reverse (sampling) step. More...
 
class  NoOpMetricsSink
 Does nothing. The charter's stated minimum viable MetricsSink implementation. More...
 
class  NormalizedString
 Text being normalized and pre-tokenized, remembering where each byte came from in the original input, so offsets survive changes such as NFC composition or byte-to-character mapping. More...
 
class  Normalizer
 Changes text before it is split (lowercasing, NFC, ...). More...
 
class  NormalizeTransform
 Per-channel normalization: pixel = (pixel - mean[c]) / std[c]. In-place, no backend needed (same shape in and out). More...
 
struct  NullModelComparison
 NullModelBaseline()'s result: the analysis on the trained model and on the null model. More...
 
struct  Offset
 A byte range [begin, end) of the text passed to TextTokenizer::encode(). More...
 
class  ParameterDecomposition
 Trains a decomposition of the ComponentLinear layers inside model against the model itself: the target is the model with every layer in target mode. More...
 
class  ParameterSnapshot
 Saves every parameter of a module and restores them exactly when it goes out of scope. More...
 
struct  ParameterSpec
 One named parameter's description: its kind plus the bounds/categories that kind needs. Only the fields relevant to kind are meaningful (e.g. categories is empty/unused for Continuous) – this is a description, not a union, since a SearchSpace's own accessors (below) are the only place callers read it back. More...
 
struct  ParamGroup
 Optimizer settings for the parameters selects picks. More...
 
class  ParamGroupSet
 The group machinery SGDOptimizer and AdamOptimizer share. More...
 
struct  ParamRef
 A trainable parameter and its accumulated gradient, as owned by some Module. More...
 
struct  PartialDependence2D
 Partial dependence on two features at once, over a grid of value pairs. More...
 
struct  PartialDependenceDocument
 pulsatrix.partial_dependence.v1: a partial dependence curve over one feature, with the individual (ICE) curves it averages when they were computed (CFS-1). More...
 
struct  PartialDependenceSvgOptions
 Options for RenderPartialDependenceSvg. More...
 
struct  PBTResult
 The best-performing trial's index, its metric, and how many generations ran. More...
 
class  PBTResumableTrial
 A ResumableTrial that additionally exposes its live weights (a flat vector) and its current hyperparameter Configuration, both readable and replaceable mid-training. More...
 
struct  PBTTruncationGroups
 Indices of the population's current worst- and best-performing members. More...
 
struct  Pca
 A fitted PCA. More...
 
class  PDP
 PDP_j(v) = (1/|B|) * sum_{b in B} f(x_j=v, x_{-j}=b_{-j}) – for each grid value v, replace every background instance's feature j with v (keeping its other features), average the model's output over the whole background set. More...
 
struct  PersistenceDiagram
 The features of one homology dimension: H0 for components, H1 for loops, H2 for voids. More...
 
struct  PersistenceDiagramDocument
 Persistence diagrams of one point cloud, one entry per homology dimension. More...
 
struct  PersistenceDiagramEntry
 One homology dimension of a PersistenceDiagramDocument. More...
 
struct  PersistenceImage
 A persistence image: values[row * width + column], row 0 at persistence 0. More...
 
struct  PersistenceImageOptions
 ComputePersistenceImage()'s settings. More...
 
struct  PersistenceLandscape
 PersistenceLandscape()'s result: layers[k][i] is lambda_{k+1}(grid[i]). More...
 
struct  PersistencePair
 One feature of a persistence diagram. More...
 
struct  PersistenceViewOptions
 Settings shared by the three views. More...
 
struct  PerturbationCurve
 A perturbation curve: the target score after each fraction of features was changed. More...
 
struct  PerturbationOptions
 Options for DeletionCurve() and InsertionCurve(). More...
 
struct  PlannedCheck
 One check the plan asks for. More...
 
struct  PlannedExplainer
 One explainer the plan recommends. More...
 
struct  Point3
 A position in Ångström. More...
 
class  PointCloud
 A set of points in R^dimension, built from activation batches. More...
 
struct  PointCloudOptions
 PointCloud's settings. More...
 
struct  PointOrigin
 Where one point of a PointCloud came from. More...
 
class  PolicyGradientLoss
 loss = mean_b( -log pi(a_b | s_b) * G_b ), where a_b is the action actually taken on step b of a rollout and G_b its return – the REINFORCE policy-gradient surrogate of Williams 1992. More...
 
class  PostProcessor
 Adds tokens around an encoding (BOS and EOS, sentence pairs, ...). More...
 
class  PPOClippedLoss
 loss = mean_b( -min( r_b * A_b, clamp(r_b, 1-eps, 1+eps) * A_b ) ), where r_b = pi_new(a_b|s_b) / pi_old(a_b|s_b) – the clipped surrogate objective of Schulman et al. 2017 (arXiv:1707.06347), negated so that minimizing it maximizes the objective the paper states. More...
 
struct  PredictionInterval
 One prediction interval. More...
 
class  PrependNormalizer
 Puts a string in front of non-empty text (Hugging Face's Prepend normalizer). More...
 
class  PreTokenizer
 Splits text into the pieces the model tokenizes separately, and may change them (byte- level mapping). More...
 
struct  ProbeGain
 A probe on a representation beside the same probe on a baseline representation. More...
 
struct  ProbeOptions
 
struct  ProbeResult
 A probe's quality on held-out rows. More...
 
struct  ProbeSelectivity
 A probe on the real task beside the same probe on the control task. More...
 
struct  ProjectionDocument
 pulsatrix.projection.v1: inputs placed in a few dimensions (INT-5), such as their first principal components, for a scatter plot. Each point can carry a label (shown on hover), a group (drawn as a color) and a value (drawn on a color scale when there are no groups). More...
 
struct  PromptCompletion
 One example: the prompt's token ids, then the completion's. More...
 
struct  ProteinFeature
 One annotated stretch, numbered from 1, inclusive, as UniProt numbers it. More...
 
struct  ProteinGymAssay
 One assay's row of ProteinGym's reference file (DMS_substitutions.csv). More...
 
struct  ProteinStructure
 The protein chains of a structure's first model. More...
 
struct  ProtoDashOptions
 ProtoDash()'s settings. More...
 
struct  ProtoDashResult
 ProtoDash()'s result. More...
 
struct  PrototypeOptions
 FindPrototypes()' settings. More...
 
struct  PrototypeResult
 FindPrototypes()' result. More...
 
struct  QRResult
 QR()'s result, the thin factorization A = Q R. More...
 
struct  RandomizationCheckResult
 The randomization check's result: after randomizing layers[0..i], how similar the explanation stays (Spearman of |relevance| per residue with the original). More...
 
struct  RandomizationResult
 The model-parameter randomization test's result. More...
 
struct  Rdm
 A representational dissimilarity matrix: the distance between every pair of n inputs. More...
 
struct  ReconstructionMetrics
 EvaluateReconstruction()'s result. More...
 
struct  RecurrentCellArgs
 Operand pointers for DeviceBackend::recurrent_cell (passed to kernels by value). More...
 
struct  RegressionReport
 How well a regressor does. More...
 
struct  RelevanceDiff
 The two explanations of the same prediction, and their difference. More...
 
struct  RelevanceGraphOptions
 
struct  ReliabilityBin
 One confidence bin, (lower, upper]; the first bin also holds a confidence of 0. More...
 
struct  ReliabilitySeries
 One classifier on a reliability diagram. More...
 
class  ReluModule
 y = max(x, 0), elementwise. No parameters, no parameter gradients. More...
 
class  Reparameterize
 VAE reparameterization trick (Kingma & Welling 2013, arXiv:1312.6114), z[b,d] = mu[b,d] + exp(log_sigma[b,d]) * epsilon[b,d]. More...
 
struct  ReparamGrad
 The (grad_mu, grad_log_sigma) pair both VAE building blocks produce. More...
 
class  ReplaceDecoder
 Replaces a literal string or regex in every token (Hugging Face's Replace decoder). More...
 
class  ReplaceNormalizer
 Replaces every match of a literal string or a regex (Hugging Face's Replace normalizer). More...
 
struct  ReplayBatch
 One uniformly-sampled minibatch of transitions, one Tensor per transition field. More...
 
class  ReplayBuffer
 Fixed-capacity circular replay buffer of (observation, action, reward, next_observation, done) transitions, with uniform-random-with-replacement batch sampling – the off-policy experience store of Mnih et al. 2015 (DQN), reused unchanged by SAC and every other off-policy learner in this campaign. More...
 
class  Report
 A document of markdown, code and rich outputs, written as a Jupyter notebook (nbformat 4.5) or as one self-contained HTML page. Neither needs Python or a kernel: the notebook renders on GitHub, in JupyterLab, VS Code and Quarto with its outputs already in place. The title becomes a heading cell at the top. More...
 
struct  RepresentationComparison
 Three views of how alike two representations are. More...
 
struct  RepresentationComparisonOptions
 CompareRepresentations()'s settings. More...
 
class  ResampleTransform
 Resamples a waveform (sample.fields[0], shape (1, channels, num_samples) – WavReader's/AudioFolderDataset's convention) from source_sample_rate to target_sample_rate via linear interpolation. More...
 
class  ResidualIntervention
 A trainable edit of the residual stream after a transformer block (TRN-9: LoReFT), run by CausalLM::set_intervention(). Maps hidden states (N, L, hidden_size) to the same shape and, as a Module, trains and explains with the model. More...
 
class  ResidualModule
 y = x + inner->forward(x) for an arbitrary already-built Module. The classic ResNet shortcut connection, owning its own native relevance-split rule – the charter's explicitly named failure mode to avoid is Captum/Zennit's "Canonizer surgery" (an external post-hoc graph rewrite for residual connections). More...
 
struct  ResidueAgreement
 How a per-residue explanation agrees with an independent per-residue signal. More...
 
struct  ResidueDeletionCurve
 A deletion curve against its random baseline. More...
 
struct  ResidueEmbeddings
 Per-residue representations at some layers: for each layer, residues x hidden values, the proteins' residues one after another. More...
 
struct  ResidueLogProbs
 Log-probabilities of every token at each residue: length rows of vocab values. More...
 
struct  ResidueRelevance
 Relevance per residue for one explained value. More...
 
struct  ResidueTracksDocument
 pulsatrix.residue_tracks.v1: per-residue signals stacked under a sequence, and annotated stretches (domains, sites), as in a genome or protein browser. The same document colors a 3D structure (RenderStructureHtml). More...
 
class  ResizeTransform
 Every transform in this file operates on sample.fields[0], assumed to be an image Tensor of shape (1, channels, height, width) – the convention MnistDatasetAdapter, CsvDataset, and ImageDecoder all already share (image/features first, label last). More...
 
struct  ResNetConfig
 A torchvision ResNet with basic blocks (ResNet18 and ResNet34; ResNet18 is the one tested on the published weights). More...
 
class  ResumableTrial
 A single hyperparameter configuration's live, resumable training state – own whatever network/optimizer/dataset a concrete trial needs, and train it incrementally across multiple calls rather than all at once. More...
 
class  RetNetModule
 Core RetNet retention block (Sun et al. 2023, arXiv:2307.08621), recurrent mode, input (N, L, d_model) -> output (N, L, d_model). More...
 
struct  ReverseStepCoefficients
 One reverse step as x_prev = skip * x_t - network * eps_theta + noise * z (DIFF-5). DDPM and DDIM steps both have this form; only the coefficients differ. More...
 
struct  RgbColor
 An RGB color, each channel in [0, 1]. More...
 
struct  RgbImageBuffer
 An interleaved-RGB, row-major byte buffer ready for a texture upload. More...
 
struct  RipsFeature
 One feature of the diagram, with where it comes from. More...
 
struct  RipsOptions
 ComputeRipsPersistence()'s settings. More...
 
struct  RipsResult
 ComputeRipsPersistence()'s result. More...
 
struct  RlRowArgs
 Operand pointers and dims for DeviceBackend::rl_rows (passed to kernels by value). More...
 
class  RMSNormModule
 y_{n,i} = gamma_i * x_{n,i} / rms(x_n), rms(x_n) = sqrt(mean_i(x_{n,i}^2) + eps), computed independently per batch row n. Batched ((N, num_features)), migrated from the original unbatched (rank-1) scope by campaign_exai_dl_library_batch_dimension_support – no mean-centering, no beta/bias term (RMSNorm's defining simplification vs. LayerNorm). More...
 
class  RNNModule
 h_t = tanh(x_t @ W_xh + h_{t-1} @ W_hh + b_h), h_0 = 0 (zero-initialized, not learnable – a deliberate scope cut, see the class-level conservation note below). Input (N, L, input_size) -> output (N, L, hidden_size), the full hidden-state sequence. Single layer, tanh only, no bidirectional/multi-layer/ variable-length support. More...
 
struct  RobustnessCurve
 RobustAccuracyCurve()'s result. More...
 
struct  RobustnessPoint
 One budget's result on a robustness curve. More...
 
struct  RolloutBatch
 One whole stored rollout, reduced to what a policy-gradient update consumes: the visited observations, the actions taken, the discounted return-to-go of each step, and the log-probability the acting policy assigned to each action. More...
 
class  RolloutBuffer
 Fixed-length, fill-once on-policy trajectory buffer of (observation, action, reward, log_prob, done) steps, with discounted return-to-go computation – the storage REINFORCE/A2C/PPO collect a rollout into. More...
 
class  RoPEModule
 Rotary Position Embedding (RoPE, Su et al. 2021): a fixed, non-learnable, position-dependent rotation of each adjacent feature pair of a Q/K-shaped tensor. More...
 
struct  RsaTestResult
 RsaPermutationTest()'s result. More...
 
struct  RtdOptions
 Rtd()'s settings: the paper's Algorithm 2. More...
 
struct  RtdResult
 Rtd()'s result. More...
 
struct  RuleCondition
 One test on a path: x[feature] > threshold when greater, x[feature] <= threshold otherwise. More...
 
class  RWKVModule
 Core RWKV-4 time-mixing block (Peng et al. 2023, arXiv:2305.13048), input (N, L, d_model) -> output (N, L, d_model). More...
 
class  SafetensorsFile
 A parsed, fully validated safetensors file, held in memory or memory-mapped. Copies share the same bytes. More...
 
struct  SafetensorsTensorInfo
 One tensor's header entry. Offsets are relative to the start of the data section. More...
 
class  Saliency
 Raw-gradient saliency: d(output[target_index])/d(input), computed by seeding ExplainerContext::backward_pass with a one-hot vector at target_index. More...
 
class  SaliencyHeatmapView
 Draws a 2D saliency heatmap plus a colormap scale bar. Unsigned magnitudes (e.g. Grad-CAM) use Viridis (perceptually uniform, colorblind-safe – hc_information_visualization.md SS4) over [0, max]; signed attributions (any negative value – gradients, IG, LRP, LIME, SHAP) use the blue-white-red DivergingColormap over the symmetric range [-max|v|, +max|v|], so zero is always the neutral midpoint. The choice is ComputeHeatmapColorScale's (plot_data.hpp, unit-tested). Row 0 of the grid is drawn at the top (image convention) with square cells. More...
 
struct  Sample
 One dataset sample: an ordered list of Tensor fields (e.g. {features, label} or {image, label}). Field order/count is a contract between a Dataset implementation and whatever CollateFn (collate.hpp) later assembles samples into a Batch. More...
 
class  Sampler
 Produces the order in which a DataLoader visits a Dataset's indices for one epoch. More...
 
class  SatisfactionLoss
 loss = 1 - agg_p(truth_values) – the standard LTN "Real Logic" training objective (research_2026_neuro_symbolic_ai.md §1/§2): maximizing a knowledge base's aggregated satisfaction via ordinary gradient descent is the same as minimizing this loss. More...
 
struct  ScalarSeries
 One scalar tag's logged (step, value) pairs, in log order. More...
 
struct  ScoreCardScaleContext
 Shared axis/color-scale state across several ExplanationScoreCard instances shown together (small multiples – hc_information_visualization.md SS6), so each card's attribution bar chart uses a comparable scale rather than independently auto-scaling and silently making cross-card comparison invalid. More...
 
class  SearchSpace
 Describes a hyperparameter search space as an ordered list of named, typed parameters. Every HPO algorithm (grid/random search, GP-BO, TPE, Hyperband/ASHA) consumes a SearchSpace to know what it may propose; this type itself has no sampling logic (that is each algorithm's own job, e.g. RandomSample/GridSample). More...
 
struct  SensitivityBounds
 The low and high value to try for every feature of an input (flat order). More...
 
struct  SensitivityDocument
 pulsatrix.sensitivity.v1: how one output moves when each input feature, alone, goes to a low and a high value (CFS-3). The data behind a tornado chart. More...
 
struct  SensitivityOptions
 ExplanationSensitivity()'s settings. More...
 
struct  SensitivityReport
 ExplanationSensitivity()'s result. More...
 
struct  SeparationRange
 Pairs (i, j) counted by separation j - i: at least min, and under max unless max is 0. More...
 
class  SequenceDecoder
 Runs decoders in order, each on the previous one's tokens. More...
 
class  SequenceHead
 A head on an encoder's representations (last_hidden_state), for fine-tuning or probing. Pooling::Mean averages each sequence's residues (not <cls>, <eos> or padding) and applies a linear layer: (N, L, hidden) to (N, outputs), for per-protein labels. Pooling::PerResidue applies it to every token: (N, L, hidden) to (N, L, outputs), for per-residue labels (use -100 targets at <cls>, <eos> and padding). More...
 
struct  SequenceLogoDocument
 pulsatrix.sequence_logo.v1: a distribution over letters at each residue, such as what a masked language model predicts there, drawn as a sequence logo. More...
 
class  SequenceNormalizer
 Runs normalizers in order. More...
 
class  SequencePostProcessor
 Runs post-processors in order. More...
 
class  SequencePreTokenizer
 Runs pre-tokenizers in order. More...
 
class  SequentialModule
 Composes layers_[0..n-1] in forward() order; backward()/propagate_relevance() chain layers_[n-1..0] in reverse – correct reverse-mode composition order. More...
 
class  SequentialSampler
 Visits indices [0, dataset_size) in ascending order. More...
 
struct  Series
 One line of points. More...
 
struct  SeriesDocument
 
struct  SeriesPanel
 Several series on shared axes. More...
 
struct  SeriesViewOptions
 Options for RenderSeriesSvg(). More...
 
class  SGDOptimizer
 param -= learning_rate * (grad + weight_decay * param), per parameter, for every parameter a Module exposes. Learning rate and weight decay can differ per parameter group (TRN-1). With no weight decay this is plain SGD. More...
 
class  Shape
 An N-dimensional shape. A plain aggregate of dimensions with no invariant beyond "non-negative dimensions" – see oop_design/context_oop_design_fundamentals.md's struct-vs-class discussion for why this is still a class (numel()/is_reshape_compatible() are derived queries, not raw public fields the caller could desync from dims_). More...
 
class  ShuffleSampler
 Visits indices [0, dataset_size) in a seeded pseudo-random permutation – reproducible across runs given the same seed (std::mt19937), re-shuffled fresh each reset() call (a new epoch is a new permutation, not the same one repeated). More...
 
struct  SliceError
 One slice's error. More...
 
struct  SliceErrorOptions
 PerSliceError()'s settings. More...
 
struct  SliceErrorReport
 PerSliceError()'s result. More...
 
struct  SliceErrorViewOptions
 RenderSliceErrorSvg()'s settings. More...
 
struct  SobolDocument
 pulsatrix.sobol.v1: first- and total-order Sobol indices per feature (CFS-4). More...
 
struct  SobolOptions
 Sobol settings. More...
 
struct  SobolResult
 Sobol indices, one entry per varied feature (SALib's sobol.analyze, first and total order). More...
 
class  SoftDecisionTree
 Frosst and Hinton's soft decision tree, (N, inputs) to (N, classes) log-probabilities. More...
 
struct  SoftDecisionTreeOptions
 SoftDecisionTree's settings. More...
 
class  SoftmaxModule
 Softmax over the tensor's last dimension, applied independently to every "row" (every fixed combination of all leading dimensions). More...
 
struct  SoftTreeRules
 A soft decision tree's rules, one per leaf, over weighted facts. More...
 
class  SparseAutoencoder
 A sparse autoencoder (SAE): LinearModule(dim, hidden_dim) -> ReluModule -> LinearModule(hidden_dim, dim), trained with MSELoss to reconstruct its own input while an L1 penalty on the hidden ReLU activation pushes most hidden units to zero on any given example. More...
 
struct  SparseCodes
 Sparse codes: for each residue, its active features and their values. More...
 
struct  SpeciesAssignment
 Population grouping into species: each inner vector is a list of indices into the population vector that were passed to SpeciatePopulation. More...
 
class  SplitPreTokenizer
 Splits on a regex or a literal string (Hugging Face's Split pre-tokenizer). More...
 
struct  SsmPassArgs
 Operand pointers and dims for DeviceBackend::ssm_pass (passed to kernels by value). More...
 
struct  StabilityResult
 The result of measuring an explainer's variance across repeated runs on the same input. More...
 
struct  SteeringOptions
 
struct  SteeringReport
 MeasureSteering()'s result. More...
 
class  StepRelevanceModel
 One denoising step's model as the explainer sees it: a forward pass that keeps what the relevance pass needs, and the relevance pass. EncoderLMStepModel wraps an EncoderLM. More...
 
struct  StepResult
 What one Environment::step() produces: the next observation, this step's reward, and whether the episode ended. More...
 
class  StripDecoder
 Removes up to start leading and stop trailing copies of a character from every token (Hugging Face's Strip decoder). More...
 
struct  StructureChain
 A chain's residues, in file order. More...
 
struct  StructureResidue
 One residue of a chain and its atoms. More...
 
class  SubTBLoss
 One sub-trajectory pair's contribution to the SubTB(λ) loss: Δ(i,j) = log F(s_i) + Σ log P_F − log F(s_j) − Σ log P_B (summed over the edges spanned by [i,j)), weighted by ‘pair_weight_ratio = λ^{j-i} / Σ_{i’<j'} λ^{j'-i'}` (the pre-normalized share of the total weighted-average loss this specific pair contributes). More...
 
struct  SuccessiveHalvingResult
 The winning configuration, its final metric, and the total epoch-budget actually spent across every trial/rung (the exit-gate's own "reduces total training compute" measure). More...
 
struct  SurrogateFidelity
 How well the tree imitates the model. More...
 
struct  SurrogateNode
 One node. A leaf has feature -1. More...
 
struct  SurrogateTree
 A fitted tree. nodes[0] is the root. More...
 
struct  SurrogateTreeOptions
 How the tree is grown. More...
 
struct  SurrogateTreeResult
 FitSurrogateTree()'s result. More...
 
struct  SvccaOptions
 Svcca()'s settings. More...
 
struct  SvccaResult
 Svcca()'s result. More...
 
struct  SVDResult
 SVD()'s result, the thin factorization A = U diag(S) V^T with k = min(m, n). More...
 
struct  SvgOptions
 Options shared by every SVG chart. More...
 
class  SwiGLUModule
 down_proj(silu(gate_proj(x)) * up_proj(x)), the gated feedforward block used in place of a plain two-linear-layer MLP in most modern transformers. Rank-agnostic over (..., d_model) -> (..., d_model), matching MultiHeadAttentionModule's I/O contract so Phase 3 Mission 5 (TransformerBlock) can chain them directly. More...
 
class  SystemMonitor
 Samples CPU/GPU utilization, memory use and temperatures on a background thread, keeps a bounded in-memory history, and streams every sample to a log file. More...
 
struct  SystemSample
 One point-in-time measurement of the host. More...
 
struct  TaggingBatch
 Ragged sequences: real tokens 1..kVocab-1 followed by padding (input 0, target -100). More...
 
struct  TanhGaussianGrad
 The (grad_mean, grad_log_std) pair TanhGaussianPolicy::backward() produces – both (N, action_dim), the shape of the forward's own mean/log_std. More...
 
class  TanhGaussianPolicy
 SAC's reparameterized, tanh-squashed Gaussian policy sample (Haarnoja et al. 2018, arXiv:1801.01290, Appendix C "Enforcing Action Bounds"): u = mean + exp(log_std) * epsilon, action = tanh(u), with the change-of-variables corrected log-density log_prob = sum_d [ -0.5*epsilon^2 - log_std - 0.5*log(2*pi) - log(1 - action^2 + 1e-6) ]. More...
 
struct  TanhGaussianSample
 The (action, log_prob) pair TanhGaussianPolicy::forward() produces. More...
 
struct  TcavOptions
 
struct  TcavResult
 RunTcav()'s result. More...
 
struct  TemperatureFit
 A fitted temperature and the weighted mean log loss before and after it. More...
 
class  TemplatePostProcessor
 Special tokens around a single sequence (Hugging Face's TemplateProcessing, single). More...
 
class  Tensor
 N-dimensional tensor. Owns its data buffer exclusively; a DeviceBackend* is injected (not owned) – the backend must outlive every Tensor constructed against it, per cpp_style_guide/context_style_project_conventions.md's ownership table. More...
 
class  TextDataset
 Dataset over a line-delimited text corpus: each line becomes one sample, tokenized via Tokenizer::Tokenize and indexed via a Vocabulary into a (1, seq_len) float32 Tensor of token indices – Decision Point 6's resolved representation (token IDs as float32 values, the same integer-as-float32 pattern CsvDataset's label column and MnistDatasetAdapter's class label already use). seq_len varies per sample; no padding here (see PadCollate, Mission 10) – an empty line produces a zero-element (1, 0) Tensor, a valid, non-error Tensor state. More...
 
class  TextTokenizer
 A tokenizer: added tokens are split out of the raw text first (longest match, earliest first); each remaining segment is normalized, pre-tokenized and tokenized by the model; then the post-processor runs. Every component but the model is optional. More...
 
class  TextureCache
 Uploads decoded image Tensors to OpenGL textures, keyed and cached by an arbitrary integer key (e.g. a Dataset index) so a scrolling image grid doesn't re-upload the same image every frame. More...
 
class  TiedLMHeadModule
 logits = x @ E^T, where E is a token embedding table (vocab, d_model) that the head shares rather than copies – Hugging Face's tie_word_embeddings (SmolLM2, Qwen3, Gemma 3). Shape (..., d_model) -> (..., vocab). More...
 
struct  TimingStats
 Summary of repeated timings, in milliseconds. More...
 
class  TinyTagger
 Embedding -> TransformerBlock -> per-token Linear head: (N, L) tokens to (N, L, C) logits. More...
 
class  TokenCrossEntropyLoss
 sum over tokens of -log softmax(logits)[target], divided by a normalizer; tokens whose target is the ignore index (padding) contribute nothing. More...
 
class  Tokenizer
 Splits text into lowercase word/punctuation tokens – pulsatrix's first text primitive (campaign_exai_dl_library_data_pipeline, Phase 3, Decision Point 6: a minimal whitespace/punctuation tokenizer, not BPE – training a real subword-merge algorithm is a project-sized undertaking on its own). More...
 
struct  TokenizerMismatch
 The first difference on one line of the corpus. More...
 
struct  TokenizerParityReport
 How a tokenizer compares with the reference, field by field. More...
 
class  TokenModel
 Turns one pre-tokenized piece into tokens (word-level lookup, BPE, ...). More...
 
struct  TokenRelevanceDocument
 pulsatrix.token_relevance.v1: relevance scores over the pieces of a text, in reading order. MakeTokenRelevanceDocument() and MakeWordRelevanceDocument() (viz/text_relevance.hpp) build one from a tokenizer's Encoding or from word scores. More...
 
class  TokenRelevanceShift
 Collects RelevanceDiff results over a dataset by input token: which tokens a fine-tune made the model rely on more, and which less. More...
 
class  TokenRelevanceView
 Draws a document's pieces as running text that wraps to the window, each scored piece on a background colored by its relevance (DivergingColormap, scaled to the largest |relevance|), as the SVG token strip does. Unscored pieces (the spaces between words) are plain text, and a newline starts a new line. Hovering a piece shows its text and score. More...
 
struct  TokenShift
 One token's relevance shift, averaged over every occurrence seen. More...
 
struct  TopKResult
 top_k()'s result: the selected values and their positions along the last dimension. More...
 
struct  TopKSaeOptions
 
class  TopKSparseAutoencoder
 A TopK sparse autoencoder: z = ReLU(TopK_k(W_enc (x - b_dec) + b_enc)), x̂ = z W_dec + b_dec. More...
 
struct  TorchvisionLoadReport
 What LoadTorchvisionWeights() did. More...
 
class  TorchvisionResNet
 torchvision's ResNet(BasicBlock, ...): a 7x7 stride-2 convolution, BatchNorm, ReLU and 3x3 stride-2 max pooling; four stages of basic blocks (two 3x3 convolutions with BatchNorm, and a 1x1 convolution with BatchNorm on the shortcut where the shape changes); global average pooling and a linear classifier. Input (N, 3, H, W), output (N, classes). More...
 
class  TorchvisionVGG
 torchvision's VGG: 3x3 convolutions with bias and ReLU, 2x2 max pooling, adaptive average pooling to (pool_size, pool_size), then Linear, ReLU, Dropout, Linear, ReLU, Dropout, Linear. Parameter names are torchvision's (features.0.weight, classifier.6.bias, ...). Every layer is top-level in layers(), so the first convolution can take ZBox in an EpsilonGammaBox composite. More...
 
class  ToyKnowledgeBase
 A small, hand-traceable knowledge base: two neural predicates A(x)/B(x) (each a sigmoid-squashed LinearModule(1,1), producing a fuzzy truth degree in (0,1)), one logical rule A(x) -> not(B(x)), expressed via De Morgan (not(A(x)) or not(B(x)), Product t-conorm/t-negation) using only NegationModule/DisjunctionModule (Mission 0) – no dedicated Implication Module – aggregated across synthetic groundings into one scalar via SatisfactionLoss (Mission 1). More...
 
class  TrainingDashboard
 Draws a live training dashboard: a data-ink-minimal per-tag summary line (last/min/max value, current step – Tufte SS6: no chartjunk, just the numbers that matter) followed by ImPlotMetricsSink's line charts and histogram snapshots. More...
 
struct  TrainingLogDocument
 pulsatrix.training_log.v1: scalar series and the latest histogram per tag. More...
 
class  TrajectoryBalanceLoss
 Δ(τ) = log Zθ + Σ log P_F(s_{t+1}|s_t) − log R(x) − Σ log P_B(s_t|s_{t+1}), loss = Δ(τ)². More...
 
struct  TrajectoryHop
 One reverse step's split, aggregated over elements. More...
 
struct  TrajectoryLrpConfig
 
struct  TrajectoryRelevance
 Where the seed's relevance went. The budget balances exactly: value = x_T + condition + time + noise + absorbed + leak. More...
 
class  Transcoder
 A transcoder: z = ReLU(TopK_k(x W_enc + b_enc)), ŷ = z W_dec + b_dec [+ x W_skip], trained to predict an MLP's output y from its input x by mean((ŷ - y)²) plus AuxK. More...
 
struct  TranscoderOptions
 
class  Transform
 A single sample-level preprocessing step (normalize, augment, tokenize, ...). More...
 
class  TransformDataset
 Decorates a Dataset with a Transform, applied to every sample get() returns – lets Transform/Compose compose with any Dataset without modifying it or DataLoader. More...
 
class  TransformerBlock
 y1 = x + MHA(RMSNorm(x)), y2 = y1 + SwiGLU(RMSNorm(y1)). Shape (N, L, d_model) -> (N, L, d_model). More...
 
struct  TransformerBlockOptions
 The parts of a TransformerBlock beyond its attention (LLM-9 adds Gemma's). More...
 
struct  TreeRules
 A crisp tree's rules, one per leaf. More...
 
class  Trial
 A configuration paired with the metric history observed while evaluating it (instantiate a network under this configuration, train it, record whatever metrics the training loop reports). Deliberately decoupled from SearchSpace – a Trial records what actually happened, a SearchSpace describes what could be proposed; neither needs to reference the other directly. More...
 
struct  TTestResult
 A two-sample t-test's result. More...
 
struct  TwoNNResult
 TwoNNDimension()'s result. More...
 
struct  UncertaintyDecomposition
 DecomposeUncertainty()'s result: one value per input, entropies in nats. More...
 
class  UnicodeRegex
 A compiled pattern, matched leftmost-first with backtracking as Oniguruma (which Hugging Face tokenizers uses) and Perl do. More...
 
class  UniformFrameSampleTransform
 Samples num_frames evenly-spaced frames from a clip Tensor (sample.fields[0], shape (T, C, H, W) – VideoFrameDirectoryDataset's convention), producing an (N, C, H, W) Tensor – deliberately identical in shape convention to Phase 2's image Dataset/Transform outputs (ImageFolderDataset, ResizeTransform, etc.): a video clip, once frame-sampled, is just a batch of images from this codebase's perspective. More...
 
struct  UniversalNullResult
 UniversalNullTest()'s result. More...
 
struct  ValidationIssue
 One detected data-quality issue: a missing (NaN) value or a statistical outlier. More...
 
class  VariantScorer
 Scores variants with a masked language model and its tokenizer, the way ProteinGym scores ESM models. A higher score means the model finds the variant more plausible. More...
 
struct  VariantScoringOptions
 
struct  VGGConfig
 A torchvision VGG without BatchNorm (VGG11 to VGG19; VGG16 is the one tested on the published weights). More...
 
class  VideoFrameDirectoryDataset
 Dataset over a directory tree of the form root_dir/<class_name>/<clip_name>/<sequentially-named-frame-image>, decoding each clip's frames (via ImageDecoder) into one (T, C, H, W) Tensor per sample. More...
 
struct  VizFontFile
 A font file, and the face to use when it holds several (.ttc). More...
 
struct  VizFontOptions
 Which fonts a VizWindow loads. More...
 
class  VizWindow
 Owns a GLFW window, OpenGL3 context, and ImGui/ImPlot context for the lifetime of one demo app. Every examples/viz/*_demo.cpp uses this instead of hand-rolling the standard imgui_impl_glfw_opengl3 boilerplate. More...
 
class  Vocabulary
 Token<->index lookup table. Index 0 is always the reserved "<unk>" token – guaranteed by construction, not caller convention: the constructor takes the ranked list of real tokens and prepends "<unk>" itself. More...
 
struct  WaterfallBar
 One floating waterfall bar: spans [bottom, top] on the value axis. More...
 
struct  WaterfallStep
 One waterfall step: a labeled delta and the running cumulative value after it. More...
 
struct  WavData
 One decoded WAV file's contents: waveform Tensor plus its sample rate. More...
 
class  WavReader
 Reads uncompressed 16-bit PCM WAV files directly – pulsatrix's first audio primitive (campaign_exai_dl_library_data_pipeline, Phase 4, Decision Point 4: hand-rolled over libsndfile, same "narrowest thing that satisfies the exit gate" reasoning as Decision Points 1/2/6). More...
 
struct  WeightLoadOptions
 Loading settings. More...
 
struct  WeightLoadReport
 What a load did. More...
 
struct  WeightMapping
 One entry of a name-mapping manifest. More...
 
class  WordLevelModel
 Each piece is one token, looked up in a vocabulary; unknown pieces become the unknown token. More...
 
class  WordPunctuationSplit
 The split Tokenizer::Tokenize makes: runs of ASCII letters, digits and apostrophes are words, ASCII whitespace separates, and every other character is a token of its own. More...
 
struct  WordScore
 One word and its score. More...
 
struct  WordScores
 Per-word scores for one text. More...
 
class  XorNetwork
 A tiny MLP (Linear(2,4) -> ReLU -> Linear(4,1)) trained on XOR – the canonical not-linearly-separable case, exactly representable by a small MLP, giving an unambiguous convergence target for Phase 1's "prove the training loop works" goal. More...
 

Typedefs

using HiddenStateHook = std::function< Tensor(int64_t position, const Tensor &hidden)>
 Reads or replaces a language model's residual stream during forward() (FEAT-3): called with a position, 0 for the embeddings entering layer 0 and i for layer i's output, and the hidden states there, (N, L, hidden_size) on the model's device. What it returns, the same shape, is what the model continues with: return the input unchanged to only read it. Splicing a featurizer's reconstruction back in uses it (MeasureLossRecovered, featurizer_metrics.hpp).
 
using CollateFn = std::function< Batch(std::vector< Sample >, DeviceBackend *)>
 A function assembling a list of Samples into one Batch – pulsatrix's analogue of PyTorch's collate_fn. The standard extension point for ragged/variable-length modalities (text padding, variable-length audio): a caller-supplied CollateFn replacing DefaultCollate, not a subclass hierarchy.
 
using ConceptCondition = std::vector< ConceptMask >
 One conditional heatmap's masks, at most one per layer.
 
using PredictFn = std::function< Tensor(const Tensor &input)>
 The model as a function: input (with a leading batch dimension of 1) to outputs.
 
using ExplainFn = std::function< Attribution(const Tensor &input)>
 Explains input using the model in its current state.
 
using NextTokenLogitsFn = std::function< std::vector< float >(const std::vector< int64_t > &tokens)>
 The model as generation sees it: the token sequence so far in, the logits for the next token out (one per vocabulary entry). How they're computed is up to the caller: a full forward pass over the sequence (MakeNextTokenLogits), or a cached step (LLM-5).
 
using BlockOutputHook = std::function< Tensor(int64_t layer, int64_t start, int64_t prompt_length, const Tensor &hidden)>
 Called on each block's output in MakeCachedNextTokenLogits(): block layer's hidden states (1, L, d) for positions [start, start + L), in a sequence whose prompt is prompt_length long; returns what the next block reads. CausalLM uses it to run its interventions (TRN-9).
 
using LRPComposite = std::function< LRPRuleConfig(size_t layer_index, const Module &module)>
 Per-layer LRP rule choice: maps (top-level module index in forward order, module) to the LRPRuleConfig that module applies.
 
using DenoiserFn = std::function< std::vector< float >(const std::vector< int64_t > &tokens)>
 The model as the sampler sees it: the current sequence (masked positions included) in, logits for every position out, L * vocab values, row-major. MakeDenoiser builds one for an EncoderLM or a bidirectional CausalLM.
 
using MlpHook = std::function< Tensor(const Tensor &mlp_input, const Tensor &mlp_output)>
 Called with an MLP's input (after the block's norm, where it has one) and its output (the branch added to the residual stream), both shaped like the block's input. What it returns, the same shape, is added to the residual stream instead of the output: return the output unchanged to only read it.
 
using NodeId = size_t
 Stable identifier for a Node within its owning ComputationGraph.
 
using Objectives = std::vector< double >
 
using ParamSelector = std::function< bool(const std::string &name, const Tensor &value)>
 Picks parameters by their named_parameters() name and value.
 
using EmbedFn = std::function< std::vector< float >(const Tensor &input)>
 Maps an input to the vector distances are measured in.
 
using ConfigValue = std::variant< double, int64_t, std::string >
 A concrete value for one parameter – a double (Continuous/LogUniform), an int64_t (Integer), or a std::string (Categorical, naming one of that parameter's categories).
 
using Configuration = std::map< std::string, ConfigValue >
 A concrete hyperparameter configuration: parameter name -> concrete value.
 
using TrialFactory = std::function< std::unique_ptr< ResumableTrial >(const Configuration &)>
 Builds a fresh ResumableTrial for a given configuration.
 
using TextureId = unsigned int
 Opaque GL texture handle, typed to avoid a GL header include in this public header.
 

Enumerations

enum class  AttackNorm { Linf , L2 }
 The norm an attack's budget is measured in. More...
 
enum class  BsfVariant { Vanilla , Grassmannian , GroupLasso }
 
enum class  BlockSelection { TopK , Tournament }
 
enum class  SplitBehavior {
  Removed , Isolated , MergedWithPrevious , MergedWithNext ,
  Contiguous
}
 What a split does with the pieces that match (Hugging Face's SplitDelimiterBehavior). More...
 
enum class  WeightTransform { Identity , Transpose }
 How a source tensor becomes a target parameter. More...
 
enum class  ReferenceMode { Relevance , Activation }
 How ConceptReferenceSamples() ranks inputs. More...
 
enum class  ConformalScore { Lac , Aps }
 How a conformal classifier scores an example. More...
 
enum class  CrosscoderSparsity { L1 , BatchTopK }
 
enum class  LatentClass { AOnly , BOnly , Shared , Other }
 
enum class  DeviceType { Cpu , Cuda , Hip }
 Which physical device a Tensor's buffer resides on. More...
 
enum class  CopyDirection { HostToDevice , DeviceToHost , DeviceToDevice , HostToHost }
 Direction of a DeviceBackend::copy() call. More...
 
enum class  ElementwiseOp {
  Relu , Neg , Tanh , Sigmoid ,
  Silu , Exp , GeluTanh , Gelu
}
 Unary elementwise operations supported by DeviceBackend::elementwise(). More...
 
enum class  LrpGate { None , Positive , Negative }
 Elementwise boolean gate for DeviceBackend::lrp_stabilized_divide(). More...
 
enum class  LogicOp {
  ConjunctionForward , ConjunctionBackward , ConjunctionLrp , DisjunctionForward ,
  DisjunctionBackward , DisjunctionLrp
}
 Elementwise passes of the fuzzy-logic modules, for DeviceBackend::logic_pointwise. More...
 
enum class  RecurrentCellOp {
  RnnBackward , LstmForward , LstmBackward , LstmLrp ,
  GruBackward , GruLrp
}
 Fused per-element recurrent-cell passes, for DeviceBackend::recurrent_cell. Slots (in[] / out[]), all (rows x hidden) per timestep unless noted: More...
 
enum class  SsmPassOp {
  MambaForward , MambaBackward , MambaGradBC , MambaLrp ,
  RwkvTokenShift , RwkvForward , RwkvBackward , RwkvShiftBackward ,
  RwkvLrp , RwkvShiftLrp , StabilizedDiv , RetnetForward ,
  RetnetStateGrad , RetnetGradQK , RetnetGradV , RetnetScores ,
  RetnetReadout , RetnetLrpInput , ReverseTimeSum
}
 Fused passes of the state-space / linear-recurrence modules (MambaModule, RWKVModule, RetNetModule), for DeviceBackend::ssm_pass. Dims come from SsmPassArgs: n batch, l sequence length, d d_model (or C for ReverseTimeSum), s Mamba's state_size / RetNet's key_dim. Sequences are (n, l, X) row-major; "states" buffers are (n, l + 1, ...) with the zero initial state at index 0. Lanes and slots (in[] -> out[]): More...
 
enum class  RlRowOp {
  DqnLoss , DqnGrad , PgLoss , PgGrad ,
  PpoLoss , PpoGrad , DqnTarget , PolyakBlend ,
  TokenCeLoss
}
 Fused per-row reinforcement-learning passes, for DeviceBackend::rl_rows. One lane per batch row (per element for PolyakBlend); rows x cols from RlRowArgs. Index slots hold validated whole-number action indices as floats. Slots (in[] -> out[]): More...
 
enum class  DistillationDivergence { Forward , Reverse }
 Which way round the soft term's KL divergence goes. More...
 
enum class  MutationObjective { Minimax , Heuristic , LeastSquares }
 E-GAN's three named mutation objectives. More...
 
enum class  NormType { LayerNorm , RMSNorm }
 The layer's normalization. More...
 
enum class  NormPosition { Pre , Post }
 Where the norms sit. More...
 
enum class  MlpType { Plain , Gated }
 The MLP's form. More...
 
enum class  EncoderLMHead { Esm , Linear }
 An EncoderLM's output head. More...
 
enum class  XaiQuestion {
  Input , Output , Performance , HowGlobal ,
  Why , WhyNot , WhatIf , HowToBeThat ,
  HowToStillBeThis
}
 The nine question categories of Liao, Gruen and Miller's XAI question bank (CHI 2020). More...
 
enum class  XaiReason { Justify , Control , Improve , Discover }
 Adadi and Berrada's four reasons to explain a model (IEEE Access, 2018). More...
 
enum class  ExplanationScope { Local , Global }
 Whether an explainer explains one prediction or the model as a whole. More...
 
enum class  ModelAccess {
  BlackBox , Weights , Activations , Gradients ,
  Relevance
}
 The least an explainer needs from the model, from least to most access. More...
 
enum class  InputKind {
  Any , Tabular , Image , Tokens ,
  Protein , Symbolic , Representation
}
 What the explainer's input has to be. More...
 
enum class  CheckPriority { Required , Recommended }
 How much a check matters for this reason. More...
 
enum class  CheckOutcome { Passed , Failed , Measured , NotRun }
 What a check found. More...
 
enum class  CaveatSeverity { Blocking , Warning , Note }
 How much a caveat limits what the explanation supports. More...
 
enum class  FinishReason { Eos , Length }
 Why generation stopped. More...
 
enum class  AcquisitionKind { ExpectedImprovement , ProbabilityOfImprovement , UpperConfidenceBound }
 Which acquisition function RunGPBOLoop maximizes over candidates each iteration. More...
 
enum class  LRPSeed { OutputValue , OneHot }
 How LRP seeds relevance at the target output. More...
 
enum class  LRPRule { Epsilon , Gamma , AlphaBeta , ZBox }
 The LRP rule family a module applies. Semantics follow Zennit 1.0.0 exactly (Anders et al. 2021); every rule other than Epsilon is defined only for affine layers (LinearModule, Conv2DModule) – see Module::supports_lrp_rule(). More...
 
enum class  LoRARelevance { Split , Merged }
 How a LinearModule with an unmerged LoRA adapter (TRN-7, TRN-8) propagates relevance. More...
 
enum class  UnmaskingSchedule { Confidence , Ancestral , Remasking }
 How the sampler chooses which masked positions to fill at each step. More...
 
enum class  CommitmentMode { Graph , StepLocal }
 How far relevance travels. More...
 
enum class  NeighborMetric { Cosine , Euclidean }
 How nearness is measured. More...
 
enum class  OpType {
  Linear , Conv , Activation , Elementwise ,
  Reduction , Normalization , Pooling , Embedding ,
  Composite , Recurrent , Attention
}
 The op-type tag a Node carries. Charter Part 2 §3: nodes are tagged by a small closed set of op types rather than by concrete layer class, so a query like "find the last conv layer's activations" (Grad-CAM) works by querying op type, not by string-matching a layer name. More...
 
enum class  DecompositionMethod { SPD , VPD }
 
enum class  OutputDivergence { MeanSquaredError , KlOnLogits }
 How the masked model's output is compared with the target's. More...
 
enum class  SliceTest { Auto , FisherExact , Permutation }
 How PerSliceError() tests a slice against the rest. More...
 
enum class  ContactAtom { Beta , Alpha , VirtualBeta }
 Which atom stands for a residue in residue distances. More...
 
enum class  VariantStrategy { MaskedMarginals , WildTypeMarginals }
 How variants are scored. More...
 
enum class  CkaEstimator { Debiased , Biased }
 Which estimator of CKA to use. More...
 
enum class  RdmMetric { Correlation , Euclidean , Cosine }
 How RepresentationalDissimilarity() measures the distance between two inputs. More...
 
enum class  RdmComparison { Spearman , Pearson }
 How CompareRdms() correlates two RDMs. More...
 
enum class  RoPELayout { AdjacentPairs , RotateHalf }
 Which features RoPE rotates together (LLM-1). More...
 
enum class  SafetensorsDtype {
  Bool , U8 , I8 , I16 ,
  U16 , I32 , U32 , I64 ,
  U64 , F8_E4M3 , F8_E5M2 , F16 ,
  BF16 , F32 , F64
}
 Element types a safetensors file can declare. The floating-point ones convert to a Tensor. More...
 
enum class  ParameterKind { Continuous , LogUniform , Integer , Categorical }
 Which family of values a named parameter draws from. More...
 
enum class  PrependScheme { Always , First , Never }
 When Metaspace puts its replacement in front of a piece. More...
 
enum class  SurrogateTask { Classification , Regression }
 What the surrogate imitates. More...
 
enum class  GatedActivation { Silu , GeluTanh , Gelu }
 The gate activation of a gated MLP: SiLU (SwiGLU: Llama, Qwen), GELU's tanh approximation (GeGLU: Gemma, LLM-9) or exact GELU (GeGLU as first published). More...
 
enum class  LogFormat { LogFormat::JsonLines , LogFormat::Csv }
 Log record encoding. More...
 
enum class  TaggingRule { SumWithPrevious , DifferenceWithPrevious }
 How a token's tag follows from it and the token before it (the first token's predecessor is 0). Tags are modulo kClasses. More...
 
enum class  CavMethod { LogisticRegression , DifferenceOfMeans }
 How TrainCav() finds the concept direction. More...
 
enum class  DistanceMethod { Gemm , Exact }
 How PairwiseDistances() computes the distances. More...
 
enum class  PointPooling {
  Flatten , PerPosition , Mean , Max ,
  Last
}
 How PointCloud turns one sample's activations into points. More...
 
enum class  ContinuousSampler { Ddpm , Ddim }
 Which reverse process to run. More...
 
enum class  TrajectorySplit { AbsoluteRatio , SignedEpsilon , SignedRatio }
 How the relevance on x_prev is split across skip, network and noise (h_1, h_2, h_3). More...
 
enum class  HtmlScripts { Cdn , Inline }
 How a page gets the Vega libraries. More...
 
enum class  AxisScale { Linear , Log }
 How an axis maps values to positions. More...
 
enum class  IceStyle { Raw , Centered , Derivative }
 Which form of the ICE curves RenderPartialDependenceSvg draws (CFS-1). More...
 
enum class  WordSplit { WordsAndPunctuation , Whitespace }
 How the text is cut into words. More...
 
enum class  WordAggregation { Sum , Mean , Max , MaxAbs }
 How a word's score is made from the scores of the tokens that overlap it. More...
 

Functions

double StandardNormalPdf (double z)
 Standard normal PDF, phi(z) = (1/sqrt(2*pi)) * exp(-z^2/2).
 
double StandardNormalCdf (double z)
 Standard normal CDF, Phi(z) = 0.5 * (1 + erf(z / sqrt(2))).
 
double ExpectedImprovement (double mean, double variance, double best_value, double xi=0.01)
 Expected Improvement: the expected amount by which a candidate exceeds best_value + xi, under the posterior N(mean, variance).
 
double ProbabilityOfImprovement (double mean, double variance, double best_value, double xi=0.01)
 Probability of Improvement: P(candidate's value > best_value + xi) under the posterior N(mean, variance).
 
double UpperConfidenceBound (double mean, double variance, double kappa=2.0)
 GP-Upper-Confidence-Bound: mean + kappa * sqrt(variance).
 
DifferentiableClassifier ClassifierFrom (ExplainerContext &context)
 Differentiates through an ExplainerContext's autograd, as the gradient explainers do; the model's parameter gradients are left alone. The context must outlive the result.
 
DifferentiableClassifier ClassifierFrom (Module &model)
 Differentiates through Module::forward and Module::backward. backward() also accumulates the parameters' gradients, so zero them before training again. The module must outlive the result, and should be in eval mode, so dropout doesn't change between the steps.
 
AttackResult Fgsm (const DifferentiableClassifier &model, const Tensor &input, const std::vector< int64_t > &labels, DeviceBackend *backend, const AttackOptions &options={}, bool targeted=false)
 The fast gradient sign method: one step of size epsilon (options.steps, step_size and random_start are ignored).
 
AttackResult Pgd (const DifferentiableClassifier &model, const Tensor &input, const std::vector< int64_t > &labels, DeviceBackend *backend, const AttackOptions &options={}, bool targeted=false)
 Projected gradient descent: random start, then steps steps, each projected onto the epsilon-ball around the input and into [clip_min, clip_max]. Returns the last iterate.
 
RobustnessCurve RobustAccuracyCurve (const DifferentiableClassifier &model, const Tensor &input, const std::vector< int64_t > &labels, const std::vector< double > &epsilons, DeviceBackend *backend, const AttackOptions &options={})
 Robust accuracy against untargeted PGD at each budget: how fast the accuracy falls as the attacker gets more room. options.epsilon is ignored; options.step_size, when set, is a fraction of each epsilon (0 keeps 2.5 / steps).
 
JsonValue ToJson (const AttackResult &result, const AttackOptions &options)
 The result as a pulsatrix.attack.v1 document, without the adversarial inputs.
 
JsonValue ToJson (const RobustnessCurve &curve)
 The curve as a pulsatrix.robustness_curve.v1 document.
 
Anchor FindAnchor (const std::function< Tensor(const Tensor &)> &predict, const Tensor &input, const std::vector< Tensor > &background, const AnchorOptions &options={})
 Finds an anchor for the model's prediction on input.
 
std::string DescribeAnchor (const Anchor &anchor, const std::vector< std::string > &feature_names={})
 IF income > 0.71 AND debt <= -0.12 THEN class 1 (precision 0.97, coverage 0.21).
 
JsonValue ToJson (const Anchor &anchor, const std::vector< std::string > &feature_names={})
 The anchor as a pulsatrix.anchor.v1 document; an infinite bound is null.
 
ASHAResult RunASHAOnConfigQueue (std::vector< Configuration > config_queue, const TrialFactory &make_trial, int initial_epoch_budget, double eta, int num_rungs)
 Runs ASHA, drawing new configurations from an explicit, ordered queue (rather than sampling indefinitely) – the pure, deterministic core; RunASHA (below) is the thin SearchSpace/RNG-sampling wrapper around it.
 
template<typename RNG >
ASHAResult RunASHA (const SearchSpace &space, const TrialFactory &make_trial, size_t max_configs_started, int initial_epoch_budget, double eta, int num_rungs, RNG &rng)
 RNG-driven wrapper: draws max_configs_started configurations from space via RandomSample to serve as the queue, then runs RunASHAOnConfigQueue.
 
double PearsonCorrelation (const std::vector< float > &x, const std::vector< float > &y)
 Pearson correlation of two equal-length vectors; 0 if either is constant.
 
LRPRuleConfig LxtAttnLrpConfig ()
 The rule configuration that matches LXT's AttnLRP on a Hugging Face model: the epsilon rule with a tiny epsilon, biases kept in the denominator as LXT's gradient * input keeps them in z (Qwen2's QKV biases), and LayerNorm with only its standard deviation held constant (LRPRuleConfig::layer_norm_detach_std; ESM-2, PLM-6).
 
AttnLrpReport CompareToAttnLrp (CausalLM &model, const SafetensorsFile &reference, const LRPRuleConfig &config=LxtAttnLrpConfig(), float threshold=0.99f)
 Explains each ids.<k> sequence of an AttnLRP reference file (as written by tools/golden/make_attnlrp_reference.py) from the logit of target.<k> at the last position, seeded with that logit as LXT's examples do, and compares the input relevance and every layer's K/V-head relevance with the reference's.
 
CollateFn AudioPadCollate ()
 Builds a CollateFn that zero-pads (silence) variable-length waveforms (sample.fields[0], shape (1, channels, num_samples) – WavReader's/ AudioFolderDataset's convention) to the batch's own max sample count, producing one (N, channels, max_samples) Tensor, plus a (N,) length field. Phase 4's version of PadCollate (Phase 3, text) – a second proof that the CollateFn extension point handles ragged/variable-length modalities with zero Dataset/DataLoader/Batch interface changes.
 
TimingStats SummarizeTimings (std::vector< double > samples_ms)
 Summarizes timings. Percentiles interpolate linearly between the sorted samples.
 
TimingStats TimeIt (const std::function< void()> &fn, int warmup, int repeats)
 Runs fn warmup times untimed, then repeats times timed with a steady clock.
 
std::string ToJson (const BenchmarkReport &report)
 
BenchmarkReport ParseBenchmarkReport (std::string_view json)
 Reads a report, following the viz document rules (docs/visualization): schema and version checks, unknown fields ignored, "nonfinite" for NaN and infinity, and errors that name the JSON Pointer of the problem.
 
std::vector< BenchmarkComparison > CompareBenchmarks (const std::vector< BenchmarkReport > &baseline_runs, const std::vector< BenchmarkReport > &candidate_runs, const CompareOptions &options={})
 Compares a candidate build with a baseline, record by record (matched on name and device). Several reports per side are the rounds of an interleaved A/B run; each side's value is the median over its rounds, so one noisy round doesn't decide, and with three or more rounds per side a time regresses only if its rounds also separate (CompareOptions::significance).
 
BlockGeometry MeasureBlockGeometry (Featurizer &featurizer, const Tensor &x, int64_t batch=4096)
 
DescriptionLength MeasureDescriptionLength (Featurizer &featurizer, const Tensor &x, double distortion_fraction=0.1, int64_t batch=4096)
 
Tensor EnsembleLogProbabilities (const std::vector< Tensor > &logits, DeviceBackend *backend)
 log((1/G) Σ_g softmax(logits_g)) row by row, (..., classes), on the first tensor's device.
 
Tensor PermuteDarkKnowledge (const Tensor &teacher_logits, uint64_t seed, DeviceBackend *backend)
 The teacher's logits with each row's non-maximal entries shuffled among themselves by a portable generator seeded with seed: the same result on every platform. The largest entry (the first, if tied) stays in place.
 
const std::vector< std::string > & ByteLevelAlphabet ()
 The GPT-2 byte-to-character table byte-level BPE uses: printable bytes stand for themselves, the rest for U+0100 onward.
 
TemperatureFit FitBinaryTemperature (const std::vector< double > &logits, const std::vector< int64_t > &labels, const std::vector< double > &weights={})
 Fits T for binary log-odds: P(y = 1) = sigmoid(logit / T).
 
TemperatureFit FitTemperature (const std::vector< std::vector< double > > &logits, const std::vector< int64_t > &labels, const std::vector< double > &weights={})
 Fits T for multi-class logits: P(y = k) = softmax(logits / T)_k.
 
LogOddsErrorReport LogOddsError (const std::vector< double > &predicted, const std::vector< double > &reference, const std::vector< double > &weights={}, const std::vector< double > &band_edges={1e-3}, double clip=1e-6)
 The error in log-odds of predicted probabilities against reference ones.
 
JsonValue ToJson (const LogOddsErrorReport &report)
 The report as a JSON object: clip, overall, and bands.
 
WeightLoadReport LoadWeights (Module &model, const HfCheckpoint &checkpoint, const std::vector< WeightMapping > &mapping, const WeightLoadOptions &options={})
 Loads checkpoint tensors into model's named parameters and buffers by mapping. Every tensor is read, converted to fp32 (IO-6), sliced and transformed, and checked against its target's shape before anything is written, so a failed load leaves the model unchanged.
 
std::vector< WeightMapping > HuggingFaceMapping (const HfModelConfig &config)
 The manifest for a Llama-family Hugging Face checkpoint (model.embed_tokens.weight, model.layers.<i>.self_attn.q_proj.weight, ..., model.norm.weight, lm_head.weight) onto CausalLM's parameters: Linear weights transposed, biases and norms as they are.
 
std::unique_ptr< CausalLM > LoadCausalLM (const std::string &directory, DeviceBackend *backend)
 Reads config.json and the weights in a downloaded Hugging Face model directory into a new CausalLM, strictly: a tied checkpoint's lm_head.weight is the only tensor allowed to go unused.
 
std::string OptimizerStatePath (const std::string &checkpoint_path)
 Where the optimizer state for checkpoint_path is stored: model.safetensors becomes model.optim.safetensors; any other name gets .optim.safetensors appended.
 
void SaveCheckpoint (const std::string &path, Module &model, const std::map< std::string, std::string > &metadata={})
 Writes every parameter and buffer of model, under their hierarchical names, to a safetensors file with format = "pulsatrix" and format_version metadata.
 
void SaveCheckpoint (const std::string &path, Module &model, const AdamOptimizer &optimizer, const std::map< std::string, std::string > &metadata={})
 SaveCheckpoint(), plus optimizer's per-parameter state in OptimizerStatePath(path).
 
void LoadCheckpoint (const std::string &path, Module &model, CheckpointLoadOptions options={})
 Loads parameters and buffers saved by SaveCheckpoint() (or any safetensors file whose names match) into model, in place.
 
void LoadCheckpoint (const std::string &path, Module &model, AdamOptimizer &optimizer, CheckpointLoadOptions options={})
 LoadCheckpoint(), plus optimizer's state from OptimizerStatePath(path), so training resumes exactly where it stopped.
 
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 upcast:
 
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 logits and every active feature through the frozen model.
 
CircuitScores ScoreCircuit (const CircuitTrace &trace)
 Circuit-tracer's replacement and completeness scores (graph.py).
 
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 indirect influence on the logits (node_threshold), then edges by influence-weighted score (edge_threshold), then nodes left without edges. Node ids, types and labels follow circuit-tracer ("<layer>_<feature>_<position>", "cross layer transcoder", "mlp reconstruction error", "E_<token>_<position>", "<L+1>_<token>_<position>" for logits).
 
std::vector< std::vector< double > > AskGivenSamples (const CMAESState &state, const std::vector< std::vector< double > > &z_samples)
 Pure core: decodes an explicit set of standard-normal sample vectors into offspring points, x_i = mean + sigma * sqrt(variances) (elementwise) * z_i.
 
CMAESState TellGivenSamples (const CMAESState &state, const std::vector< std::vector< double > > &z_samples, const std::vector< std::vector< double > > &offspring, const std::vector< double > &fitness, double step_size_learning_rate, double scale_learning_rate)
 Pure core: given the offspring AskGivenSamples produced (same order), their maximization-convention fitness values, and the z_samples that produced them, returns the next generation's state.
 
Batch DefaultCollate (std::vector< Sample > samples, DeviceBackend *backend)
 Stacks a list of samples into one Batch, field-by-field, via Tensor::Stack – pulsatrix's default CollateFn (PyTorch's default_collate analogue).
 
Tensor LayerRelevance (const LRP &lrp, ExplainerContext &ctx, const Tensor &input, const LRPTarget &target, NodeId layer, DeviceBackend *backend)
 The relevance at layer for explaining target: the layer's shape, (N, C, ...).
 
std::vector< double > ChannelRelevance (const Tensor &layer_relevance)
 Each row's relevance per channel, summed over the remaining dimensions: (N, C) values, row-major. With a conserving rule they add up to the explained output.
 
std::vector< Attribution > ConditionalHeatmaps (const LRP &lrp, ExplainerContext &ctx, const Tensor &input, const LRPTarget &target, const std::vector< ConceptCondition > &conditions, DeviceBackend *backend)
 One input heatmap per condition: LRP from target with the relevance zeroed, at each masked layer, outside the mask's channels.
 
std::vector< int64_t > ConceptReferenceSamples (const LRP &lrp, ExplainerContext &ctx, const Tensor &candidates, int64_t target, NodeId layer, int64_t channel, int64_t k, ReferenceMode mode, DeviceBackend *backend)
 The k inputs of candidates that show a channel best, best first: the reference samples by which CRP shows what a concept is.
 
ConformalClassifier CalibrateConformalClassifier (const Tensor &probabilities, const std::vector< int64_t > &labels, const ConformalOptions &options={})
 Calibrates on held-out examples the model wasn't trained on.
 
std::vector< std::vector< int64_t > > PredictionSets (const ConformalClassifier &classifier, const Tensor &probabilities)
 The prediction set of each input: the classes, most probable first.
 
ConformalRegressor CalibrateConformalRegressor (const std::vector< double > &predictions, const std::vector< double > &targets, double alpha=0.1)
 Calibrates intervals ŷ ± q̂ from a point regressor's predictions on held-out examples.
 
ConformalRegressor CalibrateConformalQuantileRegressor (const std::vector< double > &lower, const std::vector< double > &upper, const std::vector< double > &targets, double alpha=0.1)
 Calibrates CQR intervals [lo − q̂, hi + q̂] from a quantile regressor's lower and upper predictions, such as its alpha/2 and 1 − alpha/2 quantiles, on held-out examples.
 
std::vector< PredictionInterval > PredictionIntervals (const ConformalRegressor &regressor, const std::vector< double > &predictions)
 The intervals for a point regressor's predictions (absolute_residual).
 
std::vector< PredictionInterval > PredictionIntervals (const ConformalRegressor &regressor, const std::vector< double > &lower, const std::vector< double > &upper)
 The intervals for a quantile regressor's predictions (cqr).
 
CoverageReport EvaluateCoverage (const std::vector< std::vector< int64_t > > &sets, const std::vector< int64_t > &labels)
 
CoverageReport EvaluateCoverage (const std::vector< PredictionInterval > &intervals, const std::vector< double > &targets)
 
JsonValue ToJson (const CoverageReport &report)
 The report as a pulsatrix.coverage.v1 document, without the per-input misses.
 
ContrastiveResult FindPertinentNegative (ExplainerContext &ctx, const Tensor &input, const ContrastiveOptions &options={})
 The pertinent negative of input: what would have to be added, where the input has nothing, to change its class.
 
ContrastiveResult FindPertinentPositive (ExplainerContext &ctx, const Tensor &input, const ContrastiveOptions &options={})
 The pertinent positive of input: the least of it that the model still gives its class.
 
JsonValue ToJson (const ContrastiveResult &result, const std::string &kind)
 The result as a pulsatrix.contrastive.v1 document; kind is "pertinent_negative" or "pertinent_positive".
 
std::vector< float > MedianAbsoluteDeviation (const std::vector< Tensor > &background)
 Each feature's median absolute deviation over background (flat order), the distance scale Wachter et al. recommend for tabular data. A feature with zero MAD gets 1, as in DiCE, so it can still move.
 
CounterfactualResult FindCounterfactual (ExplainerContext &ctx, const Tensor &input, const CounterfactualTarget &target, const CounterfactualConstraints &constraints={}, const CounterfactualOptions &options={})
 Finds a nearby input that reaches target (Wachter, Mittelstadt and Russell 2017): minimizes ‘lambda * loss(f(x’), target) + sum_j |x'_j - x_j| / scale_j` by proximal gradient descent, so features the prediction doesn't need stay exactly unchanged. If a round ends without reaching the target, lambda grows and the search continues from where it was.
 
CounterfactualResult GrowingSpheresCounterfactual (const std::function< Tensor(const Tensor &)> &predict, const Tensor &input, const CounterfactualTarget &target, const CounterfactualConstraints &constraints={}, const GrowingSpheresOptions &options={})
 A counterfactual for any prediction function, with no gradients (growing spheres, Laugel et al. 2018): draws points uniformly in a ball around the input, halving its radius while it still contains a point that reaches the target, then in ever larger shells until one does; takes the nearest such point and puts features back to their original values, smallest change first, while it still reaches the target.
 
DiverseCounterfactualResult FindDiverseCounterfactuals (ExplainerContext &ctx, const Tensor &input, const CounterfactualTarget &target, const CounterfactualConstraints &constraints={}, const DiverseCounterfactualOptions &options={})
 Several counterfactuals found together so that they differ from each other (DiCE, Mothilal, Sharma and Tan 2020): one person may be able to raise their income, another to pay down debt, and a single counterfactual shows only one of those routes.
 
float Plausibility (const Tensor &counterfactual, const std::vector< Tensor > &background, const std::vector< float > &scale={}, int k=5)
 How typical a counterfactual is of real data: its mean scaled L1 distance to its k nearest instances in background (lower is more plausible), the kNN measure of the CARLA benchmark. A counterfactual far from every real instance may be valid but describe nobody.
 
std::vector< CrosscoderLatentStats > CrosscoderLatents (Crosscoder &crosscoder, int64_t a=0, int64_t b=1)
 Every latent's stats for sources a and b.
 
LatentClass ClassifyLatent (const CrosscoderLatentStats &stats)
 Minder et al.'s bins on Δnorm.
 
std::vector< LatentScaling > MeasureLatentScaling (Crosscoder &crosscoder, const Tensor &x, const std::vector< int64_t > &latents, int64_t a=0, int64_t b=1, int64_t batch=4096)
 Latent Scaling of each of latents on x, (N, S·d), in batches of batch. β is 0 (and ν 0) for a latent that never fires.
 
std::vector< double > ExplainedVarianceBySource (Crosscoder &crosscoder, const Tensor &x, int64_t batch=4096)
 Each source's explained variance on x: 1 - Σ|x^s - x̂^s|² / Σ|x^s - mean(x^s)|².
 
template<typename T >
std::pair< std::vector< T >, std::vector< T > > OnePointCrossoverAtPoint (const std::vector< T > &parent1, const std::vector< T > &parent2, size_t point)
 Splits both parents at point and swaps tails.
 
template<typename T , typename RNG >
std::pair< std::vector< T >, std::vector< T > > OnePointCrossover (const std::vector< T > &parent1, const std::vector< T > &parent2, RNG &rng)
 RNG-driven wrapper: draws an interior point in [1, size-1] uniformly.
 
template<typename T >
std::pair< std::vector< T >, std::vector< T > > TwoPointCrossoverAtPoints (const std::vector< T > &parent1, const std::vector< T > &parent2, size_t point1, size_t point2)
 Swaps the [point1, point2) segment between both parents.
 
template<typename T , typename RNG >
std::pair< std::vector< T >, std::vector< T > > TwoPointCrossover (const std::vector< T > &parent1, const std::vector< T > &parent2, RNG &rng)
 RNG-driven wrapper: draws two points in [0, size], sorted ascending.
 
template<typename T >
std::pair< std::vector< T >, std::vector< T > > UniformCrossoverByMask (const std::vector< T > &parent1, const std::vector< T > &parent2, const std::vector< bool > &swap_mask)
 Swaps each gene independently wherever swap_mask is true.
 
template<typename T , typename RNG >
std::pair< std::vector< T >, std::vector< T > > UniformCrossover (const std::vector< T > &parent1, const std::vector< T > &parent2, double swap_probability, RNG &rng)
 RNG-driven wrapper: each gene swaps independently with probability swap_probability.
 
std::pair< std::vector< double >, std::vector< double > > BlendCrossoverByGamma (const std::vector< double > &parent1, const std::vector< double > &parent2, const std::vector< double > &gamma)
 Blends each gene pair via an explicit per-gene gamma: child1_i = (1-gamma_i)*x1_i + gamma_i*x2_i, child2_i = gamma_i*x1_i + (1-gamma_i)*x2_i.
 
template<typename RNG >
std::pair< std::vector< double >, std::vector< double > > BlendCrossover (const std::vector< double > &parent1, const std::vector< double > &parent2, double alpha, RNG &rng)
 RNG-driven wrapper (DEAP's cxBlend): draws gamma_i = (1+2*alpha)*u_i - alpha per gene, u_i ~ Uniform(0, 1).
 
std::pair< std::vector< double >, std::vector< double > > SimulatedBinaryCrossoverByDraw (const std::vector< double > &parent1, const std::vector< double > &parent2, double eta, const std::vector< double > &draws)
 Simulated binary crossover (Deb & Agrawal 1995; DEAP's cxSimulatedBinary), given an explicit per-gene draw in [0, 1).
 
template<typename RNG >
std::pair< std::vector< double >, std::vector< double > > SimulatedBinaryCrossover (const std::vector< double > &parent1, const std::vector< double > &parent2, double eta, RNG &rng)
 RNG-driven wrapper: draws u_i ~ Uniform(0, 1) per gene (std::uniform_real_distribution is documented to produce values in [0, 1), matching the pure core's requirement).
 
void set_seed (uint64_t seed)
 Sets the global seed and restarts the seed stream next_seed() draws from.
 
uint64_t global_seed ()
 The seed most recently passed to set_seed() (0 by default).
 
uint64_t next_seed ()
 The next seed in the global stream: a distinct, well-mixed 64-bit value per call, reproducible for a given global seed. Components built without an explicit seed take theirs from here, so two of them never share a random stream by accident.
 
void set_deterministic (bool enabled)
 Turns deterministic mode on (the default) or off.
 
bool deterministic ()
 Whether deterministic mode is on.
 
void check_deterministic_allowed (const char *operation)
 Guard for a nondeterministic code path: call it before running one.
 
Tensor ComputeDQNTarget (const Tensor &next_q_target, const Tensor &rewards, const Tensor &dones, float gamma, DeviceBackend *backend)
 Vanilla DQN Bellman target (Mnih et al. 2015): targets[b,0] = rewards[b,0] + gamma * (1 - dones[b,0]) * max_a next_q_target[b,a].
 
Tensor ComputeDoubleDQNTarget (const Tensor &next_q_online, const Tensor &next_q_target, const Tensor &rewards, const Tensor &dones, float gamma, DeviceBackend *backend)
 Double DQN Bellman target (van Hasselt et al. 2016, arXiv:1509.06461): a* = argmax_a next_q_online[b,a], then targets[b,0] = rewards[b,0] + gamma * (1 - dones[b,0]) * next_q_target[b, a*].
 
void SyncTargetNetwork (Module &source, Module &destination)
 Hard target-network update: copies every parameter value of source into destination, element-wise and in place (Mnih et al. 2015's periodic full copy).
 
float QualityFitness (const Tensor &logits)
 E-GAN's own quality fitness Fq: mean sigmoid(D(fake)) over the batch – how convincingly "real" the discriminator currently rates these samples. Higher is better (the discriminator being fooled more).
 
float DiversityFitness (Module &discriminator, const Tensor &fake, DeviceBackend *backend)
 E-GAN's own diversity fitness Fd = -log(||grad||): the negative log of the L2 norm of the discriminator's own parameter gradient from its fake-recognition loss term (BCEWithLogitsLoss(D(fake), 0)), evaluated on fake. A smaller discriminator gradient here means the discriminator is already close to a local optimum against these particular samples – the paper's own signal that this offspring is contributing mode coverage the discriminator can't easily exploit further (discourages mode collapse).
 
float CombinedFitness (float quality, float diversity, float gamma=0.05f)
 Combined E-GAN fitness: Fq + gamma*Fd (Wang et al. 2019's own weighted combination). gamma's default (0.05) is this mission's own reasonable working value, not a literal reproduction of the paper's own tuned constant (never stated precisely enough there to reproduce exactly) – a deliberate, documented choice, not an assumed one.
 
template<typename OptimizerT >
float RunMutationStep (Module &offspring, Module &discriminator, const Tensor &noise, MutationObjective objective, OptimizerT &g_optimizer, DeviceBackend *backend, float gamma=0.05f)
 Runs one E-GAN mutation training step: trains offspring (an already-independent Module instance – typically initialized as a copy of some parent's current weights, which this function does not itself construct or assume anything about) for one step against discriminator using the given objective, then scores the mutated result via CombinedFitness on offspring's own post-mutation samples.
 
template<typename MakeGenerator , typename DOptimizerT >
std::vector< float > RunEGANGeneration (GeneratorPopulation &population, Module &discriminator, const Tensor &real_batch, const std::vector< Tensor > &noise_per_generator, const std::vector< MutationObjective > &objectives, MakeGenerator make_generator, float g_learning_rate, DOptimizerT &d_optimizer, DeviceBackend *backend, float gamma=0.05f)
 Runs one E-GAN generation: for every population member, attempts every objective in objectives (each against a fresh weight-copy offspring built by make_generator + RestoreParameters), keeps the best-combined-fitness offspring, replaces that population slot with it, then trains discriminator on real_batch plus the now-mutated population's own pooled fake output.
 
template<typename MakeGenerator , typename DOptimizerT , typename RNG >
void RunEGANTraining (GeneratorPopulation &population, Module &discriminator, const Tensor &real_batch, int num_generations, int64_t noise_dim, int64_t per_generator_batch, const std::vector< MutationObjective > &objectives, MakeGenerator make_generator, float g_learning_rate, DOptimizerT &d_optimizer, DeviceBackend *backend, RNG &rng, float gamma=0.05f)
 RNG-driven wrapper: draws fresh standard-normal noise for every population member every generation, then runs RunEGANGeneration num_generations times.
 
std::vector< uint8_t > SerializeNpy (const Tensor &x)
 A tensor as a .npy file: format version 1.0, little-endian float32 (<f4), C order, with the tensor's shape.
 
void WriteNpy (const std::string &path, const Tensor &x)
 SerializeNpy() written to path.
 
Tensor ParseNpy (const std::vector< uint8_t > &bytes, DeviceBackend *backend)
 A .npy file as a float32 tensor on backend, with the file's shape.
 
Tensor ReadNpy (const std::string &path, DeviceBackend *backend)
 ParseNpy() of the file at path.
 
std::string ProjectorVectorsTsv (const Tensor &x)
 The Embedding Projector's tensor file: a line per row of x, its values separated by tabs. Dimensions after the first are flattened.
 
std::string ProjectorMetadataTsv (const std::vector< MetadataColumn > &columns)
 The Embedding Projector's metadata file: a line per point, a column per entry of columns, separated by tabs.
 
void ExportEmbeddings (const std::string &directory, const Tensor &x, const std::vector< MetadataColumn > &columns={})
 Writes x for UMAP and t-SNE tools into directory, which must exist: vectors.npy, vectors.tsv, and metadata.tsv when there are columns.
 
EncoderLMConfig ParseEsmConfig (std::string_view json)
 Reads an ESM config.json.
 
EncoderLMConfig ReadEsmConfig (const std::string &path)
 ParseEsmConfig on a file.
 
EncoderLMConfig ParseMdlmConfig (std::string_view json)
 Reads an MDLM config.json (kuleshov-group/mdlm-owt and models trained with the same code): a bidirectional transformer with rotate-half RoPE, LayerNorms without biases, bias-free attention, a tanh-GELU MLP four times the width, and an untied linear output layer. The mask token is the vocabulary's last id.
 
std::vector< WeightMapping > EsmMapping (const EncoderLMConfig &config)
 The name mapping from an EsmForMaskedLM checkpoint to EncoderLM. Q/K/V, output, MLP and LM-head dense weights are transposed.
 
std::vector< std::string > EsmIgnoredTensors (const EncoderLMConfig &config)
 Checkpoint tensors an ESM-2 EncoderLM doesn't use: the absolute-position table and ids (unused with rotary), each layer's rotary inv_freq (read separately), and the contact head (LoadEsmContactHead reads it).
 
std::vector< WeightMapping > MdlmMapping (const EncoderLMConfig &config)
 The name mapping from an MDLM checkpoint to EncoderLM. The fused attn_qkv is split into q, k and v; linear weights are transposed. The LayerNorm biases and the adaLN modulation have no counterpart here: LoadEncoderLM folds them in (see there).
 
std::unique_ptr< EncoderLM > LoadEncoderLM (const std::string &directory, DeviceBackend *backend)
 Loads a masked LM directory: config.json and safetensors weights (one file or sharded). The config's model_type picks the model.
 
std::vector< double > ESUpdateGivenPerturbations (const std::vector< double > &theta, const std::vector< std::vector< double > > &epsilons, const std::vector< double > &fitnesses, double alpha, double sigma)
 Pure core: the exact ES parameter update given already-sampled perturbations and their fitness scores – ‘theta’ = theta + (alpha / (N*sigma)) * sum_i(F_i * epsilon_i)`.
 
template<typename FitnessFn , typename RNG >
std::vector< double > ESStep (const std::vector< double > &theta, FitnessFn fitness_fn, int population_size, double sigma, double alpha, RNG &rng)
 RNG-driven wrapper: samples population_size/2 standard-normal perturbation vectors, scores theta+sigma*epsilon and theta-sigma*epsilon for each (mirrored sampling), and returns the updated theta via ESUpdateGivenPerturbations.
 
template<typename FitnessFn , typename RNG >
ESResult RunEvolutionStrategies (std::vector< double > theta, FitnessFn fitness_fn, int num_iterations, int population_size, double sigma, double alpha, RNG &rng)
 Runs num_iterations of Evolution Strategies starting from theta, tracking the best (theta, fitness) pair seen across every evaluated center point (global elitism, the same precedent this campaign's NEAT evolutionary loop already established) – vanilla ES itself has no such tracking, but a returnable "best point found" is genuinely necessary for this to be usable as an optimizer, so it is added here as a small, logged addition beyond the paper's own bare update rule.
 
template<typename Genotype , typename FitnessT , typename FitnessFn >
void EvaluatePopulation (std::vector< Individual< Genotype, FitnessT > > &population, FitnessFn &fitness_fn, DataThreadPool *thread_pool)
 Evaluates (or re-evaluates) every individual's fitness in place via fitness_fn.
 
template<typename Genotype , typename FitnessT , typename FitnessFn , typename OffspringFn , typename SurvivorFn >
std::vector< Individual< Genotype, FitnessT > > RunEvolutionaryLoop (std::vector< Individual< Genotype, FitnessT > > population, size_t num_generations, size_t lambda_size, FitnessFn fitness_fn, OffspringFn produce_offspring_genotype, SurvivorFn survivor_selector, DataThreadPool *thread_pool=nullptr)
 Runs num_generations of the shared evolutionary-loop skeleton: evaluate -> produce lambda_size offspring (via produce_offspring_genotype, called once per offspring) -> evaluate offspring -> survivor-select mu individuals for the next generation.
 
std::string_view QuestionText (XaiQuestion question)
 The question as Liao et al. phrase it, for example "Why is this instance given this prediction?".
 
std::string_view ReasonText (XaiReason reason)
 One sentence on the reason.
 
const std::vector< XaiQuestion > & AllXaiQuestions ()
 All nine questions, in the enum's order.
 
const std::vector< XaiReason > & AllXaiReasons ()
 All four reasons, in the enum's order.
 
const std::vector< ExplainerCapabilities > & ExplainerCatalog ()
 Every explainer pulsatrix has, in a fixed order.
 
const ExplainerCapabilities & ExplainerCapabilitiesOf (std::string_view name)
 The catalog entry named name.
 
std::vector< const ExplainerCapabilities * > ExplainersFor (XaiQuestion question)
 The explainers that answer question: those that list it first, then the rest, each group in catalog order. Empty for a question pulsatrix has no explainer for yet.
 
JsonValue ToJson (const ExplainerCapabilities &capabilities)
 The declaration as a JSON object, with the enums as their to_string() names.
 
JsonValue ExplainerCatalogDocument ()
 The whole catalog: a pulsatrix.explainer_catalog.v1 document.
 
StabilityResult ComputeAttributionStability (const std::vector< Attribution > &repeated_runs)
 Measures an explainer's stability across repeated runs on the same input (charter's "repeated-run variance measured and documented" audit category). Known-unstable methods (LIME, KernelSHAP) are expected to show is_deterministic == false; every other native/surrogate explainer in this codebase is deterministic by construction.
 
AgreementReport CompareExplanations (const std::vector< Attribution > &teacher, const std::vector< Attribution > &student, const AgreementOptions &options={})
 Compares two models' attributions of the same inputs, in the same order.
 
AgreementReport ExplanationAgreement (const std::vector< Tensor > &inputs, const ExplainFn &teacher, const ExplainFn &student, const AgreementOptions &options={})
 Explains every input with both explainers, then CompareExplanations().
 
JsonValue ToJson (const AgreementReport &report)
 The report as a pulsatrix.explanation_agreement.v1 document. NaNs are written as null.
 
float Sparseness (const Attribution &attribution)
 Gini index of the attribution magnitudes (Chalasani et al. 2020; Quantus Sparseness): 0 when relevance is spread evenly, approaching 1 when one feature holds it all.
 
float Complexity (const Attribution &attribution)
 Entropy of the fractional contributions |a_i| / sum |a| (Bhatt et al. 2020; Quantus Complexity), natural log: 0 when one feature holds all relevance, ln n when spread evenly.
 
float SpearmanRankCorrelation (const std::vector< float > &x, const std::vector< float > &y)
 Spearman rank correlation, with tied values given their average rank.
 
Tensor Impute (const Tensor &input, const std::vector< bool > &removed, const Imputation &imputation)
 Returns input with every element whose removed flag is set filled by imputation.
 
PerturbationCurve DeletionCurve (const PredictFn &predict, const Tensor &input, const Attribution &attribution, const PerturbationOptions &options={})
 Deletion (MoRF): removes features from most to least relevant, imputing them, and records the target score. A faithful attribution makes the score drop fast: lower AUC is better.
 
PerturbationCurve InsertionCurve (const PredictFn &predict, const Tensor &input, const Attribution &attribution, const PerturbationOptions &options={})
 Insertion: starts from the fully imputed input and restores features from most to least relevant. A faithful attribution makes the score rise fast: higher AUC is better.
 
RandomizationResult ModelParameterRandomizationTest (Module &model, const ExplainFn &explain, const Tensor &input, uint64_t seed)
 The model-parameter randomization test (Adebayo et al., "Sanity Checks for Saliency Maps", NeurIPS 2018), cascading: randomizes the model's layers from the output down, re-explains input after each, and measures how similar the explanation stays.
 
RandomizationResult ModelParameterRandomizationTest (Module &model, const ExplainFn &explain, const Tensor &input, uint64_t seed, const std::vector< std::string > &layers)
 ModelParameterRandomizationTest over layers, in the order given: each a prefix of named_parameters() names, such as "layers.11", randomized cumulatively.
 
std::string_view to_string (CheckPriority priority)
 
JsonValue ToJson (const ExplanationPlan &plan)
 The plan as a pulsatrix.explanation_plan.v1 document. Each explainer appears by name, with its header and entry points, so the document stands alone.
 
std::string DescribePlan (const ExplanationPlan &plan)
 The plan as plain text, for a terminal or a log: the question, the explainers in order with their reasons, the checks, and the warnings.
 
Explanation BuildExplanation (const ExplanationRequest &request, const Tensor &input, const ExplainFn &explain, const PredictFn &predict, Module *model, const ExplanationCheckOptions &options={})
 Explains input with explain and runs the checks the plan asks for.
 
Explanation ReportExplanation (const ExplanationRequest &request, std::optional< Attribution > attribution, std::vector< CheckResult > checks)
 The report for an explanation whose checks ran elsewhere: plans request.question and request.reason, matches checks to the planned ones by name (each takes the planned priority), marks the planned checks missing from checks NotRun, and derives the caveats.
 
CheckResult SliceErrorCheck (const SliceErrorReport &report)
 The per_slice_error check's result for a report PerSliceError() made: Failed when a slice is worse than the rest, Passed otherwise. For ReportExplanation(), or a model BuildExplanation() can't score, such as a regressor.
 
std::vector< Caveat > DeriveCaveats (const Explanation &explanation)
 The caveats an explanation carries, from the report alone:
 
std::string_view to_string (CheckOutcome outcome)
 
std::string_view to_string (CaveatSeverity severity)
 
JsonValue ToJson (const Explanation &explanation)
 The explanation as a pulsatrix.explanation.v1 document, attribution values included.
 
std::string DescribeExplanation (const Explanation &explanation)
 The explanation as plain text: the question, whether it supports the reason, the largest attributions, the checks and the caveats.
 
SensitivityReport ExplanationSensitivity (const Tensor &input, const ExplainFn &explain, const PredictFn &predict, const DifferentiableClassifier *classifier, DeviceBackend *backend, const SensitivityOptions &options={})
 Measures how much explain's explanation of input changes under small perturbations.
 
JsonValue ToJson (const SensitivityReport &report)
 The report as a pulsatrix.explanation_sensitivity.v1 document.
 
Tensor AttentionMap (const Tensor &features, DeviceBackend *backend, double p=2.0)
 The attention map AttentionTransferLoss compares: (N, positions), each row L2-normalized, on features' device.
 
double MeanL0 (const std::vector< float > &codes, int64_t num_features, float threshold=0.0f)
 The mean number of codes above threshold in magnitude per input (L0), for codes row-major (N, num_features).
 
double MeanL0 (Featurizer &featurizer, const Tensor &x, float threshold=0.0f)
 MeanL0 of a featurizer's codes for x, in blocks: a block counts once when any of its codes is above threshold in magnitude.
 
template<typename Optimizer >
FeaturizerLoss TrainFeaturizer (Featurizer &featurizer, const Tensor &x, Optimizer &optimizer, bool unit_norm_decoder=true, FeatureActivityTracker *tracker=nullptr)
 One training step for any featurizer: zero the gradients, loss_and_backward(), one optimizer step, then normalize_decoder() when unit_norm_decoder. When tracker is given it observes the batch's codes.
 
template<typename Optimizer >
FeaturizerLoss TrainFeaturizer (Featurizer &featurizer, const Tensor &x, const Tensor &target, Optimizer &optimizer, bool unit_norm_decoder=true, FeatureActivityTracker *tracker=nullptr)
 TrainFeaturizer for a transcoder: one step on predicting target from x.
 
ReconstructionMetrics EvaluateReconstruction (Featurizer &featurizer, const Tensor &x, double dense_rate=0.1, int64_t batch=4096)
 Encodes and reconstructs x, (N, input_dim), in batches of batch rows.
 
ReconstructionMetrics EvaluatePrediction (Featurizer &featurizer, const Tensor &x, const Tensor &target, double dense_rate=0.1, int64_t batch=4096)
 EvaluateReconstruction for a transcoder: predict(x) against target, (N, output_dim). Explained variance is relative to the targets' variance.
 
HiddenStateHook SpliceHook (Featurizer &featurizer, int64_t position, std::vector< bool > rows={})
 Splices the featurizer in at one position: a hook that replaces the hidden states there, (N, L, input_dim), by their reconstructions, and leaves other positions alone.
 
HiddenStateHook AblationHook (int64_t position, std::vector< bool > rows={})
 Zero-ablates one position: the same rows set to 0 instead of reconstructed.
 
MlpHook MlpSpliceHook (Featurizer &transcoder, std::vector< bool > rows={})
 Splices a transcoder in for an MLP (install it with EncoderBlock::set_mlp_hook() or TransformerBlock::set_mlp_hook()): the MLP's output rows are replaced by predict() of its input rows.
 
MlpHook MlpAblationHook (std::vector< bool > rows={})
 Zero-ablates an MLP: its output rows set to 0.
 
LossRecovered MeasureLossRecovered (Featurizer &featurizer, int64_t position, const std::function< double(const HiddenStateHook &)> &loss, const std::vector< bool > &rows={})
 Loss recovered, SAEBench's main downstream measure.
 
LossRecovered MeasureMlpLossRecovered (Featurizer &transcoder, const std::function< double(const MlpHook &)> &loss, const std::vector< bool > &rows={})
 Loss recovered for a transcoder spliced in for an MLP: loss installs the MlpHook it is given on the MLP's block, runs the model, removes it and returns the loss. Ablation zeroes the MLP's output.
 
AbsorptionResult FeatureAbsorption (Featurizer &featurizer, const Tensor &x, const std::vector< int > &labels, const AbsorptionOptions &options={})
 Feature absorption (Chanin et al.; SAEBench's version, in outline). A concept is absorbed when the features that stand for it stay silent on an input that has it, because a more specific feature fires instead and carries its direction: a "starts with S" feature that skips "short", which a "short" feature covers.
 
RelevanceDiff DiffRelevance (Module &base, Module &tuned, const Tensor &input, const DiffTarget &target={}, const LRPRuleConfig &config={})
 Explains the same prediction in both models: forward() on input, then relevance seeded with each model's own score for the class, at the class only.
 
RelevanceDiff DiffAdapterRelevance (Module &model, const Tensor &input, const DiffTarget &target={}, const LRPRuleConfig &config={})
 DiffRelevance() for a fine-tune held as adapters on model: the tuned run with its LoRA adapters, IA³ vectors and (for a CausalLM) interventions on, the base run with them off. They are back on afterwards, even if a call throws.
 
IntruderResult IntruderDimensions (const Tensor &base, const Tensor &tuned, int64_t k=10, double epsilon=0.6)
 Counts the top-k singular vectors of tuned that no singular vector of base resembles: |cos| < epsilon against every one of them.
 
std::vector< LayerIntruders > LoraIntruderDimensions (Module &model, int64_t k=10, double epsilon=0.6)
 Intruder dimensions of every LoRA layer: its base weight W against W + (alpha / r) A B.
 
std::vector< LayerIntruders > IntruderDimensions (Module &base, Module &tuned, int64_t k=10, double epsilon=0.6)
 Intruder dimensions of every LinearModule the two models share by name and shape: a full fine-tune against its base.
 
double SpearmanCorrelation (const std::vector< double > &x, const std::vector< double > &y)
 Spearman's rank correlation, ties given their average rank (scipy's spearmanr). NaN if either input is constant.
 
double RocAuc (const std::vector< int > &labels, const std::vector< double > &scores)
 Area under the ROC curve of scores for labels (0 or 1), ties counted half (sklearn's roc_auc_score). NaN if only one class is present.
 
double MatthewsCorrelation (const std::vector< int > &labels, const std::vector< int > &predicted)
 Matthews correlation of binary labels and predicted (sklearn's matthews_corrcoef); 0 when a row or column of the confusion matrix is empty.
 
double MedianSplitMcc (const std::vector< int > &labels, const std::vector< double > &scores)
 ProteinGym's MCC: scores at or above their median predict 1.
 
double Ndcg (const std::vector< double > &true_scores, const std::vector< double > &predicted, double top_percent=10.0)
 ProteinGym's NDCG: gains are the true scores min-max scaled to [0, 1]; the variants the model ranks in the top top_percent (floor of the count) contribute gain / log2(rank + 1), normalized by the same sum for the truly best ones. Zero gains are dropped.
 
double TopRecall (const std::vector< double > &true_scores, const std::vector< double > &predicted, double top_true=10.0, double top_model=10.0)
 ProteinGym's top recall: of the variants at or above the true scores' (100 - top) percentile, the fraction also at or above the predicted scores' percentile. Percentiles interpolate linearly, as numpy's do.
 
double Percentile (std::vector< double > values, double q)
 The q-th percentile (0 to 100) with linear interpolation (numpy's default).
 
FitnessMetrics EvaluateFitness (const std::vector< double > &dms_scores, const std::vector< int > &dms_bins, const std::vector< double > &predicted)
 FitnessMetrics for one assay: measured scores and their binarized labels, and predictions.
 
double FixedTopologyXORForward (const std::vector< double > &theta, const std::array< double, 2 > &inputs)
 Forward pass: theta layout is [w1_00, w1_01, b1_0, w1_10, w1_11, b1_1, w2_0, w2_1, b2] – h_j = sigmoid(w1_j0*x0 + w1_j1*x1 + b1_j) for j in {0,1}, y = sigmoid(w2_0*h0 + w2_1*h1 + b2).
 
double FixedTopologyXORFitness (const std::vector< double > &theta)
 Scores theta against all four XOR patterns as 4.0 minus the sum of squared errors – identical convention to XORFitness (neat_xor_fitness.hpp), so an all-zero theta scores exactly 3.0 (every pattern outputs sigmoid(0)=0.5), the same fixed point NEAT's own fresh, all-zero-weight genome scores.
 
GAEResult ComputeGAE (const Tensor &rewards, const Tensor &dones, const Tensor &values, float bootstrap_value, float gamma, float lambda, DeviceBackend *backend)
 Generalized Advantage Estimation (Schulman et al. 2016, arXiv:1506.02438): the exponentially-weighted average of k-step advantage estimators, computed in one reverse pass.
 
void ProcessLogits (std::vector< float > &logits, const std::vector< int64_t > &tokens, int64_t num_new_tokens, const GenerationConfig &config)
 Applies the configured logit processing, in Hugging Face's order: repetition penalty, the EOS ban before min_new_tokens, then (when sampling) temperature, top-k, top-p and min-p. Removed tokens get -infinity. With do_sample false only the first two apply.
 
GenerationResult Generate (const NextTokenLogitsFn &model, const std::vector< int64_t > &prompt, const GenerationConfig &config={})
 Generates up to max_new_tokens after prompt, one at a time: process the next-token logits, take the most likely token (greedy) or draw one from their softmax (sampling), append it, and stop after an EOS token.
 
NextTokenLogitsFn MakeNextTokenLogits (std::vector< Module * > layers, DeviceBackend *backend)
 A NextTokenLogitsFn for a stack of pulsatrix modules that maps token ids (1, L) to logits (1, L, vocab) (for example EmbeddingModule, causal TransformerBlocks, an RMSNorm and a TiedLMHeadModule): it runs the whole sequence through the modules and returns the last position's logits.
 
NextTokenLogitsFn MakeCachedNextTokenLogits (EmbeddingModule &embedding, std::vector< TransformerBlock * > blocks, std::vector< Module * > head, DeviceBackend *backend, int64_t max_length, float embed_scale=1.0f, BlockOutputHook after_block={})
 A NextTokenLogitsFn for embedding -> transformer blocks -> head layers that keeps a KV cache per block (LLM-5): each call runs only the tokens after the longest prefix it has already processed, so generating n tokens costs one pass over the prompt and then one position per token, instead of n passes over the whole sequence. A call with a different history (a new prompt, or a shorter or edited one) truncates the caches to the shared prefix and continues from there.
 
Tensor SliceBatch (const Tensor &t, int64_t start, int64_t count, DeviceBackend *backend)
 Extracts rows [start, start+count) along t's leading dimension into a new Tensor – the inverse of Tensor::Stack, needed to split a pooled discriminator gradient back into each population member's own slice.
 
std::vector< float > FlattenParameters (Module &module)
 Flattens every parameter tensor module.parameters() reports (in that order) into one vector – the concrete mechanism Phase 5 Mission 2's mutation-offspring construction uses to copy a parent generator's current weights into a freshly-constructed (architecturally identical) offspring instance before mutating the copy.
 
void RestoreParameters (Module &module, const std::vector< float > &flat)
 Overwrites every parameter tensor module.parameters() reports (in that order) from flat – the inverse of FlattenParameters.
 
void ZeroModuleGradients (Module &module)
 Zeros every gradient tensor module.parameters() reports – a standalone alternative to calling some optimizer's own zero_grad(module) when no persistent per-module optimizer instance is being kept around (Phase 5 Mission 2's own mutation-attempt loop constructs a fresh optimizer per attempt, so there is no single optimizer instance left to call zero_grad on between generations).
 
Tensor GeneratePooledFakeSamples (GeneratorPopulation &population, const std::vector< Tensor > &noise_per_generator, DeviceBackend *backend)
 Runs every population member's generator forward on its own noise batch (noise_per_generator[i] for population member i), then pools the results (Tensor::Stack, concatenated along the batch dimension, in population order) into one combined fake-sample batch – the discriminator's own training input in E-GAN.
 
void BackwardThroughPopulation (GeneratorPopulation &population, const Tensor &pooled_grad, const std::vector< int64_t > &batch_sizes, DeviceBackend *backend)
 Given pooled_grad (the gradient w.r.t. the pooled fake batch GeneratePooledFakeSamples produced – e.g. from discriminator.backward() called after a forward on that pooled batch), routes each population member's own slice back through that member's own backward() – the concrete mechanism that lets one shared discriminator train against every generator's own output while each generator's own parameters still receive exactly its own correct gradient.
 
GFlowNetTrajectory sample_gflownet_trajectory (HyperGridEnv &env, GFlowNetForwardPolicy &forward_policy)
 Samples one full trajectory: resets env, then repeatedly samples a masked action from forward_policy and steps env until termination (an explicit stop or env's own max_steps cap).
 
std::vector< std::vector< float > > MorrisSample (const GlobalSensitivityProblem &problem, const MorrisOptions &options={})
 Morris trajectories (Morris 1991): each starts at a random grid point and moves one feature at a time, in a random order, by the Morris step. Rows are feature values in the problem's ranges, (num_features + 1) per trajectory.
 
MorrisResult AnalyzeMorris (const std::vector< std::vector< float > > &samples, const std::vector< float > &outputs, const MorrisOptions &options={})
 Morris statistics from samples laid out as MorrisSample's (or SALib's) trajectories and one output per row: the same elementary effects and mu, mu*, sigma as SALib 1.6 morris.analyze (unscaled). The confidence interval is a bootstrap with this library's own generator, so it agrees with SALib's in distribution, not digit for digit.
 
MorrisResult ComputeMorris (const std::function< Tensor(const Tensor &)> &predict, const GlobalSensitivityProblem &problem, int64_t target_index, const MorrisOptions &options={})
 Samples, runs the model and analyzes: MorrisSample, then AnalyzeMorris.
 
SobolResult AnalyzeSobol (const std::vector< float > &outputs, int64_t num_features, const SobolOptions &options={})
 Sobol indices from outputs in SALib's layout without second order: N blocks of (num_features + 2) outputs, f(A), f(AB_1) ... f(AB_D), f(B). Outputs are standardized first, then the first order uses Saltelli et al. (2010)'s estimator and the total order Jansen's, exactly as SALib 1.6 does. The bootstrap uses this library's generator.
 
SobolResult ComputeSobol (const std::function< Tensor(const Tensor &)> &predict, const GlobalSensitivityProblem &problem, int64_t target_index, const SobolOptions &options={})
 Samples two independent uniform matrices A and B over the problem's ranges, builds the Saltelli design (AB_j is A with column j from B), runs the model on every row and calls AnalyzeSobol.
 
GoldenSequenceResult CompareLogits (const std::vector< float > &got, const std::vector< float > &expected, int64_t num_tokens, int64_t vocab)
 Compares one sequence's logits, both (L, vocab) row-major.
 
GoldenReport CompareToGolden (CausalLM &model, const SafetensorsFile &golden, float threshold=1e-3f)
 Runs model on every ids.<k> sequence of a golden file (as written by tools/golden/make_golden.py) and compares all its logits with logits.<k> (CompareLogits).
 
Configuration UnitCubeToConfiguration (const SearchSpace &space, const std::vector< float > &t)
 Maps a unit-hypercube point (one value per parameter, each in [0, 1]) to a Configuration, using space's own declared bounds.
 
template<typename ObjectiveFn , typename RNG >
std::vector< Trial > RunGPBOLoop (const SearchSpace &space, ObjectiveFn objective_fn, size_t num_initial_random, size_t num_iterations, AcquisitionKind acquisition, size_t num_candidates, RNG &rng)
 Runs GP-BO: num_initial_random uniformly-random trials, then num_iterations trials each chosen by fitting a GP to every trial so far and maximizing acquisition over num_candidates random points in the unit hypercube.
 
float ClipGradNorm (Module &module, float max_norm, bool error_if_nonfinite=false)
 Scales every trainable parameter's gradient so their global L2 norm is at most max_norm, as torch.nn.utils.clip_grad_norm_ does, and returns the norm before clipping.
 
HfModelConfig ParseHfConfig (std::string_view json)
 Parses config.json text. A multimodal config's text_config is read for the language model.
 
HfModelConfig ReadHfConfig (const std::string &path)
 ParseHfConfig on a file.
 
std::vector< double > RopeInverseFrequencies (const HfModelConfig &config)
 The RoPE frequency of each pair, head_dim / 2 of them, as Hugging Face computes them: rope_theta^(-2i / head_dim), then rescaled by rope_scaling when it is "linear" (all divided by the factor) or "llama3" (low frequencies divided by the factor, high ones kept, the band between interpolated; LLM-6).
 
AttentionConfig ToAttentionConfig (const HfModelConfig &config)
 The attention layer the config describes: rotate-half RoPE (with its scaling), causal unless the config says otherwise, its head counts, biases, QK-Norm and epsilon, and Gemma's score scale and QK-Norm offset. For a model whose layers differ, this is a full-attention layer.
 
AttentionConfig ToAttentionConfig (const HfModelConfig &config, int64_t layer)
 Layer layer's attention (LLM-9): a sliding-window layer gets its window and its own RoPE base, unscaled; a full-attention layer is ToAttentionConfig(config).
 
Configuration DecodeGenotype (const SearchSpace &space, const std::vector< double > &genotype)
 Decodes a unit-hypercube genotype into a Configuration using space's own declared bounds: Continuous linearly, LogUniform geometrically (both identical to gp_bo.hpp's UnitCubeToConfiguration); Integer by linear interpolation then rounding to the nearest integer (std::round – ties away from zero, portable); Categorical by linear interpolation into an index, floored, clamped to the last category (handles the gene == 1.0 boundary, which would otherwise floor to one-past-the-end).
 
template<typename RNG >
Configuration RandomSample (const SearchSpace &space, RNG &rng)
 Draws one configuration uniformly at random from space: Continuous parameters uniform over [lower, upper]; LogUniform parameters uniform in log-space (so e.g. [0.001, 1.0] gives 0.001-0.01, 0.01-0.1, and 0.1-1.0 equal probability, not the top decade 90% of the draws); Integer parameters uniform over the inclusive integer range; Categorical parameters uniform over the category list.
 
std::vector< Configuration > GridSample (const SearchSpace &space, size_t points_per_continuous_dimension)
 Enumerates the full cartesian-product grid over space.
 
std::vector< HyperbandBracket > ComputeHyperbandBrackets (int max_resource, double eta)
 Computes the classic Hyperband bracket schedule: s_max = floor(log_eta(max_resource)), B = (s_max + 1) * max_resource; for s from s_max down to 0, num_configs = ceil((B / max_resource) * (eta^s / (s + 1))), initial_budget = round(max_resource / eta^s) (each floored at 1).
 
template<typename RNG >
HyperbandResult RunHyperband (const SearchSpace &space, const TrialFactory &make_trial, int max_resource, double eta, RNG &rng)
 Runs one Successive Halving bracket (successive_halving.hpp) per ComputeHyperbandBrackets(max_resource, eta), keeping the best result across all of them.
 
std::vector< std::string > ApplyIA3 (Module &model, const IA3Config &config={})
 Attaches an IA³ vector to each LinearModule config selects, then freezes everything else, as PEFT's get_peft_model() does.
 
std::vector< std::pair< std::string, LinearModule * > > IA3Layers (Module &model)
 The model's LinearModules with an IA³ vector, by name, in the model's order.
 
void MergeIA3 (Module &model)
 Folds every vector into its layer's weights (and an output-scaling layer's bias).
 
void UnmergeIA3 (Module &model)
 Divides it back out, as PEFT does. Entries of l within 1e-8 of 0 can't be undone exactly.
 
void SetIA3Enabled (Module &model, bool enabled)
 Turns every vector on or off.
 
void RemoveIA3 (Module &model)
 Removes every vector; merged ones stay in the weights.
 
void SaveIA3Adapter (Module &model, const std::string &directory, const std::vector< WeightMapping > &mapping={})
 Writes the model's IA³ vectors as a PEFT adapter directory (adapter_model.safetensors with base_model.model.<module>.ia3_l, (out, 1) or (1, in), and adapter_config.json).
 
void LoadIA3Adapter (Module &model, const std::string &directory, const std::vector< WeightMapping > &mapping={})
 Reads a PEFT IA³ adapter directory onto the model, telling feedforward layers by the vectors' shapes, and freezes the rest of the model.
 
std::vector< float > FeatureGrid (const std::vector< Tensor > &background, int64_t feature_index, int64_t grid_size=100, float lower_percentile=0.05f, float upper_percentile=0.95f)
 An evenly spaced grid for one feature, built the way scikit-learn's partial_dependence builds it: the feature's distinct values when there are fewer than grid_size of them, otherwise grid_size points from the lower to the upper percentile of the feature's values (scipy.stats.mstats.mquantiles with its default plotting positions).
 
IceResult ComputeIce (const std::function< Tensor(const Tensor &)> &predict, const std::vector< Tensor > &instances, int64_t feature_index, int64_t target_index, const std::vector< float > &grid)
 Computes ICE curves for every instance.
 
PartialDependence2D ComputePartialDependence2D (const std::function< Tensor(const Tensor &)> &predict, const std::vector< Tensor > &background, int64_t feature_x, int64_t feature_y, int64_t target_index, const std::vector< float > &grid_x, const std::vector< float > &grid_y)
 Two-feature partial dependence: for every pair (grid_x[c], grid_y[r]), the mean over the background of the prediction with both features set. Where it isn't the sum of the two one-feature curves, the features interact.
 
AleResult ComputeAle (const std::function< Tensor(const Tensor &)> &predict, const std::vector< Tensor > &instances, int64_t feature_index, int64_t target_index, int64_t num_bins=20)
 Computes first-order ALE the way PyALE 1.2 (and R's ALEPlot) does: edges at the feature's type-1 quantiles (num_bins + 1 of them, duplicates dropped), bins closed on the right with the first also holding the minimum, and centering by the count-weighted mean of each bin's midpoint effect.
 
JsonValue ParseJson (std::string_view text)
 Parses one JSON document.
 
std::string WriteJson (const JsonValue &value)
 Writes value as JSON, indented by two spaces and ending with a newline.
 
std::string WriteJsonCompact (const JsonValue &value)
 Writes value as JSON on one line, with no whitespace and no trailing newline.
 
std::vector< int64_t > EveryOtherLayer (int64_t num_layers)
 Layers 0, 2, 4, ... of a num_layers model: one out of two, DistilBERT's choice.
 
std::unique_ptr< CausalLM > MakeStudentFromLayers (CausalLM &teacher, const std::vector< int64_t > &layers, DeviceBackend *backend)
 A CausalLM with teacher's config and weights but only the blocks in layers, in that order: the student's block j is a copy of the teacher's block layers[j]. The embedding, final norm and head are copied too; layer_types keeps the chosen layers'.
 
std::vector< float > SolveLinearSystem (std::vector< std::vector< float > > a, std::vector< float > b)
 Solves A*x = b via Gaussian elimination with partial pivoting.
 
std::vector< JsonValue > ReadJsonl (const std::string &path)
 Reads a JSONL file: one JSON value a line. Blank lines are skipped.
 
std::vector< PromptCompletion > TokenizePromptCompletions (const std::vector< JsonValue > &rows, const TextTokenizer &tokenizer, const std::string &prompt_key="prompt", const std::string &completion_key="completion", bool add_special_tokens=false)
 Tokenizes each row's prompt and completion strings (objects with those keys). The two are tokenized separately, so a completion like " Yes" keeps its own tokens whatever the prompt ends with.
 
CausalLmBatch CollatePromptCompletions (const std::vector< PromptCompletion > &examples, DeviceBackend *backend, int64_t pad_id=0)
 Builds a batch for TokenCrossEntropyLoss: position i predicts token i + 1, and only the completion's tokens count. The completion's last token is never an input (nothing follows it), so each row is one token shorter than prompt + completion.
 
std::vector< double > CompletionLogProbs (CausalLM &model, const std::vector< PromptCompletion > &examples, DeviceBackend *backend, int64_t batch_size=8)
 log P(completion | prompt) under the model, summed over the completion's tokens, in double. Runs forward passes only, batch_size examples at a time, grouped by length.
 
ChoiceScores ScoreChoices (CausalLM &model, const std::vector< std::vector< int64_t > > &prompts, const std::vector< int64_t > &choice_tokens, DeviceBackend *backend, int64_t batch_size=8)
 Scores the next token after each prompt against a fixed set of single-token choices, such as " Yes" and " No". For two choices, choice_log_probs[n][0] - choice_log_probs[n][1] is the log-odds of the first.
 
int64_t SingleTokenId (const TextTokenizer &tokenizer, const std::string &text)
 The id of a string that must tokenize to exactly one token, such as " Yes".
 
std::vector< std::string > ApplyLora (Module &model, const LoRAConfig &config={})
 Attaches a LoRA adapter to each LinearModule that config.target_modules selects, then freezes everything else: only the adapters train, as with PEFT's get_peft_model().
 
std::vector< std::pair< std::string, LinearModule * > > LoraLayers (Module &model)
 The model's LinearModules that have an adapter, by name, in the model's order.
 
std::vector< LoraLayerRelevance > LoraRelevanceSplit (Module &model)
 How much of each adapted layer's relevance went through its adapter in the model's last relevance pass (LoRARelevance::Split, the default), in the model's order: where, and for which inputs, the fine-tuning changed the explanation.
 
void MergeLora (Module &model)
 Merges every adapter into its base weight (LinearModule::merge_lora()).
 
void UnmergeLora (Module &model)
 Takes every merged adapter out of its base weight again.
 
void SetLoraEnabled (Module &model, bool enabled)
 Turns every adapter on or off, so one model runs as the base or as the fine-tune.
 
void RemoveLora (Module &model)
 Removes every adapter. Merged ones stay in the weights (PEFT's merge_and_unload() is MergeLora() then this); unmerged ones are dropped (PEFT's unload()).
 
void SaveLoraAdapter (Module &model, const std::string &directory, const std::vector< WeightMapping > &mapping={})
 Writes the model's adapters as a PEFT adapter directory: adapter_model.safetensors and adapter_config.json, which PEFT's PeftModel.from_pretrained() loads onto the Hugging Face model.
 
void LoadLoraAdapter (Module &model, const std::string &directory, const std::vector< WeightMapping > &mapping={})
 Reads a PEFT LoRA adapter directory onto the model: attaches an adapter to each layer it has weights for, with r from their shapes and lora_alpha and lora_dropout from adapter_config.json, and freezes the rest as ApplyLora() does.
 
std::vector< LoReFTIntervention * > ApplyLoReFT (CausalLM &model, const LoReFTConfig &config={})
 Installs a LoReFTIntervention after each of config.layers' blocks and freezes the rest of the model: only the interventions train.
 
void OrthonormalizeLoReFT (CausalLM &model)
 orthonormalize() on every LoReFT intervention of the model: call it after each optimizer step.
 
void SaveLoReFT (CausalLM &model, const std::string &path)
 Saves the model's LoReFT interventions as safetensors: per layer i, pyreft's state dict under layer.<i>.rotate_layer, layer.<i>.learned_source.weight and layer.<i>.learned_source.bias, in pyreft's layouts, with metadata first and last.
 
std::vector< LoReFTIntervention * > LoadLoReFT (CausalLM &model, const std::string &path)
 Installs the interventions in a file SaveLoReFT() wrote, or one built from pyreft's per-intervention state dicts under those keys (convert its .bin files with tools/convert/pickle_to_safetensors.py), and freezes the rest of the model.
 
ConservationResult ComputeConservation (const Tensor &relevance_in, const Tensor &relevance_out)
 Sums relevance_in and relevance_out independently and reports their gap.
 
std::string lrp_rule_name (LRPRule rule)
 Lower-case rule name ("epsilon", "gamma", "alpha_beta", "zbox") for messages/metadata.
 
MaskedDiffusionResult SampleMaskedDiffusion (const DenoiserFn &model, const std::vector< int64_t > &tokens, const MaskedDiffusionConfig &config)
 Fills every masked position of tokens over the configured steps.
 
DenoiserFn MakeDenoiser (EncoderLM &model, DeviceBackend *backend)
 A DenoiserFn for an EncoderLM: one forward pass over the sequence, (1, L) to logits (1, L, vocab). The model isn't owned and must outlive the function.
 
DenoiserFn MakeDenoiser (CausalLM &model, DeviceBackend *backend)
 A DenoiserFn for a CausalLM loaded with bidirectional attention, such as an A2D diffusion model (HfModelConfig::causal false). The model must outlive the function.
 
CommitmentRelevance ExplainCommitments (StepRelevanceModel &model, const MaskedDiffusionResult &trajectory, int64_t mask_token_id, const std::vector< CommitmentTarget > &targets, CommitmentMode mode=CommitmentMode::Graph)
 Explains targets on trajectory, which SampleMaskedDiffusion produced with model's logits. Each step's input is rerun, so the model must give the logits it gave then.
 
MaskedDiffusionResult ReplayMaskedDiffusion (const DenoiserFn &model, const MaskedDiffusionResult &trajectory, const std::vector< int64_t > &input, const MaskedDiffusionConfig &config, const std::vector< int64_t > &skipped={})
 Reruns trajectory from input with its write order frozen: each step writes the same positions as before, each taking the model's most likely allowed token for the new sequence (greedy, as explanation runs are). Positions in skipped are never written, and a position input masks that the trajectory never wrote (a deleted prompt token) stays masked, so the result may keep mask tokens.
 
double ReplayCommitmentValue (const DenoiserFn &model, const MaskedDiffusionResult &trajectory, const std::vector< int64_t > &input, const MaskedDiffusionConfig &config, const std::vector< CommitmentTarget > &targets, const std::vector< int64_t > &skipped={})
 The explained value on a replay (ReplayMaskedDiffusion): each target's logit at the step that wrote it in trajectory, for the token the trajectory wrote there (or the target's fixed token), summed. A target in skipped still counts at that step.
 
CommitmentDeletionCurve CommitmentDeletionCheck (const DenoiserFn &model, const MaskedDiffusionResult &trajectory, const MaskedDiffusionConfig &config, const std::vector< CommitmentTarget > &targets, const std::vector< float > &prompt_relevance, int64_t steps=10, int64_t random_orders=3, uint64_t seed=0)
 Deletes prompt tokens (replaces them with the mask token) in order of how much they support the value (prompt_relevance of the value's sign, largest first), replays the trajectory each time (ReplayCommitmentValue), and records the value, beside random_orders random orders.
 
CommitmentPatchResult CommitmentPatchCheck (const DenoiserFn &model, const MaskedDiffusionResult &trajectory, const MaskedDiffusionConfig &config, const std::vector< CommitmentTarget > &targets, const CommitmentRelevance &graph)
 Leaves each committed intermediate token masked in turn, replays the trajectory, and compares the change in the value with the relevance graph relayed through that token.
 
EigenResult SymmetricEigen (const Tensor &a)
 All eigenvalues and eigenvectors of a symmetric matrix, by Householder reduction to tridiagonal form followed by QL with implicit shifts.
 
std::vector< double > SymmetricEigenvalues (std::vector< double > a, int64_t n)
 SymmetricEigen()'s eigenvalues, in double precision from end to end: for a matrix computed in double, such as a Gram matrix, whose small eigenvalues a float copy would lose.
 
DoubleEigenResult SymmetricEigenInDouble (std::vector< double > a, int64_t n)
 SymmetricEigen() in double precision from end to end, eigenvectors included: PCA's directions and variances from a covariance or Gram matrix computed in double.
 
DominantEigenResult PowerIteration (const Tensor &a, int64_t max_iterations=1000, float tolerance=1e-6f, uint64_t seed=0)
 The dominant eigenpair of a symmetric matrix by power iteration – cheaper than SymmetricEigen() when only the top eigenpair is needed (spectral norm, stable rank).
 
QRResult QR (const Tensor &a)
 Thin QR factorization by Householder reflections.
 
SVDResult SVD (const Tensor &a)
 Thin singular value decomposition by one-sided (Hestenes) Jacobi rotations.
 
void append_named_parameters (std::vector< NamedParamRef > &out, const std::string &prefix, Module &child)
 Appends child's named parameters to out, each renamed to prefix.name – the one step every container's named_parameters() repeats per child.
 
std::vector< NamedModuleRef > NamedModules (Module &root)
 Every module under root, depth first with each parent before its children, named by their full dotted path (layers.0.mha.q_proj); root itself isn't included.
 
void release_tensor (Tensor &t)
 Frees t's buffer: it becomes an empty tensor on the same backend and device.
 
void append_named_buffers (std::vector< NamedBufferRef > &out, const std::string &prefix, Module &child)
 Appends child's named buffers to out, each renamed to prefix.name.
 
std::vector< bool > BitFlipMutationByMask (const std::vector< bool > &genotype, const std::vector< bool > &flip_mask)
 Flips each gene where flip_mask is true, leaves the rest unchanged.
 
template<typename RNG >
std::vector< bool > BitFlipMutation (const std::vector< bool > &genotype, double mutation_probability, RNG &rng)
 RNG-driven wrapper: each gene flips independently with probability mutation_probability.
 
std::vector< double > GaussianMutationByNoise (const std::vector< double > &genotype, const std::vector< double > &noise, const std::vector< bool > &apply_mask)
 Adds noise[i] to genotype[i] wherever apply_mask[i] is true, leaves the rest unchanged.
 
template<typename RNG >
std::vector< double > GaussianMutation (const std::vector< double > &genotype, double sigma, double mutation_probability, RNG &rng)
 RNG-driven wrapper: each gene independently receives N(0, sigma^2) noise with probability mutation_probability.
 
double PolynomialMutationByDraw (double x, double lower, double upper, double eta, double u)
 Polynomial-mutates a single bounded gene given an explicit draw.
 
template<typename RNG >
std::vector< double > PolynomialMutation (const std::vector< double > &genotype, const std::vector< double > &lower_bounds, const std::vector< double > &upper_bounds, double eta, double mutation_probability, RNG &rng)
 RNG-driven wrapper: each gene independently mutates (via PolynomialMutationByDraw) with probability mutation_probability.
 
Neighbors NearestNeighbors (const Tensor &points, const NeighborOptions &options={})
 Each point's k nearest other points (a point is never its own neighbor).
 
Neighbors NearestNeighbors (const Tensor &queries, const Tensor &points, const NeighborOptions &options={})
 Each query's k nearest points from another set of the same width, for example new inputs against a reference set. With center, both are centered on the points' mean.
 
std::vector< std::pair< int64_t, int64_t > > MutualNearestNeighbors (const Tensor &a, const Tensor &b, const NeighborOptions &options={})
 The pairs (i, j), a[i] from a and b[j] from b, where b[j] is among a[i]'s k nearest in b and a[i] is among b[j]'s k nearest in a. Used to match items across two sets in the same space, such as the same concepts in two batches.
 
double MutualKnnAlignment (const Tensor &a, const Tensor &b, const NeighborOptions &options={})
 Mutual-kNN alignment (Huh et al. 2024): how far two representations of the same inputs agree on which inputs are alike. For each input, the fraction of its k nearest neighbors under a that are also among its k nearest under b, averaged over the inputs.
 
Hubness MeasureHubness (const Neighbors &neighbors, int64_t num_points)
 Measures hubness in neighbors, which name points 0 to num_points - 1.
 
std::vector< int > AllocateOffspringCounts (const std::vector< double > &species_adjusted_fitness_sums, int population_size)
 Pure core: allocates population_size offspring slots across species proportionally to each species' own adjusted-fitness sum, using the largest-remainder (Hamilton) apportionment method so the total always sums to exactly population_size (ties in fractional remainder broken by species index, earliest first). Falls back to an equal split (remainder to the earliest species, by index) if every species sum is non-positive, rather than dividing by zero.
 
template<typename RNG >
NEATGenome ReproduceOffspring (const NEATGenome &parent, InnovationTracker &tracker, RNG &rng, double weight_mutation_sigma, double weight_mutation_probability, double add_connection_probability, double add_node_probability)
 RNG-driven wrapper: clones parent, then applies weight mutation (gated per-connection by weight_mutation_probability inside MutateWeights itself) and, independently, one attempt each at the two structural mutations, each gated by its own probability.
 
template<typename FitnessFn , typename RNG >
NEATEvolutionResult RunNEATEvolution (std::vector< NEATGenome > population, FitnessFn fitness_fn, int num_generations, double compatibility_threshold, double c1, double c2, double c3, double weight_mutation_sigma, double weight_mutation_probability, double add_connection_probability, double add_node_probability, InnovationTracker &tracker, RNG &rng)
 Runs num_generations of speciated, mutation-only NEAT evolution. Each generation: evaluates every genome's fitness via fitness_fn, tracks the best genome seen across the whole run so far (global elitism – best_fitness never decreases generation to generation), speciates the population, applies fitness sharing, allocates each species a share of the next generation proportional to its adjusted-fitness sum, and fills that share with one unmutated species-champion copy plus mutated copies of uniformly-randomly chosen species members.
 
std::vector< double > EvaluateNEATPhenotype (const NEATGenome &genome, const std::vector< double > &inputs)
 Evaluates genome's phenotype forward pass on inputs (one value per Input node, ordered by ascending node ID; the Bias node, if present, is always implicitly 1.0 and is not part of inputs).
 
double CompatibilityDistance (const NEATGenome &a, const NEATGenome &b, double c1, double c2, double c3)
 Compatibility distance: delta = c1*E/N + c2*D/N + c3*W_bar, where E is the count of excess genes (innovation numbers beyond the other genome's own highest), D is the count of disjoint genes (innovation numbers within the overlapping range but present in only one genome), N is the larger genome's gene count (or 1 if both genomes have fewer than 20 connection genes – the original paper's own small-genome exception), and W_bar is the average weight difference over genes with matching innovation numbers (present in both genomes, regardless of enabled/disabled status).
 
SpeciesAssignment SpeciatePopulation (const std::vector< NEATGenome > &population, double compatibility_threshold, double c1, double c2, double c3)
 Groups population into species: each genome joins the first existing species whose representative (that species' own first member) it is compatible with (distance < compatibility_threshold); otherwise it founds a new species with itself as representative.
 
std::vector< double > ComputeAdjustedFitness (const std::vector< double > &raw_fitness, const std::vector< std::vector< size_t > > &species)
 Fitness sharing: each individual's adjusted fitness is its own raw fitness divided by the size of its species – protects small, structurally novel species from being immediately out-competed by a large, already-optimized one.
 
double XORFitness (const NEATGenome &genome)
 Evaluates genome's phenotype on all four XOR patterns ((0,0)->0, (0,1)->1, (1,0)->1, (1,1)->0, in that order) and scores it as 4.0 minus the sum of squared errors – a perfect fit scores 4.0; a genome producing exactly 0.5 for every pattern (e.g. a fresh, all-zero-weight genome, before any weight differentiation has emerged) scores exactly 3.0 (4.0 - 4*0.25).
 
bool Dominates (const Objectives &a, const Objectives &b)
 Pareto dominance (maximization convention): a dominates b iff a[i] >= b[i] for every objective i, and a[i] > b[i] for at least one objective.
 
std::vector< std::vector< size_t > > FastNonDominatedSort (const std::vector< Objectives > &objectives)
 Fast non-dominated sort (Deb et al. 2002, Algorithm: fast-non-dominated-sort): partitions [0, objectives.size()) into fronts – front 0 is the non-dominated set, front 1 is non-dominated after removing front 0, and so on.
 
std::vector< double > CrowdingDistance (const std::vector< Objectives > &front_objectives)
 Crowding distance within a single front.
 
template<typename Genotype >
std::vector< Individual< Genotype, Objectives > > NSGA2Replacement (const std::vector< Individual< Genotype, Objectives > > &population, std::vector< Individual< Genotype, Objectives > > offspring, size_t mu)
 NSGA-II survivor selection: combines population and offspring, fast-non-dominated- sorts the pool, includes whole fronts (best first) until the next front would overflow mu, then fills the remainder from that final front by crowding distance (largest first – more diverse/isolated solutions preferred).
 
void ReinitializeParameters (Module &model, uint64_t seed, const std::string &prefix="")
 Replaces each parameter tensor with Gaussian noise of mean 0 and that tensor's own standard deviation, from a portable generator seeded by seed.
 
template<typename Analysis >
auto NullModelBaseline (Module &model, Analysis &&analysis, uint64_t seed) -> NullModelComparison< std::decay_t< std::invoke_result_t< Analysis & > > >
 Runs analysis() on model, then again after ReinitializeParameters(model, seed), then restores the model exactly (also if analysis throws).
 
AttributionNullReport NullModelBaseline (Module &model, const ExplainFn &explain, const Tensor &input, uint64_t seed)
 Explains input with the trained and the null model and compares the two.
 
void check_optimizer_setting (float value, const std::string &what)
 Throws std::invalid_argument unless value is finite and non-negative.
 
template<typename Optimizer >
DecompositionLoss TrainDecomposition (ParameterDecomposition &d, const Tensor &x, Optimizer &optimizer)
 One training step: zero the gradients, loss_and_backward(), one optimizer step.
 
ComponentAlignment AlignComponentsToRows (ComponentLinear &layer)
 
std::vector< ImportanceStats > MeasureImportance (ParameterDecomposition &d, const Tensor &x)
 
PBTTruncationGroups ComputeTruncationGroups (const std::vector< double > &metrics, double truncation_fraction)
 Pure core: identifies the bottom and top truncation_fraction of the population by metric (higher is better). Ties are broken by a stable sort on descending metric, so the earlier index among equal values sorts toward "top." At least one individual is always selected on each end, even if floor(size*fraction) would be 0.
 
Configuration ExploreConfigurationGivenFactors (const Configuration &config, const SearchSpace &space, const std::map< std::string, double > &factors)
 Pure core: applies an explicit per-parameter multiplicative factor to every Continuous/LogUniform/Integer parameter in config, clamped to that parameter's own bounds – PBT's own "explore" step (Jaderberg et al.'s own simple perturbation: multiply by 0.8 or 1.2). Categorical parameters are left unchanged (explore, in its original form, perturbs numeric hyperparameters only – a deliberate, logged scope decision, not an oversight). Integer results are rounded to the nearest integer.
 
template<typename RNG >
Configuration ExploreConfiguration (const Configuration &config, const SearchSpace &space, RNG &rng)
 RNG-driven wrapper: draws each non-categorical parameter's factor uniformly from {0.8, 1.2} (Jaderberg et al.'s own standard explore perturbation), then applies ExploreConfigurationGivenFactors.
 
template<typename RNG >
std::vector< double > RunPBTGeneration (std::vector< std::unique_ptr< PBTResumableTrial > > &trials, const SearchSpace &space, int num_epochs, double truncation_fraction, RNG &rng)
 Runs one PBT generation: trains every live trial for num_epochs, then exploits+explores the bottom truncation_fraction of the population from a uniformly-randomly-chosen member of the top truncation_fraction. Individuals outside both groups are left running untouched. Returns each trial's metric as of this generation (post exploit/explore for any trial that was replaced) – the value to feed into the next generation's own truncation.
 
template<typename RNG >
PBTResult RunPBT (std::vector< std::unique_ptr< PBTResumableTrial > > &trials, const SearchSpace &space, int num_generations, int epochs_per_generation, double truncation_fraction, RNG &rng)
 Runs num_generations of RunPBTGeneration in sequence.
 
Pca FitPca (const Tensor &x, int64_t components, bool center=true)
 Fits the components directions of most variance.
 
Tensor PcaProject (const Pca &pca, const Tensor &x, bool whiten=false)
 Each row's coordinates on the components: (x - mean) components^T, shape (n, components), on x's backend.
 
Tensor PcaReconstruct (const Pca &pca, const Tensor &scores)
 The rows that coordinates map back to: mean + scores components, shape (n, width). Projecting and reconstructing keeps only what the components hold.
 
std::vector< float > PcaComponent (const Pca &pca, int64_t index)
 Component index as a unit vector of floats, for SteeringHook(). One standard deviation along it is sqrt(explained_variance[index]), a natural unit for the coefficient.
 
double SubspaceOverlap (const Pca &a, const Pca &b, int64_t k)
 How much two PCAs' first k components span the same space: the mean squared cosine of the principal angles between them, |A_k B_k^T|_F^2 / k. 1 when the spans are the same (whatever the order or rotation inside them), 0 when they are orthogonal, and about k / width for unrelated random subspaces.
 
double PcaSplitHalfOverlap (const Tensor &x, int64_t k, uint64_t seed=0)
 Fits k components on each half of the rows, split at random, and returns their SubspaceOverlap(). Near 1 means the k-dimensional picture is a property of the data; well below 1 means it depends on which inputs happened to be drawn.
 
ClassificationReport EvaluateClassifier (const Tensor &probabilities, const std::vector< int64_t > &labels, const ClassificationOptions &options={})
 Scores a classifier's probabilities against the labels.
 
RegressionReport EvaluateRegressor (const std::vector< double > &predictions, const std::vector< double > &targets)
 Scores a regressor's predictions against the targets.
 
SliceErrorReport PerSliceError (const std::vector< double > &errors, const std::vector< std::string > &slices, const SliceErrorOptions &options={})
 The error on each slice of a dataset, each tested against the rest.
 
SliceErrorReport PerSliceError (const Tensor &probabilities, const std::vector< int64_t > &labels, const std::vector< std::string > &slices, const SliceErrorOptions &options={})
 A classifier's error rate on each slice: an input is wrong when its most probable class isn't its label.
 
JsonValue ToJson (const ClassificationReport &report)
 The report as a pulsatrix.classification_report.v1 document.
 
JsonValue ToJson (const RegressionReport &report)
 The report as a pulsatrix.regression_report.v1 document.
 
JsonValue ToJson (const SliceErrorReport &report)
 The report as a pulsatrix.slice_error.v1 document.
 
std::string DescribeSliceError (const SliceErrorReport &report)
 The slices as a plain-text table, worst first, with the test and whether any is worse.
 
void PolyakUpdate (Module &source, Module &destination, float tau)
 Soft target-network update (Lillicrap et al. 2016 / Haarnoja et al. 2018): destination_param[i] = tau * source_param[i] + (1 - tau) * destination_param[i], element-wise and in place.
 
ProbeResult TrainLinearProbe (const std::vector< float > &features, int64_t dim, const std::vector< int > &labels, int classes, const std::vector< bool > &train, const std::vector< bool > &test, DeviceBackend *backend, const ProbeOptions &options={})
 Trains a linear softmax probe (standardized features, AdamW, cross-entropy) on the rows marked in train and scores it on those marked in test.
 
std::vector< int > ControlTaskLabels (const std::vector< int64_t > &token_types, const std::vector< int > &labels, int classes, uint64_t seed)
 Hewitt and Liang's control labels: each distinct value in token_types gets one label, drawn from the distribution of labels, and every row of that type carries it.
 
ProbeSelectivity MeasureSelectivity (const std::vector< float > &features, int64_t dim, const std::vector< int > &labels, int classes, const std::vector< int64_t > &token_types, const std::vector< bool > &train, const std::vector< bool > &test, DeviceBackend *backend, const ProbeOptions &options={})
 Trains one probe on labels and one on ControlTaskLabels(token_types, labels, classes, options.seed), with the same features, split and options, and reports both.
 
ProbeGain CompareToBaseline (const std::vector< float > &features, int64_t dim, const std::vector< float > &baseline, int64_t baseline_dim, const std::vector< int > &labels, int classes, const std::vector< bool > &train, const std::vector< bool > &test, DeviceBackend *backend, const ProbeOptions &options={})
 Trains the same probe on features and on baseline, rows matched, and reports how much better the representation does. A gain near zero means the probe reads nothing from the representation that the baseline (local sequence, a random model's layer, the raw input) doesn't already hold.
 
std::vector< AnnotatedProtein > ParseAnnotatedProteins (std::string_view jsonl)
 Reads JSON lines, one protein per line: {"accession", "sequence", "features": [{"type", "start", "end"}]} (tools/plm/fetch_swissprot_annotations.py writes them). Blank lines are skipped.
 
std::vector< AnnotatedProtein > ReadAnnotatedProteins (const std::string &path)
 ParseAnnotatedProteins on a file.
 
std::vector< int > ConceptLabels (const AnnotatedProtein &protein, const std::string &type)
 1 for each residue a feature of type covers, 0 elsewhere. A disulfide bond marks only its two cysteines (UniProt gives them as start and end), not the stretch between.
 
std::vector< int > SecondaryStructureLabels (const AnnotatedProtein &protein)
 Three-state secondary structure per residue: 0 helix (Helix), 1 strand (Beta strand), 2 anything else (turns and coil).
 
std::vector< std::pair< std::string, int64_t > > ConceptCounts (const std::vector< AnnotatedProtein > &proteins)
 Each feature type, with the residues it covers over proteins, most first.
 
ResidueEmbeddings EmbedResidues (EncoderLM &model, const TextTokenizer &tokenizer, DeviceBackend *backend, const std::vector< std::string > &sequences, const std::vector< int64_t > &layers, int64_t max_tokens=1024)
 Runs sequences through the model one at a time and keeps each residue's representation (not <cls> or <eos>) at layers: 0 is the embeddings, i the output of layer i, and num_layers() the final representation, after the final LayerNorm, as ESM embeddings are usually taken.
 
std::vector< float > SequenceWindowFeatures (const std::vector< std::string > &sequences, int64_t window)
 The control a residue probe has to beat: each residue's local sequence, one-hot over the 20 amino acids at every position within window of it (20 * (2 window + 1) values, zeros past the ends and for other letters). A linear probe that reads a concept from a layer no better than from this hasn't shown the model adds anything beyond nearby sequence.
 
SparseCodes EncodeSparse (Featurizer &featurizer, const std::vector< float > &rows, DeviceBackend *backend, int64_t batch=4096)
 featurizer's codes for every residue in rows (residues x input_dim), encoded in batches of batch and kept where above zero.
 
SparseCodes NeuronCodes (const std::vector< float > &rows, int64_t dim)
 Dense values as codes, each dimension d twice: as feature 2d (its positive part) and 2d + 1 (its negative part, flipped), so single neurons can be matched to concepts the same way as features.
 
ConceptMatch MatchConcept (const SparseCodes &codes, const std::vector< int > &labels, const std::string &concept_name, const std::vector< double > &thresholds={0.0, 0.15, 0.5, 0.6, 0.8})
 InterPLM's matching: a feature predicts the concept on a residue when its value exceeds a threshold, a share of its largest value (thresholds), and is scored by F1 over the residues. Returns the best feature and threshold.
 
EsmContactHead LoadEsmContactHead (const std::string &directory, const EncoderLMConfig &config)
 Reads the contact head from an ESM-2 checkpoint directory: esm.contact_head.regression.* (EsmForMaskedLM) or contact_head.regression.* (EsmModel).
 
ContactMap ContactFeatures (const float *attention, int64_t tokens)
 One head's contact features from its attention map over <cls>, L residues and <eos> (tokens x tokens, row-major, tokens = L + 2): the residue block, made symmetric (A + Aᵀ), then corrected by the average product (APC): F - rowsum * colsum / total.
 
double ContactPrecision (const ContactMap &predicted, const ContactMap &truth, SeparationRange range, int64_t top)
 The fraction of the top highest-scoring pairs in range that are true contacts.
 
ContactPrecisions PrecisionAtL (const ContactMap &predicted, const ContactMap &truth, SeparationRange range)
 
ContactEvaluation EvaluateContacts (const ContactMap &predicted, const ContactMap &truth)
 
std::vector< HeadPrecision > RankContactHeads (ContactPredictor &predictor, const std::vector< LabeledProtein > &proteins, SeparationRange range=kLongRange)
 Every head, best first, by its features' mean precision at L in range over proteins. The top K make an unsupervised predictor with ContactPredictor::average_heads (arXiv 2606.21876 chooses them with 10 labeled proteins). Choose heads on proteins you won't evaluate on.
 
ResidueAgreement CompareResidueSignals (const std::vector< float > &relevance, const std::vector< float > &signal, double top_fraction=0.1)
 Compares |relevance| with signal over the residues where both are finite; top_fraction picks k (at least 1).
 
std::vector< float > DmsPositionSensitivity (const DmsVariants &variants, std::string_view sequence, int64_t offset=1)
 Each residue's sensitivity in a deep mutational scan: minus the mean score of its single mutants (higher scores being fitter, as in ProteinGym), so residues that tolerate no change rank highest. NaN where no single mutant was measured. Multiple mutants are skipped.
 
std::vector< float > AlignmentConservation (const std::vector< FastaRecord > &alignment)
 Conservation of each query residue in a multiple sequence alignment whose first record is the query: log2(20) - entropy of the column's amino acids, in bits, times the share of sequences without a gap there. NaN for query residues outside the alignment's focus columns (lowercase).
 
std::string AlignmentQuery (const std::vector< FastaRecord > &alignment)
 The query's residues in alignment's first record: its letters, uppercased.
 
std::vector< float > RelevanceProfile (EncoderExplainer &explainer, std::string_view sequence, const std::function< void(int64_t done, int64_t total)> &progress={})
 How much the model draws on each residue when it predicts the others: the mean, over every residue's masked wild-type logit (EncoderTarget::MaskedToken), of each residue's share of the explanation's total |relevance|. A per-protein explanation to compare with per-residue signals such as DMS sensitivity or conservation.
 
ResidueDeletionCurve DeletionCheck (EncoderExplainer &explainer, std::string_view sequence, const EncoderTarget &target, const std::vector< float > &relevance, int64_t steps=20, int64_t random_orders=5, uint64_t seed=0)
 Masks residues (<mask>) in order of how much they support the explained value (relevance of the value's own sign, largest first) and records the value, beside random_orders random orders. A faithful explanation moves the value toward zero faster than random. The explained residue itself is never masked twice: a masked target's residue stays masked throughout, and isn't counted.
 
RandomizationCheckResult RandomizationCheck (EncoderExplainer &explainer, std::string_view sequence, const EncoderTarget &target, uint64_t seed=0)
 Cascading model randomization (Adebayo et al. 2018) over the encoder's own layers, top down: the LM head, then each layer from the last to the first, then the embeddings. Each step redraws the group's weight matrices (Gaussian, each with its own standard deviation) and re-explains. Norm gains and biases are kept: redrawn from their own small spread, a pre-LN block's gains shrink toward zero and the block becomes its residual connection, which would hide the randomization. The model's parameters are restored before returning.
 
TextTokenizer MakeEsmTokenizer (const std::vector< std::string > &vocab)
 ESM's tokenizer (Hugging Face's EsmTokenizer) over a vocabulary listed one token per line, by id: <cls> <pad> <eos> <unk> L A G V ... <mask> for ESM-2.
 
TextTokenizer LoadEsmTokenizer (const std::string &vocab_path)
 MakeEsmTokenizer on a vocab.txt.
 
std::vector< FastaRecord > ParseFasta (std::string_view text)
 Parses FASTA text: records start with >, sequences may span lines, and blank lines and ; comment lines are skipped. Line endings may be \n or \r\n.
 
std::vector< FastaRecord > ReadFasta (const std::string &path)
 ParseFasta on a file.
 
std::string WriteFasta (const std::vector< FastaRecord > &records, size_t width=60)
 FASTA text for records, sequences wrapped at width residues (0: one line).
 
ProteinStructure ParsePdb (std::string_view text)
 Reads PDB-format text: the ATOM records, and the HETATM records of selenomethionine, of the first model.
 
ProteinStructure ParseMmcif (std::string_view text)
 Reads mmCIF text: the _atom_site loop, with the same choices as ParsePdb. Chains and residue numbers are the author's (auth_asym_id, auth_seq_id), as in PDB files, so both formats of one entry give the same structure.
 
ProteinStructure ReadStructure (const std::string &path)
 Reads a structure file: mmCIF for .cif or .mmcif, PDB format otherwise (.pdb, .ent).
 
ContactMap ResidueDistances (const StructureChain &chain, ContactAtom atom=ContactAtom::Beta)
 Distances between the residues of chain, in Ångström, L x L for its L residues. A residue missing the atoms atom needs gives NaN in its row and column.
 
ContactMap TrueContacts (const StructureChain &chain, double threshold=8.0, ContactAtom atom=ContactAtom::Beta)
 True contacts: 1 where two residues are closer than threshold (8 Å by convention), 0 where they aren't, and NaN where a distance is unknown.
 
void InitializeEsm (EncoderLM &model, uint64_t seed, float std=0.02f)
 Initializes a model for training from scratch as transformers' EsmPreTrainedModel does: linear weights and the embedding table from N(0, std²) (the <pad> row zeroed), biases 0, LayerNorm gains 1 and offsets 0. Deterministic for a seed.
 
float MaskedLMForwardBackward (EncoderLM &model, const MaskedLMBatch &batch, TokenCrossEntropyLoss &loss, float normalizer=0.0f)
 One masked-LM forward and backward: sets the batch's padding mask, runs the model, and accumulates the gradient of the cross-entropy over the picked tokens, divided by normalizer (0: the batch's own num_targets, i.e. the mean). Gradients add to what's there; zero them between optimizer steps.
 
MaskedLMEvaluation EvaluateMaskedLM (EncoderLM &model, const TextTokenizer &tokenizer, DeviceBackend *backend, const std::vector< std::string > &sequences, int64_t batch_size=8, uint64_t seed=0, MaskedLMOptions options={})
 Masks sequences with a collator seeded by seed (so every model sees the same masks) and measures the loss over the picked tokens, in batches of batch_size. The model keeps no activations while it runs.
 
Tensor ResidueMask (const Tensor &ids, const Tensor *keep, const TextTokenizer &tokenizer, DeviceBackend *backend)
 The residue mask for SequenceHead::Pooling::Mean from token ids and a padding mask (or none): 1 for every real token that isn't <cls> or <eos>.
 
std::vector< ProteinGymAssay > ReadProteinGymReference (const std::string &path)
 Every assay in a reference file.
 
DmsVariants ReadDmsVariants (const std::string &path)
 Reads an assay's CSV.
 
AssayResult EvaluateAssay (VariantScorer &scorer, const ProteinGymAssay &assay, const DmsVariants &variants, VariantStrategy strategy=VariantStrategy::MaskedMarginals)
 Scores every variant of assay and evaluates them against the measurements.
 
PrototypeResult FindPrototypes (const std::function< Tensor(const Tensor &)> &predict, const Tensor &input, const std::vector< Tensor > &background, const PrototypeOptions &options={})
 The background examples nearest input that the model classes the same way, and those it classes differently. Classes are the index of the model's largest output.
 
ProtoDashResult ProtoDash (const std::vector< Tensor > &source, const std::vector< Tensor > &target, const ProtoDashOptions &options={})
 ProtoDash: chooses up to options.count points of source, with weights, whose weighted kernel mean best matches the kernel mean of target (an MMD criterion).
 
JsonValue ToJson (const PrototypeResult &result)
 The result as a pulsatrix.prototypes.v1 document.
 
AttributionGraph BuildRelevanceGraph (CausalLM &model, DeviceBackend *backend, const std::vector< int64_t > &ids, int64_t target, const RelevanceGraphOptions &options)
 Explains the model's logit for target at the last position with LRP and returns the relevance flow as an attribution graph.
 
double Anisotropy (const Tensor &x, bool center=false)
 The mean cosine similarity over all pairs of different rows: about 0 for directions spread evenly, near 1 when every row points the same way.
 
EffectiveRank MeasureEffectiveRank (const Tensor &x, bool center=true)
 How many directions the rows spread along, from the singular values of x.
 
TwoNNResult TwoNNDimension (const Tensor &x, double discard_fraction=0.1)
 TwoNN intrinsic dimension (Facco, d'Errico, Rodriguez and Laio, Scientific Reports 2017): from each point's distances to its two nearest neighbors, mu = r2 / r1, whose distribution depends only on the dimension the points vary in locally.
 
double LinearCka (const Tensor &x, const Tensor &y, CkaEstimator estimator=CkaEstimator::Debiased)
 Linear CKA between two representations of the same inputs.
 
CkaMatrix LinearCkaMatrix (const std::vector< Tensor > &a, const std::vector< Tensor > &b, CkaEstimator estimator=CkaEstimator::Debiased, std::size_t max_gram_bytes=std::size_t{2}<< 30)
 LinearCka() between every representation in a and every one in b.
 
Rdm RepresentationalDissimilarity (const Tensor &x, RdmMetric metric=RdmMetric::Correlation)
 The RDM of a representation, shape (n, ...): a row per input, later dimensions flattened.
 
double CompareRdms (const Rdm &a, const Rdm &b, RdmComparison comparison=RdmComparison::Spearman)
 The correlation between two RDMs of the same inputs, in the same order.
 
double Rsa (const Tensor &x, const Tensor &y, RdmMetric metric=RdmMetric::Correlation, RdmComparison comparison=RdmComparison::Spearman)
 RSA between two representations of the same inputs: CompareRdms(RepresentationalDissimilarity(x), RepresentationalDissimilarity(y)).
 
RsaTestResult RsaPermutationTest (const Rdm &a, const Rdm &b, RdmComparison comparison=RdmComparison::Spearman, int64_t permutations=999, uint64_t seed=0)
 Whether two RDMs agree more than chance: the Mantel test RSA uses.
 
std::vector< double > CanonicalCorrelations (const Tensor &x, const Tensor &y)
 The canonical correlations between two representations of the same inputs, largest first: min(rank x, rank y) values between 0 and 1.
 
SvccaResult Svcca (const Tensor &x, const Tensor &y, const SvccaOptions &options={})
 SVCCA: CanonicalCorrelations() between each representation's top singular directions.
 
TreeRules ExtractRules (const SurrogateTree &tree, const std::vector< std::string > &feature_names={}, const std::vector< std::string > &class_names={})
 The rules of a classification tree, one per leaf, in the tree's node order.
 
std::vector< int64_t > ClassifyWithRules (const TreeRules &rules, const std::vector< std::vector< float > > &inputs)
 Runs the rules on each input with the Datalog engine and returns the class whose predict fact it derives, or -1 if none.
 
SoftTreeRules ExtractRules (const SoftDecisionTree &tree, const std::vector< std::string > &class_names={})
 The rules of a soft decision tree.
 
std::vector< double > ClassProbabilitiesFromRules (const SoftTreeRules &rules, const SoftDecisionTree &tree, int64_t row)
 Each class's probability for row row of tree's last forward(), from the rules evaluated over the real semiring.
 
std::string FormatRule (const datalog::Rule &rule)
 A rule in Datalog's usual text: head(A, b) :- body1(A), body2(A, c).
 
JsonValue ToJson (const TreeRules &rules)
 The rules as a pulsatrix.tree_rules.v1 document: each rule's text, conditions, class, support and confidence.
 
std::vector< uint8_t > SerializeSafetensors (const std::vector< std::pair< std::string, const Tensor * > > &tensors, const std::map< std::string, std::string > &metadata={})
 Serializes tensors (as F32) and string metadata into safetensors bytes.
 
void WriteSafetensors (const std::string &path, const std::vector< std::pair< std::string, const Tensor * > > &tensors, const std::map< std::string, std::string > &metadata={})
 SerializeSafetensors() written to path.
 
template<typename Genotype , typename FitnessT , typename RNG >
size_t TournamentSelect (const std::vector< Individual< Genotype, FitnessT > > &population, size_t tournament_size, RNG &rng)
 Tournament selection: draw tournament_size individuals without replacement from population and return the index of the fittest among them.
 
template<typename Genotype , typename FitnessT >
size_t RouletteSelectByDraw (const std::vector< Individual< Genotype, FitnessT > > &population, FitnessT draw)
 Fitness-proportionate ("roulette wheel") selection given an explicit draw in [0, total_fitness). Pure and deterministic – the hand-testable core RouletteSelect wraps with an RNG-generated draw.
 
template<typename Genotype , typename FitnessT , typename RNG >
size_t RouletteSelect (const std::vector< Individual< Genotype, FitnessT > > &population, RNG &rng)
 RNG-driven wrapper around RouletteSelectByDraw: draws uniformly from [0, total_fitness) and selects accordingly.
 
template<typename Genotype , typename FitnessT >
size_t RankSelectByDraw (const std::vector< Individual< Genotype, FitnessT > > &population, double draw)
 Linear-rank selection given an explicit draw in [0, total_weight). Individuals are ranked ascending by fitness (worst = rank 1, best = rank population.size()); each rank's selection weight equals its rank, so the best individual is population.size() times as likely to be drawn as the worst. Pure and deterministic – the hand-testable core RankSelect wraps with an RNG-generated draw.
 
template<typename Genotype , typename FitnessT , typename RNG >
size_t RankSelect (const std::vector< Individual< Genotype, FitnessT > > &population, RNG &rng)
 RNG-driven wrapper around RankSelectByDraw: draws uniformly from [0, total_weight) and selects accordingly.
 
SensitivityBounds DeltaBounds (const Tensor &input, float delta)
 x - delta and x + delta for every feature.
 
SensitivityBounds ScaledDeltaBounds (const Tensor &input, const std::vector< Tensor > &background, float num_std=1.0f)
 x -/+ num_std standard deviations of each feature over background, so every feature moves by a comparable amount whatever its units. A feature constant over the background doesn't move.
 
SensitivityBounds RangeBounds (const std::vector< Tensor > &background, float lower_percentile=0.05f, float upper_percentile=0.95f)
 Each feature's lower and upper percentile over background (linear interpolation, as numpy.percentile): the classic tornado-diagram range, a typical low and high value.
 
LocalSensitivityResult ComputeLocalSensitivity (const std::function< Tensor(const Tensor &)> &predict, const Tensor &input, int64_t target_index, const SensitivityBounds &bounds, const std::vector< int64_t > &features={})
 Sets each feature in turn to its low and then its high bound, leaving the others at the input's values, and records the target output each time.
 
Attribution Occlusion (const std::function< Tensor(const Tensor &)> &predict, const Tensor &input, int64_t target_index, const std::vector< int64_t > &window, const std::vector< int64_t > &strides, float baseline=0.0f)
 Occlusion (Zeiler and Fergus 2014) with Captum 0.9's semantics: a window slides over the input with the given strides, everything under it is set to baseline, and each element's attribution is the drop in the target output, f(x) - f(occluded), averaged over the windows that covered it.
 
Tensor SinusoidalTimestepEmbedding (int64_t t, int64_t embedding_dim, DeviceBackend *backend, float base=10000.0f)
 Standard Transformer-style sinusoidal encoding of a diffusion timestep t: emb[2i] = sin(t / base^(2i/embedding_dim)), emb[2i+1] = cos(t / base^(2i/embedding_dim)) for i in [0, embedding_dim/2).
 
std::vector< float > DifferenceOfMeans (const std::vector< float > &positive, const std::vector< float > &negative, int64_t d)
 The difference of means: the mean of positive minus the mean of negative, both (N, d) row-major. The simple baseline that usually wins.
 
std::vector< float > FeaturizerDirection (Featurizer &featurizer, int64_t feature)
 Feature feature's decoder direction, as a steering direction (unit length for a featurizer with unit-norm decoders).
 
HiddenStateHook SteeringHook (int64_t position, std::vector< float > direction, float coefficient, std::vector< bool > rows={})
 A hook that adds coefficient * direction to the hidden states at position (0 is the embeddings, i layer i's output), for the rows in rows (every row when empty). Install it with CausalLM::set_hidden_state_hook() or EncoderLM::set_hidden_state_hook().
 
SteeringReport MeasureSteering (const std::function< double(int64_t i, const HiddenStateHook &hook)> &behavior, int64_t num_inputs, int64_t position, const std::vector< float > &direction, const SteeringOptions &options={})
 Measures steering along direction, and along random directions of the same norm.
 
SuccessiveHalvingResult RunSuccessiveHalvingOnConfigs (std::vector< Configuration > configs, const TrialFactory &make_trial, int initial_epoch_budget, double eta)
 Runs Successive Halving over an explicit, caller-supplied list of configurations – the pure, deterministic core; RunSuccessiveHalving (below) is the thin SearchSpace/RNG-sampling wrapper around it.
 
template<typename RNG >
SuccessiveHalvingResult RunSuccessiveHalving (const SearchSpace &space, const TrialFactory &make_trial, size_t num_configs, int initial_epoch_budget, double eta, RNG &rng)
 RNG-driven wrapper: draws num_configs configurations from space via RandomSample, then runs RunSuccessiveHalvingOnConfigs.
 
SurrogateTree FitDecisionTree (const std::vector< std::vector< float > > &x, const std::vector< double > &y, SurrogateTask task, int64_t num_classes, const SurrogateTreeOptions &options)
 Fits CART to rows x and targets y: class indices for classification, values for regression. FitSurrogateTree() calls this on the model's predictions; it is public so the tree can be checked on its own.
 
std::vector< double > FeatureImportance (const SurrogateTree &tree)
 Each feature's share of the tree's impurity decrease (scikit-learn's feature_importances_).
 
SurrogateTreeResult FitSurrogateTree (const std::function< Tensor(const Tensor &)> &predict, const std::vector< Tensor > &instances, const SurrogateTreeOptions &options={})
 Labels instances with the model, holds out options.test_fraction of them, fits a tree to the rest and measures its fidelity on both parts.
 
std::string DescribeSurrogateTree (const SurrogateTree &tree, const std::vector< std::string > &feature_names={})
 The tree as nested if/else rules, one node per line: if income <= 41.5: ... class 1 (40 inputs, 95%).
 
JsonValue ToJson (const SurrogateTreeResult &result, const std::vector< std::string > &feature_names={})
 The result as a pulsatrix.surrogate_tree.v1 document.
 
std::string_view to_string (SurrogateTask task)
 
template<typename Genotype , typename FitnessT >
std::vector< Individual< Genotype, FitnessT > > GenerationalReplacement (const std::vector< Individual< Genotype, FitnessT > > &, std::vector< Individual< Genotype, FitnessT > > offspring, size_t mu)
 Generational replacement (DEAP's eaSimple): the offspring pool becomes the entire next generation; population is ignored (parents never survive).
 
template<typename Genotype , typename FitnessT >
std::vector< Individual< Genotype, FitnessT > > MuPlusLambdaReplacement (const std::vector< Individual< Genotype, FitnessT > > &population, std::vector< Individual< Genotype, FitnessT > > offspring, size_t mu)
 (mu+lambda) replacement: the next generation is the fittest mu individuals from population union offspring (parents may survive) – more exploitative than (mu,lambda), since a fit parent is never discarded just for being old.
 
template<typename Genotype , typename FitnessT >
std::vector< Individual< Genotype, FitnessT > > MuCommaLambdaReplacement (const std::vector< Individual< Genotype, FitnessT > > &, std::vector< Individual< Genotype, FitnessT > > offspring, size_t mu)
 (mu,lambda) replacement: the next generation is the fittest mu individuals from offspring only (population/parents are always discarded) – more explorative than (mu+lambda), since it cannot get stuck re-selecting the same elite parent forever.
 
std::string format_iso8601_utc (std::chrono::system_clock::time_point tp)
 Formats tp as ISO-8601 UTC with milliseconds, e.g. "2026-10-02T12:34:56.789Z".
 
std::string sample_to_json (const SystemSample &sample)
 Encodes sample as one JSON object (no trailing newline), the JSON Lines log record.
 
void InitTagger (TinyTagger &tagger, uint64_t seed)
 Fills the tagger's parameters reproducibly on every platform: matrices uniform in +-1/sqrt(fan_in), normalization gains 1, biases 0.
 
TaggingBatch MakeTaggingBatch (TaggingRule rule, int64_t batch_size, uint64_t seed, DeviceBackend *backend=nullptr)
 A deterministic, platform-independent batch; lengths are 5 to kSeqLen.
 
std::vector< float > TrainTagger (TinyTagger &tagger, TaggingRule rule, const FineTuneConfig &config, DeviceBackend *backend)
 Trains every parameter of tagger on rule with the whole v1.1 training stack: AdamW with parameter groups, warmup plus cosine, gradient accumulation normalized by the window's token count, and gradient clipping.
 
float TaggingAccuracy (TinyTagger &tagger, TaggingRule rule, int64_t num_sequences)
 Fraction of real tokens tagged correctly on num_sequences fresh sequences.
 
Cav TrainCav (const Tensor &concept_activations, const Tensor &random_activations, const CavOptions &options={})
 Trains a CAV from a layer's activations on concept examples and on random examples.
 
std::vector< double > ConceptualSensitivities (const Tensor &gradients, const Cav &cav)
 Each input's directional derivative along the CAV: the row of gradients dotted with cav.direction.
 
double TcavScore (const std::vector< double > &sensitivities)
 The fraction of sensitivities above zero.
 
TTestResult StudentTTest (const std::vector< double > &a, const std::vector< double > &b)
 Student's two-sample t-test with pooled variance, two-sided, as scipy.stats.ttest_ind computes by default and the TCAV library uses.
 
Tensor LayerActivations (ExplainerContext &ctx, const Tensor &inputs, NodeId layer)
 The layer's activations for inputs, from one forward pass: shape (n, width).
 
Tensor LayerGradients (ExplainerContext &ctx, const Tensor &inputs, NodeId layer, int64_t target, DeviceBackend *backend)
 The gradient of logit target with respect to the layer, for each of inputs: shape (n, width).
 
TcavResult RunTcav (ExplainerContext &ctx, NodeId layer, int64_t target, const Tensor &class_inputs, const Tensor &concept_inputs, const std::vector< Tensor > &random_inputs, DeviceBackend *backend, const TcavOptions &options={})
 TCAV with Kim et al.'s significance test, for one concept, layer and class.
 
Certified< double > BottleneckDistance (const PersistenceDiagram &a, const PersistenceDiagram &b)
 The bottleneck distance between two diagrams of the same dimension.
 
double WassersteinDistance (const PersistenceDiagram &a, const PersistenceDiagram &b, double order=2)
 The q-Wasserstein distance between two diagrams of the same dimension, with the L-infinity norm between points.
 
DistanceMatrix PairwiseDistances (const Tensor &points, const DistanceOptions &options={})
 Euclidean distances between every pair of rows.
 
DistanceMatrix PairwiseDistances (const PointCloud &cloud, DeviceBackend *backend, const DistanceOptions &options={})
 Euclidean distances between every pair of a cloud's points, on the given backend.
 
H0Result ComputeH0 (const DistanceMatrix &distances)
 H0 persistence of the Vietoris-Rips filtration on the given distances.
 
std::vector< int64_t > SingleLinkageClusters (const std::vector< MstEdge > &edges, int64_t points, double threshold)
 The clusters of single linkage cut at a scale: points joined by tree edges no longer than threshold share a label.
 
Landmarks FarthestPointLandmarks (const Tensor &points, const LandmarkOptions &options)
 Picks farthest-point landmarks among the rows of points.
 
Landmarks FarthestPointLandmarks (const PointCloud &cloud, DeviceBackend *backend, const LandmarkOptions &options)
 Landmarks of a cloud's points, computed on the given backend.
 
Tensor LandmarkPoints (const Tensor &points, const Landmarks &landmarks)
 The landmark rows of points, as a (k, ...) tensor on points' backend.
 
PersistenceDiagram WithSubsamplingBound (PersistenceDiagram diagram, const Landmarks &landmarks)
 A diagram of the landmarks re-certified against the whole cloud: its error_bound becomes its own plus the subsampling term, a bound on its bottleneck distance from the diagram of all the points (with exact distances).
 
PointCloud MakePointCloud (const std::vector< ActivationSnapshot > &snapshots, NodeId node, PointCloudOptions options={})
 A cloud from one node of several forward passes, such as one snapshot per batch.
 
RipsResult ComputeRipsPersistence (const DistanceMatrix &distances, const RipsOptions &options={})
 Persistent homology of the Vietoris-Rips filtration on the given distances, in dimensions 0 to options.max_dimension.
 
PersistenceDiagram CrossBarcode (const DistanceMatrix &w, const DistanceMatrix &w_tilde, int dimension=1)
 The R-Cross-Barcode in one dimension: the Rips diagram of the 2n-vertex graph with distances, for points A_1..A_n and copies A'_1..A'_n (the paper's practical form, its Equation 1 with the extra vertex O folded in):
 
RtdResult Rtd (const Tensor &a, const Tensor &b, const RtdOptions &options={})
 Representation Topology Divergence between two representations of the same inputs (the paper's Algorithm 2): in each batch, Euclidean distances within a and within b, each divided by its 0.9 quantile so that scale doesn't count, then the total H1 length of both cross-barcodes.
 
RepresentationComparison CompareRepresentations (const Tensor &a, const Tensor &b, const RepresentationComparisonOptions &options={})
 CKA, mutual-kNN alignment and RTD of the same two representations, for a report: they disagree informatively, as when CKA is high but RTD isn't 0 because one layer splits a cluster the other keeps whole.
 
UniversalNullResult UniversalNullTest (const PersistenceDiagram &diagram, double alpha=0.05)
 Bobrowski and Skraba's universal null test for every feature of a Vietoris-Rips diagram in dimension 1 or above: ell = log log(death / birth) - L-bar - (Euler-Mascheroni's constant), compared with the left-skewed Gumbel, whose survival function is exp(-e^ell).
 
BootstrapBandResult BootstrapBand (const DistanceMatrix &distances, int dimension, const BootstrapOptions &options={})
 A bootstrap confidence band for a Rips diagram (after Fasy, Lecci, Rinaldo, Wasserman, Balakrishnan and Singh, Ann. Statist. 2014): resample the points with replacement, compute each resample's diagram, and take the (1 - alpha) quantile of their bottleneck distances to the original.
 
Tensor GaussianBaseline (const Tensor &points, int64_t count, uint32_t seed=0)
 count points from a Gaussian with the mean and sample covariance of the rows of points: mu + Z^T (X - mu) / sqrt(n - 1) with Z standard normal (one GEMM on points' backend), so no decomposition of the covariance is needed and its rank is kept.
 
double BaselinePValue (double observed, const std::vector< double > &baselines)
 The rank p-value of an observed statistic against the same statistic on baselines: (1 + #{baseline >= observed}) / (1 + baselines.size()). Small means the observed value is larger than chance gives; the smallest possible is 1 / (1 + baselines.size()).
 
double MaxPersistence (const PersistenceDiagram &diagram)
 The largest finite persistence in a diagram, 0 if it has none: a common statistic for BaselinePValue().
 
DistanceMatrix SubDistanceMatrix (const DistanceMatrix &distances, const std::vector< int64_t > &indices)
 A sub-matrix of a distance matrix: the distances among the given points (repeats allowed), in the given order.
 
std::vector< double > LinearGrid (double start, double stop, int64_t n)
 n evenly spaced values from start to stop, both included (n >= 2), or {start} for n == 1.
 
std::vector< int64_t > BettiCurve (const PersistenceDiagram &diagram, const std::vector< double > &grid)
 The Betti curve: how many features are alive, birth <= t < death, at each scale t.
 
Certified< PersistenceLandscape > ComputePersistenceLandscape (const PersistenceDiagram &diagram, const std::vector< double > &grid, int64_t layers=5)
 The first layers persistence landscape functions (Bubenik, JMLR 2015) on a grid: lambda_k(t) is the k-th largest of max(0, min(t - b, d - t)) over the finite points.
 
PersistenceImage ComputePersistenceImage (const PersistenceDiagram &diagram, const PersistenceImageOptions &options={})
 The persistence image (Adams et al., JMLR 2017): each finite point (b, d) placed at (b, d - b), weighted by its persistence divided by persistence_max (so features near the diagonal count for little), and spread by a Gaussian; each pixel holds the integral over it, so a pixel's value doesn't depend on the resolution's sampling.
 
double PersistentEntropy (const PersistenceDiagram &diagram)
 Persistent entropy (Chintakunta et al. 2015; Rucco et al. 2016): the Shannon entropy, in nats, of the finite points' persistences divided by their sum. 0 for one point; log n for n points of equal persistence; 0 for an empty diagram.
 
void require_device (const Tensor &t, DeviceType expected, const char *where)
 Throws unless t lives on expected – the check every module and loss runs on the tensors handed to it (roadmap FND-8, gpu_review #1).
 
CollateFn PadCollate (float pad_index=0.0f)
 Builds a CollateFn that right-pads variable-length token sequences (sample.fields[0], shape (1, seq_len) – TextDataset::get()'s output) to the batch's own max length, producing one (N, max_len) Tensor, plus a (N,) length field recording each sample's real (pre-padding) length. This is the CollateFn extension point Phase 1's architecture design reserved for ragged/variable-length modalities (PyTorch's collate_fn equivalent) – exercised here for the first time, with zero changes needed to Dataset/DataLoader/Batch themselves.
 
int64_t CountTargetTokens (const Tensor &targets, int64_t ignore_index=TokenCrossEntropyLoss::kIgnoreIndex)
 Number of entries of targets that aren't ignore_index: the normalizer for one accumulation window when summed over its micro-batches' targets.
 
TextTokenizer MakeWordLevelTokenizer (const Vocabulary &vocab)
 The word-level tokenizer over a Vocabulary: AsciiLowercase, WordPunctuationSplit and a WordLevelModel whose unknown token is <unk> (id 0). On ASCII text its tokens are Tokenizer::Tokenize's and its ids are Vocabulary::IndexOf's.
 
TextTokenizer MakeByteTokenizer (const std::vector< std::string > &special_tokens={})
 Bytes as ids 0..255, then special_tokens as ids 256, 257, ...; decodes by concatenation.
 
TextTokenizer MakeCharTokenizer (std::vector< std::string > chars, const std::vector< std::string > &special_tokens={})
 Characters by id from chars, then <unk> (unless chars has it), then special_tokens; decodes by concatenation.
 
TextTokenizer ParseTokenizerJson (std::string_view json)
 Builds the tokenizer a tokenizer.json describes.
 
TextTokenizer LoadTokenizerJson (const std::string &path)
 ParseTokenizerJson on a file.
 
TokenizerParityReport CompareToTokenizerReference (const TextTokenizer &tokenizer, const std::string &path, size_t max_examples=5)
 Encodes and decodes every line of a reference file (JSON lines with text, ids, plain_ids, offsets in characters, decoded, decoded_skip, and normalized: whether the normalizer changed the line) and counts the lines that differ. A line round-trips exactly when the normalizer leaves it alone and decoding its plain ids gives it back; offsets are compared exactly on those lines.
 
Offset ByteToCharOffset (std::string_view text, Offset bytes)
 A byte offset range of text as a character (code point) range, widened to whole characters, which is how Hugging Face reports offsets.
 
TopKResult top_k (const Tensor &input, int64_t k, bool largest=true)
 Selects the k largest (or smallest) entries of every row along the last dimension.
 
double GaussianKdeDensity (const std::vector< double > &observations, double bandwidth, double x)
 Fixed-bandwidth Gaussian KDE: density(x) = mean over every observation o of N(x; o, bandwidth^2).
 
double CategoricalDensity (const std::vector< std::string > &observations, size_t num_categories, const std::string &category)
 Laplace(add-one)-smoothed empirical probability of category among observations.
 
double LogDensityRatio (const SearchSpace &space, const Configuration &candidate, const std::vector< Configuration > &good_configs, const std::vector< Configuration > &bad_configs)
 log(l(candidate)) - log(g(candidate)): the TPE scoring function, summed independently over every parameter in space (so a candidate's mixed continuous/categorical parameters each contribute their own term, composing naturally rather than needing a joint density over the whole space).
 
template<typename ObjectiveFn , typename RNG >
std::vector< Trial > RunTPELoop (const SearchSpace &space, ObjectiveFn objective_fn, size_t num_initial_random, size_t num_iterations, double gamma, size_t num_candidates, RNG &rng)
 Runs TPE: num_initial_random uniformly-random trials (RandomSample), then num_iterations trials each chosen by splitting all trials so far into good/bad by the gamma quantile (maximization convention: good = highest objective values) and picking, among num_candidates uniformly-random candidates, the one maximizing LogDensityRatio.
 
LRPRuleConfig TrajectoryNetworkRules ()
 The network rules ConcatDenoiser uses unless told otherwise: the epsilon rule with the bias in the denominator (Zennit's), so the biases absorb their share. The codebase's default pre-bias rule divides by x W alone, which a hidden layer's bias can leave near zero while the unit is active; chained over the steps of a sampler its relevance blew up (DIFF-5's planted DDPM: conditioning shares up to 570 times the explained value).
 
ContinuousTrajectory SampleContinuousDiffusion (ContinuousDenoiser &model, const NoiseSchedule &schedule, const std::vector< float > &x_T, const ContinuousSamplerConfig &config)
 Runs the reverse process from x_T and records it.
 
std::vector< float > StandardNormal (size_t n, uint64_t seed)
 Draws n standard normal values from seed, as SampleContinuousDiffusion does.
 
std::vector< float > RegionSeed (const std::vector< float > &sample, const std::vector< int64_t > &region)
 The sum of sample over region: relevance x0_i on the region's elements, 0 elsewhere.
 
std::vector< float > ReconstructionSeed (const std::vector< float > &sample, const std::vector< float > &reference)
 The reconstruction error ||x_0 - reference||^2, as LRP for autoencoders seeds it (Kobayashi et al. 2023): relevance (x0_i - ref_i)^2 on each element.
 
TrajectoryRelevance ExplainTrajectory (ContinuousDenoiser &model, const ContinuousTrajectory &trajectory, const std::vector< float > &seed, const TrajectoryLrpConfig &config={})
 Explains seed, relevance on the trajectory's sample x_0 (RegionSeed, ReconstructionSeed, or a downstream classifier's input relevance), back through trajectory, which SampleContinuousDiffusion produced with model.
 
std::vector< Tensor > McDropoutSamples (Module &model, const std::function< Tensor(const Tensor &)> &predict, const Tensor &input, int64_t samples)
 Monte Carlo dropout: runs predict on input samples times with every dropout layer under model in training mode and everything else in eval mode, so BatchNorm uses its running statistics and only the dropout masks change between passes.
 
std::vector< Tensor > EnsembleSamples (const std::vector< std::function< Tensor(const Tensor &)> > &members, const Tensor &input)
 A deep ensemble's samples: each member's output for input.
 
UncertaintyDecomposition DecomposeUncertainty (const std::vector< Tensor > &samples)
 Splits the uncertainty of a set of probability samples into its aleatoric and epistemic parts, input by input.
 
GaussianMixturePrediction CombineGaussians (const std::vector< std::vector< double > > &means, const std::vector< std::vector< double > > &variances={})
 Mixes M Gaussian predictions per input into one, as Lakshminarayanan et al. do: the mixture's mean is the mean of the means, and its variance the mean of (variance + mean^2) minus the mixture mean squared.
 
JsonValue ToJson (const UncertaintyDecomposition &decomposition)
 The decomposition as a pulsatrix.uncertainty.v1 document, without the mean probabilities.
 
std::vector< Mutation > ParseMutations (std::string_view text)
 Parses a variant, A23G, or several joined by :, A23G:L45P (ProteinGym's format).
 
std::string ApplyMutations (std::string_view sequence, const std::vector< Mutation > &mutations, int64_t offset=1)
 sequence with mutations applied; position p is sequence[p - offset].
 
int64_t ScoringPassBytes (const EncoderLMConfig &config, int64_t length)
 Roughly the most memory one sequence of length tokens takes in a forward pass of config's model that keeps no activations (EncoderLM::set_keep_activations(false)): one layer's attention scores and their softmax copies, its projections and MLP, and the logits. The weights aren't counted.
 
std::pair< int64_t, int64_t > OptimalWindow (int64_t position, int64_t length, int64_t window)
 ProteinGym's get_optimal_window: the token range [begin, end) around position in a sequence of length tokens, for a model that sees window tokens.
 
TorchvisionLoadReport LoadTorchvisionWeights (Module &model, const std::string &safetensors_path)
 Loads a torchvision state dict converted to safetensors (tools/convert/pickle_to_safetensors.py) into model by name: every parameter and buffer of the model is looked up under the same name. Linear weights (every rank-2 parameter), stored (out, in) by PyTorch, are transposed; num_batches_tracked counters are ignored.
 
std::string ToNeuronpediaJson (const AttributionGraph &graph)
 The graph as Neuronpedia/circuit-tracer JSON, including circuit-tracer's optional node fields (token_prob, is_target_logit) and an empty qParams.
 
AttributionGraph ParseNeuronpediaGraph (std::string_view json)
 Reads a graph written by ToNeuronpediaJson, circuit-tracer or Neuronpedia. Unknown fields are ignored.
 
void ComputeInfluence (AttributionGraph &graph, const std::vector< double > &scores)
 Sets each node's influence the way circuit-tracer's pruning does: nodes other than embeddings and logits, by |score| largest first, get the cumulative fraction of the total |score| up to and including them. The viewer keeps nodes whose influence is at most its threshold, so a threshold of 0.8 keeps the fewest nodes holding 80% of the score.
 
void PruneLinks (AttributionGraph &graph, double edge_threshold)
 Keeps the fewest links, largest |weight| first, whose |weight| sums to at least edge_threshold of the total; ties keep their order. Links into a logit node are always kept.
 
AttributionGraph FromCircuitGraph (const CircuitGraphDocument &doc, const std::string &slug, const std::string &scan)
 A circuit graph (a chain of operations scored by ablation) for the viewer: two columns, "input" holding an embedding node and "network" holding each operation one layer up, with the last operation as the output. Influence comes from the ablation effects.
 
float NormalizeUnsigned (float value, float max_abs)
 Normalizes value into [0, 1] against a known maximum magnitude, for unsigned (magnitude-only) quantities such as saliency intensity or ablation effect.
 
float NormalizeSigned (float value, float max_abs)
 Normalizes value into [-1, 1] against a known maximum absolute magnitude, for signed quantities such as attribution direction (positive/negative contribution).
 
RgbColor ViridisColormap (float normalized_value)
 Viridis colormap – perceptually uniform, colorblind-safe – for sequential/unsigned magnitude (hc_information_visualization.md SS4: "Recommended Color Systems").
 
RgbColor DivergingColormap (float signed_normalized_value)
 Blue-White-Red diverging colormap for signed attribution (positive/negative contribution) – hue encodes direction only, never magnitude (hc_information_visualization.md SS1's Cleveland-McGill rule: color hue is categorical/directional, magnitude must be position or length).
 
std::string VizDocumentKind (std::string_view json)
 Reads only a document's "schema" member and returns its kind (for example "attribution"), so a viewer can pick the matching reader.
 
AttributionDocument ToAttributionDocument (const Attribution &attr)
 Copies attr into a document, reading its values to the host.
 
Attribution ToAttribution (const AttributionDocument &doc, DeviceBackend *backend)
 Rebuilds an Attribution whose values live on backend.
 
std::string ToJson (const AttributionDocument &doc)
 
AttributionDocument ParseAttributionDocument (std::string_view json)
 
HeatmapDocument ToHeatmapDocument (const HeatmapGrid &grid, std::string title="")
 
HeatmapGrid ToHeatmapGrid (const HeatmapDocument &doc)
 
std::string ToJson (const HeatmapDocument &doc)
 
HeatmapDocument ParseHeatmapDocument (std::string_view json)
 
std::string ToJson (const TokenRelevanceDocument &doc)
 
TokenRelevanceDocument ParseTokenRelevanceDocument (std::string_view json)
 
CircuitGraphDocument ToCircuitGraphDocument (const CircuitGraph &graph)
 
CircuitGraph ToCircuitGraph (const CircuitGraphDocument &doc)
 
std::string ToJson (const CircuitGraphDocument &doc)
 
CircuitGraphDocument ParseCircuitGraphDocument (std::string_view json)
 
const char * OpTypeName (OpType op_type)
 The name ToCircuitGraphDocument writes for op_type, for example "Linear".
 
OpType OpTypeFromName (std::string_view name)
 
TrainingLogDocument ToTrainingLogDocument (const ImPlotMetricsSink &sink)
 Copies everything sink has logged, sorted by tag.
 
void ReplayTrainingLog (const TrainingLogDocument &doc, MetricsSink &sink)
 Logs every scalar in doc to sink in the order recorded, then every histogram (at step 0, since the log keeps only the latest one), so any sink can show a saved run: an ImPlotMetricsSink for the training dashboard, for example.
 
std::string ToJson (const TrainingLogDocument &doc)
 
TrainingLogDocument ParseTrainingLogDocument (std::string_view json)
 
std::string ToJson (const FeatureDashboardDocument &doc)
 
FeatureDashboardDocument ParseFeatureDashboardDocument (std::string_view json)
 
PartialDependenceDocument ToPartialDependenceDocument (const IceResult &result, std::string feature="", std::string target="")
 Copies result, its partial dependence curve included.
 
PartialDependenceDocument ToPartialDependenceDocument (const AleResult &result, std::string feature="", std::string target="")
 An ALE curve as a document with method "ale": the bin edges as the grid, the effects as the curve, and the instances' feature values for the rug.
 
IceResult ToIceResult (const PartialDependenceDocument &doc)
 Rebuilds the ICE curves for their centered and derivative views.
 
HeatmapDocument ToHeatmapDocument (const PartialDependence2D &pd, std::string title="")
 A two-feature partial dependence as a heatmap: rows follow grid_y, columns grid_x, and the labels are the grid values.
 
std::string ToJson (const PartialDependenceDocument &doc)
 
PartialDependenceDocument ParsePartialDependenceDocument (std::string_view json)
 
SensitivityDocument ToSensitivityDocument (const LocalSensitivityResult &result, const std::vector< std::string > &names={}, std::string target="")
 Copies result. names, if not empty, has one name per input feature (flat index); features without a name are called feature_<index>.
 
std::string ToJson (const SensitivityDocument &doc)
 
SensitivityDocument ParseSensitivityDocument (std::string_view json)
 
CounterfactualDocument ToCounterfactualDocument (const Tensor &input, const CounterfactualResult &result, const std::vector< std::string > &names={}, const std::vector< float > &scale={}, std::string target="")
 Pairs input with result's counterfactual. names and scale, if not empty, have one entry per feature; scale should be the one the search used.
 
std::string ToJson (const CounterfactualDocument &doc)
 
CounterfactualDocument ParseCounterfactualDocument (std::string_view json)
 
MorrisDocument ToMorrisDocument (const MorrisResult &result, const std::vector< std::string > &names={}, std::string target="")
 names, if not empty, has one name per entry of result.features (the varied features, in order); otherwise features are called feature_<index>.
 
SobolDocument ToSobolDocument (const SobolResult &result, const std::vector< std::string > &names={}, std::string target="")
 names, if not empty, has one name per entry of result.features (the varied features, in order); otherwise features are called feature_<index>.
 
std::string ToJson (const MorrisDocument &doc)
 
MorrisDocument ParseMorrisDocument (std::string_view json)
 
std::string ToJson (const SobolDocument &doc)
 
SobolDocument ParseSobolDocument (std::string_view json)
 
ProjectionDocument MakeProjectionDocument (const Pca &pca, const Tensor &scores, std::vector< std::string > labels={}, std::vector< std::string > groups={}, std::vector< float > values={}, std::string title="")
 A projection document from PcaProject()'s scores: axes PC1, PC2, ... with the PCA's explained variance ratios.
 
ProjectionDocument MakeProjectionDocument (const Tensor &coordinates, std::string method, std::vector< std::string > labels={}, std::vector< std::string > groups={}, std::vector< float > values={}, std::string title="")
 A projection document from coordinates made elsewhere, such as UMAP or t-SNE output read with ReadNpy() (embedding_export.hpp): axes <method> 1, <method> 2, ..., and no variance shares.
 
bool IsNeighborEmbedding (const ProjectionDocument &doc)
 Whether the document's method is UMAP or t-SNE (umap, tsne, t-sne or opentsne, any case), whose plots keep neighbors but not distances, cluster sizes or densities. The views say so on such plots.
 
std::string ToJson (const ProjectionDocument &doc)
 
ProjectionDocument ParseProjectionDocument (std::string_view json)
 
std::vector< VizFontFile > FindFallbackFonts ()
 The system fonts that together cover as many scripts as this machine has fonts for, best first.
 
VizFontOptions DefaultVizFontOptions ()
 The font options a VizWindow uses when given none. With the environment variable PULSATRIX_VIZ_FONTS set to font paths (separated by ';', or ':' outside Windows), those fonts come first. Set to "none", only ImGui's default font is used.
 
std::vector< VizFontFile > LoadVizFonts (const VizFontOptions &options)
 Loads ImGui's default font and merges options' fonts into it, in the current ImGui context. Since ImGui 1.92 glyphs are drawn on first use, so a merged font costs only its file in memory.
 
bool VizFontsUseFreeType ()
 Whether this build's ImGui uses FreeType (color emoji) rather than stb_truetype.
 
JsonValue ToVegaLiteBarChart (const AttributionDocument &doc, int top_k=10, const HtmlOptions &options={})
 Horizontal bars of the top_k features with the largest |attribution|, colored by sign on the SVG renderer's diverging scale.
 
JsonValue ToVegaLiteWaterfall (const AttributionDocument &doc, float baseline_value, const HtmlOptions &options={})
 A waterfall from baseline_value through the features' contributions to the prediction (ToWaterfallSteps).
 
JsonValue ToVegaLiteHeatmap (const HeatmapDocument &doc, const HtmlOptions &options={})
 A heatmap: diverging around zero when any value is negative, Viridis otherwise. Non-finite cells are gray.
 
JsonValue ToVegaLiteBeeswarm (const std::vector< AttributionDocument > &docs, const std::vector< int64_t > &feature_indices, const HtmlOptions &options={})
 One row per feature in feature_indices: every document's value for it, spread so points don't overlap (ToBeeswarmPoints).
 
JsonValue ToVegaLitePartialDependence (const PartialDependenceDocument &doc, const PartialDependenceSvgOptions &pd={}, const HtmlOptions &options={})
 A partial dependence plot: ICE curves under the average, and a rug of the instances' feature values. Zoom with the mouse wheel; drag to pan.
 
JsonValue ToVegaLiteTornado (const SensitivityDocument &doc, int top_k=10, const HtmlOptions &options={})
 A tornado chart of the top_k features with the largest swing.
 
JsonValue ToVegaLiteCounterfactual (const CounterfactualDocument &doc, int max_rows=12, const HtmlOptions &options={})
 The changed features of a counterfactual, costliest first, as bars of their change in scale units; the tooltip has the old and new values.
 
JsonValue ToVegaLiteCounterfactualSet (const std::vector< CounterfactualDocument > &docs, const HtmlOptions &options={})
 Several counterfactuals of one input: a grid of features (rows) by counterfactuals (columns), each cell colored by the change in scale units and labeled with the new value.
 
JsonValue ToVegaLiteMorris (const MorrisDocument &doc, const HtmlOptions &options={})
 Morris screening: mu* against sigma per feature, with mu*'s confidence interval and the sigma = mu* line.
 
JsonValue ToVegaLiteSobol (const SobolDocument &doc, int top_k=10, const HtmlOptions &options={})
 Sobol indices: first-order bars in front of total-order ones, with confidence whiskers.
 
JsonValue ToVegaLiteProjection (const ProjectionDocument &doc, const HtmlOptions &options={})
 A projection as a zoomable scatter plot, colored as RenderProjectionSvg colors it, with each point's label on hover. With three or more axes, three panels: PC1 against PC2, PC1 against PC3 and PC2 against PC3, the views of a 3D projection.
 
JsonValue ToVegaLiteTrainingLog (const TrainingLogDocument &doc, const HtmlOptions &options={})
 A training log: one zoomable line chart per scalar tag, and one histogram per histogram tag.
 
JsonValue ToVegaLiteFeatureHistogram (const FeatureDashboardDocument &doc, const HtmlOptions &options={})
 A feature's activation histogram (the dashboard's chart; RenderFeatureDashboardHtml adds the top examples).
 
JsonValue ToVegaLiteSeries (const SeriesDocument &doc, const SeriesViewOptions &view={}, const HtmlOptions &options={})
 A series document (VIZ-9): one zoomable chart per panel, stacked, each a line per series with points and interval rules, colored as RenderSeriesSvg colors them.
 
std::string VegaLitePage (const JsonValue &spec, const std::string &heading, const HtmlOptions &options={}, const std::string &extra_html="")
 A complete page that draws spec with vega-embed, which adds the PNG/SVG export menu.
 
std::string RenderBarChartHtml (const AttributionDocument &doc, int top_k=10, const HtmlOptions &options={})
 
std::string RenderWaterfallHtml (const AttributionDocument &doc, float baseline_value, const HtmlOptions &options={})
 
std::string RenderHeatmapHtml (const HeatmapDocument &doc, const HtmlOptions &options={})
 
std::string RenderBeeswarmHtml (const std::vector< AttributionDocument > &docs, const std::vector< int64_t > &feature_indices, const HtmlOptions &options={})
 
std::string RenderPartialDependenceHtml (const PartialDependenceDocument &doc, const PartialDependenceSvgOptions &pd={}, const HtmlOptions &options={})
 
std::string RenderTornadoHtml (const SensitivityDocument &doc, int top_k=10, const HtmlOptions &options={})
 
std::string RenderCounterfactualHtml (const CounterfactualDocument &doc, int max_rows=12, const HtmlOptions &options={})
 
std::string RenderCounterfactualSetHtml (const std::vector< CounterfactualDocument > &docs, const HtmlOptions &options={})
 
std::string RenderMorrisHtml (const MorrisDocument &doc, const HtmlOptions &options={})
 
std::string RenderSobolHtml (const SobolDocument &doc, int top_k=10, const HtmlOptions &options={})
 
std::string RenderProjectionHtml (const ProjectionDocument &doc, const HtmlOptions &options={})
 
std::string RenderSeriesHtml (const SeriesDocument &doc, const SeriesViewOptions &view={}, const HtmlOptions &options={})
 
std::string RenderTrainingLogHtml (const TrainingLogDocument &doc, const HtmlOptions &options={})
 
std::string RenderFeatureDashboardHtml (const FeatureDashboardDocument &doc, const HtmlOptions &options={}, const std::string &extra_html="")
 The feature's statistics, its activation histogram, and its top examples with each token shaded by its activation. extra_html is appended as is, such as a structure panel (StructurePanelHtml, PLM-8).
 
std::string RenderTokenRelevanceHtml (const TokenRelevanceDocument &doc, const HtmlOptions &options={})
 The text with each piece (token or word) on a background colored by its relevance, as plain HTML with no scripts: the browser lays out and shapes the text, so every script reads correctly (right-to-left, joined Arabic, Indic conjuncts), and wraps it. Hovering a piece shows its score; unscored pieces are plain text. Scripts option is ignored.
 
JsonValue ToVegaLiteCircuitGraph (const CircuitGraphDocument &doc)
 A Vega-Lite node-link view of a circuit graph: nodes in columns by depth (longest path from a source), colored by ablation effect, edges as lines weighted by |weight|.
 
std::string Base64Encode (const std::vector< uint8_t > &bytes)
 Standard base64 (RFC 4648, with padding), for image/png data.
 
template<class Json >
void to_json (Json &j, const JsonValue &value)
 Converts a JsonValue to another JSON library's value type by its common interface (assignment from null, bool, number and string; object(), array(), operator[], push_back). nlohmann::json finds it by argument-dependent lookup, so nlohmann::json j = value; works without pulsatrix including nlohmann.
 
template<class Json >
void to_json (Json &j, const MimeBundle &bundle)
 The bundle as a JSON object of MIME type to data (see to_json(Json&, const JsonValue&)).
 
ClassificationReport ParseClassificationReport (std::string_view json)
 Reads a pulsatrix.classification_report.v1 document, as ToJson(ClassificationReport) writes it.
 
SliceErrorReport ParseSliceErrorReport (std::string_view json)
 Reads a pulsatrix.slice_error.v1 document, as ToJson(SliceErrorReport) writes it.
 
std::string RenderReliabilityDiagramSvg (const std::vector< ReliabilitySeries > &series, const SvgOptions &options={})
 A reliability diagram (Guo et al., ICML 2017): each confidence bin's accuracy against its mean confidence, one line per classifier. A calibrated classifier lies on the diagonal; points below it are overconfident, above it underconfident. The marks grow with the bin's share of the inputs, and a strip below shows that share, since a bin of three inputs can sit far from the diagonal by chance. The legend gives each one's ECE.
 
std::string RenderReliabilityDiagramSvg (const ClassificationReport &report, const SvgOptions &options={})
 The diagram of one classifier.
 
std::string RenderSliceErrorSvg (const SliceErrorReport &report, const SliceErrorViewOptions &view={}, const SvgOptions &options={})
 The error on each slice, worst first: a point with its interval, the error of the whole dataset as a dashed line, and each slice's p-value. Slices worse than the rest, after Bonferroni's correction, are red.
 
BarSeries ToFeatureImportanceBars (const Attribution &attr, int top_k)
 Converts an Attribution's per-feature values into labeled, magnitude-sorted bars for a horizontal bar chart – the canonical XAI feature-importance encoding (hc_information_visualization.md SS5: position on a shared axis, Cleveland-McGill rank 1).
 
std::vector< WaterfallStep > ToWaterfallSteps (const Attribution &attr, float baseline_value)
 Converts an Attribution's per-feature values into a cascading waterfall from a real baseline to the final prediction (hc_information_visualization.md SS5/SS6: the one case where a bar chart legitimately does not start at zero, since the baseline itself is the meaningful reference point – Tufte's lie-factor rule is satisfied relative to that baseline, not to zero).
 
std::vector< WaterfallBar > ToWaterfallBars (const std::vector< WaterfallStep > &steps, float baseline_value)
 Converts waterfall steps into floating bars, each spanning from the previous running total to its own running total – i.e. bar i covers [min(c_{i-1}, c_i), max(c_{i-1}, c_i)] with c_{-1} = baseline_value. Correct for any sign of baseline or running total: a cascade that starts below zero, crosses zero, or stays negative (e.g. explaining a negative logit) floats exactly where the running total is, rather than being anchored at zero the way stacked bar segments are.
 
HeatmapGrid ToSaliencyHeatmap (const Attribution &attr)
 Reshapes an Attribution's values into a 2D grid for a saliency overlay heatmap.
 
HeatmapColorScale ComputeHeatmapColorScale (const HeatmapGrid &grid)
 Chooses a heatmap's color scale from its values (hc_information_visualization.md SS4: sequential maps for unsigned magnitude, diverging maps centred on the meaningful midpoint – zero – for signed quantities).
 
std::vector< BeeswarmPoint > ToBeeswarmPoints (const std::vector< Attribution > &runs, int64_t feature_index)
 Converts one feature's attribution value across many repeated/independent runs into jittered (x, y) points for a beeswarm plot – the global-explanation distribution view (hc_information_visualization.md SS5: "SHAP beeswarm plot... each point is one prediction; x-position is the SHAP value"). Deterministic, density-based jitter: points are binned along x, then colliding points within a bin are alternately offset above/below y=0 so they read as spread rather than overlapping – not a random jitter, so two calls with the same input always produce the same layout.
 
std::string CircuitNodeDisplayLabel (const CircuitNode &node)
 Human-readable label for a CircuitGraph node: the node's own label when it has one, otherwise its operation type and id (e.g. "Conv #1", "Activation #2") – so an unlabeled ComputationGraph still renders as a readable layer diagram rather than a row of anonymous "node_<id>" markers.
 
HistogramBins ToFieldHistogramBins (const Dataset &dataset, int64_t field_index, int num_bins)
 Bins one Sample field's values (flattened across every sample's Tensor at that field position, mirroring DatasetValidator's aggregation convention) into num_bins equal-width bins, for a per-field distribution histogram (hc_information_visualization.md's data-preview touchpoint).
 
RgbImageBuffer ToRgbImageBuffer (const Tensor &image_chw)
 Converts a decoded image Tensor into an interleaved-RGB byte buffer for GPU texture upload (the data-preview "image grid" touchpoint's pure half – the actual glTexImage2D call lives in TextureCache, which is GL-dependent and untestable here).
 
MutationMapDocument MakeMutationMapDocument (std::string_view sequence, const std::vector< float > &scan, std::string method="", int64_t first_position=1)
 A mutation map from VariantScorer::single_mutant_scan (L x 20, in kAminoAcids order).
 
std::string ToJson (const MutationMapDocument &doc)
 
MutationMapDocument ParseMutationMapDocument (std::string_view json)
 
SequenceLogoDocument MakeSequenceLogoDocument (const ResidueLogProbs &log_probs, const TextTokenizer &tokenizer, std::string_view sequence, std::string method="", int64_t first_position=1)
 A logo from a model's log-probabilities (VariantScorer::masked_marginals or wild_type_marginals): each residue's probabilities over the 20 amino acids, renormalized to sum to 1 (special and rare tokens dropped).
 
std::vector< float > InformationContent (const SequenceLogoDocument &doc)
 Each position's information content in bits, log2(letters) - entropy: 0 when every letter is equally likely, log2(20) (4.32) when one is certain. A logo stacks the letters to this height, each in proportion to its probability.
 
std::string ToJson (const SequenceLogoDocument &doc)
 
SequenceLogoDocument ParseSequenceLogoDocument (std::string_view json)
 
ContactMapDocument MakeContactMapDocument (std::string_view sequence, const ContactMap &predicted, const ContactMap *truth=nullptr, std::string method="", int64_t first_position=1)
 Pairs a prediction with the structure's contacts (TrueContacts), if any.
 
std::string ToJson (const ContactMapDocument &doc)
 
ContactMapDocument ParseContactMapDocument (std::string_view json)
 
std::vector< float > MeanSubstitutionScore (const MutationMapDocument &doc)
 Each residue's mean score over its substitutions (the wild type left out): how much the model minds a change there. NaN where none was scored.
 
std::vector< std::string > ResidueIds (const StructureChain &chain)
 chain's residue ids, for ResidueTracksDocument::residue_ids.
 
std::string ToJson (const ResidueTracksDocument &doc)
 
ResidueTracksDocument ParseResidueTracksDocument (std::string_view json)
 
std::string RenderMutationMapSvg (const MutationMapDocument &doc, const SvgOptions &options={})
 A mutation map: a row per letter of the alphabet, a column per residue, each cell colored by its score (diverging, scaled to the largest |score|). The wild type's cell has a dot, and the sequence runs along the top. Unscored cells are gray.
 
std::string RenderSequenceLogoSvg (const SequenceLogoDocument &doc, const SvgOptions &options={})
 A sequence logo: at each position, the letters stacked to the position's information content in bits (InformationContent), each as tall as its share, the likeliest on top. Letters are colored by chemistry, as WebLogo does: hydrophobic black, polar green, amide purple, basic blue, acidic red. The sequence's own letters run underneath.
 
std::string RenderContactMapSvg (const ContactMapDocument &doc, const ContactMapViewOptions &view={}, const SvgOptions &options={})
 A contact map: one square, residue against residue. Above the diagonal, the predicted scores (white to dark blue). Below it, the true contacts in gray, and the L best-scored pairs at least min_separation apart as dots: blue where the structure has a contact, red where it doesn't, hollow where it's unknown. A caption gives the precision at L for those pairs and for long-range ones (24 apart and more), as ContactPrecision computes it. Without a structure, the lower triangle shows the dots alone.
 
std::string RenderResidueTracksSvg (const ResidueTracksDocument &doc, const SvgOptions &options={})
 Residue tracks: a ruler and the sequence, then a row of colored cells per track (signed tracks diverging around zero, others Viridis from their minimum or zero), then a row of labeled spans per feature category. Each track has its own scale, shown in a legend.
 
std::string RenderMutationMapHtml (const MutationMapDocument &doc, const HtmlOptions &options={})
 
std::string RenderSequenceLogoHtml (const SequenceLogoDocument &doc, const HtmlOptions &options={})
 
std::string RenderContactMapHtml (const ContactMapDocument &doc, const ContactMapViewOptions &view={}, const HtmlOptions &options={})
 
std::string RenderResidueTracksHtml (const ResidueTracksDocument &doc, const HtmlOptions &options={})
 
std::string RenderStructureHtml (const std::string &structure, const std::string &chain, const ResidueTracksDocument &tracks, const HtmlOptions &options={})
 A 3D structure, drawn as a cartoon with 3Dmol.js, with the residues of chain colored by one of tracks' tracks at a time (a menu switches between them). Hovering a residue shows its name, number and value. Other chains are light gray, ligands are sticks, and water is hidden.
 
std::string StructurePanelHtml (const std::string &structure, const std::string &chain, const ResidueTracksDocument &tracks, const HtmlOptions &options, const std::string &id)
 RenderStructureHtml's viewer as a fragment to place in any page: the track menu, the legend, the 3D view and its scripts. Its elements' ids start with id, so a page can hold several.
 
std::string RenderFeatureDashboardHtml (const FeatureDashboardDocument &doc, const std::string &structure, const std::string &chain, size_t example, const HtmlOptions &options={})
 A feature dashboard (RenderFeatureDashboardHtml) with a structure panel (PLM-8): top example example drawn on structure's chain, colored by the feature's activation. The example's tokens must be single residues matching the chain one for one, as an AlphaFold DB model of the protein does.
 
std::string MarkdownToHtml (const std::string &markdown)
 Markdown (the subset Report::to_html() supports) as HTML; raw HTML is escaped.
 
const char * AxisScaleName (AxisScale scale)
 
std::string ToJson (const SeriesDocument &doc)
 
SeriesDocument ParseSeriesDocument (std::string_view json)
 
std::string RenderSeriesSvg (const SeriesDocument &doc, const SeriesViewOptions &view={}, const SvgOptions &options={})
 The panels stacked top to bottom, each a line per series with a marker per point and a whisker per interval; one legend for all panels. Every marker has a tooltip with its values.
 
std::string RenderBarChartSvg (const AttributionDocument &doc, int top_k=10, const SvgOptions &options={})
 Horizontal bars of the top_k features with the largest |attribution|, largest first, on an axis through zero, each colored by its signed value and labeled with it. Labels come from metadata["feature_names"] (comma-separated) when present.
 
std::string RenderWaterfallSvg (const AttributionDocument &doc, float baseline_value, const SvgOptions &options={})
 A waterfall from baseline_value through each feature's contribution, in the document's feature order, to the final value: red columns raise the running total, blue columns lower it, with the baseline and the final value marked.
 
std::string RenderHeatmapSvg (const HeatmapDocument &doc, const SvgOptions &options={})
 The heatmap's grid with square cells and a color bar. Signed grids use the diverging map on a range symmetric about zero, unsigned grids Viridis on [0, max] (ComputeHeatmapColorScale's rule). Non-finite cells are gray and left out of the scale. Row and column labels are drawn when the document has them.
 
std::string RenderTokenStripSvg (const TokenRelevanceDocument &doc, const SvgOptions &options={})
 The text's pieces (tokens or words) in reading order, wrapped across lines, each on a background colored by its relevance (diverging, scaled to the largest |relevance|). Pieces are drawn in a monospace font, so their widths are exact, with whitespace kept. Unscored pieces (context such as the spaces between words) are plain text and don't count toward the scale; non-finite relevance is drawn gray. The target and the unassigned relevance, when set, are shown after the text.
 
std::string RenderBeeswarmSvg (const std::vector< AttributionDocument > &docs, const std::vector< int64_t > &feature_indices, const SvgOptions &options={})
 One beeswarm row per feature in feature_indices: each point is one document's value for that feature, placed by value on a shared axis through zero, spread vertically so points don't overlap (ToBeeswarmPoints's deterministic layout), and colored by value. Labels come from the first document's metadata["feature_names"] when present.
 
std::string RenderPartialDependenceSvg (const PartialDependenceDocument &doc, const PartialDependenceSvgOptions &pd={}, const SvgOptions &options={})
 A partial dependence plot: thin ICE curves under the bold average, over the feature's grid, with a rug of the instances' own feature values along the bottom. For IceStyle::Centered and IceStyle::Derivative the average is recomputed from the transformed curves, and a dashed line marks zero.
 
std::string RenderTornadoSvg (const SensitivityDocument &doc, int top_k=10, const SvgOptions &options={})
 A tornado chart: one row per feature, the top_k with the largest swing first. Each row has two bars from the unchanged output, one to the output at the feature's high value (red) and one to its low value (blue), labeled with those values; a dashed line marks the unchanged output.
 
std::string RenderCounterfactualSvg (const CounterfactualDocument &doc, int max_rows=12, const SvgOptions &options={})
 What a counterfactual changed: a verdict line (whether it reaches the target, and the output before and after), then one row per changed feature, costliest first, with its old and new value and a bar of its change in units of its scale, colored by direction. A feature counts as changed when it moved by more than 1e-3 of its scale.
 
std::string RenderMorrisSvg (const MorrisDocument &doc, const SvgOptions &options={})
 Morris screening as a scatter of mu* (importance) against sigma (how much the effect varies), one labeled point per feature with a horizontal bar for mu*'s confidence interval. Points above the dashed line sigma = mu* have effects that vary more than their average: nonlinear, or interacting with other features.
 
std::string RenderSobolSvg (const SobolDocument &doc, int top_k=10, const SvgOptions &options={})
 Sobol indices: one row per feature, the top_k with the largest total order first, with a bar for the first-order index, a lighter bar for the total-order index behind it, and whiskers for both confidence intervals. The gap between the two bars is the share of variance the feature explains only through interactions.
 
std::string RenderProjectionSvg (const ProjectionDocument &doc, int x_axis=0, int y_axis=1, const SvgOptions &options={})
 A projection as a scatter plot of two of its axes (INT-5), both on one scale so distances on the page are distances in the projection. Points are colored by group with a legend, else by value on Viridis with a color bar (gray where a value isn't finite), and each has a tooltip with its label and coordinates. Lines mark zero, the mean of a PCA.
 
std::string RenderCounterfactualSetSvg (const std::vector< CounterfactualDocument > &docs, const SvgOptions &options={})
 Several counterfactuals of one input side by side (CFS-7): a column for the input and one per counterfactual (headed by whether it reaches the target), and a row for every feature that at least one of them changes. Changed values are on a background colored by the change's direction and size in scale units; unchanged ones are blank.
 
TokenRelevanceDocument MakeTokenRelevanceDocument (std::string_view text, const Encoding &encoding, const std::vector< float > &token_scores, std::string method, std::string target="", bool include_special_tokens=true)
 A token-level document for text from its Encoding and one score per token.
 
TokenRelevanceDocument MakeWordRelevanceDocument (std::string_view text, const WordScores &words, std::string method, std::string target="")
 A word-level document for text from AggregateToWords(): each word scored, the text between words as unscored pieces, and the words' unassigned relevance carried over.
 
PersistenceDiagramDocument ToPersistenceDiagramDocument (const std::vector< PersistenceDiagram > &diagrams, std::string title="")
 The diagrams as a document: births, deaths and each diagram's error bound.
 
PersistenceDiagramDocument ToPersistenceDiagramDocument (const RipsResult &result, std::string title="")
 The same, from ComputeRipsPersistence(), with its threshold.
 
void AttachSignificance (PersistenceDiagramDocument &doc, int dimension, const UniversalNullResult &test)
 Adds UniversalNullTest()'s p-values and corrected threshold to the entry for dimension. Features the test skipped get NaN.
 
void AttachBootstrapBand (PersistenceDiagramDocument &doc, int dimension, const BootstrapBandResult &band)
 Adds BootstrapBand()'s band to the entry for dimension.
 
bool IsSignificant (const PersistenceDiagramEntry &entry, size_t i)
 Whether feature i of entry passed the attached tests: its p-value is below the threshold, or, with only a bootstrap band, its persistence is above twice the band. True for every feature when no test is attached.
 
std::string ToJson (const PersistenceDiagramDocument &doc)
 Writes the document.
 
PersistenceDiagramDocument ParsePersistenceDiagramDocument (std::string_view json)
 Reads a document ToJson() wrote.
 
std::string RenderPersistenceDiagramSvg (const PersistenceDiagramDocument &doc, const PersistenceViewOptions &view={}, const SvgOptions &options={})
 Birth against death, one point per feature. Points far above the diagonal persist long. A shaded band along the diagonal marks persistence within twice the certified error bound, which the distances' own error could explain. Essential features sit on a dashed line marked ∞. When tests are attached, significant features are filled and the others hollow; a bootstrap band is drawn as a dashed line parallel to the diagonal.
 
std::string RenderBarcodeSvg (const PersistenceDiagramDocument &doc, const PersistenceViewOptions &view={}, const SvgOptions &options={})
 One bar per feature, from its birth to its death, grouped by dimension and longest first. Each end has a whisker of ±the certified error bound; essential bars end in an arrow. Features that failed an attached test are drawn faint.
 
std::string RenderBettiCurveSvg (const PersistenceDiagramDocument &doc, const PersistenceViewOptions &view={}, const SvgOptions &options={})
 The Betti curve of each dimension: how many features are alive at each scale (BettiCurve()).
 
Vocabulary BuildVocabulary (const std::vector< std::vector< std::string > > &tokenized_corpus, int64_t max_vocab_size=-1)
 Builds a Vocabulary from a tokenized corpus, ranked by descending token frequency (ties broken by first-seen order, for determinism).
 
std::vector< float > fit_weighted_linear_regression (const std::vector< std::vector< float > > &samples, const std::vector< float > &targets, const std::vector< float > &weights, float l2_lambda)
 Fits w* = argmin_w sum_i weight_i*(target_i - w^T sample_i)^2 + l2_lambda*||w||^2 via the normal equations (X^T W X + l2_lambda*I) w = X^T W y.
 
std::vector< Offset > SplitWords (std::string_view text, WordSplit split=WordSplit::WordsAndPunctuation)
 The words of valid UTF-8 text, as byte ranges in order. Scripts written without spaces (Chinese, Japanese, Thai) come out as long runs; pass a pattern for those.
 
std::vector< Offset > SplitWords (std::string_view text, const UnicodeRegex &pattern)
 The words of text: every match of pattern.
 
WordScores AggregateToWords (std::string_view text, const std::vector< Offset > &token_offsets, const std::vector< float > &token_scores, const std::vector< Offset > &words, WordAggregation aggregation=WordAggregation::Sum)
 Merges per-token scores into the given words.
 
WordScores AggregateToWords (std::string_view text, const Encoding &encoding, const std::vector< float > &token_scores, WordAggregation aggregation=WordAggregation::Sum, WordSplit split=WordSplit::WordsAndPunctuation)
 AggregateToWords over an Encoding of text, with words from SplitWords(text, split).
 
The KL bounds KL-LUCB uses (Kaufmann and Kalyanakrishnan 2013), as in the reference code.
double BernoulliKl (double p, double q)
 KL divergence between Bernoulli(p) and Bernoulli(q), with p and q clipped to (0, 1).
 
double KlUpperBound (double p, double level)
 The largest q >= p with BernoulliKl(p, q) <= level.
 
double KlLowerBound (double p, double level)
 The smallest q <= p with BernoulliKl(p, q) <= level.
 
Names. Lower-case snake case, as in reports and JSON: "how_global", "justify".
std::string_view to_string (XaiQuestion question)
 
std::string_view to_string (XaiReason reason)
 
std::string_view to_string (ExplanationScope scope)
 
std::string_view to_string (ModelAccess access)
 
std::string_view to_string (InputKind input)
 
Parsing. The inverse of to_string(); std::nullopt for any other text.
std::optional< XaiQuestion > ParseXaiQuestion (std::string_view text)
 
std::optional< XaiReason > ParseXaiReason (std::string_view text)
 
mime_bundle_repr

What a notebook shows for each type. Every bundle has text/plain.

xeus-cpp's xcpp::display(x) calls mime_bundle_repr(x) unqualified, so argument-dependent lookup finds these overloads, and the result converts to xeus's nlohmann::json through to_json() below; pulsatrix itself doesn't depend on xeus or on nlohmann. NB-2's notebook writer and NB-3's Python _repr_mimebundle_ use the same bundles.

  • Tensor: a summary (shape, device, statistics, leading values) as text and an HTML table.
  • Attribution: rank 3 or more, read as (N, H, W) or (N, C, H, W), as a heatmap of the first example with channels summed: PNG when it has more than 64 x 64 cells, SVG plus Vega-Lite otherwise. Rank 1 or 2 as a bar chart of the first example's largest features.
  • Documents with a Vega-Lite view get Vega-Lite and the SVG figure; token relevance and the protein views get their SVG; circuit graphs and training logs get Vega-Lite only.
MimeBundle mime_bundle_repr (const Tensor &tensor)
 
MimeBundle mime_bundle_repr (const Attribution &attribution)
 
MimeBundle mime_bundle_repr (const CircuitGraph &graph)
 
MimeBundle mime_bundle_repr (const AttributionDocument &doc)
 
MimeBundle mime_bundle_repr (const HeatmapDocument &doc)
 
MimeBundle mime_bundle_repr (const TokenRelevanceDocument &doc)
 
MimeBundle mime_bundle_repr (const CircuitGraphDocument &doc)
 
MimeBundle mime_bundle_repr (const TrainingLogDocument &doc)
 
MimeBundle mime_bundle_repr (const PartialDependenceDocument &doc)
 
MimeBundle mime_bundle_repr (const SensitivityDocument &doc)
 
MimeBundle mime_bundle_repr (const CounterfactualDocument &doc)
 
MimeBundle mime_bundle_repr (const MorrisDocument &doc)
 
MimeBundle mime_bundle_repr (const SobolDocument &doc)
 
MimeBundle mime_bundle_repr (const ProjectionDocument &doc)
 
MimeBundle mime_bundle_repr (const MutationMapDocument &doc)
 
MimeBundle mime_bundle_repr (const SequenceLogoDocument &doc)
 
MimeBundle mime_bundle_repr (const ContactMapDocument &doc)
 
MimeBundle mime_bundle_repr (const ResidueTracksDocument &doc)
 
MimeBundle mime_bundle_repr (const PersistenceDiagramDocument &doc)
 
MimeBundle mime_bundle_repr (const SeriesDocument &doc)
 
MimeBundle mime_bundle_repr (const ClassificationReport &report)
 
MimeBundle mime_bundle_repr (const SliceErrorReport &report)
 

Variables

constexpr int kCheckpointFormatVersion = 1
 The checkpoint format this build writes. Files record it as format_version; a file without one (any plain safetensors file) is version 0. Older versions load through a migration table; newer ones are rejected.
 
constexpr size_t kFixedTopologyXORNumParams = 9
 Total flat-parameter count: 2*2 (input->hidden weights) + 2 (hidden biases) + 2 (hidden->output weights) + 1 (output bias) = 9.
 
constexpr SeparationRange kShortRange {6, 12}
 CASP's and ESM's ranges: short 6–11, medium 12–23, long 24 and up.
 
constexpr SeparationRange kMediumRange {12, 24}
 
constexpr SeparationRange kLongRange {24, 0}
 
constexpr const char * kAminoAcids = "ACDEFGHIKLMNPQRSTVWY"
 The 20 standard amino acids, in the order SingleMutantScan's columns use.
 
constexpr int kVizDocumentVersion = 1
 The document format version this build writes and reads.
 
constexpr const char * kVegaVersion = "6.4.0"
 The versions of Vega, Vega-Lite and vega-embed the pages load (BSD-3-Clause).
 
constexpr const char * kVegaLiteVersion = "6.4.3"
 
constexpr const char * kVegaEmbedVersion = "7.3.0"
 
constexpr const char * kVegaLiteMimeType = "application/vnd.vegalite.v5+json"
 The MIME type Jupyter front ends (JupyterLab, Notebook 7, VS Code) render Vega-Lite from. pulsatrix's specs use only Vega-Lite 5 features, so they're sent as version 5.
 
constexpr const char * k3DmolVersion = "2.5.5"
 The 3Dmol.js version the structure page loads.
 

Typedef Documentation

◆ BlockOutputHook

using pulsatrix::BlockOutputHook = typedef std::function<Tensor(int64_t layer, int64_t start, int64_t prompt_length, const Tensor& hidden)>

Called on each block's output in MakeCachedNextTokenLogits(): block layer's hidden states (1, L, d) for positions [start, start + L), in a sequence whose prompt is prompt_length long; returns what the next block reads. CausalLM uses it to run its interventions (TRN-9).

◆ CollateFn

using pulsatrix::CollateFn = typedef std::function<Batch(std::vector<Sample>, DeviceBackend*)>

A function assembling a list of Samples into one Batch – pulsatrix's analogue of PyTorch's collate_fn. The standard extension point for ragged/variable-length modalities (text padding, variable-length audio): a caller-supplied CollateFn replacing DefaultCollate, not a subclass hierarchy.

◆ ConceptCondition

using pulsatrix::ConceptCondition = typedef std::vector<ConceptMask>

One conditional heatmap's masks, at most one per layer.

◆ Configuration

using pulsatrix::Configuration = typedef std::map<std::string, ConfigValue>

A concrete hyperparameter configuration: parameter name -> concrete value.

◆ ConfigValue

using pulsatrix::ConfigValue = typedef std::variant<double, int64_t, std::string>

A concrete value for one parameter – a double (Continuous/LogUniform), an int64_t (Integer), or a std::string (Categorical, naming one of that parameter's categories).

◆ DenoiserFn

using pulsatrix::DenoiserFn = typedef std::function<std::vector<float>(const std::vector<int64_t>& tokens)>

The model as the sampler sees it: the current sequence (masked positions included) in, logits for every position out, L * vocab values, row-major. MakeDenoiser builds one for an EncoderLM or a bidirectional CausalLM.

◆ EmbedFn

using pulsatrix::EmbedFn = typedef std::function<std::vector<float>(const Tensor& input)>

Maps an input to the vector distances are measured in.

◆ ExplainFn

using pulsatrix::ExplainFn = typedef std::function<Attribution(const Tensor& input)>

Explains input using the model in its current state.

◆ HiddenStateHook

using pulsatrix::HiddenStateHook = typedef std::function<Tensor(int64_t position, const Tensor& hidden)>

Reads or replaces a language model's residual stream during forward() (FEAT-3): called with a position, 0 for the embeddings entering layer 0 and i for layer i's output, and the hidden states there, (N, L, hidden_size) on the model's device. What it returns, the same shape, is what the model continues with: return the input unchanged to only read it. Splicing a featurizer's reconstruction back in uses it (MeasureLossRecovered, featurizer_metrics.hpp).

Note
backward() and the relevance passes after a forward() that changed the stream run as if the replacement were an input: no gradient flows through the hook.

◆ LRPComposite

using pulsatrix::LRPComposite = typedef std::function<LRPRuleConfig(size_t layer_index, const Module& module)>

Per-layer LRP rule choice: maps (top-level module index in forward order, module) to the LRPRuleConfig that module applies.

Note
LRP calls a composite exactly once per module, in ascending index order starting at 0, on every explain() – presets that depend on position (epsilon_gamma_box's "first Conv2D") rely on that order.
Applied to the ExplainerContext's top-level modules: a SequentialModule receives one config, which it forwards to all of its layers (it supports a rule only if they all do).

◆ MlpHook

using pulsatrix::MlpHook = typedef std::function<Tensor(const Tensor& mlp_input, const Tensor& mlp_output)>

Called with an MLP's input (after the block's norm, where it has one) and its output (the branch added to the residual stream), both shaped like the block's input. What it returns, the same shape, is added to the residual stream instead of the output: return the output unchanged to only read it.

Note
backward() and the relevance passes after a forward() that changed the output run as if the MLP had produced it: no gradient flows through the hook.

◆ NextTokenLogitsFn

using pulsatrix::NextTokenLogitsFn = typedef std::function<std::vector<float>(const std::vector<int64_t>& tokens)>

The model as generation sees it: the token sequence so far in, the logits for the next token out (one per vocabulary entry). How they're computed is up to the caller: a full forward pass over the sequence (MakeNextTokenLogits), or a cached step (LLM-5).

◆ NodeId

using pulsatrix::NodeId = typedef size_t

Stable identifier for a Node within its owning ComputationGraph.

◆ Objectives

using pulsatrix::Objectives = typedef std::vector<double>

◆ ParamSelector

using pulsatrix::ParamSelector = typedef std::function<bool(const std::string& name, const Tensor& value)>

Picks parameters by their named_parameters() name and value.

◆ PredictFn

using pulsatrix::PredictFn = typedef std::function<Tensor(const Tensor& input)>

The model as a function: input (with a leading batch dimension of 1) to outputs.

◆ TextureId

using pulsatrix::TextureId = typedef unsigned int

Opaque GL texture handle, typed to avoid a GL header include in this public header.

◆ TrialFactory

using pulsatrix::TrialFactory = typedef std::function<std::unique_ptr<ResumableTrial>(const Configuration&)>

Builds a fresh ResumableTrial for a given configuration.

Enumeration Type Documentation

◆ AcquisitionKind

enum class pulsatrix::AcquisitionKind
strong

Which acquisition function RunGPBOLoop maximizes over candidates each iteration.

Enumerator
ExpectedImprovement 
ProbabilityOfImprovement 
UpperConfidenceBound 

◆ AttackNorm

enum class pulsatrix::AttackNorm
strong

The norm an attack's budget is measured in.

Enumerator
Linf 
L2 

◆ AxisScale

enum class pulsatrix::AxisScale
strong

How an axis maps values to positions.

Enumerator
Linear 
Log 

◆ BlockSelection

enum class pulsatrix::BlockSelection
strong
Enumerator
TopK 

Π_k: each input keeps its k blocks of largest norm.

Tournament 

Tournament top-k (Jerpelea and Ananthram): blocks are taken by norm, but one that overlaps an already-taken block loses a duel and is skipped; see BlockSparseOptions.

◆ BsfVariant

enum class pulsatrix::BsfVariant
strong
Enumerator
Vanilla 

A free encoder: z = Π_k(x W_enc + b_enc), decoder atoms of unit norm.

Grassmannian 

Tied, orthonormal frames: z_g = γ_g x D_gᵀ with D_g D_gᵀ = I, then Π_k.

GroupLasso 

A free encoder and a learned threshold per block: a block fires when its norm is above θ_g, under an L0 penalty whose weight is set by dual ascent to hit target_l0.

◆ CaveatSeverity

enum class pulsatrix::CaveatSeverity
strong

How much a caveat limits what the explanation supports.

Enumerator
Blocking 

The explanation shouldn't be used for its reason: a required check failed or didn't run, or the planner excluded the method for this model.

Warning 

A recommended check failed, or a known failure mode applies to these settings.

Note 

A limitation of the method worth knowing whenever it is read.

◆ CavMethod

enum class pulsatrix::CavMethod
strong

How TrainCav() finds the concept direction.

Enumerator
LogisticRegression 

The weights of an L2-regularized logistic regression, as Kim et al. train them. The features are standardized while fitting and the direction mapped back.

DifferenceOfMeans 

The difference of the two sets' mean activations. It needs no fitting, and doesn't rotate towards dimensions that only separate the two samples by chance.

◆ CheckOutcome

enum class pulsatrix::CheckOutcome
strong

What a check found.

Enumerator
Passed 

The check ran and the explanation met its criterion.

Failed 

The check ran and the explanation didn't meet it.

Measured 

The check ran and produced numbers with no pass or fail, such as an aggregate.

NotRun 

The check didn't run; CheckResult::summary says why.

◆ CheckPriority

enum class pulsatrix::CheckPriority
strong

How much a check matters for this reason.

Enumerator
Required 

The reason requires it: an explanation without it shouldn't be used for that reason.

Recommended 

Worth running; the reason doesn't depend on it.

◆ CkaEstimator

enum class pulsatrix::CkaEstimator
strong

Which estimator of CKA to use.

Enumerator
Debiased 

Unbiased HSIC in place of HSIC: near 0 for unrelated representations at any number of inputs. Needs at least 4 inputs, and can be slightly negative.

Biased 

Kornblith et al.'s original estimator. Between 0 and 1, but biased upwards when the inputs are few compared with the width.

◆ CommitmentMode

enum class pulsatrix::CommitmentMode
strong

How far relevance travels.

Enumerator
Graph 

Relevance on a committed token is re-seeded at the step that wrote it, until it reaches the prompt or a mask token.

StepLocal 

Each target is explained at its own step only: relevance on committed tokens stops there. What the graph is compared with.

◆ ConformalScore

enum class pulsatrix::ConformalScore
strong

How a conformal classifier scores an example.

Enumerator
Lac 

1 − p(true class): Least Ambiguous set-valued Classifier.

Aps 

The mass of the classes ranked at or above the true one: Adaptive Prediction Sets.

◆ ContactAtom

enum class pulsatrix::ContactAtom
strong

Which atom stands for a residue in residue distances.

Enumerator
Beta 

Cβ, or Cα for glycine (CASP's definition).

Alpha 

Cα.

VirtualBeta 

A Cβ placed from the backbone (N, Cα, C) with ideal geometry, for every residue, glycine included. ESM's contact-prediction example and trRosetta use it.

◆ ContinuousSampler

enum class pulsatrix::ContinuousSampler
strong

Which reverse process to run.

Enumerator
Ddpm 

Ancestral DDPM (Ho et al. 2020): every timestep T..1, noise sqrt(beta_t), none at t = 1.

Ddim 

DDIM (Song et al. 2021) on evenly spaced timesteps; deterministic when eta = 0.

◆ CopyDirection

enum class pulsatrix::CopyDirection
strong

Direction of a DeviceBackend::copy() call.

Enumerator
HostToDevice 
DeviceToHost 
DeviceToDevice 
HostToHost 

◆ CrosscoderSparsity

enum class pulsatrix::CrosscoderSparsity
strong
Enumerator
L1 

Lindsey et al.: λ · Σ_i f_i Σ_s |d_i^s|, an L1 penalty on each code weighted by the sum (not the L2 norm) of its decoder norms across sources, so a latent pays for every source it writes to and a source-exclusive latent stays cheap.

BatchTopK 

Minder et al.: the batch's N · k largest values of f_i · Σ_s |d_i^s| are kept (the unscaled f_i is the code), with AuxK for dead latents. Inference uses a threshold on the scaled value (threshold()).

◆ DecompositionMethod

enum class pulsatrix::DecompositionMethod
strong
Enumerator
SPD 

SPD: masks m = g + (1 - g) r, r uniform; the losses are faithfulness, reconstruction with every layer masked, reconstruction with one layer masked at a time, and importance minimality Σ g^p.

VPD 

VPD: the Δ weight is part of the forward pass under its own mask; reconstruction routes each input through a random k of the L layers' components (k uniform), and again under adversarial masks (persistent PGD); importance minimality adds a frequency term; the causal importance's lower clamp is straight-through.

◆ DeviceType

enum class pulsatrix::DeviceType
strong

Which physical device a Tensor's buffer resides on.

Note
CPUBackend, CUDABackend and HIPBackend implement Cpu, Cuda and Hip respectively. Tensor::to(target, target_backend) moves a buffer between them.
Enumerator
Cpu 
Cuda 
Hip 

◆ DistanceMethod

enum class pulsatrix::DistanceMethod
strong

How PairwiseDistances() computes the distances.

Enumerator
Gemm 

|x|^2 + |y|^2 - 2 x.y, with the dot products from the backend's float32 GEMM and the rest in double on the host. O(n^2 d) on the device.

Exact 

The sum of squared differences, in double on the host. Slower, with an error bound near double precision: a reference, or for clouds whose points nearly coincide.

◆ DistillationDivergence

Which way round the soft term's KL divergence goes.

Enumerator
Forward 

KL(teacher ‖ student): the student covers every mode the teacher puts mass on.

Reverse 

KL(student ‖ teacher): the student concentrates on the teacher's main modes.

◆ ElementwiseOp

enum class pulsatrix::ElementwiseOp
strong

Unary elementwise operations supported by DeviceBackend::elementwise().

Note
Binary elementwise ops (add, mul) are intentionally not part of this Phase 0 interface — Tensor's arithmetic operators are designed in Mission 1 (Shape & Tensor Core), and a binary-op signature added speculatively now would likely need to change once that design exists.
Every op here computes the forward value only – no derivative variant exists in this interface. A module that needs an activation's derivative (ReluModule, RNNModule, LSTMModule, GRUModule) computes it locally from its own cached forward output, which is why adding Tanh/Sigmoid/Silu here removes those modules' raw forward loops but not their backward/LRP derivative math.
Enumerator
Relu 
Neg 
Tanh 

tanh(x)

Sigmoid 

1 / (1 + exp(-x))

Silu 

x * sigmoid(x) – a.k.a. swish; the gate half of SwiGLU

Exp 

exp(x) – GPU-native-kernels Mission 1b (Reparameterize, KL divergence)

GeluTanh 

GELU, tanh approximation (gelu_pytorch_tanh) – the gate of Gemma's GeGLU (LLM-9)

Gelu 

exact GELU, x * Phi(x) with erf – the MLP activation of BERT and ESM (PLM-1)

◆ EncoderLMHead

enum class pulsatrix::EncoderLMHead
strong

An EncoderLM's output head.

Enumerator
Esm 

ESM's: dense, GELU, LayerNorm, then the embedding table transposed plus a bias.

Linear 

One linear layer with a bias, not tied to the embeddings (MDLM).

◆ ExplanationScope

enum class pulsatrix::ExplanationScope
strong

Whether an explainer explains one prediction or the model as a whole.

Enumerator
Local 

One input at a time (a batch is explained row by row).

Global 

The model, a layer or a dataset.

◆ FinishReason

enum class pulsatrix::FinishReason
strong

Why generation stopped.

Enumerator
Eos 

An EOS token was generated.

Length 

max_new_tokens were generated.

◆ GatedActivation

enum class pulsatrix::GatedActivation
strong

The gate activation of a gated MLP: SiLU (SwiGLU: Llama, Qwen), GELU's tanh approximation (GeGLU: Gemma, LLM-9) or exact GELU (GeGLU as first published).

Enumerator
Silu 
GeluTanh 
Gelu 

◆ HtmlScripts

enum class pulsatrix::HtmlScripts
strong

How a page gets the Vega libraries.

Enumerator
Cdn 

From the jsDelivr CDN, pinned to the versions above and checked with Subresource Integrity hashes. The page is small, but viewing it needs a network connection.

Inline 

Copied into the page from script_dir, so it works offline and can be mailed as one file (about 830 KB more). tools/render/fetch_vega.sh downloads the files.

◆ IceStyle

enum class pulsatrix::IceStyle
strong

Which form of the ICE curves RenderPartialDependenceSvg draws (CFS-1).

Enumerator
Raw 

The predictions themselves.

Centered 

Each curve minus its value at the first grid point (c-ICE).

Derivative 

Each curve's slope (d-ICE).

◆ InputKind

enum class pulsatrix::InputKind
strong

What the explainer's input has to be.

Enumerator
Any 

Any tensor.

Tabular 

A flat feature vector, one value per named feature.

Image 

Images: (N, C, H, W).

Tokens 

Token ids into a language model.

Protein 

Amino-acid sequences into a protein language model.

Symbolic 

Facts and rules in the Datalog engine.

Representation 

Representations: an (N, d) matrix of activations or embeddings.

◆ LatentClass

enum class pulsatrix::LatentClass
strong
Enumerator
AOnly 

Δnorm below 0.1.

BOnly 

Δnorm above 0.9.

Shared 

Δnorm in [0.4, 0.6].

Other 

◆ LogicOp

enum class pulsatrix::LogicOp
strong

Elementwise passes of the fuzzy-logic modules, for DeviceBackend::logic_pointwise.

Note
Paired with a norm index: 0 Product, 1 Lukasiewicz, 2 Godel – the declaration order of ConjunctionModule::TNorm and DisjunctionModule::TConorm.
Enumerator
ConjunctionForward 
ConjunctionBackward 
ConjunctionLrp 
DisjunctionForward 
DisjunctionBackward 
DisjunctionLrp 

◆ LoRARelevance

enum class pulsatrix::LoRARelevance
strong

How a LinearModule with an unmerged LoRA adapter (TRN-7, TRN-8) propagates relevance.

Enumerator
Split 

The layer is two parallel paths, the base weight W and the adapter's (alpha / r) A B, and the rule runs on both at once, as one Linear layer on the input repeated twice with the two weights stacked. The input relevance is the sum of the two paths' parts, which the adapter keeps (LoRAAdapter::last_adapter_relevance()). For the epsilon rule the sum equals Merged's result; Gamma and AlphaBeta treat the paths' positive and negative parts separately, so it differs.

Merged 

The rule runs on the adapted weight W + (alpha / r) A B, exactly as on a merged adapter.

◆ LrpGate

enum class pulsatrix::LrpGate
strong

Elementwise boolean gate for DeviceBackend::lrp_stabilized_divide().

Enumerator
None 

every element passes

Positive 

passes where gate > 0

Negative 

passes where gate < 0

◆ LRPRule

enum class pulsatrix::LRPRule
strong

The LRP rule family a module applies. Semantics follow Zennit 1.0.0 exactly (Anders et al. 2021); every rule other than Epsilon is defined only for affine layers (LinearModule, Conv2DModule) – see Module::supports_lrp_rule().

Enumerator
Epsilon 

R_in = x * ((R / stab(z)) @ W^T). The bias is left out of z unless LRPRuleConfig::epsilon_bias_in_denominator is set (Zennit's Epsilon includes it).

Gamma 

Zennit's generalized Gamma rule: weights W + gamma W^+ / W + gamma W^-, split by the sign of the input and of the original output (Montavon et al. 2019, generalized to negative activations).

AlphaBeta 

Alpha-beta rule (Bach et al. 2015) with alpha - beta == 1; alpha 1, beta 0 is ZPlus.

ZBox 

Z^B rule (Montavon et al. 2017) for a box-bounded input [low, high]; meant for the input layer.

◆ LRPSeed

enum class pulsatrix::LRPSeed
strong

How LRP seeds relevance at the target output.

Enumerator
OutputValue 

R[n, t] = y[n, t]: the total relevance is the explained logit itself (the classic Bach et al. 2015 setup, where conservation reads "attributions sum to the output").

OneHot 

R[n, t] = 1: unit relevance at the target, the convention Zennit / LXT attributors use when handed a one-hot output gradient. Use this to compare against those libraries.

◆ MlpType

enum class pulsatrix::MlpType
strong

The MLP's form.

Enumerator
Plain 

Linear -> activation -> Linear (BERT, ESM): FeedForwardModule.

Gated 

down(act(gate(x)) * up(x)) (Llama's SwiGLU, Gemma's GeGLU): SwiGLUModule.

◆ ModelAccess

enum class pulsatrix::ModelAccess
strong

The least an explainer needs from the model, from least to most access.

Enumerator
BlackBox 

Only a prediction function, Tensor(const Tensor&): works on any model.

Weights 

The weights alone, without running the model.

Activations 

Activations at a layer, collected beforehand or through a hook.

Gradients 

Gradients through a pulsatrix network (an ExplainerContext or a Module).

Relevance 

An LRP rule at every layer of a pulsatrix network.

◆ MutationObjective

enum class pulsatrix::MutationObjective
strong

E-GAN's three named mutation objectives.

Enumerator
Minimax 
Heuristic 
LeastSquares 

◆ NeighborMetric

enum class pulsatrix::NeighborMetric
strong

How nearness is measured.

Enumerator
Cosine 

Cosine similarity: the angle between vectors, ignoring their lengths. Higher is nearer. A zero vector has similarity 0 with everything.

Euclidean 

Euclidean distance. Lower is nearer.

◆ NormPosition

enum class pulsatrix::NormPosition
strong

Where the norms sit.

Enumerator
Pre 

y = x + f(norm(x)) (ESM, GPT-2, Llama).

Post 

y = norm(x + f(x)) (BERT and the original Transformer).

◆ NormType

enum class pulsatrix::NormType
strong

The layer's normalization.

Enumerator
LayerNorm 
RMSNorm 

◆ OpType

enum class pulsatrix::OpType
strong

The op-type tag a Node carries. Charter Part 2 §3: nodes are tagged by a small closed set of op types rather than by concrete layer class, so a query like "find the last conv layer's activations" (Grad-CAM) works by querying op type, not by string-matching a layer name.

Note
This enum grows only when a genuinely new operation category is needed – it is not meant to enumerate every concrete Module subtype (LinearModule and a future EmbeddingModule might both tag their nodes Linear if they're mathematically the same operation).
Enumerator
Linear 
Conv 
Activation 
Elementwise 
Reduction 
Normalization 
Pooling 
Embedding 
Composite 
Recurrent 
Attention 

Multi-head (scaled dot-product) attention – Phase 3's MultiHeadAttentionModule.

Note
Justification for growing the enum here (contrast RoPEModule, which deliberately reused Elementwise): attention is a genuinely new operation category, not a new spelling of an existing one. It contracts two learned projections against each other (Q @ K^T) and re-mixes a third along the sequence axis – an input-dependent, content-addressed mixing across positions that no existing category describes. It is not Linear (the mixing weights are computed from the input, not stored), not Composite (Composite means "a container of other modules with no math of its own", which SequentialModule is and this is not – this module owns the two batched matmuls, the scale and the bilinear LRP rule), and not Recurrent (no state carried across steps; all positions are attended in parallel). The charter's stated reason for the enum – "find the last conv layer"-style graph queries – is exactly the use case that needs "find the attention blocks" to be answerable.

◆ OutputDivergence

enum class pulsatrix::OutputDivergence
strong

How the masked model's output is compared with the target's.

Enumerator
MeanSquaredError 

mean((y - y*)²) over every value.

KlOnLogits 

KL(softmax(y*) ‖ softmax(y)) over the last dimension, averaged over rows: for logits.

◆ ParameterKind

enum class pulsatrix::ParameterKind
strong

Which family of values a named parameter draws from.

Enumerator
Continuous 
LogUniform 
Integer 
Categorical 

◆ PointPooling

enum class pulsatrix::PointPooling
strong

How PointCloud turns one sample's activations into points.

Enumerator
Flatten 

One point per sample: every dimension after the batch, flattened.

PerPosition 

One point per position (token, pixel): the feature axis is its coordinates.

Mean 

One point per sample: the mean over its positions.

Max 

One point per sample: the maximum over its positions, per feature.

Last 

One point per sample: its last position, as a causal language model reads it.

◆ PrependScheme

enum class pulsatrix::PrependScheme
strong

When Metaspace puts its replacement in front of a piece.

Enumerator
Always 
First 
Never 

◆ RdmComparison

enum class pulsatrix::RdmComparison
strong

How CompareRdms() correlates two RDMs.

Enumerator
Spearman 

Spearman's rank correlation, ties given their average rank (scipy's spearmanr). Only the order of the distances counts, so it suits RDMs on different scales.

Pearson 

Pearson's correlation of the distances themselves.

◆ RdmMetric

enum class pulsatrix::RdmMetric
strong

How RepresentationalDissimilarity() measures the distance between two inputs.

Enumerator
Correlation 

1 minus the Pearson correlation of the two rows, between 0 and 2: the classic RSA choice, blind to each row's mean and scale.

Euclidean 

The Euclidean distance between the rows.

Cosine 

1 minus the cosine of the angle between the rows, between 0 and 2.

◆ RecurrentCellOp

enum class pulsatrix::RecurrentCellOp
strong

Fused per-element recurrent-cell passes, for DeviceBackend::recurrent_cell. Slots (in[] / out[]), all (rows x hidden) per timestep unless noted:

  • RnnBackward: in g, dh_next, h -> out dz
  • LstmForward: in i, f, g, o (activated gates), c_prev -> out c, tanh(c), h
  • LstmBackward: in g, dh_next, dc_next, i, f, g, o, tanh_c, c_prev -> out dz_i, dz_f, dz_g, dz_o, dc_prev
  • LstmLrp: in r, R_h_next, R_c_next, i, f, g, c_prev, c -> out R_g, R_c_prev
  • GruBackward: in g, dh_next, z, r, n, hn, h_prev -> out dh_prev_direct, dz_pre, dn_pre, dr_pre, dhn_prev
  • GruLrp: in r, R_h_next, z, r_gate, n, hn, h_prev, h, n_pre -> out R_hprev_direct, R_n, R_term_b
Enumerator
RnnBackward 
LstmForward 
LstmBackward 
LstmLrp 
GruBackward 
GruLrp 

◆ ReferenceMode

enum class pulsatrix::ReferenceMode
strong

How ConceptReferenceSamples() ranks inputs.

Enumerator
Relevance 

By the channel's relevance for the target class, summed over positions.

Activation 

By the channel's largest activation over positions.

◆ RlRowOp

enum class pulsatrix::RlRowOp
strong

Fused per-row reinforcement-learning passes, for DeviceBackend::rl_rows. One lane per batch row (per element for PolyakBlend); rows x cols from RlRowArgs. Index slots hold validated whole-number action indices as floats. Slots (in[] -> out[]):

  • DqnLoss: in q (rows, cols), indices, targets -> out per-row squared TD error
  • DqnGrad: in q, indices, targets -> out grad (rows, cols), caller-zeroed; only the taken action's element is written (uses scale)
  • PgLoss: in logits, indices, returns -> out probs (rows, cols), per-row loss term
  • PgGrad: in probs, indices, returns -> out grad (dense; uses scale)
  • PpoLoss: in logits, indices, old_log_probs, advantages -> out probs, per-row loss term, ratio, mask (uses lower, upper)
  • PpoGrad: in probs, indices, advantages, ratios, masks -> out grad (dense; uses scale)
  • DqnTarget: in q_select, q_eval (both rows x cols), rewards, dones -> out target (uses gamma)
  • PolyakBlend: in source, destination -> out tau*source + (1 - tau)*destination over rows elements (out may alias destination; uses tau)
    Note
    TokenCeLoss (HIP-6, TokenCrossEntropyLoss::forward): in[0] logits (rows, cols), in[1] the raw targets as floats; out[0] probabilities (rows, cols), out[1] per-row statistics (rows, 4): the loss term, 1 for a counted token, 1 for a target that isn't a whole number, 1 for one outside [0, cols) that isn't ignore_index; out[2] the decoded indices and out[3] the weights (PgGrad's in[1] and in[2]). A bad or ignored target gets index 0, weight 0.
Enumerator
DqnLoss 
DqnGrad 
PgLoss 
PgGrad 
PpoLoss 
PpoGrad 
DqnTarget 
PolyakBlend 
TokenCeLoss 

◆ RoPELayout

enum class pulsatrix::RoPELayout
strong

Which features RoPE rotates together (LLM-1).

Note
The two layouts are the same rotation of a permuted feature vector, so they give different results on the same weights. A checkpoint is trained with one of them.
Enumerator
AdjacentPairs 

Pair i is features (2i, 2i+1): the original RoPE paper and Meta's own Llama code.

RotateHalf 

Pair i is features (i, i + head_dim/2): Hugging Face rotate_half, which every Llama-family checkpoint on the Hub (SmolLM2, Qwen, Llama, Gemma) expects.

◆ SafetensorsDtype

enum class pulsatrix::SafetensorsDtype
strong

Element types a safetensors file can declare. The floating-point ones convert to a Tensor.

Enumerator
Bool 
U8 
I8 
I16 
U16 
I32 
U32 
I64 
U64 
F8_E4M3 
F8_E5M2 
F16 
BF16 
F32 
F64 

◆ SliceTest

enum class pulsatrix::SliceTest
strong

How PerSliceError() tests a slice against the rest.

Enumerator
Auto 

Fisher's exact test when every error is 0 or 1, a permutation test otherwise.

FisherExact 

Fisher's exact test, one-sided: whether the slice's errors are more frequent than the rest's. Needs every error to be 0 or 1.

Permutation 

A permutation test, one-sided, of the slice's mean error against the rest's.

◆ SplitBehavior

enum class pulsatrix::SplitBehavior
strong

What a split does with the pieces that match (Hugging Face's SplitDelimiterBehavior).

Enumerator
Removed 
Isolated 
MergedWithPrevious 
MergedWithNext 
Contiguous 

◆ SsmPassOp

enum class pulsatrix::SsmPassOp
strong

Fused passes of the state-space / linear-recurrence modules (MambaModule, RWKVModule, RetNetModule), for DeviceBackend::ssm_pass. Dims come from SsmPassArgs: n batch, l sequence length, d d_model (or C for ReverseTimeSum), s Mamba's state_size / RetNet's key_dim. Sequences are (n, l, X) row-major; "states" buffers are (n, l + 1, ...) with the zero initial state at index 0. Lanes and slots (in[] -> out[]):

  • MambaForward (n*d lanes, t ascending): in input, z_delta (bias added), B, C, A (d, s), D (d) -> out delta, Abar, Bbar (n, l, d, s), states (n, l+1, d, s), output
  • MambaBackward (n*d lanes, t descending): in grad_output, input, delta, z_delta, states, Abar, Bbar, B, C, A, D -> out dx_direct, dz_delta, dh_total, A_terms (n, l, d, s), carry scratch (n, d, s), zero-filled by the caller
  • MambaGradBC (n*l*s lanes): in grad_output, input, delta, states, dh_total -> out dB, dC
  • MambaLrp (n*d lanes, t descending): in input, output, relevance_out, states, Abar, Bbar, C, D -> out relevance_in, carry scratch (n, d, s), zero-filled (uses eps)
  • RwkvTokenShift (n*l*d): in input, mu_r, mu_k, mu_v -> out xr, xk, xv
  • RwkvForward (n*d lanes, t ascending): in z_r, k, v, u, w -> out r, e, num, den, wkv, kk, a states, b states (n, l+1, d), gated
  • RwkvBackward (n*d lanes, t descending): in g_gated, r, v, e, kk, num, den, a states, b states, wkv, w -> out dz_r, dk, dv, u_terms, w_terms
  • RwkvShiftBackward (n*l*d): in input, g_xr, g_xk, g_xv, mu_r, mu_k, mu_v -> out grad_input, mu_r_terms, mu_k_terms, mu_v_terms
  • RwkvLrp (n*d lanes, t descending): in r_gated, a states, den, e, v, wkv, kk, w -> out v_relevance (uses eps)
  • RwkvShiftLrp (n*l*d): in input, xv, r_xv_raw, mu_v -> out relevance_in (uses eps)
  • StabilizedDiv (n*l*d): in r, z -> out r / (z + eps*sign(z))
  • RetnetForward (n*d lanes, t ascending): in q, k, v -> out states (n, l+1, s, d), output (uses gamma)
  • RetnetStateGrad (n*s*d lanes, t descending): in grad_output, q -> out dS (n, l, s, d) (uses gamma)
  • RetnetGradQK (n*l*s): in grad_output, states, dS, v -> out dq, dk
  • RetnetGradV (n*l*d): in dS, k -> out dv
  • RetnetScores (n*l*l): in q, k -> out QK, G = gamma^(t-s) QK (both 0 for s > t)
  • RetnetReadout (n*l*d): in G, v -> out Y = G @ V over s <= t
  • RetnetLrpInput (n*l*d): in input, W_q, W_k, W_v, q, k, v, r_q, r_k, r_v -> out relevance_in (uses eps)
  • ReverseTimeSum (d lanes): in terms (n, l, d) -> out[c] = sum over t descending, b ascending – a backward loop's parameter-gradient accumulation order
Enumerator
MambaForward 
MambaBackward 
MambaGradBC 
MambaLrp 
RwkvTokenShift 
RwkvForward 
RwkvBackward 
RwkvShiftBackward 
RwkvLrp 
RwkvShiftLrp 
StabilizedDiv 
RetnetForward 
RetnetStateGrad 
RetnetGradQK 
RetnetGradV 
RetnetScores 
RetnetReadout 
RetnetLrpInput 
ReverseTimeSum 

◆ SurrogateTask

enum class pulsatrix::SurrogateTask
strong

What the surrogate imitates.

Enumerator
Classification 

The model's class: the index of its largest output. Fidelity is agreement.

Regression 

One output's value. Fidelity is R².

◆ TaggingRule

enum class pulsatrix::TaggingRule
strong

How a token's tag follows from it and the token before it (the first token's predecessor is 0). Tags are modulo kClasses.

Enumerator
SumWithPrevious 
DifferenceWithPrevious 

◆ TrajectorySplit

enum class pulsatrix::TrajectorySplit
strong

How the relevance on x_prev is split across skip, network and noise (h_1, h_2, h_3).

Enumerator
AbsoluteRatio 

R_k = R |h_k| / (sum_j |h_j| + epsilon), the absolute-value ratio of LRP for ResNets (Otsuki et al. 2024), D1's first design. Bounded however much the terms cancel, and conserving up to the epsilon, which only handles 0/0. But it loses sign: a term that opposes x_prev still gets a share of R's sign. The network term opposes the skip term whenever eps_theta removes noise, so everything that acts through eps_theta comes back with the wrong sign. On DIFF-5's planted DDPM the class got the wrong sign in 9 of 12 samples.

SignedEpsilon 

The signed epsilon rule, R_k = R h_k / (s + e sign(s)) with s = sum_j h_j and the stabilizer e = epsilon * sum_j |h_j|. Shares grow without bound when the terms cancel; what the stabilizer absorbs is reported.

SignedRatio 

R_k = R h_k sign(s) / (sum_j |h_j| + epsilon): each term keeps the sign of its contribution to x_prev and is bounded by |R|. What the terms cancel, R (1 - |s| / sum_j |h_j|), is absorbed and reported. It is the signed epsilon rule with the stabilizer sum_j |h_j| - |s|, just large enough to bound every share.

◆ UnmaskingSchedule

enum class pulsatrix::UnmaskingSchedule
strong

How the sampler chooses which masked positions to fill at each step.

Enumerator
Confidence 

LLaDA's low-confidence remasking: every step fills a fixed share of the positions that started masked (spread as evenly as the step count allows, earlier steps taking the remainder), choosing the masked positions whose chosen token the model is most sure of. Ties go to the earlier position. Fully deterministic when greedy.

Ancestral 

MDLM's ancestral sampler (ddpm_cache): time runs linearly from 1 to 1e-5, and at each step every masked position is filled independently with probability (t - s) / t, where s is the next step's time. Positions still masked after the last step are filled with their most likely token, as MDLM's final noise-removal step does. Steps that fill nothing don't run the model (MDLM reuses its output the same way).

Remasking 

DPLM's reparameterized decoding (reparam-uncond-deterministic-linear, its default): at step t of T the model scores every position that started masked by the log-probability, over the allowed tokens, of the token it would choose there now, filled or not. Of those n positions, the floor(n * (1 - t / T)) with the lowest score are masked, including positions filled at earlier steps; a position is masked when its score is strictly below the cutoff, as DPLM's topk_masking does. Every other masked position takes its chosen token, and every other filled position keeps the token it has. Every step runs the model and is recorded, even one that changes nothing, and the last masks nothing.

◆ VariantStrategy

enum class pulsatrix::VariantStrategy
strong

How variants are scored.

Enumerator
MaskedMarginals 
WildTypeMarginals 

◆ WeightTransform

enum class pulsatrix::WeightTransform
strong

How a source tensor becomes a target parameter.

Enumerator
Identity 
Transpose 

Swap the two axes of a matrix: PyTorch's nn.Linear stores (out, in), pulsatrix's LinearModule (in, out).

◆ WordAggregation

enum class pulsatrix::WordAggregation
strong

How a word's score is made from the scores of the tokens that overlap it.

A token overlapping several words gives each a share: the fraction of its bytes inside words that fall inside that word. Bytes outside every word (the space in a byte-level "Ġworld") don't count, so a token's shares add up to 1.

Enumerator
Sum 

Σ share × score. Conserves the total: the words' scores plus the unassigned score add up to the tokens' (what relevance needs).

Mean 

Σ share × score / Σ share: the share-weighted mean of the overlapping tokens.

Max 

The largest score among the overlapping tokens.

MaxAbs 

The score with the largest magnitude among the overlapping tokens, sign kept (for signed attributions, where Max would hide strong negative evidence).

◆ WordSplit

enum class pulsatrix::WordSplit
strong

How the text is cut into words.

Enumerator
WordsAndPunctuation 

Runs of letters, marks, digits and underscores, and runs of other non-space characters (\w+|[^\w\s]+, Hugging Face's Whitespace pre-tokenizer): "don't!" is "don", "'", "t", "!".

Whitespace 

Runs of non-space characters (\S+): "don't!" is one word.

◆ XaiQuestion

enum class pulsatrix::XaiQuestion
strong

The nine question categories of Liao, Gruen and Miller's XAI question bank (CHI 2020).

Enumerator
Input 

What data the model was trained on or sees: dataset statistics, the training examples nearest an input.

Output 

What the model's output is and means: its schema, labels and scope.

Performance 

How well the model does: accuracy, calibration, error by slice, uncertainty.

HowGlobal 

How the model works overall: its general logic, the features and concepts it uses.

Why 

Why this input gets this prediction.

WhyNot 

Why this input gets this prediction instead of another one.

WhatIf 

What happens to the prediction if the input changes in a given way.

HowToBeThat 

What change to the input would give a different, chosen prediction.

HowToStillBeThis 

What can change, or must stay, for the prediction to remain the same.

◆ XaiReason

enum class pulsatrix::XaiReason
strong

Adadi and Berrada's four reasons to explain a model (IEEE Access, 2018).

Enumerator
Justify 

Justify a decision to someone it affects or who must sign it off.

Control 

Control the model: find its flaws and failure modes before they do harm.

Improve 

Improve the model: find what to change in its data, features or training.

Discover 

Discover something new about the domain from what the model learned.

Function Documentation

◆ AblationHook()

HiddenStateHook pulsatrix::AblationHook ( int64_t  position,
std::vector< bool >  rows = {} 
)

Zero-ablates one position: the same rows set to 0 instead of reconstructed.

◆ AggregateToWords() [1/2]

WordScores pulsatrix::AggregateToWords ( std::string_view  text,
const Encoding &  encoding,
const std::vector< float > &  token_scores,
WordAggregation  aggregation = WordAggregation::Sum,
WordSplit  split = WordSplit::WordsAndPunctuation 
)

AggregateToWords over an Encoding of text, with words from SplitWords(text, split).

◆ AggregateToWords() [2/2]

WordScores pulsatrix::AggregateToWords ( std::string_view  text,
const std::vector< Offset > &  token_offsets,
const std::vector< float > &  token_scores,
const std::vector< Offset > &  words,
WordAggregation  aggregation = WordAggregation::Sum 
)

Merges per-token scores into the given words.

Parameters
textThe text the offsets point into.
token_offsetsOne byte range of text per token (Encoding::offsets).
token_scoresOne score per token.
wordsByte ranges of text, in order and not overlapping (SplitWords()).
Exceptions
std::invalid_argumentif the sizes differ, or an offset or word lies outside the text, or the words overlap or are out of order.

◆ AlignComponentsToRows()

ComponentAlignment pulsatrix::AlignComponentsToRows ( ComponentLinear &  layer)

◆ AlignmentConservation()

std::vector< float > pulsatrix::AlignmentConservation ( const std::vector< FastaRecord > &  alignment)

Conservation of each query residue in a multiple sequence alignment whose first record is the query: log2(20) - entropy of the column's amino acids, in bits, times the share of sequences without a gap there. NaN for query residues outside the alignment's focus columns (lowercase).

Reads both A2M layouts: column-aligned files, where every record has the query's length and lowercase marks non-focus columns (ProteinGym's and EVE's), and standard A2M, where lowercase letters and '.' are insertions and the match columns (uppercase and '-') line up.

Note
Sequences are counted unweighted; tools that reweight by similarity give somewhat different numbers for families with many near-duplicates.
Returns
One value per query residue (its letters, any case).
Exceptions
std::invalid_argumentfor no records, or records whose match columns don't line up.

◆ AlignmentQuery()

std::string pulsatrix::AlignmentQuery ( const std::vector< FastaRecord > &  alignment)

The query's residues in alignment's first record: its letters, uppercased.

◆ AllocateOffspringCounts()

std::vector< int > pulsatrix::AllocateOffspringCounts ( const std::vector< double > &  species_adjusted_fitness_sums,
int  population_size 
)
inline

Pure core: allocates population_size offspring slots across species proportionally to each species' own adjusted-fitness sum, using the largest-remainder (Hamilton) apportionment method so the total always sums to exactly population_size (ties in fractional remainder broken by species index, earliest first). Falls back to an equal split (remainder to the earliest species, by index) if every species sum is non-positive, rather than dividing by zero.

Exceptions
std::invalid_argumentif species_adjusted_fitness_sums is empty or population_size is not positive.

◆ AllXaiQuestions()

const std::vector< XaiQuestion > & pulsatrix::AllXaiQuestions ( )

All nine questions, in the enum's order.

◆ AllXaiReasons()

const std::vector< XaiReason > & pulsatrix::AllXaiReasons ( )

All four reasons, in the enum's order.

◆ AnalyzeMorris()

MorrisResult pulsatrix::AnalyzeMorris ( const std::vector< std::vector< float > > &  samples,
const std::vector< float > &  outputs,
const MorrisOptions &  options = {} 
)

Morris statistics from samples laid out as MorrisSample's (or SALib's) trajectories and one output per row: the same elementary effects and mu, mu*, sigma as SALib 1.6 morris.analyze (unscaled). The confidence interval is a bootstrap with this library's own generator, so it agrees with SALib's in distribution, not digit for digit.

Exceptions
std::invalid_argumentif the rows don't form whole trajectories of num_features + 1 rows, a step changes other than exactly one feature, or an option is invalid.

◆ AnalyzeSobol()

SobolResult pulsatrix::AnalyzeSobol ( const std::vector< float > &  outputs,
int64_t  num_features,
const SobolOptions &  options = {} 
)

Sobol indices from outputs in SALib's layout without second order: N blocks of (num_features + 2) outputs, f(A), f(AB_1) ... f(AB_D), f(B). Outputs are standardized first, then the first order uses Saltelli et al. (2010)'s estimator and the total order Jansen's, exactly as SALib 1.6 does. The bootstrap uses this library's generator.

Exceptions
std::invalid_argumentif the outputs don't form whole blocks or an option is invalid.

◆ Anisotropy()

double pulsatrix::Anisotropy ( const Tensor &  x,
bool  center = false 
)

The mean cosine similarity over all pairs of different rows: about 0 for directions spread evenly, near 1 when every row points the same way.

Parameters
xshape (n, ...): a row per input. Dimensions after the first are flattened.
centerSubtract the mean row first. Centering removes the common direction, so the result drops to about -1/(n - 1) when nothing but that direction was shared.
Note
Exact over all n(n - 1) pairs, at the cost of one pass: the sum of unit vectors u gives (|sum u|^2 - n) / (n (n - 1)).
Exceptions
std::invalid_argumentif x has rank below 2, fewer than 2 rows, a NaN or infinity, or a row of zeros (after centering, if centering).

◆ append_named_buffers()

void pulsatrix::append_named_buffers ( std::vector< NamedBufferRef > &  out,
const std::string &  prefix,
Module &  child 
)
inline

Appends child's named buffers to out, each renamed to prefix.name.

◆ append_named_parameters()

void pulsatrix::append_named_parameters ( std::vector< NamedParamRef > &  out,
const std::string &  prefix,
Module &  child 
)
inline

Appends child's named parameters to out, each renamed to prefix.name – the one step every container's named_parameters() repeats per child.

Note
A child that overrides only the legacy parameters() hook reports no names; its parameters are appended under positional names (prefix.0, prefix.1, ...) so a container never hides them from an optimizer that used to see them.

◆ ApplyIA3()

std::vector< std::string > pulsatrix::ApplyIA3 ( Module &  model,
const IA3Config &  config = {} 
)

Attaches an IA³ vector to each LinearModule config selects, then freezes everything else, as PEFT's get_peft_model() does.

Returns
The adapted layers' names, in the model's order.
Exceptions
std::invalid_argumentif a target or feedforward name matches no module or a module that isn't a LinearModule, a feedforward name isn't a target, nothing is selected, or a selected layer already has an IA³ vector or a LoRA adapter. Nothing changes then.

◆ ApplyLora()

std::vector< std::string > pulsatrix::ApplyLora ( Module &  model,
const LoRAConfig &  config = {} 
)

Attaches a LoRA adapter to each LinearModule that config.target_modules selects, then freezes everything else: only the adapters train, as with PEFT's get_peft_model().

Returns
The adapted layers' names, in the model's order.
Note
Each layer's A is drawn from config.seed and the layer's position in that order.
Exceptions
std::invalid_argumentif a target matches no module or a module that isn't a LinearModule, nothing is selected, or a selected layer already has an adapter. Nothing is changed then.

◆ ApplyLoReFT()

std::vector< LoReFTIntervention * > pulsatrix::ApplyLoReFT ( CausalLM &  model,
const LoReFTConfig &  config = {} 
)

Installs a LoReFTIntervention after each of config.layers' blocks and freezes the rest of the model: only the interventions train.

Returns
The interventions, in layer order; the model owns them.
Exceptions
std::invalid_argumentfor a layer the model doesn't have, or invalid sizes; std::logic_error if a chosen layer already has an intervention.

◆ ApplyMutations()

std::string pulsatrix::ApplyMutations ( std::string_view  sequence,
const std::vector< Mutation > &  mutations,
int64_t  offset = 1 
)

sequence with mutations applied; position p is sequence[p - offset].

Exceptions
std::invalid_argumentif a position is outside the sequence or its residue isn't the listed wild type.

◆ AskGivenSamples()

std::vector< std::vector< double > > pulsatrix::AskGivenSamples ( const CMAESState &  state,
const std::vector< std::vector< double > > &  z_samples 
)
inline

Pure core: decodes an explicit set of standard-normal sample vectors into offspring points, x_i = mean + sigma * sqrt(variances) (elementwise) * z_i.

Exceptions
std::invalid_argumentif any z_sample's dimension doesn't match state.mean's.

◆ AttachBootstrapBand()

void pulsatrix::AttachBootstrapBand ( PersistenceDiagramDocument &  doc,
int  dimension,
const BootstrapBandResult &  band 
)

Adds BootstrapBand()'s band to the entry for dimension.

Exceptions
std::invalid_argumentif the document has no such dimension.

◆ AttachSignificance()

void pulsatrix::AttachSignificance ( PersistenceDiagramDocument &  doc,
int  dimension,
const UniversalNullResult &  test 
)

Adds UniversalNullTest()'s p-values and corrected threshold to the entry for dimension. Features the test skipped get NaN.

Parameters
testThe test of that dimension's diagram, exactly as the document holds it.
Exceptions
std::invalid_argumentif the document has no such dimension, or a tested feature isn't in it: its index is out of range, or the pair there has a different death / birth.

◆ AttentionMap()

Tensor pulsatrix::AttentionMap ( const Tensor &  features,
DeviceBackend *  backend,
double  p = 2.0 
)

The attention map AttentionTransferLoss compares: (N, positions), each row L2-normalized, on features' device.

Exceptions
std::invalid_argumentif the rank is below 3.

◆ AudioPadCollate()

CollateFn pulsatrix::AudioPadCollate ( )

Builds a CollateFn that zero-pads (silence) variable-length waveforms (sample.fields[0], shape (1, channels, num_samples) – WavReader's/ AudioFolderDataset's convention) to the batch's own max sample count, producing one (N, channels, max_samples) Tensor, plus a (N,) length field. Phase 4's version of PadCollate (Phase 3, text) – a second proof that the CollateFn extension point handles ragged/variable-length modalities with zero Dataset/DataLoader/Batch interface changes.

Returns
A CollateFn producing Batch{ {padded_waveforms (N,channels,max_samples), lengths (N,)} }.
Exceptions
std::invalid_argument(from the returned CollateFn, at call time) if samples is empty, or if samples have differing channel counts – external boundary, matching DefaultCollate's/PadCollate's own convention.

◆ AxisScaleName()

const char * pulsatrix::AxisScaleName ( AxisScale  scale)

◆ BackwardThroughPopulation()

void pulsatrix::BackwardThroughPopulation ( GeneratorPopulation &  population,
const Tensor &  pooled_grad,
const std::vector< int64_t > &  batch_sizes,
DeviceBackend *  backend 
)
inline

Given pooled_grad (the gradient w.r.t. the pooled fake batch GeneratePooledFakeSamples produced – e.g. from discriminator.backward() called after a forward on that pooled batch), routes each population member's own slice back through that member's own backward() – the concrete mechanism that lets one shared discriminator train against every generator's own output while each generator's own parameters still receive exactly its own correct gradient.

Parameters
batch_sizesEach population member's own noise batch's leading-dimension size, in the same order GeneratePooledFakeSamples pooled them (not assumed uniform across members).
Exceptions
std::invalid_argumentif batch_sizes.size() != population.size(), or the batch sizes don't sum to pooled_grad's own leading dimension (delegates to SliceBatch/each generator's own backward() for their own further preconditions).

◆ Base64Encode()

std::string pulsatrix::Base64Encode ( const std::vector< uint8_t > &  bytes)

Standard base64 (RFC 4648, with padding), for image/png data.

◆ BaselinePValue()

double pulsatrix::BaselinePValue ( double  observed,
const std::vector< double > &  baselines 
)

The rank p-value of an observed statistic against the same statistic on baselines: (1 + #{baseline >= observed}) / (1 + baselines.size()). Small means the observed value is larger than chance gives; the smallest possible is 1 / (1 + baselines.size()).

Exceptions
std::invalid_argumentif baselines is empty or a value is NaN.

◆ BernoulliKl()

double pulsatrix::BernoulliKl ( double  p,
double  q 
)

KL divergence between Bernoulli(p) and Bernoulli(q), with p and q clipped to (0, 1).

◆ BettiCurve()

std::vector< int64_t > pulsatrix::BettiCurve ( const PersistenceDiagram &  diagram,
const std::vector< double > &  grid 
)

The Betti curve: how many features are alive, birth <= t < death, at each scale t.

Exceptions
std::invalid_argumentif a grid value is NaN.

◆ BitFlipMutation()

template<typename RNG >
std::vector< bool > pulsatrix::BitFlipMutation ( const std::vector< bool > &  genotype,
double  mutation_probability,
RNG &  rng 
)

RNG-driven wrapper: each gene flips independently with probability mutation_probability.

Exceptions
std::invalid_argumentif mutation_probability is outside [0, 1].
Note
mutation_probability == 0.0 or 1.0 make std::bernoulli_distribution deterministic (never / always flips) – exact, RNG-independent correctness cases.

◆ BitFlipMutationByMask()

std::vector< bool > pulsatrix::BitFlipMutationByMask ( const std::vector< bool > &  genotype,
const std::vector< bool > &  flip_mask 
)
inline

Flips each gene where flip_mask is true, leaves the rest unchanged.

Exceptions
std::invalid_argumentif genotype and flip_mask sizes differ.

◆ BlendCrossover()

template<typename RNG >
std::pair< std::vector< double >, std::vector< double > > pulsatrix::BlendCrossover ( const std::vector< double > &  parent1,
const std::vector< double > &  parent2,
double  alpha,
RNG &  rng 
)

RNG-driven wrapper (DEAP's cxBlend): draws gamma_i = (1+2*alpha)*u_i - alpha per gene, u_i ~ Uniform(0, 1).

Exceptions
std::invalid_argumentif parent sizes differ or alpha < 0.

◆ BlendCrossoverByGamma()

std::pair< std::vector< double >, std::vector< double > > pulsatrix::BlendCrossoverByGamma ( const std::vector< double > &  parent1,
const std::vector< double > &  parent2,
const std::vector< double > &  gamma 
)
inline

Blends each gene pair via an explicit per-gene gamma: child1_i = (1-gamma_i)*x1_i + gamma_i*x2_i, child2_i = gamma_i*x1_i + (1-gamma_i)*x2_i.

Exceptions
std::invalid_argumentif parent1/parent2/gamma sizes are not all equal.
Note
child1_i + child2_i == parent1_i + parent2_i for any gamma_i – an algebraic invariant, not just a property at specific gamma values, useful for testing the RNG-driven wrapper without controlling its draws directly.

◆ BootstrapBand()

BootstrapBandResult pulsatrix::BootstrapBand ( const DistanceMatrix &  distances,
int  dimension,
const BootstrapOptions &  options = {} 
)

A bootstrap confidence band for a Rips diagram (after Fasy, Lecci, Rinaldo, Wasserman, Balakrishnan and Singh, Ann. Statist. 2014): resample the points with replacement, compute each resample's diagram, and take the (1 - alpha) quantile of their bottleneck distances to the original.

Parameters
distancesThe whole cloud's distances; resamples reuse them, so nothing is recomputed.
dimensionThe homology dimension to test.
Note
Fasy et al. prove coverage for distance-function filtrations; for Rips diagrams the band is the standard heuristic. A resample repeats some points, which only adds zero-length edges.
Exceptions
std::invalid_argumentif resamples < 1, alpha is outside (0, 1), or dimension is above options.rips.max_dimension.

◆ BottleneckDistance()

Certified< double > pulsatrix::BottleneckDistance ( const PersistenceDiagram &  a,
const PersistenceDiagram &  b 
)

The bottleneck distance between two diagrams of the same dimension.

Returns
The distance between the diagrams as given, certified to be within a.error_bound + b.error_bound of the distance between the exact diagrams (by the triangle inequality). Infinite if the diagrams have different numbers of essential features, which can't be matched to the diagonal.
Note
Exact: a binary search over the candidate values, each tested by a maximum bipartite matching (Hopcroft-Karp) on the points and their diagonal projections. Comfortable up to a few hundred points per diagram; the cost grows as (n1 + n2)^2.5 times a logarithm.
Exceptions
std::invalid_argumentif the diagrams' dimensions differ.

◆ BuildExplanation()

Explanation pulsatrix::BuildExplanation ( const ExplanationRequest &  request,
const Tensor &  input,
const ExplainFn &  explain,
const PredictFn &  predict,
Module *  model,
const ExplanationCheckOptions &  options = {} 
)

Explains input with explain and runs the checks the plan asks for.

What each check does:

  • faithfulness: DeletionCurve and InsertionCurve, scored as insertion AUC minus deletion AUC and compared with options.random_orderings random orderings of the features; it passes when the rank p-value is at most options.alpha. Not run when the attribution's shape isn't the input's (Grad-CAM).
  • stability: repeated runs and runs on a noisy input, compared by the Spearman correlation of the attribution magnitudes, with ComputeAttributionStability's variance; passes when every correlation is at least options.min_stability.
  • robustness: ExplanationSensitivity() with options.robustness_radius and robustness_samples, and FGSM's point through model when there is one (its parameter gradients are restored); passes when the max-sensitivity and the sensitivity at FGSM's point are at most options.max_sensitivity. NotRun when every perturbation changed the prediction.
  • conservation: the attributions' sum against LRP's seeded total (its metadata), or f(input) - f(baseline) when request.baseline is given; passes within options.conservation_tolerance.
  • randomization: ModelParameterRandomizationTest; passes when the explanation of the fully randomized model correlates at most options.max_random_similarity with the original.
  • null_model: NullModelBaseline, with the same threshold.
  • aggregate: the mean absolute attribution over request.dataset (Measured).
  • per_slice_error: PerSliceError() on request.dataset, with an input wrong when the index of predict's largest output isn't its label; fails when a slice is worse than the rest at options.alpha (SliceErrorCheck()). Any other check is NotRun.
Parameters
inputThe input to explain, with a leading batch dimension of 1.
explainRuns the explainer on its argument, reading the model as it is at that moment: the randomization test and the null model call it again on a randomized model.
predictThe model as a function, as in DeletionCurve().
modelThe Module explain and predict read, for the randomization test and the null model; nullptr if there is none, and those checks don't run. It is restored exactly.
Exceptions
std::invalid_argumentif request.method isn't in the catalog, doesn't answer request.question, or doesn't return an attribution (use ReportExplanation()).

◆ BuildRelevanceGraph()

AttributionGraph pulsatrix::BuildRelevanceGraph ( CausalLM &  model,
DeviceBackend *  backend,
const std::vector< int64_t > &  ids,
int64_t  target,
const RelevanceGraphOptions &  options 
)

Explains the model's logit for target at the last position with LRP and returns the relevance flow as an attribution graph.

Nodes are the residual stream at each token position: the embeddings (layer "E"), then the output of every block (layers "0" to "L-1"), and the output token. A node's activation is its relevance (summed over the hidden size). A link from position i in one layer to position j in the next is the part of j's relevance that the block passes back to i: the block's LRP run with relevance only at j. Because the LRP rules are linear in the incoming relevance, a node's outgoing links sum to its own relevance, and the embedding nodes hold the per-token relevance that CausalLM::propagate_relevance gives. A layer's total needn't equal the next layer's: LRP through norms and biases isn't strictly conservative.

Parameters
idsThe prompt's token ids (one sequence).
Note
Cost: one forward pass, one full LRP pass, then one block LRP pass per layer and position.
Exceptions
std::invalid_argumentfor an empty or too long prompt, a target outside the vocabulary, or prompt_tokens of the wrong length.

◆ BuildVocabulary()

Vocabulary pulsatrix::BuildVocabulary ( const std::vector< std::vector< std::string > > &  tokenized_corpus,
int64_t  max_vocab_size = -1 
)

Builds a Vocabulary from a tokenized corpus, ranked by descending token frequency (ties broken by first-seen order, for determinism).

Parameters
tokenized_corpusOne token sequence per document/line (e.g. Tokenizer::Tokenize's output for each line of a corpus).
max_vocab_sizeIf >= 0, keeps only the top max_vocab_size most frequent real tokens (the reserved <unk> at index 0 doesn't count against this limit). -1 (default) keeps every distinct token seen.
Returns
The built Vocabulary. An empty corpus produces a Vocabulary containing only <unk> (size() == 1) – not an error, just nothing to rank.

◆ ByteLevelAlphabet()

const std::vector< std::string > & pulsatrix::ByteLevelAlphabet ( )

The GPT-2 byte-to-character table byte-level BPE uses: printable bytes stand for themselves, the rest for U+0100 onward.

◆ ByteToCharOffset()

Offset pulsatrix::ByteToCharOffset ( std::string_view  text,
Offset  bytes 
)

A byte offset range of text as a character (code point) range, widened to whole characters, which is how Hugging Face reports offsets.

◆ CalibrateConformalClassifier()

ConformalClassifier pulsatrix::CalibrateConformalClassifier ( const Tensor &  probabilities,
const std::vector< int64_t > &  labels,
const ConformalOptions &  options = {} 
)

Calibrates on held-out examples the model wasn't trained on.

Parameters
probabilities(n, K), each row the model's probabilities for one calibration example.
labelsThe true class of each.
Exceptions
std::invalid_argumentif probabilities isn't (n, K) with n >= 1 and K >= 2, labels has another length or a class outside [0, K), a probability is negative or not finite, alpha isn't in (0, 1), or options.randomized is set for LAC.

◆ CalibrateConformalQuantileRegressor()

ConformalRegressor pulsatrix::CalibrateConformalQuantileRegressor ( const std::vector< double > &  lower,
const std::vector< double > &  upper,
const std::vector< double > &  targets,
double  alpha = 0.1 
)

Calibrates CQR intervals [lo − q̂, hi + q̂] from a quantile regressor's lower and upper predictions, such as its alpha/2 and 1 − alpha/2 quantiles, on held-out examples.

Exceptions
std::invalid_argumentas CalibrateConformalRegressor() does, for all three.

◆ CalibrateConformalRegressor()

ConformalRegressor pulsatrix::CalibrateConformalRegressor ( const std::vector< double > &  predictions,
const std::vector< double > &  targets,
double  alpha = 0.1 
)

Calibrates intervals ŷ ± q̂ from a point regressor's predictions on held-out examples.

Exceptions
std::invalid_argumentif the two are empty, have different lengths or hold a value that isn't finite, or alpha isn't in (0, 1).

◆ CanonicalCorrelations()

std::vector< double > pulsatrix::CanonicalCorrelations ( const Tensor &  x,
const Tensor &  y 
)

The canonical correlations between two representations of the same inputs, largest first: min(rank x, rank y) values between 0 and 1.

The first is the largest correlation between any direction in x's (centered) space and any in y's; each later one the largest among directions uncorrelated with the earlier ones. They are invariant to invertible linear maps of either representation.

Note
Directions whose variance is rounding error (below the largest × max(n, width) × machine epsilon) don't count towards a rank.
Exceptions
std::invalid_argumentif a tensor has rank below 2 or a NaN or infinite value, the two have different numbers of rows, either is constant, or rank x + rank y isn't below the number of inputs: then at least one correlation is 1 whatever the data, and the rest are inflated.

◆ CategoricalDensity()

double pulsatrix::CategoricalDensity ( const std::vector< std::string > &  observations,
size_t  num_categories,
const std::string &  category 
)
inline

Laplace(add-one)-smoothed empirical probability of category among observations.

Exceptions
std::invalid_argumentif num_categories == 0.
Note
observations may be empty (probability reduces to the uniform prior 1/num_categories).

◆ ChannelRelevance()

std::vector< double > pulsatrix::ChannelRelevance ( const Tensor &  layer_relevance)

Each row's relevance per channel, summed over the remaining dimensions: (N, C) values, row-major. With a conserving rule they add up to the explained output.

Exceptions
std::invalid_argumentif layer_relevance has rank below 2.

◆ check_deterministic_allowed()

void pulsatrix::check_deterministic_allowed ( const char *  operation)

Guard for a nondeterministic code path: call it before running one.

Parameters
operationNames the operation in the error message.
Exceptions
std::logic_errorif deterministic mode is on.

◆ check_optimizer_setting()

void pulsatrix::check_optimizer_setting ( float  value,
const std::string &  what 
)
inline

Throws std::invalid_argument unless value is finite and non-negative.

◆ CircuitNodeDisplayLabel()

std::string pulsatrix::CircuitNodeDisplayLabel ( const CircuitNode &  node)

Human-readable label for a CircuitGraph node: the node's own label when it has one, otherwise its operation type and id (e.g. "Conv #1", "Activation #2") – so an unlabeled ComputationGraph still renders as a readable layer diagram rather than a row of anonymous "node_<id>" markers.

◆ ClassifierFrom() [1/2]

DifferentiableClassifier pulsatrix::ClassifierFrom ( ExplainerContext &  context)

Differentiates through an ExplainerContext's autograd, as the gradient explainers do; the model's parameter gradients are left alone. The context must outlive the result.

◆ ClassifierFrom() [2/2]

DifferentiableClassifier pulsatrix::ClassifierFrom ( Module &  model)

Differentiates through Module::forward and Module::backward. backward() also accumulates the parameters' gradients, so zero them before training again. The module must outlive the result, and should be in eval mode, so dropout doesn't change between the steps.

◆ ClassifyLatent()

LatentClass pulsatrix::ClassifyLatent ( const CrosscoderLatentStats &  stats)

Minder et al.'s bins on Δnorm.

◆ ClassifyWithRules()

std::vector< int64_t > pulsatrix::ClassifyWithRules ( const TreeRules &  rules,
const std::vector< std::vector< float > > &  inputs 
)

Runs the rules on each input with the Datalog engine and returns the class whose predict fact it derives, or -1 if none.

◆ ClassProbabilitiesFromRules()

std::vector< double > pulsatrix::ClassProbabilitiesFromRules ( const SoftTreeRules &  rules,
const SoftDecisionTree &  tree,
int64_t  row 
)

Each class's probability for row row of tree's last forward(), from the rules evaluated over the real semiring.

◆ ClipGradNorm()

float pulsatrix::ClipGradNorm ( Module &  module,
float  max_norm,
bool  error_if_nonfinite = false 
)

Scales every trainable parameter's gradient so their global L2 norm is at most max_norm, as torch.nn.utils.clip_grad_norm_ does, and returns the norm before clipping.

Parameters
moduleIts parameters with requires_grad() set are counted and scaled; frozen ones are left alone (FND-2).
max_normPositive, finite limit.
error_if_nonfiniteThrow instead of returning when the norm is NaN or infinite.
Returns
The global norm before clipping, which is also the usual quantity to log.
Note
Call it after gradient accumulation and before the optimizer step. When the norm exceeds max_norm, every gradient is multiplied by the same factor max_norm / (norm + 1e-6), so the update's direction is kept.
One difference from PyTorch: a NaN or infinite norm leaves the gradients unchanged (PyTorch scales them anyway, spreading the NaN). Check the returned norm and skip the step.
Exceptions
std::invalid_argumentif max_norm isn't positive and finite.
std::runtime_errorif error_if_nonfinite is set and the norm is NaN or infinite.

◆ CollatePromptCompletions()

CausalLmBatch pulsatrix::CollatePromptCompletions ( const std::vector< PromptCompletion > &  examples,
DeviceBackend *  backend,
int64_t  pad_id = 0 
)

Builds a batch for TokenCrossEntropyLoss: position i predicts token i + 1, and only the completion's tokens count. The completion's last token is never an input (nothing follows it), so each row is one token shorter than prompt + completion.

Parameters
pad_idThe id written into padding; its value doesn't matter (see the file comment).
Exceptions
std::invalid_argumentif examples is empty or an example has an empty prompt or completion.

◆ CombinedFitness()

float pulsatrix::CombinedFitness ( float  quality,
float  diversity,
float  gamma = 0.05f 
)
inline

Combined E-GAN fitness: Fq + gamma*Fd (Wang et al. 2019's own weighted combination). gamma's default (0.05) is this mission's own reasonable working value, not a literal reproduction of the paper's own tuned constant (never stated precisely enough there to reproduce exactly) – a deliberate, documented choice, not an assumed one.

◆ CombineGaussians()

GaussianMixturePrediction pulsatrix::CombineGaussians ( const std::vector< std::vector< double > > &  means,
const std::vector< std::vector< double > > &  variances = {} 
)

Mixes M Gaussian predictions per input into one, as Lakshminarayanan et al. do: the mixture's mean is the mean of the means, and its variance the mean of (variance + mean^2) minus the mixture mean squared.

Parameters
meansmeans[m][i]: member m's mean for input i.
variancesThe same shape, or empty for members that predict only a mean (Monte Carlo dropout of a plain regressor); the aleatoric part is then 0.
Exceptions
std::invalid_argumentif there are fewer than 2 members, the members have different lengths or none, a value isn't finite, or a variance is negative.

◆ CommitmentDeletionCheck()

CommitmentDeletionCurve pulsatrix::CommitmentDeletionCheck ( const DenoiserFn &  model,
const MaskedDiffusionResult &  trajectory,
const MaskedDiffusionConfig &  config,
const std::vector< CommitmentTarget > &  targets,
const std::vector< float > &  prompt_relevance,
int64_t  steps = 10,
int64_t  random_orders = 3,
uint64_t  seed = 0 
)

Deletes prompt tokens (replaces them with the mask token) in order of how much they support the value (prompt_relevance of the value's sign, largest first), replays the trajectory each time (ReplayCommitmentValue), and records the value, beside random_orders random orders.

Note
Cost: (steps + 1) * (1 + random_orders) replays.
Exceptions
std::invalid_argumentif prompt_relevance doesn't have one value per position, the input has no prompt, steps < 1 or random_orders < 1.

◆ CommitmentPatchCheck()

CommitmentPatchResult pulsatrix::CommitmentPatchCheck ( const DenoiserFn &  model,
const MaskedDiffusionResult &  trajectory,
const MaskedDiffusionConfig &  config,
const std::vector< CommitmentTarget > &  targets,
const CommitmentRelevance &  graph 
)

Leaves each committed intermediate token masked in turn, replays the trajectory, and compares the change in the value with the relevance graph relayed through that token.

Parameters
graphExplainCommitments' result for the same targets, in CommitmentMode::Graph.
Note
Cost: one replay per patched position, plus one.
Exceptions
std::invalid_argumentif graph isn't a Graph result for this trajectory, or as ReplayCommitmentValue.

◆ CompareBenchmarks()

std::vector< BenchmarkComparison > pulsatrix::CompareBenchmarks ( const std::vector< BenchmarkReport > &  baseline_runs,
const std::vector< BenchmarkReport > &  candidate_runs,
const CompareOptions &  options = {} 
)

Compares a candidate build with a baseline, record by record (matched on name and device). Several reports per side are the rounds of an interleaved A/B run; each side's value is the median over its rounds, so one noisy round doesn't decide, and with three or more rounds per side a time regresses only if its rounds also separate (CompareOptions::significance).

Note
A metric that is NaN or infinite in the candidate but finite in the baseline is a regression. A record missing from either side is reported, not a regression.
Exceptions
std::invalid_argumentif either side has no reports, a tolerance is negative, or the significance is outside (0, 1].

◆ CompareExplanations()

AgreementReport pulsatrix::CompareExplanations ( const std::vector< Attribution > &  teacher,
const std::vector< Attribution > &  student,
const AgreementOptions &  options = {} 
)

Compares two models' attributions of the same inputs, in the same order.

Exceptions
std::invalid_argumentif the lists are empty or of different lengths, an attribution's size differs from the first's, there are fewer than 2 features, top_fraction isn't in (0, 1], or permutations is negative.

◆ CompareLogits()

GoldenSequenceResult pulsatrix::CompareLogits ( const std::vector< float > &  got,
const std::vector< float > &  expected,
int64_t  num_tokens,
int64_t  vocab 
)

Compares one sequence's logits, both (L, vocab) row-major.

Note
Each position's differences are divided by max(1, max |reference logit| there), so the threshold is absolute for logits up to 1 and relative above. fp32 sums drift with the size of what they add up, and Qwen2.5's logits reach about 24 (1.1e-3 absolute on CPU, 5e-5 relative), while a layout bug moves logits by about their own size.
Exceptions
std::invalid_argumentif the sizes don't match L * vocab.

◆ CompareRdms()

double pulsatrix::CompareRdms ( const Rdm &  a,
const Rdm &  b,
RdmComparison  comparison = RdmComparison::Spearman 
)

The correlation between two RDMs of the same inputs, in the same order.

Returns
Between -1 and 1; NaN if either RDM is constant.
Exceptions
std::invalid_argumentif either describes fewer than 3 inputs, holds the wrong number of values or a NaN or infinite one, or the two describe different numbers of inputs.

◆ CompareRepresentations()

RepresentationComparison pulsatrix::CompareRepresentations ( const Tensor &  a,
const Tensor &  b,
const RepresentationComparisonOptions &  options = {} 
)

CKA, mutual-kNN alignment and RTD of the same two representations, for a report: they disagree informatively, as when CKA is high but RTD isn't 0 because one layer splits a cluster the other keeps whole.

Exceptions
std::invalid_argumentas the three measures do.

◆ CompareResidueSignals()

ResidueAgreement pulsatrix::CompareResidueSignals ( const std::vector< float > &  relevance,
const std::vector< float > &  signal,
double  top_fraction = 0.1 
)

Compares |relevance| with signal over the residues where both are finite; top_fraction picks k (at least 1).

Exceptions
std::invalid_argumentif the lengths differ, fewer than 3 residues compare, or top_fraction isn't in (0, 1].

◆ CompareToAttnLrp()

AttnLrpReport pulsatrix::CompareToAttnLrp ( CausalLM &  model,
const SafetensorsFile &  reference,
const LRPRuleConfig &  config = LxtAttnLrpConfig(),
float  threshold = 0.99f 
)

Explains each ids.<k> sequence of an AttnLRP reference file (as written by tools/golden/make_attnlrp_reference.py) from the logit of target.<k> at the last position, seeded with that logit as LXT's examples do, and compares the input relevance and every layer's K/V-head relevance with the reference's.

Parameters
thresholdThe roadmap's criterion: correlation above 0.99.
Exceptions
std::invalid_argumentif the file holds no sequences or its tensors don't fit the model.

◆ CompareToBaseline()

ProbeGain pulsatrix::CompareToBaseline ( const std::vector< float > &  features,
int64_t  dim,
const std::vector< float > &  baseline,
int64_t  baseline_dim,
const std::vector< int > &  labels,
int  classes,
const std::vector< bool > &  train,
const std::vector< bool > &  test,
DeviceBackend *  backend,
const ProbeOptions &  options = {} 
)

Trains the same probe on features and on baseline, rows matched, and reports how much better the representation does. A gain near zero means the probe reads nothing from the representation that the baseline (local sequence, a random model's layer, the raw input) doesn't already hold.

Exceptions
std::invalid_argumentif baseline doesn't have the same rows as features, or for what TrainLinearProbe() rejects.

◆ CompareToGolden()

GoldenReport pulsatrix::CompareToGolden ( CausalLM &  model,
const SafetensorsFile &  golden,
float  threshold = 1e-3f 
)

Runs model on every ids.<k> sequence of a golden file (as written by tools/golden/make_golden.py) and compares all its logits with logits.<k> (CompareLogits).

Parameters
thresholdThe roadmap's criterion: fp32, every logit within 1e-3 of the reference, relative to the position's largest logit when that exceeds 1.
Exceptions
std::invalid_argumentif the file holds no sequences, a sequence's ids aren't I64 or don't fit the vocabulary, or its logits' shape doesn't match.

◆ CompareToTokenizerReference()

TokenizerParityReport pulsatrix::CompareToTokenizerReference ( const TextTokenizer &  tokenizer,
const std::string &  path,
size_t  max_examples = 5 
)

Encodes and decodes every line of a reference file (JSON lines with text, ids, plain_ids, offsets in characters, decoded, decoded_skip, and normalized: whether the normalizer changed the line) and counts the lines that differ. A line round-trips exactly when the normalizer leaves it alone and decoding its plain ids gives it back; offsets are compared exactly on those lines.

Parameters
max_examplesHow many mismatches to keep in the report.
Exceptions
std::runtime_errorif the file can't be read; std::invalid_argument if a line is malformed.

◆ CompatibilityDistance()

double pulsatrix::CompatibilityDistance ( const NEATGenome &  a,
const NEATGenome &  b,
double  c1,
double  c2,
double  c3 
)
inline

Compatibility distance: delta = c1*E/N + c2*D/N + c3*W_bar, where E is the count of excess genes (innovation numbers beyond the other genome's own highest), D is the count of disjoint genes (innovation numbers within the overlapping range but present in only one genome), N is the larger genome's gene count (or 1 if both genomes have fewer than 20 connection genes – the original paper's own small-genome exception), and W_bar is the average weight difference over genes with matching innovation numbers (present in both genomes, regardless of enabled/disabled status).

Exceptions
std::invalid_argumentif either genome has zero connection genes.

◆ CompletionLogProbs()

std::vector< double > pulsatrix::CompletionLogProbs ( CausalLM &  model,
const std::vector< PromptCompletion > &  examples,
DeviceBackend *  backend,
int64_t  batch_size = 8 
)

log P(completion | prompt) under the model, summed over the completion's tokens, in double. Runs forward passes only, batch_size examples at a time, grouped by length.

Exceptions
std::invalid_argumentas CollatePromptCompletions(), or if batch_size < 1.

◆ Complexity()

float pulsatrix::Complexity ( const Attribution &  attribution)

Entropy of the fractional contributions |a_i| / sum |a| (Bhatt et al. 2020; Quantus Complexity), natural log: 0 when one feature holds all relevance, ln n when spread evenly.

Returns
0 for an all-zero attribution.

◆ ComputeAdjustedFitness()

std::vector< double > pulsatrix::ComputeAdjustedFitness ( const std::vector< double > &  raw_fitness,
const std::vector< std::vector< size_t > > &  species 
)
inline

Fitness sharing: each individual's adjusted fitness is its own raw fitness divided by the size of its species – protects small, structurally novel species from being immediately out-competed by a large, already-optimized one.

Exceptions
std::invalid_argumentif raw_fitness's size doesn't match the total number of individuals named across every species (i.e. every population index must appear in exactly one species).

◆ ComputeAle()

AleResult pulsatrix::ComputeAle ( const std::function< Tensor(const Tensor &)> &  predict,
const std::vector< Tensor > &  instances,
int64_t  feature_index,
int64_t  target_index,
int64_t  num_bins = 20 
)

Computes first-order ALE the way PyALE 1.2 (and R's ALEPlot) does: edges at the feature's type-1 quantiles (num_bins + 1 of them, duplicates dropped), bins closed on the right with the first also holding the minimum, and centering by the count-weighted mean of each bin's midpoint effect.

Parameters
num_binsRequested number of bins, >= 1; ties in the feature can merge bins.
Note
2 * instances.size() model calls. An empty bin contributes no effect.
Exceptions
std::invalid_argumentfor the same inputs ComputeIce rejects, num_bins < 1, or a feature that takes only one value.

◆ ComputeAttributionStability()

StabilityResult pulsatrix::ComputeAttributionStability ( const std::vector< Attribution > &  repeated_runs)

Measures an explainer's stability across repeated runs on the same input (charter's "repeated-run variance measured and documented" audit category). Known-unstable methods (LIME, KernelSHAP) are expected to show is_deterministic == false; every other native/surrogate explainer in this codebase is deterministic by construction.

Parameters
repeated_runsTwo or more Attribution results from independent calls to the same explainer on the same input (varying only, e.g., a stochastic method's seed).
Exceptions
std::invalid_argumentif repeated_runs is empty, or if the runs' Attribution values do not all share the same element count – external boundary: the caller assembles this list from independent explainer invocations, not an internal invariant.

◆ ComputeConservation()

ConservationResult pulsatrix::ComputeConservation ( const Tensor &  relevance_in,
const Tensor &  relevance_out 
)

Sums relevance_in and relevance_out independently and reports their gap.

Parameters
relevance_inA module's propagate_relevance() input-side relevance tensor.
relevance_outThe same call's output-side relevance tensor.
Note
Deliberately does not call Module::propagate_relevance itself – the caller has already produced both tensors (from whichever module/config it used); this function is a pure summation over already-computed results, reusable regardless of which module type or LRP rule produced them.

◆ ComputeDoubleDQNTarget()

Tensor pulsatrix::ComputeDoubleDQNTarget ( const Tensor &  next_q_online,
const Tensor &  next_q_target,
const Tensor &  rewards,
const Tensor &  dones,
float  gamma,
DeviceBackend *  backend 
)

Double DQN Bellman target (van Hasselt et al. 2016, arXiv:1509.06461): a* = argmax_a next_q_online[b,a], then targets[b,0] = rewards[b,0] + gamma * (1 - dones[b,0]) * next_q_target[b, a*].

Vanilla DQN both selects and evaluates the next action with the same network, so any positive noise in a Q-estimate is systematically picked up by the max and propagated into the target – the well-documented overestimation bias. Double DQN decouples the two: the online network says which action looks best, the target network says what it is worth. The two only agree when the networks agree, and the divergence when they disagree is exactly the property this function exists for (and is directly tested against ComputeDQNTarget).

Parameters
next_q_onlineThe online network's Q-values for the next state, shape (N, action_dim) – used for action selection only.
next_q_targetThe target network's Q-values for the next state, same shape – used for evaluation only.
rewardsImmediate rewards, shape (N, 1).
donesEpisode-termination flags as 0.0f/1.0f floats, shape (N, 1).
gammaDiscount factor, in [0, 1].
backendBackend to allocate the result through. Not owned; must outlive the result.
Returns
The Bellman targets, shape (N, 1).
Exceptions
std::invalid_argumenton the same conditions as ComputeDQNTarget, plus if next_q_online and next_q_target have different shapes – external boundaries.
Note
Ties in next_q_online resolve to the lowest index, matching ComputeDQNTarget's own max scan and DQNAgent's argmax, so the three are consistent by construction.
A free function rather than a class or an enum-flagged variant of ComputeDQNTarget: it is a pure computation with no state to carry, and the extra next_q_online argument – not a mode flag – is the whole difference. Mission 1's training loop picks which of the two to call; nothing downstream needs to branch.

◆ ComputeDQNTarget()

Tensor pulsatrix::ComputeDQNTarget ( const Tensor &  next_q_target,
const Tensor &  rewards,
const Tensor &  dones,
float  gamma,
DeviceBackend *  backend 
)

Vanilla DQN Bellman target (Mnih et al. 2015): targets[b,0] = rewards[b,0] + gamma * (1 - dones[b,0]) * max_a next_q_target[b,a].

Parameters
next_q_targetThe target network's Q-values for the next state, shape (N, action_dim). Both the action selection (the max) and its evaluation come from this one tensor – which is precisely the coupling Double DQN breaks.
rewardsImmediate rewards, shape (N, 1).
donesEpisode-termination flags as 0.0f/1.0f floats, shape (N, 1) – ReplayBatch's own encoding, so a sampled batch feeds straight in.
gammaDiscount factor, in [0, 1].
backendBackend to allocate the result through. Not owned; must outlive the result. Passed explicitly because Tensor exposes no accessor for the backend it was built against, and this codebase's convention is an injected, non-owned DeviceBackend* rather than a global default.
Returns
The Bellman targets, shape (N, 1) – ready to hand straight to DQNLoss::forward().
Exceptions
std::invalid_argumentif next_q_target is not rank-2 with N >= 1 and action_dim >= 1, if rewards/dones are not (N, 1) for that same N, or if gamma is outside [0, 1] – all external boundaries.
Note
A dones[b,0] == 1 row zeroes the bootstrapped term exactly: a terminal state has no successor whose value could be backed up, so its target is the reward alone. This is a hard cut, not a heavy discount, and is tested as an exact equality.
dones is used as a plain multiplier, not thresholded – 0.0f/1.0f is the documented encoding, and silently reinterpreting anything else would hide a caller's bug.
Device-generic (GPU-native-kernels Mission 7): one DeviceBackend::rl_rows(DqnTarget) lane per transition (row argmax, ties to the lowest index) through backend, which must address the inputs' device; the result is allocated through it too.

◆ ComputeGAE()

GAEResult pulsatrix::ComputeGAE ( const Tensor &  rewards,
const Tensor &  dones,
const Tensor &  values,
float  bootstrap_value,
float  gamma,
float  lambda,
DeviceBackend *  backend 
)

Generalized Advantage Estimation (Schulman et al. 2016, arXiv:1506.02438): the exponentially-weighted average of k-step advantage estimators, computed in one reverse pass.

Per step:

  • delta[t] = rewards[t] + gamma * (1 - dones[t]) * V_next[t] - values[t], where V_next[t] = values[t+1] for t < N-1 and V_next[N-1] = bootstrap_value.
  • advantages[t] = delta[t] + gamma * lambda * (1 - dones[t]) * advantages[t+1], with advantages[N] := 0 (nothing exists past the end of the rollout).
  • returns[t] = advantages[t] + values[t].

lambda interpolates between the two ends of the bias/variance trade-off: lambda == 0 collapses the recursion to advantages[t] == delta[t], the single-step TD residual (low variance, biased by whatever the critic gets wrong); lambda == 1 accumulates every discounted residual to the end of the episode, which telescopes to the Monte-Carlo advantage sum gamma^k r - V(s_t) (unbiased, high variance). Both ends are directly tested.

Parameters
rewardsImmediate rewards, shape (N, 1).
donesEpisode-termination flags as 0.0f/1.0f floats, shape (N, 1) – the same encoding ReplayBatch and ComputeDQNTarget use.
valuesThe critic's value estimate V(s_t) for each stored step, shape (N, 1).
bootstrap_valueV of the state immediately following the last stored step. Supplied by the caller as a plain scalar rather than read from the buffer: RolloutBuffer stores no next_observation (unlike ReplayBuffer), and the training loop already holds that observation from its own most recent env.step(). Ignored in effect when the last step is terminal, since (1 - dones[N-1]) zeroes it exactly. Conventionally 0.0f when the rollout ends on a terminal step.
gammaDiscount factor, in [0, 1].
lambdaGAE trace-decay parameter, in [0, 1].
backendBackend to allocate the results through. Not owned; must outlive them. Passed explicitly for ComputeDQNTarget()'s reason: Tensor exposes no accessor for the backend it was built against, and this codebase injects a non-owned DeviceBackend* rather than consulting a global default.
Returns
The advantages and the critic's targets, both (N, 1).
Exceptions
std::invalid_argumentif rewards is not rank-2 (N, 1) with N >= 1, if dones or values is not (N, 1) for that same N, or if gamma or lambda is outside [0, 1] – all external boundaries.
Note
returns is advantages + values, not the raw discounted return-to-go RolloutBuffer::compute_returns() computes, and this function never calls that method: it consumes raw rewards/dones directly. The GAE identity is the whole point – regressing the critic onto A_t + V(s_t) keeps the critic's target consistent with the very advantage the actor is being updated with, at the same lambda. Feeding compute_returns()'s Monte-Carlo return instead would silently train the critic against a lambda == 1 target while the actor used a different one.
A dones[t] == 1 row cuts both the bootstrap and the trace recursion exactly – an advantage must not propagate backwards across a terminal state, the same hard cut (not heavy discount) RolloutBuffer::compute_returns()'s reset-at-done performs. The recurrence shape is that reverse pass's; the recurrence itself is different.
dones is used as a plain multiplier, not thresholded – 0.0f/1.0f is the documented encoding, and silently reinterpreting anything else would hide a caller's bug. Same convention as ComputeDQNTarget().
A free function rather than a class: a pure reduction with no state to carry, matching ComputeDQNTarget()/ComputeDoubleDQNTarget()'s own free-function precedent.
Host boundary (GPU-native-kernels Mission 7): a strictly sequential reverse recursion over one rollout. The inputs may live on any device – one device->host copy of each of rewards, dones and values per call – and both results are uploaded through backend.

◆ ComputeH0()

H0Result pulsatrix::ComputeH0 ( const DistanceMatrix &  distances)

H0 persistence of the Vietoris-Rips filtration on the given distances.

Note
Prim's algorithm over the dense matrix: O(n^2) reads, the same order as reading the distances once, and far cheaper than computing them (O(n^2 d)). Equal lengths are broken by the lower point index, so the result is the same on every platform.
Exceptions
std::invalid_argumentif distances has fewer than 2 points.

◆ ComputeHeatmapColorScale()

HeatmapColorScale pulsatrix::ComputeHeatmapColorScale ( const HeatmapGrid &  grid)

Chooses a heatmap's color scale from its values (hc_information_visualization.md SS4: sequential maps for unsigned magnitude, diverging maps centred on the meaningful midpoint – zero – for signed quantities).

Returns
For an all-non-negative grid, [0, max] with is_signed == false. For a grid with any negative value, the symmetric range [-max|v|, +max|v|] with is_signed == true, so zero always lands on the diverging map's neutral midpoint and equal magnitudes of opposite sign get equal color intensity. A degenerate all-zero (or empty) grid returns [0, 1] rather than a zero-width range.

◆ ComputeHyperbandBrackets()

std::vector< HyperbandBracket > pulsatrix::ComputeHyperbandBrackets ( int  max_resource,
double  eta 
)
inline

Computes the classic Hyperband bracket schedule: s_max = floor(log_eta(max_resource)), B = (s_max + 1) * max_resource; for s from s_max down to 0, num_configs = ceil((B / max_resource) * (eta^s / (s + 1))), initial_budget = round(max_resource / eta^s) (each floored at 1).

Exceptions
std::invalid_argumentif max_resource <= 0 or eta <= 1.0.

◆ ComputeIce()

IceResult pulsatrix::ComputeIce ( const std::function< Tensor(const Tensor &)> &  predict,
const std::vector< Tensor > &  instances,
int64_t  feature_index,
int64_t  target_index,
const std::vector< float > &  grid 
)

Computes ICE curves for every instance.

Parameters
predictForward pass for one instance: input in, output out.
instancesThe instances to draw curves for, all the same shape. Their mean is the partial dependence over them.
feature_indexFlat index of the feature to vary.
target_indexFlat index of the output element to read.
gridValues to set the feature to (see FeatureGrid). Non-empty.
Note
Calls predict instances.size() * grid.size() times. Tensors are built beside each instance (same backend and device); only the target element is read back.
Exceptions
std::invalid_argumentif instances or grid is empty, the instances differ in shape, or an index is out of range.

◆ ComputeInfluence()

void pulsatrix::ComputeInfluence ( AttributionGraph &  graph,
const std::vector< double > &  scores 
)

Sets each node's influence the way circuit-tracer's pruning does: nodes other than embeddings and logits, by |score| largest first, get the cumulative fraction of the total |score| up to and including them. The viewer keeps nodes whose influence is at most its threshold, so a threshold of 0.8 keeps the fewest nodes holding 80% of the score.

Parameters
scoresOne per node, in node order; embedding and logit entries are ignored.
Exceptions
std::invalid_argumentif the sizes differ or a score isn't finite.

◆ ComputeLocalSensitivity()

LocalSensitivityResult pulsatrix::ComputeLocalSensitivity ( const std::function< Tensor(const Tensor &)> &  predict,
const Tensor &  input,
int64_t  target_index,
const SensitivityBounds &  bounds,
const std::vector< int64_t > &  features = {} 
)

Sets each feature in turn to its low and then its high bound, leaving the others at the input's values, and records the target output each time.

Parameters
featuresFlat feature indices to vary; empty means all of them.
Note
1 + 2 * features model calls. Unlike a gradient, which describes an infinitesimal neighborhood, this measures a finite one: the two disagree exactly where the model saturates or has a kink.
Exceptions
std::invalid_argumentif bounds don't have one entry per feature, a feature index or target index is out of range.

◆ ComputeMorris()

MorrisResult pulsatrix::ComputeMorris ( const std::function< Tensor(const Tensor &)> &  predict,
const GlobalSensitivityProblem &  problem,
int64_t  target_index,
const MorrisOptions &  options = {} 
)

Samples, runs the model and analyzes: MorrisSample, then AnalyzeMorris.

◆ ComputePartialDependence2D()

PartialDependence2D pulsatrix::ComputePartialDependence2D ( const std::function< Tensor(const Tensor &)> &  predict,
const std::vector< Tensor > &  background,
int64_t  feature_x,
int64_t  feature_y,
int64_t  target_index,
const std::vector< float > &  grid_x,
const std::vector< float > &  grid_y 
)

Two-feature partial dependence: for every pair (grid_x[c], grid_y[r]), the mean over the background of the prediction with both features set. Where it isn't the sum of the two one-feature curves, the features interact.

Exceptions
std::invalid_argumentfor the same inputs ComputeIce rejects, or feature_x == feature_y.

◆ ComputePersistenceImage()

PersistenceImage pulsatrix::ComputePersistenceImage ( const PersistenceDiagram &  diagram,
const PersistenceImageOptions &  options = {} 
)

The persistence image (Adams et al., JMLR 2017): each finite point (b, d) placed at (b, d - b), weighted by its persistence divided by persistence_max (so features near the diagonal count for little), and spread by a Gaussian; each pixel holds the integral over it, so a pixel's value doesn't depend on the resolution's sampling.

Exceptions
std::invalid_argumentif width or height is below 1, or the ranges are empty.

◆ ComputePersistenceLandscape()

Certified< PersistenceLandscape > pulsatrix::ComputePersistenceLandscape ( const PersistenceDiagram &  diagram,
const std::vector< double > &  grid,
int64_t  layers = 5 
)

The first layers persistence landscape functions (Bubenik, JMLR 2015) on a grid: lambda_k(t) is the k-th largest of max(0, min(t - b, d - t)) over the finite points.

Returns
Certified: the landscapes of the exact diagram are within bound() of these, in the sup norm, at every grid point, because landscapes are 1-Lipschitz in the bottleneck distance.
Exceptions
std::invalid_argumentif layers < 1 or a grid value is NaN.

◆ ComputeRipsPersistence()

RipsResult pulsatrix::ComputeRipsPersistence ( const DistanceMatrix &  distances,
const RipsOptions &  options = {} 
)

Persistent homology of the Vietoris-Rips filtration on the given distances, in dimensions 0 to options.max_dimension.

Note
Diagrams list finite pairs by death, then birth, then essential ones, as PersistenceDiagram does; pairs with zero persistence are left out. The diagrams don't depend on how equal distances are ordered; critical edges and cocycles do, and are the same on every platform.
Exceptions
std::invalid_argumentif distances has fewer than 2 points, max_dimension is outside [0, 8], coefficient isn't a prime below 2^15, or the simplices of dimension max_dimension + 1 can't be indexed in 63 bits.

◆ ComputeSobol()

SobolResult pulsatrix::ComputeSobol ( const std::function< Tensor(const Tensor &)> &  predict,
const GlobalSensitivityProblem &  problem,
int64_t  target_index,
const SobolOptions &  options = {} 
)

Samples two independent uniform matrices A and B over the problem's ranges, builds the Saltelli design (AB_j is A with column j from B), runs the model on every row and calls AnalyzeSobol.

Note
Sobol indices assume the varied features are independent.
Exceptions
std::invalid_argumentfor an invalid problem or options, or a target out of range.

◆ ComputeTruncationGroups()

PBTTruncationGroups pulsatrix::ComputeTruncationGroups ( const std::vector< double > &  metrics,
double  truncation_fraction 
)
inline

Pure core: identifies the bottom and top truncation_fraction of the population by metric (higher is better). Ties are broken by a stable sort on descending metric, so the earlier index among equal values sorts toward "top." At least one individual is always selected on each end, even if floor(size*fraction) would be 0.

Exceptions
std::invalid_argumentif metrics has fewer than 2 entries, or truncation_fraction is not in (0, 0.5].

◆ ConceptCounts()

std::vector< std::pair< std::string, int64_t > > pulsatrix::ConceptCounts ( const std::vector< AnnotatedProtein > &  proteins)

Each feature type, with the residues it covers over proteins, most first.

◆ ConceptLabels()

std::vector< int > pulsatrix::ConceptLabels ( const AnnotatedProtein &  protein,
const std::string &  type 
)

1 for each residue a feature of type covers, 0 elsewhere. A disulfide bond marks only its two cysteines (UniProt gives them as start and end), not the stretch between.

◆ ConceptReferenceSamples()

std::vector< int64_t > pulsatrix::ConceptReferenceSamples ( const LRP &  lrp,
ExplainerContext &  ctx,
const Tensor &  candidates,
int64_t  target,
NodeId  layer,
int64_t  channel,
int64_t  k,
ReferenceMode  mode,
DeviceBackend *  backend 
)

The k inputs of candidates that show a channel best, best first: the reference samples by which CRP shows what a concept is.

Parameters
candidatesA batch of inputs, the model's input shape with a leading batch dimension.
targetThe class the relevance explains; unused for ReferenceMode::Activation.
Note
Ties keep the lower index first.
Exceptions
std::invalid_argumentif k is below 1, the channel is outside the layer, or for what LayerRelevance() rejects.

◆ ConceptualSensitivities()

std::vector< double > pulsatrix::ConceptualSensitivities ( const Tensor &  gradients,
const Cav &  cav 
)

Each input's directional derivative along the CAV: the row of gradients dotted with cav.direction.

Parameters
gradientsshape (n, ...): the gradient of the class logit with respect to the layer, a row per input.
Exceptions
std::invalid_argumentif the rows aren't the CAV's width.

◆ ConditionalHeatmaps()

std::vector< Attribution > pulsatrix::ConditionalHeatmaps ( const LRP &  lrp,
ExplainerContext &  ctx,
const Tensor &  input,
const LRPTarget &  target,
const std::vector< ConceptCondition > &  conditions,
DeviceBackend *  backend 
)

One input heatmap per condition: LRP from target with the relevance zeroed, at each masked layer, outside the mask's channels.

Returns
Attribution{"crp", the input's shape, metadata: condition (layer:c,c;...), relevance_in_sum}.
Exceptions
std::invalid_argumentif a condition is empty, masks a layer twice, names a layer outside [1, number of modules] or a channel outside the layer, or for what LRP::explain() rejects.

◆ ContactFeatures()

ContactMap pulsatrix::ContactFeatures ( const float *  attention,
int64_t  tokens 
)

One head's contact features from its attention map over <cls>, L residues and <eos> (tokens x tokens, row-major, tokens = L + 2): the residue block, made symmetric (A + Aᵀ), then corrected by the average product (APC): F - rowsum * colsum / total.

Returns
The L x L features, the input to ESM's regression.
Exceptions
std::invalid_argumentif tokens is under 3.

◆ ContactPrecision()

double pulsatrix::ContactPrecision ( const ContactMap &  predicted,
const ContactMap &  truth,
SeparationRange  range,
int64_t  top 
)

The fraction of the top highest-scoring pairs in range that are true contacts.

  • Only pairs i < j whose truth is known (not NaN) compete.
  • Ties keep the order (i, j), row by row.
  • With fewer than top such pairs, the missing ones count as wrong, as in ESM's compute_precisions.
    Returns
    NaN if top is 0.
    Exceptions
    std::invalid_argumentif the maps' sizes differ, or top is negative.

◆ ControlTaskLabels()

std::vector< int > pulsatrix::ControlTaskLabels ( const std::vector< int64_t > &  token_types,
const std::vector< int > &  labels,
int  classes,
uint64_t  seed 
)

Hewitt and Liang's control labels: each distinct value in token_types gets one label, drawn from the distribution of labels, and every row of that type carries it.

Parameters
token_typesOne id per row saying which token type (a word, an amino acid) the row is.
labelsThe real task's labels, one per row in [0, classes). Only their distribution is used.
seedThe same seed, types and labels give the same control labels. The types are visited in increasing order, so the order of the rows doesn't matter.
Exceptions
std::invalid_argumentif the sizes differ, there are no rows, classes < 2, or a label is outside [0, classes).

◆ CountTargetTokens()

int64_t pulsatrix::CountTargetTokens ( const Tensor &  targets,
int64_t  ignore_index = TokenCrossEntropyLoss::kIgnoreIndex 
)

Number of entries of targets that aren't ignore_index: the normalizer for one accumulation window when summed over its micro-batches' targets.

◆ CrossBarcode()

PersistenceDiagram pulsatrix::CrossBarcode ( const DistanceMatrix &  w,
const DistanceMatrix &  w_tilde,
int  dimension = 1 
)

The R-Cross-Barcode in one dimension: the Rips diagram of the 2n-vertex graph with distances, for points A_1..A_n and copies A'_1..A'_n (the paper's practical form, its Equation 1 with the extra vertex O folded in):

  • A_i to A_j: 0;
  • A'_i to A'_j: min(w_ij, w~_ij);
  • A_i to A'_j: w_ij if i < j, 0 if i == j, and never connected if i > j.
    Parameters
    w,w_tildeThe two representations' distances, for the same n points in the same order, used as given (Rtd() normalizes them first).
    dimensionThe homology dimension; RTD uses 1.
    Note
    By Theorem 2.1 of the paper, the barcode is empty when w == w~, and when w~ is all zeros the barcode in dimension k + 1 is the ordinary Rips barcode of w in dimension k.
    Exceptions
    std::invalid_argumentif the sizes differ, there are fewer than 2 points, or dimension is outside [1, 7].

◆ CrosscoderLatents()

std::vector< CrosscoderLatentStats > pulsatrix::CrosscoderLatents ( Crosscoder &  crosscoder,
int64_t  a = 0,
int64_t  b = 1 
)

Every latent's stats for sources a and b.

Exceptions
std::invalid_argumentfor a source out of range or a == b.

◆ CrowdingDistance()

std::vector< double > pulsatrix::CrowdingDistance ( const std::vector< Objectives > &  front_objectives)
inline

Crowding distance within a single front.

Parameters
front_objectivesObjective vectors for exactly the individuals in one front (any order); the returned distances are indexed identically (distances[i] corresponds to front_objectives[i]), not by any global population index.
Exceptions
std::invalid_argumentif the objective vectors are not all the same size.
Note
Fronts of size 1 or 2: every individual is a boundary individual for every objective by construction – assigned infinity directly, no neighbor-gap computation.
Uses a stable sort per objective so that individuals sharing an identical value for that objective break ties in a fixed, reproducible order rather than an implementation- or input-order-dependent one.
If a front is uniform in some objective (max == min across the whole front), that objective contributes nothing to any individual's distance in this front (skipped outright) rather than dividing by a zero range.

◆ DecodeGenotype()

Configuration pulsatrix::DecodeGenotype ( const SearchSpace &  space,
const std::vector< double > &  genotype 
)
inline

Decodes a unit-hypercube genotype into a Configuration using space's own declared bounds: Continuous linearly, LogUniform geometrically (both identical to gp_bo.hpp's UnitCubeToConfiguration); Integer by linear interpolation then rounding to the nearest integer (std::round – ties away from zero, portable); Categorical by linear interpolation into an index, floored, clamped to the last category (handles the gene == 1.0 boundary, which would otherwise floor to one-past-the-end).

Exceptions
std::invalid_argumentif genotype.size() != space.size(), or any gene is outside [0, 1].

◆ DecomposeUncertainty()

UncertaintyDecomposition pulsatrix::DecomposeUncertainty ( const std::vector< Tensor > &  samples)

Splits the uncertainty of a set of probability samples into its aleatoric and epistemic parts, input by input.

Parameters
samplesTwo or more (N, K) probability tensors of the same shape, such as McDropoutSamples() or EnsembleSamples() returns.
Exceptions
std::invalid_argumentif there are fewer than 2 samples, they aren't all (N, K) of the same shape with K >= 2, or a probability is negative or not finite.

◆ DefaultCollate()

Batch pulsatrix::DefaultCollate ( std::vector< Sample >  samples,
DeviceBackend *  backend 
)

Stacks a list of samples into one Batch, field-by-field, via Tensor::Stack – pulsatrix's default CollateFn (PyTorch's default_collate analogue).

Parameters
samplesNon-empty list of samples, each with the same field count.
backendBackend to allocate stacked field tensors through.
Returns
A Batch with one stacked Tensor per field position.
Exceptions
std::invalid_argumentif samples is empty or samples have differing field counts – external boundary: the list of samples is assembled by a DataLoader from independently constructed Dataset::get() results, not a compile-time-known invariant. Per-field shape/device mismatches are reported by Tensor::Stack.

◆ DefaultVizFontOptions()

VizFontOptions pulsatrix::DefaultVizFontOptions ( )

The font options a VizWindow uses when given none. With the environment variable PULSATRIX_VIZ_FONTS set to font paths (separated by ';', or ':' outside Windows), those fonts come first. Set to "none", only ImGui's default font is used.

◆ DeletionCheck()

ResidueDeletionCurve pulsatrix::DeletionCheck ( EncoderExplainer &  explainer,
std::string_view  sequence,
const EncoderTarget &  target,
const std::vector< float > &  relevance,
int64_t  steps = 20,
int64_t  random_orders = 5,
uint64_t  seed = 0 
)

Masks residues (<mask>) in order of how much they support the explained value (relevance of the value's own sign, largest first) and records the value, beside random_orders random orders. A faithful explanation moves the value toward zero faster than random. The explained residue itself is never masked twice: a masked target's residue stays masked throughout, and isn't counted.

Exceptions
std::invalid_argumentif relevance doesn't have one value per residue, steps < 1 or random_orders < 1.

◆ DeletionCurve()

PerturbationCurve pulsatrix::DeletionCurve ( const PredictFn &  predict,
const Tensor &  input,
const Attribution &  attribution,
const PerturbationOptions &  options = {} 
)

Deletion (MoRF): removes features from most to least relevant, imputing them, and records the target score. A faithful attribution makes the score drop fast: lower AUC is better.

Note
Features are the input's elements, ordered by attribution value (ties by index).
Exceptions
std::invalid_argumentif the attribution's shape differs from the input's, steps < 1, or target is outside the prediction.

◆ DeltaBounds()

SensitivityBounds pulsatrix::DeltaBounds ( const Tensor &  input,
float  delta 
)

x - delta and x + delta for every feature.

Exceptions
std::invalid_argumentif delta <= 0.

◆ DeriveCaveats()

std::vector< Caveat > pulsatrix::DeriveCaveats ( const Explanation &  explanation)

The caveats an explanation carries, from the report alone:

  • Blocking: a required check failed or didn't run, or the planner excluded the method;
  • Warning: a recommended check failed, or a known failure mode applies to these settings or this input (a constant fill on images, discrete input, few Integrated Gradients steps);
  • Note: a recommended check that didn't run, the method's own known limitations (a baseline, a rule choice, random sampling) and, for Justify, that an attribution shows what the model used, not whether it should have.

◆ DescribeAnchor()

std::string pulsatrix::DescribeAnchor ( const Anchor &  anchor,
const std::vector< std::string > &  feature_names = {} 
)

IF income > 0.71 AND debt <= -0.12 THEN class 1 (precision 0.97, coverage 0.21).

Parameters
feature_namesA name per feature; x[3] where missing.

◆ DescribeExplanation()

std::string pulsatrix::DescribeExplanation ( const Explanation &  explanation)

The explanation as plain text: the question, whether it supports the reason, the largest attributions, the checks and the caveats.

◆ DescribePlan()

std::string pulsatrix::DescribePlan ( const ExplanationPlan &  plan)

The plan as plain text, for a terminal or a log: the question, the explainers in order with their reasons, the checks, and the warnings.

◆ DescribeSliceError()

std::string pulsatrix::DescribeSliceError ( const SliceErrorReport &  report)

The slices as a plain-text table, worst first, with the test and whether any is worse.

◆ DescribeSurrogateTree()

std::string pulsatrix::DescribeSurrogateTree ( const SurrogateTree &  tree,
const std::vector< std::string > &  feature_names = {} 
)

The tree as nested if/else rules, one node per line: if income <= 41.5: ... class 1 (40 inputs, 95%).

Parameters
feature_namesA name per feature; x[3] where missing.

◆ deterministic()

bool pulsatrix::deterministic ( )

Whether deterministic mode is on.

◆ DiffAdapterRelevance()

RelevanceDiff pulsatrix::DiffAdapterRelevance ( Module &  model,
const Tensor &  input,
const DiffTarget &  target = {},
const LRPRuleConfig &  config = {} 
)

DiffRelevance() for a fine-tune held as adapters on model: the tuned run with its LoRA adapters, IA³ vectors and (for a CausalLM) interventions on, the base run with them off. They are back on afterwards, even if a call throws.

Exceptions
std::invalid_argumentif the model has no enabled adapters, or one is merged (its update is in the weights and can't be switched off).

◆ DifferenceOfMeans()

std::vector< float > pulsatrix::DifferenceOfMeans ( const std::vector< float > &  positive,
const std::vector< float > &  negative,
int64_t  d 
)

The difference of means: the mean of positive minus the mean of negative, both (N, d) row-major. The simple baseline that usually wins.

Exceptions
std::invalid_argumentfor empty sets or rows of different sizes.

◆ DiffRelevance()

RelevanceDiff pulsatrix::DiffRelevance ( Module &  base,
Module &  tuned,
const Tensor &  input,
const DiffTarget &  target = {},
const LRPRuleConfig &  config = {} 
)

Explains the same prediction in both models: forward() on input, then relevance seeded with each model's own score for the class, at the class only.

Exceptions
std::invalid_argumentif the models' outputs differ in shape, the output isn't (N, C) or (N, L, C), or a class or the position is out of range; as the models' own calls throw.

◆ DivergingColormap()

RgbColor pulsatrix::DivergingColormap ( float  signed_normalized_value)

Blue-White-Red diverging colormap for signed attribution (positive/negative contribution) – hue encodes direction only, never magnitude (hc_information_visualization.md SS1's Cleveland-McGill rule: color hue is categorical/directional, magnitude must be position or length).

Parameters
signed_normalized_valuePosition along the colormap, expected in [-1, 1]; values outside this range are clamped to the nearest end anchor.

◆ DiversityFitness()

float pulsatrix::DiversityFitness ( Module &  discriminator,
const Tensor &  fake,
DeviceBackend *  backend 
)
inline

E-GAN's own diversity fitness Fd = -log(||grad||): the negative log of the L2 norm of the discriminator's own parameter gradient from its fake-recognition loss term (BCEWithLogitsLoss(D(fake), 0)), evaluated on fake. A smaller discriminator gradient here means the discriminator is already close to a local optimum against these particular samples – the paper's own signal that this offspring is contributing mode coverage the discriminator can't easily exploit further (discourages mode collapse).

Note
This function's own backward() pass is a fitness-evaluation probe, not a real training step – its gradient accumulates into discriminator's own parameter-gradient buffers exactly like any other backward() call would, and the caller must zero_grad discriminator's optimizer immediately after calling this function, every time (the same gradient-contamination discipline BCEWithLogitsLoss's own
Warning
already establishes for the generator step).
Exceptions
std::invalid_argumentif discriminator has no parameters.

◆ DmsPositionSensitivity()

std::vector< float > pulsatrix::DmsPositionSensitivity ( const DmsVariants &  variants,
std::string_view  sequence,
int64_t  offset = 1 
)

Each residue's sensitivity in a deep mutational scan: minus the mean score of its single mutants (higher scores being fitter, as in ProteinGym), so residues that tolerate no change rank highest. NaN where no single mutant was measured. Multiple mutants are skipped.

Exceptions
std::invalid_argumentif a mutant doesn't parse or doesn't match sequence.

◆ Dominates()

bool pulsatrix::Dominates ( const Objectives &  a,
const Objectives &  b 
)
inline

Pareto dominance (maximization convention): a dominates b iff a[i] >= b[i] for every objective i, and a[i] > b[i] for at least one objective.

Exceptions
std::invalid_argumentif a.size() != b.size().

◆ EmbedResidues()

ResidueEmbeddings pulsatrix::EmbedResidues ( EncoderLM &  model,
const TextTokenizer &  tokenizer,
DeviceBackend *  backend,
const std::vector< std::string > &  sequences,
const std::vector< int64_t > &  layers,
int64_t  max_tokens = 1024 
)

Runs sequences through the model one at a time and keeps each residue's representation (not <cls> or <eos>) at layers: 0 is the embeddings, i the output of layer i, and num_layers() the final representation, after the final LayerNorm, as ESM embeddings are usually taken.

Exceptions
std::invalid_argumentfor a layer outside [0, num_layers()], or a sequence longer than max_tokens - 2 or holding a character the tokenizer doesn't know.

◆ EncodeSparse()

SparseCodes pulsatrix::EncodeSparse ( Featurizer &  featurizer,
const std::vector< float > &  rows,
DeviceBackend *  backend,
int64_t  batch = 4096 
)

featurizer's codes for every residue in rows (residues x input_dim), encoded in batches of batch and kept where above zero.

◆ EnsembleLogProbabilities()

Tensor pulsatrix::EnsembleLogProbabilities ( const std::vector< Tensor > &  logits,
DeviceBackend *  backend 
)

log((1/G) Σ_g softmax(logits_g)) row by row, (..., classes), on the first tensor's device.

Note
Computed on the host in double precision, with each softmax shifted by its row's maximum.
Exceptions
std::invalid_argumentif logits is empty, a rank is below 2, or the shapes or devices differ.

◆ EnsembleSamples()

std::vector< Tensor > pulsatrix::EnsembleSamples ( const std::vector< std::function< Tensor(const Tensor &)> > &  members,
const Tensor &  input 
)

A deep ensemble's samples: each member's output for input.

Parameters
membersEach runs one network, in eval mode, and returns probabilities. Train them from different seeds on the same data; Lakshminarayanan et al. used 5.
Exceptions
std::invalid_argumentif there are fewer than 2 members.

◆ EsmIgnoredTensors()

std::vector< std::string > pulsatrix::EsmIgnoredTensors ( const EncoderLMConfig &  config)

Checkpoint tensors an ESM-2 EncoderLM doesn't use: the absolute-position table and ids (unused with rotary), each layer's rotary inv_freq (read separately), and the contact head (LoadEsmContactHead reads it).

◆ EsmMapping()

std::vector< WeightMapping > pulsatrix::EsmMapping ( const EncoderLMConfig &  config)

The name mapping from an EsmForMaskedLM checkpoint to EncoderLM. Q/K/V, output, MLP and LM-head dense weights are transposed.

◆ ESStep()

template<typename FitnessFn , typename RNG >
std::vector< double > pulsatrix::ESStep ( const std::vector< double > &  theta,
FitnessFn  fitness_fn,
int  population_size,
double  sigma,
double  alpha,
RNG &  rng 
)

RNG-driven wrapper: samples population_size/2 standard-normal perturbation vectors, scores theta+sigma*epsilon and theta-sigma*epsilon for each (mirrored sampling), and returns the updated theta via ESUpdateGivenPerturbations.

Exceptions
std::invalid_argumentif population_size is not a positive even number, or sigma is not positive.

◆ ESUpdateGivenPerturbations()

std::vector< double > pulsatrix::ESUpdateGivenPerturbations ( const std::vector< double > &  theta,
const std::vector< std::vector< double > > &  epsilons,
const std::vector< double > &  fitnesses,
double  alpha,
double  sigma 
)
inline

Pure core: the exact ES parameter update given already-sampled perturbations and their fitness scores – ‘theta’ = theta + (alpha / (N*sigma)) * sum_i(F_i * epsilon_i)`.

Exceptions
std::invalid_argumentif epsilons is empty, epsilons.size() != fitnesses.size(), any epsilon's dimension doesn't match theta's, or sigma is not positive.

◆ EvaluateAssay()

AssayResult pulsatrix::EvaluateAssay ( VariantScorer &  scorer,
const ProteinGymAssay &  assay,
const DmsVariants &  variants,
VariantStrategy  strategy = VariantStrategy::MaskedMarginals 
)

Scores every variant of assay and evaluates them against the measurements.

Exceptions
std::invalid_argumentif a variant doesn't match the assay's sequence.

◆ EvaluateClassifier()

ClassificationReport pulsatrix::EvaluateClassifier ( const Tensor &  probabilities,
const std::vector< int64_t > &  labels,
const ClassificationOptions &  options = {} 
)

Scores a classifier's probabilities against the labels.

Parameters
probabilities(N, K): each row the model's probabilities for one input, such as a softmax. Rows aren't renormalized; the predicted class is the most probable one, the lowest index on a tie.
labelsThe true class of each input, in [0, K).
Exceptions
std::invalid_argumentif probabilities isn't (N, K) with N >= 1 and K >= 2, labels has another length or a class outside [0, K), a probability is negative or not finite, or options.bins < 1.

◆ EvaluateContacts()

ContactEvaluation pulsatrix::EvaluateContacts ( const ContactMap &  predicted,
const ContactMap &  truth 
)

◆ EvaluateCoverage() [1/2]

CoverageReport pulsatrix::EvaluateCoverage ( const std::vector< PredictionInterval > &  intervals,
const std::vector< double > &  targets 
)
Exceptions
std::invalid_argumentif there are no intervals or targets has another length.

◆ EvaluateCoverage() [2/2]

CoverageReport pulsatrix::EvaluateCoverage ( const std::vector< std::vector< int64_t > > &  sets,
const std::vector< int64_t > &  labels 
)
Exceptions
std::invalid_argumentif there are no sets or labels has another length.

◆ EvaluateFitness()

FitnessMetrics pulsatrix::EvaluateFitness ( const std::vector< double > &  dms_scores,
const std::vector< int > &  dms_bins,
const std::vector< double > &  predicted 
)

FitnessMetrics for one assay: measured scores and their binarized labels, and predictions.

◆ EvaluateMaskedLM()

MaskedLMEvaluation pulsatrix::EvaluateMaskedLM ( EncoderLM &  model,
const TextTokenizer &  tokenizer,
DeviceBackend *  backend,
const std::vector< std::string > &  sequences,
int64_t  batch_size = 8,
uint64_t  seed = 0,
MaskedLMOptions  options = {} 
)

Masks sequences with a collator seeded by seed (so every model sees the same masks) and measures the loss over the picked tokens, in batches of batch_size. The model keeps no activations while it runs.

◆ EvaluateNEATPhenotype()

std::vector< double > pulsatrix::EvaluateNEATPhenotype ( const NEATGenome &  genome,
const std::vector< double > &  inputs 
)
inline

Evaluates genome's phenotype forward pass on inputs (one value per Input node, ordered by ascending node ID; the Bias node, if present, is always implicitly 1.0 and is not part of inputs).

Returns
One value per Output node, ordered by ascending node ID.
Exceptions
std::invalid_argumentif inputs.size() doesn't match the genome's own number of Input nodes.
Note
Recursive, memoized evaluation over the genome's connection graph – safe against infinite recursion only because every genome constructed via NEATGenome's own public API (AddConnection's cycle check) is guaranteed acyclic; this function trusts that invariant rather than re-checking it, the same "pure core trusts its caller" division of responsibility used throughout this campaign.

◆ EvaluatePopulation()

template<typename Genotype , typename FitnessT , typename FitnessFn >
void pulsatrix::EvaluatePopulation ( std::vector< Individual< Genotype, FitnessT > > &  population,
FitnessFn &  fitness_fn,
DataThreadPool *  thread_pool 
)

Evaluates (or re-evaluates) every individual's fitness in place via fitness_fn.

Parameters
thread_poolIf non-null, each individual's fitness is submitted as an independent task; if null, evaluation runs sequentially on the calling thread. fitness_fn must be safely callable concurrently from multiple threads when a thread_pool is supplied (an ordinary pure function of its genotype argument, per this project's explainer-layer functional-purity convention, satisfies this trivially).

◆ EvaluatePrediction()

ReconstructionMetrics pulsatrix::EvaluatePrediction ( Featurizer &  featurizer,
const Tensor &  x,
const Tensor &  target,
double  dense_rate = 0.1,
int64_t  batch = 4096 
)

EvaluateReconstruction for a transcoder: predict(x) against target, (N, output_dim). Explained variance is relative to the targets' variance.

Exceptions
std::invalid_argumentfor mismatched shapes.

◆ EvaluateReconstruction()

ReconstructionMetrics pulsatrix::EvaluateReconstruction ( Featurizer &  featurizer,
const Tensor &  x,
double  dense_rate = 0.1,
int64_t  batch = 4096 
)

Encodes and reconstructs x, (N, input_dim), in batches of batch rows.

Parameters
dense_rateA feature firing on more than this share of inputs counts as dense.
Exceptions
std::invalid_argumentfor a batch that isn't (N, input_dim) with N > 0, or batch < 1.

◆ EvaluateRegressor()

RegressionReport pulsatrix::EvaluateRegressor ( const std::vector< double > &  predictions,
const std::vector< double > &  targets 
)

Scores a regressor's predictions against the targets.

Exceptions
std::invalid_argumentif the two are empty, have different lengths or hold a value that isn't finite.

◆ EveryOtherLayer()

std::vector< int64_t > pulsatrix::EveryOtherLayer ( int64_t  num_layers)

Layers 0, 2, 4, ... of a num_layers model: one out of two, DistilBERT's choice.

◆ ExpectedImprovement()

double pulsatrix::ExpectedImprovement ( double  mean,
double  variance,
double  best_value,
double  xi = 0.01 
)
inline

Expected Improvement: the expected amount by which a candidate exceeds best_value + xi, under the posterior N(mean, variance).

Parameters
variancePosterior variance (not standard deviation) – must be non-negative.
xiSmall exploration margin (default 0.01, a common practical default – without it, EI can collapse to pure exploitation once the posterior mean exceeds best_value by even a negligible amount).
Exceptions
std::invalid_argumentif variance < 0.
Note
If sigma (sqrt(variance)) is ~0 (a point the GP is fully confident about, e.g. exactly an already-observed point), EI is defined as exactly 0 – no uncertainty means no potential for improvement beyond what standard credit already reflects.

◆ ExplainCommitments()

CommitmentRelevance pulsatrix::ExplainCommitments ( StepRelevanceModel &  model,
const MaskedDiffusionResult &  trajectory,
int64_t  mask_token_id,
const std::vector< CommitmentTarget > &  targets,
CommitmentMode  mode = CommitmentMode::Graph 
)

Explains targets on trajectory, which SampleMaskedDiffusion produced with model's logits. Each step's input is rerun, so the model must give the logits it gave then.

Inputs are classified by what the step saw: a mask token is a mask, a position no step had yet written is the prompt, and anything else was committed by the last step that wrote it before this one. That definition holds under a remasking sampler too: a revoked position is a mask until it is written again.

Note
Cost: one forward and one relevance pass per step that has something seeded.
Exceptions
std::invalid_argumentfor no targets, a position given twice or not written by the trajectory, a token outside the vocabulary, or logits or relevance of the wrong size.

◆ ExplainedVarianceBySource()

std::vector< double > pulsatrix::ExplainedVarianceBySource ( Crosscoder &  crosscoder,
const Tensor &  x,
int64_t  batch = 4096 
)

Each source's explained variance on x: 1 - Σ|x^s - x̂^s|² / Σ|x^s - mean(x^s)|².

◆ ExplainerCapabilitiesOf()

const ExplainerCapabilities & pulsatrix::ExplainerCapabilitiesOf ( std::string_view  name)

The catalog entry named name.

Exceptions
std::invalid_argumentif there is none.

◆ ExplainerCatalog()

const std::vector< ExplainerCapabilities > & pulsatrix::ExplainerCatalog ( )

Every explainer pulsatrix has, in a fixed order.

◆ ExplainerCatalogDocument()

JsonValue pulsatrix::ExplainerCatalogDocument ( )

The whole catalog: a pulsatrix.explainer_catalog.v1 document.

◆ ExplainersFor()

std::vector< const ExplainerCapabilities * > pulsatrix::ExplainersFor ( XaiQuestion  question)

The explainers that answer question: those that list it first, then the rest, each group in catalog order. Empty for a question pulsatrix has no explainer for yet.

◆ ExplainTrajectory()

TrajectoryRelevance pulsatrix::ExplainTrajectory ( ContinuousDenoiser &  model,
const ContinuousTrajectory &  trajectory,
const std::vector< float > &  seed,
const TrajectoryLrpConfig &  config = {} 
)

Explains seed, relevance on the trajectory's sample x_0 (RegionSeed, ReconstructionSeed, or a downstream classifier's input relevance), back through trajectory, which SampleContinuousDiffusion produced with model.

Note
Cost: one forward and one relevance pass per step. Memory: one step's activations.
Exceptions
std::invalid_argumentif the seed's size differs from the sample's, or a model output has the wrong size.
std::runtime_errorif a step, rerun from the stored state, doesn't reproduce the stored next state within config.recompute_tolerance (the model isn't the one that sampled, or isn't deterministic).

◆ ExplanationAgreement()

AgreementReport pulsatrix::ExplanationAgreement ( const std::vector< Tensor > &  inputs,
const ExplainFn &  teacher,
const ExplainFn &  student,
const AgreementOptions &  options = {} 
)

Explains every input with both explainers, then CompareExplanations().

◆ ExplanationSensitivity()

SensitivityReport pulsatrix::ExplanationSensitivity ( const Tensor &  input,
const ExplainFn &  explain,
const PredictFn &  predict,
const DifferentiableClassifier *  classifier,
DeviceBackend *  backend,
const SensitivityOptions &  options = {} 
)

Measures how much explain's explanation of input changes under small perturbations.

Parameters
inputOne input, (1, ...).
explainThe explainer; its attribution's values are compared as one flat vector.
predictThe model; the index of its largest output is the predicted class.
classifierThe model again as a DifferentiableClassifier, for the adversarial point; nullptr to skip it.
backendBackend to put the perturbed inputs on, on the input's device.
Exceptions
std::invalid_argumentif the input's first dimension isn't 1, radius isn't finite and positive, samples < 1, max_halvings < 0, or an explanation's size changes between calls.

◆ ExploreConfiguration()

template<typename RNG >
Configuration pulsatrix::ExploreConfiguration ( const Configuration &  config,
const SearchSpace &  space,
RNG &  rng 
)

RNG-driven wrapper: draws each non-categorical parameter's factor uniformly from {0.8, 1.2} (Jaderberg et al.'s own standard explore perturbation), then applies ExploreConfigurationGivenFactors.

◆ ExploreConfigurationGivenFactors()

Configuration pulsatrix::ExploreConfigurationGivenFactors ( const Configuration &  config,
const SearchSpace &  space,
const std::map< std::string, double > &  factors 
)
inline

Pure core: applies an explicit per-parameter multiplicative factor to every Continuous/LogUniform/Integer parameter in config, clamped to that parameter's own bounds – PBT's own "explore" step (Jaderberg et al.'s own simple perturbation: multiply by 0.8 or 1.2). Categorical parameters are left unchanged (explore, in its original form, perturbs numeric hyperparameters only – a deliberate, logged scope decision, not an oversight). Integer results are rounded to the nearest integer.

Exceptions
std::invalid_argumentif config is missing a value for any parameter in space, or factors is missing an entry for any non-categorical parameter in space.

◆ ExportEmbeddings()

void pulsatrix::ExportEmbeddings ( const std::string &  directory,
const Tensor &  x,
const std::vector< MetadataColumn > &  columns = {} 
)

Writes x for UMAP and t-SNE tools into directory, which must exist: vectors.npy, vectors.tsv, and metadata.tsv when there are columns.

Exceptions
std::invalid_argumentif a column doesn't have one value per row of x, or as ProjectorVectorsTsv() and ProjectorMetadataTsv() do; std::runtime_error if a file can't be written.

◆ ExtractRules() [1/2]

SoftTreeRules pulsatrix::ExtractRules ( const SoftDecisionTree &  tree,
const std::vector< std::string > &  class_names = {} 
)

The rules of a soft decision tree.

Exceptions
std::invalid_argumentif the class names' count is wrong or they aren't distinct.

◆ ExtractRules() [2/2]

TreeRules pulsatrix::ExtractRules ( const SurrogateTree &  tree,
const std::vector< std::string > &  feature_names = {},
const std::vector< std::string > &  class_names = {} 
)

The rules of a classification tree, one per leaf, in the tree's node order.

Parameters
feature_namesNames for the features, or empty for x0, x1, ...
class_namesNames for the classes, or empty for class0, class1, ...
Exceptions
std::invalid_argumentfor a regression tree, or names of the wrong count or that aren't distinct.

◆ FarthestPointLandmarks() [1/2]

Landmarks pulsatrix::FarthestPointLandmarks ( const PointCloud &  cloud,
DeviceBackend *  backend,
const LandmarkOptions &  options 
)

Landmarks of a cloud's points, computed on the given backend.

◆ FarthestPointLandmarks() [2/2]

Landmarks pulsatrix::FarthestPointLandmarks ( const Tensor &  points,
const LandmarkOptions &  options 
)

Picks farthest-point landmarks among the rows of points.

Parameters
pointsshape (n, ...): a row per point, dimensions after the first flattened; distances are computed on its backend.
Note
Ties go to the lowest index. Each step is one GEMM of the points against the new landmark and an O(n) update, so k landmarks cost O(n k d).
Exceptions
std::invalid_argumentif points has rank below 2, no rows, a NaN or infinity; if count and radius are both 0, either is negative, or first is out of range.

◆ FastNonDominatedSort()

std::vector< std::vector< size_t > > pulsatrix::FastNonDominatedSort ( const std::vector< Objectives > &  objectives)
inline

Fast non-dominated sort (Deb et al. 2002, Algorithm: fast-non-dominated-sort): partitions [0, objectives.size()) into fronts – front 0 is the non-dominated set, front 1 is non-dominated after removing front 0, and so on.

Exceptions
std::invalid_argument– propagated from Dominates if objective vectors have inconsistent sizes.

◆ FeatureAbsorption()

AbsorptionResult pulsatrix::FeatureAbsorption ( Featurizer &  featurizer,
const Tensor &  x,
const std::vector< int > &  labels,
const AbsorptionOptions &  options = {} 
)

Feature absorption (Chanin et al.; SAEBench's version, in outline). A concept is absorbed when the features that stand for it stay silent on an input that has it, because a more specific feature fires instead and carries its direction: a "starts with S" feature that skips "short", which a "short" feature covers.

  1. A logistic probe on the raw activations finds the concept's direction (and is the baseline).
  2. Features are ranked by their mean code on positives minus negatives; the main features are added, best first, while each raises F1 by min_f1_gain.
  3. On held-out positives the probe finds but no main feature fires on, the input is absorbed when firing features whose decoder directions align with the probe carry min_share of the input's projection onto it, measured from the mean of the negatives.
Parameters
x(N, input_dim).
labels0 or 1 per input.
Note
For autoencoders: the probe lives in the input space and the decoder directions must too, so a featurizer whose output_dim differs from its input_dim is refused. For a transcoder the spaces differ even when the sizes match; compare its features with MatchConcept-style F1 instead.
Exceptions
std::invalid_argumentfor a featurizer whose output_dim isn't its input_dim, mismatched sizes, labels other than 0 and 1, or a train or test split without both classes.

◆ FeatureGrid()

std::vector< float > pulsatrix::FeatureGrid ( const std::vector< Tensor > &  background,
int64_t  feature_index,
int64_t  grid_size = 100,
float  lower_percentile = 0.05f,
float  upper_percentile = 0.95f 
)

An evenly spaced grid for one feature, built the way scikit-learn's partial_dependence builds it: the feature's distinct values when there are fewer than grid_size of them, otherwise grid_size points from the lower to the upper percentile of the feature's values (scipy.stats.mstats.mquantiles with its default plotting positions).

Parameters
backgroundInstances to read the feature from; all the same shape.
feature_indexFlat index of the feature within an instance.
grid_sizeNumber of points, >= 2.
lower_percentile,upper_percentileIn [0, 1], lower < upper. Defaults are scikit-learn's.
Exceptions
std::invalid_argumentif background is empty, the feature index is out of range, the percentiles are invalid, grid_size < 2, or the two percentiles coincide (a feature that is nearly constant; pass a grid explicitly instead).

◆ FeatureImportance()

std::vector< double > pulsatrix::FeatureImportance ( const SurrogateTree &  tree)

Each feature's share of the tree's impurity decrease (scikit-learn's feature_importances_).

◆ FeaturizerDirection()

std::vector< float > pulsatrix::FeaturizerDirection ( Featurizer &  featurizer,
int64_t  feature 
)

Feature feature's decoder direction, as a steering direction (unit length for a featurizer with unit-norm decoders).

◆ Fgsm()

AttackResult pulsatrix::Fgsm ( const DifferentiableClassifier &  model,
const Tensor &  input,
const std::vector< int64_t > &  labels,
DeviceBackend *  backend,
const AttackOptions &  options = {},
bool  targeted = false 
)

The fast gradient sign method: one step of size epsilon (options.steps, step_size and random_start are ignored).

Parameters
input(N, ...): N inputs, any shape after the first dimension.
labelsThe true class of each input, or with targeted the class to push it to.
backendBackend to put the perturbed inputs on, on the input's device.
Exceptions
std::invalid_argumentif labels doesn't have N entries, a label is outside the logits' classes, the logits aren't (N, C) with C >= 2, epsilon isn't finite and positive, or clip_min >= clip_max.

◆ FindAnchor()

Anchor pulsatrix::FindAnchor ( const std::function< Tensor(const Tensor &)> &  predict,
const Tensor &  input,
const std::vector< Tensor > &  background,
const AnchorOptions &  options = {} 
)

Finds an anchor for the model's prediction on input.

Parameters
predictThe model as a function of one input (a leading batch dimension of 1); its class is the index of its largest output.
inputThe input to explain; every element is a feature.
backgroundInputs shaped like input, from the data the model sees: the bins, the samples and the coverage all come from them.
Exceptions
std::invalid_argumentif background is empty, its inputs aren't the input's size, percentiles aren't increasing within (0, 100), or an option is out of range.

◆ FindCounterfactual()

CounterfactualResult pulsatrix::FindCounterfactual ( ExplainerContext &  ctx,
const Tensor &  input,
const CounterfactualTarget &  target,
const CounterfactualConstraints &  constraints = {},
const CounterfactualOptions &  options = {} 
)

Finds a nearby input that reaches target (Wachter, Mittelstadt and Russell 2017): minimizes ‘lambda * loss(f(x’), target) + sum_j |x'_j - x_j| / scale_j` by proximal gradient descent, so features the prediction doesn't need stay exactly unchanged. If a round ends without reaching the target, lambda grows and the search continues from where it was.

The prediction loss is a hinge, zero once the target is reached: for a class, max(0, max_{k != t} z_k - z_t + margin) on the model's outputs (logits); for a range, the distance from the output to [low, high].

Parameters
ctxThe model, run through forward_pass and backward_pass. Parameter gradients accumulate in the model, as with Saliency.
inputOne instance with its batch dimension, for example (1, F); every element is a feature.
Note
Gradient-based, so the model must be differentiable in its input. On images and other high-dimensional inputs a counterfactual found this way is usually an adversarial example (Freiesleben 2022): a change the model reacts to, not one that means anything.
Exceptions
std::invalid_argumentif the target index is out of range, a constraint vector has the wrong length or an index out of range, or an option is invalid.

◆ FindDiverseCounterfactuals()

DiverseCounterfactualResult pulsatrix::FindDiverseCounterfactuals ( ExplainerContext &  ctx,
const Tensor &  input,
const CounterfactualTarget &  target,
const CounterfactualConstraints &  constraints = {},
const DiverseCounterfactualOptions &  options = {} 
)

Several counterfactuals found together so that they differ from each other (DiCE, Mothilal, Sharma and Tan 2020): one person may be able to raise their income, another to pay down debt, and a single counterfactual shows only one of those routes.

Gradient descent on, for each counterfactual, the hinge loss of FindCounterfactual plus proximity_weight times its scaled L1 distance to the input, minus diversity_weight times the log-determinant of the set's kernel K_ij = 1 / (1 + scaled L1 distance between i and j). Then each counterfactual's unneeded changes are undone, smallest first, while it still reaches the target (DiCE's post-hoc sparsity step), and integer and one-hot features are fixed up.

Note
DiCE uses det(K); log det(K) has the same maximizer and gradients that don't vanish as the set grows.
Exceptions
std::invalid_argumentfor the inputs FindCounterfactual rejects, or invalid options.

◆ FindFallbackFonts()

std::vector< VizFontFile > pulsatrix::FindFallbackFonts ( )

The system fonts that together cover as many scripts as this machine has fonts for, best first.

  • On Linux (with fontconfig), each of about forty sample characters, one per script plus symbols, math and emoji, is matched to the best installed font.
  • On Windows and macOS, the standard fonts that ship with the system are used.
  • Without fontconfig on Linux, common Noto, DejaVu and WenQuanYi files are looked for in the usual font directories.

Fonts ImGui can't draw at every size are left out: bitmap-only color emoji fonts (Noto Color Emoji, Apple Color Emoji) hold one fixed size. Vector color emoji fonts (Segoe UI Emoji on Windows, Twemoji) are drawn in color when ImGui uses FreeType.

◆ FindPertinentNegative()

ContrastiveResult pulsatrix::FindPertinentNegative ( ExplainerContext &  ctx,
const Tensor &  input,
const ContrastiveOptions &  options = {} 
)

The pertinent negative of input: what would have to be added, where the input has nothing, to change its class.

Parameters
ctxThe model, run through forward_pass and backward_pass; its class is the index of its largest output. Parameter gradients accumulate in it, as with Saliency.
inputOne input with its batch dimension.
Exceptions
std::invalid_argumentif baseline or upper has the wrong length, or an option is out of range.

◆ FindPertinentPositive()

ContrastiveResult pulsatrix::FindPertinentPositive ( ExplainerContext &  ctx,
const Tensor &  input,
const ContrastiveOptions &  options = {} 
)

The pertinent positive of input: the least of it that the model still gives its class.

Exceptions
std::invalid_argumentas FindPertinentNegative().

◆ FindPrototypes()

PrototypeResult pulsatrix::FindPrototypes ( const std::function< Tensor(const Tensor &)> &  predict,
const Tensor &  input,
const std::vector< Tensor > &  background,
const PrototypeOptions &  options = {} 
)

The background examples nearest input that the model classes the same way, and those it classes differently. Classes are the index of the model's largest output.

Note
An example identical to the input counts, at distance 0; leave the input out of the background to exclude it.
Exceptions
std::invalid_argumentif background is empty, its inputs aren't the input's size, k < 1, or scale has the wrong length or a value that isn't positive.

◆ fit_weighted_linear_regression()

std::vector< float > pulsatrix::fit_weighted_linear_regression ( const std::vector< std::vector< float > > &  samples,
const std::vector< float > &  targets,
const std::vector< float > &  weights,
float  l2_lambda 
)
inline

Fits w* = argmin_w sum_i weight_i*(target_i - w^T sample_i)^2 + l2_lambda*||w||^2 via the normal equations (X^T W X + l2_lambda*I) w = X^T W y.

Parameters
samplesEach row is one sample's feature vector; every row must be the same length.
targetsOne target value per sample. Must match samples.size().
weightsOne non-negative weight per sample. Must match samples.size().
l2_lambdaRidge regularization strength. 0 = ordinary weighted least squares.
Returns
Coefficients, one per feature (no intercept – callers that need one center their targets/samples around a reference point first, e.g. LIME's local-model convention).
Exceptions
std::runtime_errorif the normal-equations system is near-singular (e.g. degenerate/collinear samples).
std::invalid_argumentif samples is empty, or targets/weights/any sample row's length doesn't match – external boundary ( campaign_exai_dl_library_adversarial_hardening.md, Mission 2, finding 15 systemic sweep). Escalated from PULSATRIX_ASSERT-only for consistency with this function's own near-singular-system check above, which already throws.
Note
Gaussian elimination, scoped to the small, dense, well-conditioned systems this codebase's explainers actually produce – not a general-purpose numerics library.

◆ FitBinaryTemperature()

TemperatureFit pulsatrix::FitBinaryTemperature ( const std::vector< double > &  logits,
const std::vector< int64_t > &  labels,
const std::vector< double > &  weights = {} 
)

Fits T for binary log-odds: P(y = 1) = sigmoid(logit / T).

Parameters
weightsPer example, such as importance weights; all 1 when empty.
Exceptions
std::invalid_argumentif the inputs are empty or of different lengths, a label isn't 0 or 1, a logit isn't finite, or a weight is negative, not finite, or all are 0.

◆ FitDecisionTree()

SurrogateTree pulsatrix::FitDecisionTree ( const std::vector< std::vector< float > > &  x,
const std::vector< double > &  y,
SurrogateTask  task,
int64_t  num_classes,
const SurrogateTreeOptions &  options 
)

Fits CART to rows x and targets y: class indices for classification, values for regression. FitSurrogateTree() calls this on the model's predictions; it is public so the tree can be checked on its own.

Parameters
num_classesClassification: the number of classes; every y must be in [0, num_classes).
Exceptions
std::invalid_argumentif x is empty, rows differ in length or don't match y, a class is out of range, max_depth < 0 or min_samples_leaf < 1.

◆ FitPca()

Pca pulsatrix::FitPca ( const Tensor &  x,
int64_t  components,
bool  center = true 
)

Fits the components directions of most variance.

Parameters
xshape (n, ...): a row per input. Dimensions after the first are flattened.
centerSubtract the mean row first, as PCA does. Without it the first component tends to point at the mean, and the "variances" are mean squares.
Exceptions
std::invalid_argumentif x has rank below 2, fewer than 2 rows, or a NaN or infinity; if components is below 1 or above min(n, width); or if a requested component has no variance, so has no direction.

◆ FitSurrogateTree()

SurrogateTreeResult pulsatrix::FitSurrogateTree ( const std::function< Tensor(const Tensor &)> &  predict,
const std::vector< Tensor > &  instances,
const SurrogateTreeOptions &  options = {} 
)

Labels instances with the model, holds out options.test_fraction of them, fits a tree to the rest and measures its fidelity on both parts.

Parameters
predictThe model as a function of one instance (a leading batch dimension of 1).
instancesThe inputs to imitate the model on, each flattened to one row of features.
Exceptions
std::invalid_argumentif instances is empty, their sizes differ, test_fraction isn't in [0, 1), fewer than one input would be left to fit, or target is outside the output.

◆ FitTemperature()

TemperatureFit pulsatrix::FitTemperature ( const std::vector< std::vector< double > > &  logits,
const std::vector< int64_t > &  labels,
const std::vector< double > &  weights = {} 
)

Fits T for multi-class logits: P(y = k) = softmax(logits / T)_k.

Parameters
logitsOne row per example, every row the same length K >= 2.
Exceptions
std::invalid_argumentas FitBinaryTemperature(), or if a row has another length or a label is outside [0, K).

◆ FixedTopologyXORFitness()

double pulsatrix::FixedTopologyXORFitness ( const std::vector< double > &  theta)
inline

Scores theta against all four XOR patterns as 4.0 minus the sum of squared errors – identical convention to XORFitness (neat_xor_fitness.hpp), so an all-zero theta scores exactly 3.0 (every pattern outputs sigmoid(0)=0.5), the same fixed point NEAT's own fresh, all-zero-weight genome scores.

◆ FixedTopologyXORForward()

double pulsatrix::FixedTopologyXORForward ( const std::vector< double > &  theta,
const std::array< double, 2 > &  inputs 
)
inline

Forward pass: theta layout is [w1_00, w1_01, b1_0, w1_10, w1_11, b1_1, w2_0, w2_1, b2] – h_j = sigmoid(w1_j0*x0 + w1_j1*x1 + b1_j) for j in {0,1}, y = sigmoid(w2_0*h0 + w2_1*h1 + b2).

Exceptions
std::invalid_argumentif theta.size() != kFixedTopologyXORNumParams.

◆ FlattenParameters()

std::vector< float > pulsatrix::FlattenParameters ( Module &  module)
inline

Flattens every parameter tensor module.parameters() reports (in that order) into one vector – the concrete mechanism Phase 5 Mission 2's mutation-offspring construction uses to copy a parent generator's current weights into a freshly-constructed (architecturally identical) offspring instance before mutating the copy.

◆ format_iso8601_utc()

std::string pulsatrix::format_iso8601_utc ( std::chrono::system_clock::time_point  tp)

Formats tp as ISO-8601 UTC with milliseconds, e.g. "2026-10-02T12:34:56.789Z".

◆ FormatRule()

std::string pulsatrix::FormatRule ( const datalog::Rule &  rule)

A rule in Datalog's usual text: head(A, b) :- body1(A), body2(A, c).

◆ FromCircuitGraph()

AttributionGraph pulsatrix::FromCircuitGraph ( const CircuitGraphDocument &  doc,
const std::string &  slug,
const std::string &  scan 
)

A circuit graph (a chain of operations scored by ablation) for the viewer: two columns, "input" holding an embedding node and "network" holding each operation one layer up, with the last operation as the output. Influence comes from the ablation effects.

Note
Two columns, not one: the viewer hides features seen at more than 2/3 of the positions, which with a single position is every node.
Exceptions
std::invalid_argumentfor an empty graph or a non-finite effect or weight.

◆ GaussianBaseline()

Tensor pulsatrix::GaussianBaseline ( const Tensor &  points,
int64_t  count,
uint32_t  seed = 0 
)

count points from a Gaussian with the mean and sample covariance of the rows of points: mu + Z^T (X - mu) / sqrt(n - 1) with Z standard normal (one GEMM on points' backend), so no decomposition of the covariance is needed and its rank is kept.

Parameters
pointsshape (n, ...): a row per point, n >= 2.
Returns
shape (count, width), on points' backend.
Exceptions
std::invalid_argumentif points has rank below 2, fewer than 2 rows, a NaN or infinity, or count < 1.

◆ GaussianKdeDensity()

double pulsatrix::GaussianKdeDensity ( const std::vector< double > &  observations,
double  bandwidth,
double  x 
)
inline

Fixed-bandwidth Gaussian KDE: density(x) = mean over every observation o of N(x; o, bandwidth^2).

Exceptions
std::invalid_argumentif observations is empty or bandwidth <= 0.

◆ GaussianMutation()

template<typename RNG >
std::vector< double > pulsatrix::GaussianMutation ( const std::vector< double > &  genotype,
double  sigma,
double  mutation_probability,
RNG &  rng 
)

RNG-driven wrapper: each gene independently receives N(0, sigma^2) noise with probability mutation_probability.

Exceptions
std::invalid_argumentif sigma is negative or mutation_probability is outside [0, 1].
Note
mutation_probability == 0.0 leaves the genotype unchanged exactly (mask always false); sigma == 0.0 with mutation_probability == 1.0 also leaves it unchanged exactly (every draw from N(0, 0) is exactly 0.0) – two independent, RNG-stream- -independent correctness cases.

◆ GaussianMutationByNoise()

std::vector< double > pulsatrix::GaussianMutationByNoise ( const std::vector< double > &  genotype,
const std::vector< double > &  noise,
const std::vector< bool > &  apply_mask 
)
inline

Adds noise[i] to genotype[i] wherever apply_mask[i] is true, leaves the rest unchanged.

Exceptions
std::invalid_argumentif genotype/noise/apply_mask sizes are not all equal.

◆ Generate()

GenerationResult pulsatrix::Generate ( const NextTokenLogitsFn &  model,
const std::vector< int64_t > &  prompt,
const GenerationConfig &  config = {} 
)

Generates up to max_new_tokens after prompt, one at a time: process the next-token logits, take the most likely token (greedy) or draw one from their softmax (sampling), append it, and stop after an EOS token.

Note
Sampling draws from std::mt19937_64's raw output, so a seed gives the same text on every platform as long as the model's logits are the same.
Exceptions
std::invalid_argumentif the prompt is empty, the config is invalid, or the model returns an empty or non-finite set of logits, or every token gets removed.

◆ GeneratePooledFakeSamples()

Tensor pulsatrix::GeneratePooledFakeSamples ( GeneratorPopulation &  population,
const std::vector< Tensor > &  noise_per_generator,
DeviceBackend *  backend 
)
inline

Runs every population member's generator forward on its own noise batch (noise_per_generator[i] for population member i), then pools the results (Tensor::Stack, concatenated along the batch dimension, in population order) into one combined fake-sample batch – the discriminator's own training input in E-GAN.

Exceptions
std::invalid_argumentif noise_per_generator.size() != population.size() (delegates to each generator's own forward() and to Tensor::Stack for their own preconditions).

◆ GenerationalReplacement()

template<typename Genotype , typename FitnessT >
std::vector< Individual< Genotype, FitnessT > > pulsatrix::GenerationalReplacement ( const std::vector< Individual< Genotype, FitnessT > > &  ,
std::vector< Individual< Genotype, FitnessT > >  offspring,
size_t  mu 
)

Generational replacement (DEAP's eaSimple): the offspring pool becomes the entire next generation; population is ignored (parents never survive).

Exceptions
std::invalid_argumentif offspring.size() != mu.

◆ global_seed()

uint64_t pulsatrix::global_seed ( )

The seed most recently passed to set_seed() (0 by default).

◆ GridSample()

std::vector< Configuration > pulsatrix::GridSample ( const SearchSpace &  space,
size_t  points_per_continuous_dimension 
)
inline

Enumerates the full cartesian-product grid over space.

Parameters
points_per_continuous_dimensionNumber of points (inclusive of both bounds) used for every Continuous (linearly spaced) and LogUniform (log-spaced) parameter. Integer parameters always enumerate every integer in [lower, upper]; Categorical parameters always enumerate every category – neither is affected by this parameter.
Exceptions
std::invalid_argumentif points_per_continuous_dimension < 2 (fewer than 2 points cannot include both bounds).
Note
Grid size is the product of every parameter's own point count – grows combinatorially with both the number of parameters and points_per_continuous_dimension; the caller's responsibility to keep the search space small enough for grid search specifically (this is grid search's own well-known scaling limit, not a bug).

◆ GrowingSpheresCounterfactual()

CounterfactualResult pulsatrix::GrowingSpheresCounterfactual ( const std::function< Tensor(const Tensor &)> &  predict,
const Tensor &  input,
const CounterfactualTarget &  target,
const CounterfactualConstraints &  constraints = {},
const GrowingSpheresOptions &  options = {} 
)

A counterfactual for any prediction function, with no gradients (growing spheres, Laugel et al. 2018): draws points uniformly in a ball around the input, halving its radius while it still contains a point that reaches the target, then in ever larger shells until one does; takes the nearest such point and puts features back to their original values, smallest change first, while it still reaches the target.

Parameters
predictOne instance in, outputs out. Works for models that aren't differentiable (trees, rules, thresholds) or aren't pulsatrix modules at all.
Returns
The same result and metrics as FindCounterfactual, with the same constraints (immutable features are never moved, limits clip every point, integer and one-hot features are fixed up at the end). rounds counts the balls and shells drawn; final_lambda is 0.
Note
About samples_per_layer model calls per layer, plus one per feature in the last step. The search is in scaled Euclidean distance, so pass a scale (for example MedianAbsoluteDeviation) when features have different units.
Exceptions
std::invalid_argumentfor the inputs FindCounterfactual rejects, or invalid options.

◆ HuggingFaceMapping()

std::vector< WeightMapping > pulsatrix::HuggingFaceMapping ( const HfModelConfig &  config)

The manifest for a Llama-family Hugging Face checkpoint (model.embed_tokens.weight, model.layers.<i>.self_attn.q_proj.weight, ..., model.norm.weight, lm_head.weight) onto CausalLM's parameters: Linear weights transposed, biases and norms as they are.

◆ IA3Layers()

std::vector< std::pair< std::string, LinearModule * > > pulsatrix::IA3Layers ( Module &  model)

The model's LinearModules with an IA³ vector, by name, in the model's order.

◆ Impute()

Tensor pulsatrix::Impute ( const Tensor &  input,
const std::vector< bool > &  removed,
const Imputation &  imputation 
)

Returns input with every element whose removed flag is set filled by imputation.

Exceptions
std::invalid_argumentif removed doesn't have one flag per element, or NoisyLinear is used on an input of rank below 2.

◆ InformationContent()

std::vector< float > pulsatrix::InformationContent ( const SequenceLogoDocument &  doc)

Each position's information content in bits, log2(letters) - entropy: 0 when every letter is equally likely, log2(20) (4.32) when one is certain. A logo stacks the letters to this height, each in proportion to its probability.

◆ InitializeEsm()

void pulsatrix::InitializeEsm ( EncoderLM &  model,
uint64_t  seed,
float  std = 0.02f 
)

Initializes a model for training from scratch as transformers' EsmPreTrainedModel does: linear weights and the embedding table from N(0, std²) (the <pad> row zeroed), biases 0, LayerNorm gains 1 and offsets 0. Deterministic for a seed.

◆ InitTagger()

void pulsatrix::InitTagger ( TinyTagger &  tagger,
uint64_t  seed 
)

Fills the tagger's parameters reproducibly on every platform: matrices uniform in +-1/sqrt(fan_in), normalization gains 1, biases 0.

◆ InsertionCurve()

PerturbationCurve pulsatrix::InsertionCurve ( const PredictFn &  predict,
const Tensor &  input,
const Attribution &  attribution,
const PerturbationOptions &  options = {} 
)

Insertion: starts from the fully imputed input and restores features from most to least relevant. A faithful attribution makes the score rise fast: higher AUC is better.

Exceptions
std::invalid_argumentas DeletionCurve().

◆ IntruderDimensions() [1/2]

IntruderResult pulsatrix::IntruderDimensions ( const Tensor &  base,
const Tensor &  tuned,
int64_t  k = 10,
double  epsilon = 0.6 
)

Counts the top-k singular vectors of tuned that no singular vector of base resembles: |cos| < epsilon against every one of them.

Parameters
base,tunedWeights of the same shape in pulsatrix's (in, out) layout. The vectors compared are the output-space ones, PyTorch's left singular vectors of its (out, in) weight, as in the paper.
kThe paper's figures use 10.
epsilonThe paper sweeps it (it calls 0.6 to 0.9 typical for full fine-tuning); 0.6 is a starting point, not a standard. max_similarity lets a caller apply any other threshold.
Note
The paper's Algorithm 1 compares cosines without an absolute value. A singular vector's sign is arbitrary, so this uses |cos|. Two eigendecompositions, on the CPU in double, of W^T W or W W^T, whichever is smaller: O(min(in, out)^3) (SymmetricEigen takes about 0.8 s at n = 512 in a Release build).
Exceptions
std::invalid_argumentif the shapes differ or aren't rank 2, k < 1, or epsilon isn't in (0, 1].

◆ IntruderDimensions() [2/2]

std::vector< LayerIntruders > pulsatrix::IntruderDimensions ( Module &  base,
Module &  tuned,
int64_t  k = 10,
double  epsilon = 0.6 
)

Intruder dimensions of every LinearModule the two models share by name and shape: a full fine-tune against its base.

Exceptions
std::invalid_argumentif they share none.

◆ IsNeighborEmbedding()

bool pulsatrix::IsNeighborEmbedding ( const ProjectionDocument &  doc)

Whether the document's method is UMAP or t-SNE (umap, tsne, t-sne or opentsne, any case), whose plots keep neighbors but not distances, cluster sizes or densities. The views say so on such plots.

◆ IsSignificant()

bool pulsatrix::IsSignificant ( const PersistenceDiagramEntry &  entry,
size_t  i 
)

Whether feature i of entry passed the attached tests: its p-value is below the threshold, or, with only a bootstrap band, its persistence is above twice the band. True for every feature when no test is attached.

◆ KlLowerBound()

double pulsatrix::KlLowerBound ( double  p,
double  level 
)

The smallest q <= p with BernoulliKl(p, q) <= level.

◆ KlUpperBound()

double pulsatrix::KlUpperBound ( double  p,
double  level 
)

The largest q >= p with BernoulliKl(p, q) <= level.

◆ LandmarkPoints()

Tensor pulsatrix::LandmarkPoints ( const Tensor &  points,
const Landmarks &  landmarks 
)

The landmark rows of points, as a (k, ...) tensor on points' backend.

◆ LayerActivations()

Tensor pulsatrix::LayerActivations ( ExplainerContext &  ctx,
const Tensor &  inputs,
NodeId  layer 
)

The layer's activations for inputs, from one forward pass: shape (n, width).

◆ LayerGradients()

Tensor pulsatrix::LayerGradients ( ExplainerContext &  ctx,
const Tensor &  inputs,
NodeId  layer,
int64_t  target,
DeviceBackend *  backend 
)

The gradient of logit target with respect to the layer, for each of inputs: shape (n, width).

◆ LayerRelevance()

Tensor pulsatrix::LayerRelevance ( const LRP &  lrp,
ExplainerContext &  ctx,
const Tensor &  input,
const LRPTarget &  target,
NodeId  layer,
DeviceBackend *  backend 
)

The relevance at layer for explaining target: the layer's shape, (N, C, ...).

Exceptions
std::invalid_argumentif layer isn't between 1 and the number of modules, or for what LRP::explain() rejects.

◆ LinearCka()

double pulsatrix::LinearCka ( const Tensor &  x,
const Tensor &  y,
CkaEstimator  estimator = CkaEstimator::Debiased 
)

Linear CKA between two representations of the same inputs.

Parameters
xone representation, shape (n, ...): a row per input. Dimensions after the first are flattened, so a (n, channels, height, width) activation is n vectors.
yanother representation of the same n inputs, in the same order, of any width.
Returns
The similarity, 1 for representations equal up to rotation, reflection, uniform scale and a constant offset. NaN if either representation is constant over the inputs (or, debiased, its unbiased variance estimate isn't positive), since CKA is undefined there.
Note
Computed in double precision on the host, whatever device the tensors are on. It costs about n × min(n (p + q), p q + p² + q²) multiply-adds for widths p and q.
Exceptions
std::invalid_argumentif a tensor has rank below 2, the two have different numbers of rows, or there are fewer than 2 inputs (4 for the debiased estimator).

◆ LinearCkaMatrix()

CkaMatrix pulsatrix::LinearCkaMatrix ( const std::vector< Tensor > &  a,
const std::vector< Tensor > &  b,
CkaEstimator  estimator = CkaEstimator::Debiased,
std::size_t  max_gram_bytes = std::size_t{2}<< 30 
)

LinearCka() between every representation in a and every one in b.

Note
Each representation's n × n Gram matrix is computed once and reused for every pair, so a 12 × 12 layer comparison costs about 24 Gram matrices rather than 144 CKAs. When those wouldn't fit in max_gram_bytes, each pair is computed on its own instead.
Exceptions
std::invalid_argumentas LinearCka() does, for any representation, or if a list is empty.

◆ LinearGrid()

std::vector< double > pulsatrix::LinearGrid ( double  start,
double  stop,
int64_t  n 
)

n evenly spaced values from start to stop, both included (n >= 2), or {start} for n == 1.

◆ LoadCausalLM()

std::unique_ptr< CausalLM > pulsatrix::LoadCausalLM ( const std::string &  directory,
DeviceBackend *  backend 
)

Reads config.json and the weights in a downloaded Hugging Face model directory into a new CausalLM, strictly: a tied checkpoint's lm_head.weight is the only tensor allowed to go unused.

Exceptions
std::invalid_argumentfor a config CausalLM refuses or weights that don't match it; std::runtime_error if files can't be read.

◆ LoadCheckpoint() [1/2]

void pulsatrix::LoadCheckpoint ( const std::string &  path,
Module &  model,
AdamOptimizer &  optimizer,
CheckpointLoadOptions  options = {} 
)

LoadCheckpoint(), plus optimizer's state from OptimizerStatePath(path), so training resumes exactly where it stopped.

Exceptions
std::runtime_errorif there is no optimizer file.
std::invalid_argumentif it belongs to a different save of the model, or doesn't match the model.

◆ LoadCheckpoint() [2/2]

void pulsatrix::LoadCheckpoint ( const std::string &  path,
Module &  model,
CheckpointLoadOptions  options = {} 
)

Loads parameters and buffers saved by SaveCheckpoint() (or any safetensors file whose names match) into model, in place.

Note
Everything is validated before anything is written, so a failed load leaves model unchanged. Each tensor keeps its device and requires_grad flag.
Exceptions
std::invalid_argumentif the file is from a newer format version or another framework (format other than "pulsatrix"; importing other names is roadmap IO-4), a shape differs, an entry isn't F32, or (when strict) a name is missing or unexpected.
std::runtime_errorif the file can't be read.

◆ LoadEncoderLM()

std::unique_ptr< EncoderLM > pulsatrix::LoadEncoderLM ( const std::string &  directory,
DeviceBackend *  backend 
)

Loads a masked LM directory: config.json and safetensors weights (one file or sharded). The config's model_type picks the model.

  • ESM-2 (esm), such as facebook/esm2_t6_8M_UR50D. LayerNorm parameters may be named weight/bias or, as transformers 5 saves them, gamma/beta. RoPE frequencies come from the checkpoint's inv_freq buffer when it has one (see EncoderLMConfig::rope_inverse_frequencies).
  • MDLM (mdlm), such as kuleshov-group/mdlm-owt. Its blocks are adaLN-Zero DiT blocks conditioned on the noise level, but MDLM is trained with time_conditioning off, so the conditioning is the same constant at every step: c = silu(sigma_map(0)). Every modulation vector is then a constant, and folding them into the weights is exact: LN(x)·w·(1 + scale) + shift is a LayerNorm with weight w·(1 + scale) and bias shift, and a gated branch gate · W·h (+ b) scales the output projection's columns (and bias) by gate. The loaded model is an ordinary EncoderLM, and LRP on it needs no adaLN rule.
Exceptions
std::invalid_argumentfor an unsupported config or a weight that doesn't fit; std::runtime_error for a missing file.

◆ LoadEsmContactHead()

EsmContactHead pulsatrix::LoadEsmContactHead ( const std::string &  directory,
const EncoderLMConfig &  config 
)

Reads the contact head from an ESM-2 checkpoint directory: esm.contact_head.regression.* (EsmForMaskedLM) or contact_head.regression.* (EsmModel).

Exceptions
std::invalid_argumentif the checkpoint has no contact head, or its size isn't layers * heads of config.

◆ LoadEsmTokenizer()

TextTokenizer pulsatrix::LoadEsmTokenizer ( const std::string &  vocab_path)

MakeEsmTokenizer on a vocab.txt.

Exceptions
std::runtime_errorif it can't be read.

◆ LoadIA3Adapter()

void pulsatrix::LoadIA3Adapter ( Module &  model,
const std::string &  directory,
const std::vector< WeightMapping > &  mapping = {} 
)

Reads a PEFT IA³ adapter directory onto the model, telling feedforward layers by the vectors' shapes, and freezes the rest of the model.

Exceptions
std::invalid_argumentfor a config that isn't plain IA³ (fan_in_fan_out, modules_to_save), a key that isn't an IA³ vector, a shape that fits neither side of its layer or disagrees with feedforward_modules, or a layer that doesn't exist or is already adapted. Nothing changes then.

◆ LoadLoraAdapter()

void pulsatrix::LoadLoraAdapter ( Module &  model,
const std::string &  directory,
const std::vector< WeightMapping > &  mapping = {} 
)

Reads a PEFT LoRA adapter directory onto the model: attaches an adapter to each layer it has weights for, with r from their shapes and lora_alpha and lora_dropout from adapter_config.json, and freezes the rest as ApplyLora() does.

Parameters
mappingAs for SaveLoraAdapter().
Exceptions
std::invalid_argumentfor a config that isn't plain LoRA (DoRA, rsLoRA, fan_in_fan_out, trained biases, modules_to_save, rank or alpha patterns), a key that isn't a LoRA weight, a layer that doesn't exist or already has an adapter, or a shape that doesn't match. Everything is checked before the model is changed. std::runtime_error if a file can't be read.

◆ LoadLoReFT()

std::vector< LoReFTIntervention * > pulsatrix::LoadLoReFT ( CausalLM &  model,
const std::string &  path 
)

Installs the interventions in a file SaveLoReFT() wrote, or one built from pyreft's per-intervention state dicts under those keys (convert its .bin files with tools/convert/pickle_to_safetensors.py), and freezes the rest of the model.

Exceptions
std::invalid_argumentfor missing metadata, an unknown key, a layer the model doesn't have or already intervenes on, or a shape that doesn't fit. Nothing changes then.

◆ LoadTokenizerJson()

TextTokenizer pulsatrix::LoadTokenizerJson ( const std::string &  path)

ParseTokenizerJson on a file.

Exceptions
std::runtime_errorif it can't be read.

◆ LoadTorchvisionWeights()

TorchvisionLoadReport pulsatrix::LoadTorchvisionWeights ( Module &  model,
const std::string &  safetensors_path 
)

Loads a torchvision state dict converted to safetensors (tools/convert/pickle_to_safetensors.py) into model by name: every parameter and buffer of the model is looked up under the same name. Linear weights (every rank-2 parameter), stored (out, in) by PyTorch, are transposed; num_batches_tracked counters are ignored.

Exceptions
std::invalid_argumentfor a tensor the model doesn't have, a shape that doesn't fit, or a missing parameter other than a convolution bias.

◆ LoadTranscoders()

CrossLayerTranscoder pulsatrix::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 upcast:

  • Per-layer (model_kind: transcoder_set, as in mwhanna/gemma-scope-2-270m-pt): layer_<i>.safetensors holding W_enc (F, d), W_dec (F, d), b_enc, b_dec, optionally activation_function.threshold (or threshold) and W_skip.
  • Cross-layer, circuit-tracer's lazy format: W_enc_<i>.safetensors holding W_enc_<i>, b_enc_<i>, b_dec_<i>, optionally threshold_<i> and W_skip_<i>, and W_dec_<i>.safetensors holding W_dec_<i> (F, L − i, d).
    Parameters
    num_layersThe model's layers; files are read for 0 .. num_layers − 1.
    Exceptions
    std::invalid_argumentfor a missing file or tensor, or shapes that don't agree.

◆ LoadVizFonts()

std::vector< VizFontFile > pulsatrix::LoadVizFonts ( const VizFontOptions &  options)

Loads ImGui's default font and merges options' fonts into it, in the current ImGui context. Since ImGui 1.92 glyphs are drawn on first use, so a merged font costs only its file in memory.

Returns
The fonts that loaded (missing or unreadable files are skipped).

◆ LoadWeights()

WeightLoadReport pulsatrix::LoadWeights ( Module &  model,
const HfCheckpoint &  checkpoint,
const std::vector< WeightMapping > &  mapping,
const WeightLoadOptions &  options = {} 
)

Loads checkpoint tensors into model's named parameters and buffers by mapping. Every tensor is read, converted to fp32 (IO-6), sliced and transformed, and checked against its target's shape before anything is written, so a failed load leaves the model unchanged.

Exceptions
std::invalid_argumentif a source or target doesn't exist, a target is mapped twice, a shape doesn't match, a slice is out of range, a Transpose source isn't a matrix, or (strict) a target is left unloaded or a source unused and not ignored.

◆ LogDensityRatio()

double pulsatrix::LogDensityRatio ( const SearchSpace &  space,
const Configuration &  candidate,
const std::vector< Configuration > &  good_configs,
const std::vector< Configuration > &  bad_configs 
)
inline

log(l(candidate)) - log(g(candidate)): the TPE scoring function, summed independently over every parameter in space (so a candidate's mixed continuous/categorical parameters each contribute their own term, composing naturally rather than needing a joint density over the whole space).

Parameters
good_configs,bad_configsObserved configurations split by objective quantile (RunTPELoop's own job); every config must contain every parameter named in space.
Exceptions
std::invalid_argumentif good_configs or bad_configs is empty.
Note
Per-parameter bandwidth for Continuous is 0.2 * (upper - lower); for LogUniform, 0.2 * (log(upper) - log(lower)), applied after taking the log of both the bandwidth basis and every observed/candidate value (consistent with this campaign's own established log-space convention for LogUniform elsewhere – GridSample/RandomSample/ UnitCubeToConfiguration); for Integer, 0.2 * (upper - lower), floored at 1.0 (a sub-1.0 bandwidth over integer-valued data would make the KDE unreasonably peaked).

◆ LogOddsError()

LogOddsErrorReport pulsatrix::LogOddsError ( const std::vector< double > &  predicted,
const std::vector< double > &  reference,
const std::vector< double > &  weights = {},
const std::vector< double > &  band_edges = {1e-3},
double  clip = 1e-6 
)

The error in log-odds of predicted probabilities against reference ones.

Parameters
band_edgesIncreasing edges strictly inside (0, 1): edges {1e-3} give the bands [0, 1e-3) and [1e-3, 1]. Empty gives one band.
clipBoth probabilities are clipped to [clip, 1 - clip] first, so a reference of exactly 0 or 1 gives a finite error. With the default, logit(1e-6) is about -13.8.
Exceptions
std::invalid_argumentif the inputs are empty or of different lengths, a probability is outside [0, 1] or not finite, a weight is negative or not finite or all are 0, the edges aren't increasing inside (0, 1), or clip isn't in (0, 0.5).

◆ LoraIntruderDimensions()

std::vector< LayerIntruders > pulsatrix::LoraIntruderDimensions ( Module &  model,
int64_t  k = 10,
double  epsilon = 0.6 
)

Intruder dimensions of every LoRA layer: its base weight W against W + (alpha / r) A B.

Exceptions
std::invalid_argumentif the model has no unmerged LoRA adapters.

◆ LoraLayers()

std::vector< std::pair< std::string, LinearModule * > > pulsatrix::LoraLayers ( Module &  model)

The model's LinearModules that have an adapter, by name, in the model's order.

◆ LoraRelevanceSplit()

std::vector< LoraLayerRelevance > pulsatrix::LoraRelevanceSplit ( Module &  model)

How much of each adapted layer's relevance went through its adapter in the model's last relevance pass (LoRARelevance::Split, the default), in the model's order: where, and for which inputs, the fine-tuning changed the explanation.

Note
Layers the pass didn't split (disabled or merged adapters, LoRARelevance::Merged) are left out.
Exceptions
std::logic_errorif no layer was split.

◆ lrp_rule_name()

std::string pulsatrix::lrp_rule_name ( LRPRule  rule)
inline

Lower-case rule name ("epsilon", "gamma", "alpha_beta", "zbox") for messages/metadata.

◆ LxtAttnLrpConfig()

LRPRuleConfig pulsatrix::LxtAttnLrpConfig ( )

The rule configuration that matches LXT's AttnLRP on a Hugging Face model: the epsilon rule with a tiny epsilon, biases kept in the denominator as LXT's gradient * input keeps them in z (Qwen2's QKV biases), and LayerNorm with only its standard deviation held constant (LRPRuleConfig::layer_norm_detach_std; ESM-2, PLM-6).

◆ MakeByteTokenizer()

TextTokenizer pulsatrix::MakeByteTokenizer ( const std::vector< std::string > &  special_tokens = {})

Bytes as ids 0..255, then special_tokens as ids 256, 257, ...; decodes by concatenation.

◆ MakeCachedNextTokenLogits()

NextTokenLogitsFn pulsatrix::MakeCachedNextTokenLogits ( EmbeddingModule &  embedding,
std::vector< TransformerBlock * >  blocks,
std::vector< Module * >  head,
DeviceBackend *  backend,
int64_t  max_length,
float  embed_scale = 1.0f,
BlockOutputHook  after_block = {} 
)

A NextTokenLogitsFn for embedding -> transformer blocks -> head layers that keeps a KV cache per block (LLM-5): each call runs only the tokens after the longest prefix it has already processed, so generating n tokens costs one pass over the prompt and then one position per token, instead of n passes over the whole sequence. A call with a different history (a new prompt, or a shorter or edited one) truncates the caches to the shared prefix and continues from there.

Parameters
embeddingMaps (1, L) ids to (1, L, d_model).
blocksRun with forward_cached, in order; each gets its own cache of max_length positions.
headApplied to the last position's hidden state (1, d_model): for example a final RMSNormModule and a TiedLMHeadModule; must end in (1, vocab).
after_blockOptional; see BlockOutputHook. The prompt is the sequence of the first call, or of any call that changes it: one that doesn't just extend the previous sequence past it.
Note
The returned function owns the caches (allocated once) and is stateful: use one per sequence being generated. The modules are not owned and must outlive it.
Exceptions
std::invalid_argument(when built) if blocks is empty or a pointer is null; (when called) if the sequence is empty or longer than max_length.

◆ MakeCharTokenizer()

TextTokenizer pulsatrix::MakeCharTokenizer ( std::vector< std::string >  chars,
const std::vector< std::string > &  special_tokens = {} 
)

Characters by id from chars, then <unk> (unless chars has it), then special_tokens; decodes by concatenation.

Exceptions
std::invalid_argumentas CharModel does.

◆ MakeContactMapDocument()

ContactMapDocument pulsatrix::MakeContactMapDocument ( std::string_view  sequence,
const ContactMap &  predicted,
const ContactMap *  truth = nullptr,
std::string  method = "",
int64_t  first_position = 1 
)

Pairs a prediction with the structure's contacts (TrueContacts), if any.

Exceptions
std::invalid_argumentif a map isn't L x L for the sequence's L residues.

◆ MakeDenoiser() [1/2]

DenoiserFn pulsatrix::MakeDenoiser ( CausalLM &  model,
DeviceBackend *  backend 
)

A DenoiserFn for a CausalLM loaded with bidirectional attention, such as an A2D diffusion model (HfModelConfig::causal false). The model must outlive the function.

Exceptions
std::invalid_argumentif the model is causal: each position would see only the masks before it.

◆ MakeDenoiser() [2/2]

DenoiserFn pulsatrix::MakeDenoiser ( EncoderLM &  model,
DeviceBackend *  backend 
)

A DenoiserFn for an EncoderLM: one forward pass over the sequence, (1, L) to logits (1, L, vocab). The model isn't owned and must outlive the function.

◆ MakeEsmTokenizer()

TextTokenizer pulsatrix::MakeEsmTokenizer ( const std::vector< std::string > &  vocab)

ESM's tokenizer (Hugging Face's EsmTokenizer) over a vocabulary listed one token per line, by id: <cls> <pad> <eos> <unk> L A G V ... <mask> for ESM-2.

  • Every vocabulary token is matched anywhere in the text, so MKT<mask>Y gives M, K, T, <mask>, Y.
  • Whitespace is dropped.
  • A run of other characters (between matches and whitespace) becomes one <unk>: lowercase mkta is a single <unk>, as in EsmTokenizer.
  • Encoding adds <cls> before and <eos> after. decode() joins tokens with spaces.
Exceptions
std::invalid_argumentif the vocabulary lacks <cls>, <eos> or <unk>, or a token repeats.

◆ MakeMutationMapDocument()

MutationMapDocument pulsatrix::MakeMutationMapDocument ( std::string_view  sequence,
const std::vector< float > &  scan,
std::string  method = "",
int64_t  first_position = 1 
)

A mutation map from VariantScorer::single_mutant_scan (L x 20, in kAminoAcids order).

Exceptions
std::invalid_argumentif scan isn't 20 values per residue of sequence.

◆ MakeNextTokenLogits()

NextTokenLogitsFn pulsatrix::MakeNextTokenLogits ( std::vector< Module * >  layers,
DeviceBackend *  backend 
)

A NextTokenLogitsFn for a stack of pulsatrix modules that maps token ids (1, L) to logits (1, L, vocab) (for example EmbeddingModule, causal TransformerBlocks, an RMSNorm and a TiedLMHeadModule): it runs the whole sequence through the modules and returns the last position's logits.

Parameters
layersRun in order; not owned, must outlive the function.
backendWhere the ids tensor is built.
Note
Recomputes the whole prefix at every step; MakeCachedNextTokenLogits doesn't.
Exceptions
std::invalid_argument(when called) if the output isn't rank 3 with one row per token.

◆ MakePointCloud()

PointCloud pulsatrix::MakePointCloud ( const std::vector< ActivationSnapshot > &  snapshots,
NodeId  node,
PointCloudOptions  options = {} 
)

A cloud from one node of several forward passes, such as one snapshot per batch.

Exceptions
std::invalid_argumentas PointCloud::add does, or if snapshots is empty.

◆ MakeProjectionDocument() [1/2]

ProjectionDocument pulsatrix::MakeProjectionDocument ( const Pca &  pca,
const Tensor &  scores,
std::vector< std::string >  labels = {},
std::vector< std::string >  groups = {},
std::vector< float >  values = {},
std::string  title = "" 
)

A projection document from PcaProject()'s scores: axes PC1, PC2, ... with the PCA's explained variance ratios.

Exceptions
std::invalid_argumentif scores isn't (n, pca.num_components()) with at least two components, or labels, groups or values is neither empty nor one per row.

◆ MakeProjectionDocument() [2/2]

ProjectionDocument pulsatrix::MakeProjectionDocument ( const Tensor &  coordinates,
std::string  method,
std::vector< std::string >  labels = {},
std::vector< std::string >  groups = {},
std::vector< float >  values = {},
std::string  title = "" 
)

A projection document from coordinates made elsewhere, such as UMAP or t-SNE output read with ReadNpy() (embedding_export.hpp): axes <method> 1, <method> 2, ..., and no variance shares.

Parameters
coordinates(n, axes), at least two axes.
methodWhat made them, for example "umap" or "tsne"; IsNeighborEmbedding() reads it.
Exceptions
std::invalid_argumentif coordinates isn't (n, 2 or more), method is empty, or as ToJson() does.

◆ MakeSequenceLogoDocument()

SequenceLogoDocument pulsatrix::MakeSequenceLogoDocument ( const ResidueLogProbs &  log_probs,
const TextTokenizer &  tokenizer,
std::string_view  sequence,
std::string  method = "",
int64_t  first_position = 1 
)

A logo from a model's log-probabilities (VariantScorer::masked_marginals or wild_type_marginals): each residue's probabilities over the 20 amino acids, renormalized to sum to 1 (special and rare tokens dropped).

Exceptions
std::invalid_argumentif log_probs doesn't have one row per residue of sequence, or the tokenizer lacks an amino acid.

◆ MakeStudentFromLayers()

std::unique_ptr< CausalLM > pulsatrix::MakeStudentFromLayers ( CausalLM &  teacher,
const std::vector< int64_t > &  layers,
DeviceBackend *  backend 
)

A CausalLM with teacher's config and weights but only the blocks in layers, in that order: the student's block j is a copy of the teacher's block layers[j]. The embedding, final norm and head are copied too; layer_types keeps the chosen layers'.

Note
The student is a separate model on backend's device: training it leaves the teacher alone. The teacher's interventions aren't copied.
Exceptions
std::invalid_argumentif layers is empty, has an index out of range or repeats one, or a teacher parameter has no counterpart of the same shape (a teacher with LoRA adapters, say).

◆ MakeTaggingBatch()

TaggingBatch pulsatrix::MakeTaggingBatch ( TaggingRule  rule,
int64_t  batch_size,
uint64_t  seed,
DeviceBackend *  backend = nullptr 
)

A deterministic, platform-independent batch; lengths are 5 to kSeqLen.

◆ MakeTokenRelevanceDocument()

TokenRelevanceDocument pulsatrix::MakeTokenRelevanceDocument ( std::string_view  text,
const Encoding &  encoding,
const std::vector< float > &  token_scores,
std::string  method,
std::string  target = "",
bool  include_special_tokens = true 
)

A token-level document for text from its Encoding and one score per token.

Each token is shown as the text its offset covers, so byte-level tokens appear decoded, as UTF-8. Tokens that share a character (byte-level tokens that split one, such as an emoji) are shown as one piece whose score is their sum. Text no token covers becomes an unscored piece, so the pieces read as text. Tokens with an empty offset (BOS, EOS) are shown as their token strings when include_special_tokens is set; otherwise their relevance goes to unassigned.

Exceptions
std::invalid_argumentif the scores don't match the tokens or an offset lies outside text.

◆ MakeWordLevelTokenizer()

TextTokenizer pulsatrix::MakeWordLevelTokenizer ( const Vocabulary &  vocab)

The word-level tokenizer over a Vocabulary: AsciiLowercase, WordPunctuationSplit and a WordLevelModel whose unknown token is <unk> (id 0). On ASCII text its tokens are Tokenizer::Tokenize's and its ids are Vocabulary::IndexOf's.

◆ MakeWordRelevanceDocument()

TokenRelevanceDocument pulsatrix::MakeWordRelevanceDocument ( std::string_view  text,
const WordScores &  words,
std::string  method,
std::string  target = "" 
)

A word-level document for text from AggregateToWords(): each word scored, the text between words as unscored pieces, and the words' unassigned relevance carried over.

Exceptions
std::invalid_argumentif a word's span lies outside text or the words are out of order.

◆ MarkdownToHtml()

std::string pulsatrix::MarkdownToHtml ( const std::string &  markdown)

Markdown (the subset Report::to_html() supports) as HTML; raw HTML is escaped.

◆ MaskedLMForwardBackward()

float pulsatrix::MaskedLMForwardBackward ( EncoderLM &  model,
const MaskedLMBatch &  batch,
TokenCrossEntropyLoss &  loss,
float  normalizer = 0.0f 
)

One masked-LM forward and backward: sets the batch's padding mask, runs the model, and accumulates the gradient of the cross-entropy over the picked tokens, divided by normalizer (0: the batch's own num_targets, i.e. the mean). Gradients add to what's there; zero them between optimizer steps.

Returns
The loss (mean over picked tokens unless a normalizer is given).

◆ MatchConcept()

ConceptMatch pulsatrix::MatchConcept ( const SparseCodes &  codes,
const std::vector< int > &  labels,
const std::string &  concept_name,
const std::vector< double > &  thresholds = {0.0, 0.15, 0.5, 0.6, 0.8} 
)

InterPLM's matching: a feature predicts the concept on a residue when its value exceeds a threshold, a share of its largest value (thresholds), and is scored by F1 over the residues. Returns the best feature and threshold.

Exceptions
std::invalid_argumentif labels doesn't have one value per residue.

◆ MatthewsCorrelation()

double pulsatrix::MatthewsCorrelation ( const std::vector< int > &  labels,
const std::vector< int > &  predicted 
)

Matthews correlation of binary labels and predicted (sklearn's matthews_corrcoef); 0 when a row or column of the confusion matrix is empty.

◆ MaxPersistence()

double pulsatrix::MaxPersistence ( const PersistenceDiagram &  diagram)

The largest finite persistence in a diagram, 0 if it has none: a common statistic for BaselinePValue().

◆ McDropoutSamples()

std::vector< Tensor > pulsatrix::McDropoutSamples ( Module &  model,
const std::function< Tensor(const Tensor &)> &  predict,
const Tensor &  input,
int64_t  samples 
)

Monte Carlo dropout: runs predict on input samples times with every dropout layer under model in training mode and everything else in eval mode, so BatchNorm uses its running statistics and only the dropout masks change between passes.

Dropout layers are the DropoutModule instances in the model's tree (NamedModules()) and the LinearModule layers whose LoRA adapter has dropout (LoRAAdapter::dropout() > 0). Each module's training mode is restored afterwards, also when predict throws. The masks come from each layer's seeded stream, so a run is reproducible.

Parameters
modelThe network predict runs.
predictRuns the network on its argument and returns probabilities, such as a softmax of the logits.
Returns
One output per pass.
Exceptions
std::invalid_argumentif samples < 2 or the model has no dropout layer with p > 0, whose samples would all be the same.

◆ MdlmMapping()

std::vector< WeightMapping > pulsatrix::MdlmMapping ( const EncoderLMConfig &  config)

The name mapping from an MDLM checkpoint to EncoderLM. The fused attn_qkv is split into q, k and v; linear weights are transposed. The LayerNorm biases and the adaLN modulation have no counterpart here: LoadEncoderLM folds them in (see there).

◆ MeanL0() [1/2]

double pulsatrix::MeanL0 ( const std::vector< float > &  codes,
int64_t  num_features,
float  threshold = 0.0f 
)

The mean number of codes above threshold in magnitude per input (L0), for codes row-major (N, num_features).

Exceptions
std::invalid_argumentfor a size that isn't a whole number of rows, or no rows.

◆ MeanL0() [2/2]

double pulsatrix::MeanL0 ( Featurizer &  featurizer,
const Tensor &  x,
float  threshold = 0.0f 
)

MeanL0 of a featurizer's codes for x, in blocks: a block counts once when any of its codes is above threshold in magnitude.

◆ MeanSubstitutionScore()

std::vector< float > pulsatrix::MeanSubstitutionScore ( const MutationMapDocument &  doc)

Each residue's mean score over its substitutions (the wild type left out): how much the model minds a change there. NaN where none was scored.

◆ MeasureBlockGeometry()

BlockGeometry pulsatrix::MeasureBlockGeometry ( Featurizer &  featurizer,
const Tensor &  x,
int64_t  batch = 4096 
)
Exceptions
std::invalid_argumentfor a batch that isn't (N, input_dim). Works for any featurizer: a single-direction featurizer's blocks have rank 1.

◆ MeasureDescriptionLength()

DescriptionLength pulsatrix::MeasureDescriptionLength ( Featurizer &  featurizer,
const Tensor &  x,
double  distortion_fraction = 0.1,
int64_t  batch = 4096 
)
Exceptions
std::invalid_argumentfor a batch that isn't (N, input_dim) with N >= 2, or a distortion_fraction outside (0, 1).

◆ MeasureEffectiveRank()

EffectiveRank pulsatrix::MeasureEffectiveRank ( const Tensor &  x,
bool  center = true 
)

How many directions the rows spread along, from the singular values of x.

Parameters
centerSubtract the mean row first (the default). Without it, a large common direction, the anisotropy, takes up a share of the spectrum and lowers the effective rank.
Note
The singular values come from the smaller Gram matrix, x x^T or x^T x, in double precision.
Exceptions
std::invalid_argumentif x has rank below 2, fewer than 2 rows, a NaN or infinity, or is all zeros (after centering, if centering).

◆ MeasureHubness()

Hubness pulsatrix::MeasureHubness ( const Neighbors &  neighbors,
int64_t  num_points 
)

Measures hubness in neighbors, which name points 0 to num_points - 1.

Exceptions
std::invalid_argumentif num_points < 1 or an index is outside it.

◆ MeasureImportance()

std::vector< ImportanceStats > pulsatrix::MeasureImportance ( ParameterDecomposition &  d,
const Tensor &  x 
)

◆ MeasureLatentScaling()

std::vector< LatentScaling > pulsatrix::MeasureLatentScaling ( Crosscoder &  crosscoder,
const Tensor &  x,
const std::vector< int64_t > &  latents,
int64_t  a = 0,
int64_t  b = 1,
int64_t  batch = 4096 
)

Latent Scaling of each of latents on x, (N, S·d), in batches of batch. β is 0 (and ν 0) for a latent that never fires.

Exceptions
std::invalid_argumentfor a latent or source out of range, or a == b.

◆ MeasureLossRecovered()

LossRecovered pulsatrix::MeasureLossRecovered ( Featurizer &  featurizer,
int64_t  position,
const std::function< double(const HiddenStateHook &)> &  loss,
const std::vector< bool > &  rows = {} 
)

Loss recovered, SAEBench's main downstream measure.

Parameters
lossRuns the model with the hook it is given installed (for example with CausalLM::set_hidden_state_hook()), removes it, and returns the loss: cross-entropy on held-out text, or a masked-LM loss. It is called with an empty hook for the clean loss.

◆ MeasureMlpLossRecovered()

LossRecovered pulsatrix::MeasureMlpLossRecovered ( Featurizer &  transcoder,
const std::function< double(const MlpHook &)> &  loss,
const std::vector< bool > &  rows = {} 
)

Loss recovered for a transcoder spliced in for an MLP: loss installs the MlpHook it is given on the MLP's block, runs the model, removes it and returns the loss. Ablation zeroes the MLP's output.

◆ MeasureSelectivity()

ProbeSelectivity pulsatrix::MeasureSelectivity ( const std::vector< float > &  features,
int64_t  dim,
const std::vector< int > &  labels,
int  classes,
const std::vector< int64_t > &  token_types,
const std::vector< bool > &  train,
const std::vector< bool > &  test,
DeviceBackend *  backend,
const ProbeOptions &  options = {} 
)

Trains one probe on labels and one on ControlTaskLabels(token_types, labels, classes, options.seed), with the same features, split and options, and reports both.

Exceptions
std::invalid_argumentfor what TrainLinearProbe() and ControlTaskLabels() reject.

◆ MeasureSteering()

SteeringReport pulsatrix::MeasureSteering ( const std::function< double(int64_t i, const HiddenStateHook &hook)> &  behavior,
int64_t  num_inputs,
int64_t  position,
const std::vector< float > &  direction,
const SteeringOptions &  options = {} 
)

Measures steering along direction, and along random directions of the same norm.

Parameters
behaviorReturns input i's behavior, a number that steering should raise (a logit difference, a log-probability, a probe's score), with the hook it is given installed; it must remove the hook afterwards. It is called with each coefficient for each input.
num_inputsHow many inputs behavior knows.
Exceptions
std::invalid_argumentfor no inputs, fewer than two distinct coefficients, an empty or all-zero direction, or random_directions < 0.

◆ MedianAbsoluteDeviation()

std::vector< float > pulsatrix::MedianAbsoluteDeviation ( const std::vector< Tensor > &  background)

Each feature's median absolute deviation over background (flat order), the distance scale Wachter et al. recommend for tabular data. A feature with zero MAD gets 1, as in DiCE, so it can still move.

Exceptions
std::invalid_argumentif background is empty or its shapes differ.

◆ MedianSplitMcc()

double pulsatrix::MedianSplitMcc ( const std::vector< int > &  labels,
const std::vector< double > &  scores 
)

ProteinGym's MCC: scores at or above their median predict 1.

◆ MergeIA3()

void pulsatrix::MergeIA3 ( Module &  model)

Folds every vector into its layer's weights (and an output-scaling layer's bias).

◆ MergeLora()

void pulsatrix::MergeLora ( Module &  model)

Merges every adapter into its base weight (LinearModule::merge_lora()).

◆ mime_bundle_repr() [1/22]

MimeBundle pulsatrix::mime_bundle_repr ( const Attribution &  attribution)

◆ mime_bundle_repr() [2/22]

MimeBundle pulsatrix::mime_bundle_repr ( const AttributionDocument &  doc)

◆ mime_bundle_repr() [3/22]

MimeBundle pulsatrix::mime_bundle_repr ( const CircuitGraph &  graph)

◆ mime_bundle_repr() [4/22]

MimeBundle pulsatrix::mime_bundle_repr ( const CircuitGraphDocument &  doc)

◆ mime_bundle_repr() [5/22]

MimeBundle pulsatrix::mime_bundle_repr ( const ClassificationReport &  report)

◆ mime_bundle_repr() [6/22]

MimeBundle pulsatrix::mime_bundle_repr ( const ContactMapDocument &  doc)

◆ mime_bundle_repr() [7/22]

MimeBundle pulsatrix::mime_bundle_repr ( const CounterfactualDocument &  doc)

◆ mime_bundle_repr() [8/22]

MimeBundle pulsatrix::mime_bundle_repr ( const HeatmapDocument &  doc)

◆ mime_bundle_repr() [9/22]

MimeBundle pulsatrix::mime_bundle_repr ( const MorrisDocument &  doc)

◆ mime_bundle_repr() [10/22]

MimeBundle pulsatrix::mime_bundle_repr ( const MutationMapDocument &  doc)

◆ mime_bundle_repr() [11/22]

MimeBundle pulsatrix::mime_bundle_repr ( const PartialDependenceDocument &  doc)

◆ mime_bundle_repr() [12/22]

MimeBundle pulsatrix::mime_bundle_repr ( const PersistenceDiagramDocument &  doc)

◆ mime_bundle_repr() [13/22]

MimeBundle pulsatrix::mime_bundle_repr ( const ProjectionDocument &  doc)

◆ mime_bundle_repr() [14/22]

MimeBundle pulsatrix::mime_bundle_repr ( const ResidueTracksDocument &  doc)

◆ mime_bundle_repr() [15/22]

MimeBundle pulsatrix::mime_bundle_repr ( const SensitivityDocument &  doc)

◆ mime_bundle_repr() [16/22]

MimeBundle pulsatrix::mime_bundle_repr ( const SequenceLogoDocument &  doc)

◆ mime_bundle_repr() [17/22]

MimeBundle pulsatrix::mime_bundle_repr ( const SeriesDocument &  doc)

◆ mime_bundle_repr() [18/22]

MimeBundle pulsatrix::mime_bundle_repr ( const SliceErrorReport &  report)

◆ mime_bundle_repr() [19/22]

MimeBundle pulsatrix::mime_bundle_repr ( const SobolDocument &  doc)

◆ mime_bundle_repr() [20/22]

MimeBundle pulsatrix::mime_bundle_repr ( const Tensor &  tensor)

◆ mime_bundle_repr() [21/22]

MimeBundle pulsatrix::mime_bundle_repr ( const TokenRelevanceDocument &  doc)

◆ mime_bundle_repr() [22/22]

MimeBundle pulsatrix::mime_bundle_repr ( const TrainingLogDocument &  doc)

◆ MlpAblationHook()

MlpHook pulsatrix::MlpAblationHook ( std::vector< bool >  rows = {})

Zero-ablates an MLP: its output rows set to 0.

◆ MlpSpliceHook()

MlpHook pulsatrix::MlpSpliceHook ( Featurizer &  transcoder,
std::vector< bool >  rows = {} 
)

Splices a transcoder in for an MLP (install it with EncoderBlock::set_mlp_hook() or TransformerBlock::set_mlp_hook()): the MLP's output rows are replaced by predict() of its input rows.

Parameters
rowsAs SpliceHook's: which of the N * L rows to replace, all when empty.

◆ ModelParameterRandomizationTest() [1/2]

RandomizationResult pulsatrix::ModelParameterRandomizationTest ( Module &  model,
const ExplainFn &  explain,
const Tensor &  input,
uint64_t  seed 
)

The model-parameter randomization test (Adebayo et al., "Sanity Checks for Saliency Maps", NeurIPS 2018), cascading: randomizes the model's layers from the output down, re-explains input after each, and measures how similar the explanation stays.

Note
An explanation that stays similar after its model was randomized can't be explaining the model. Each parameter tensor is replaced by Gaussian noise with that tensor's own standard deviation, drawn from a portable generator seeded by seed. Layers are the first segment of named_parameters() names (a SequentialModule's indices, for example).
The model's parameters are restored exactly before returning, even if explain throws.

◆ ModelParameterRandomizationTest() [2/2]

RandomizationResult pulsatrix::ModelParameterRandomizationTest ( Module &  model,
const ExplainFn &  explain,
const Tensor &  input,
uint64_t  seed,
const std::vector< std::string > &  layers 
)

ModelParameterRandomizationTest over layers, in the order given: each a prefix of named_parameters() names, such as "layers.11", randomized cumulatively.

Exceptions
std::invalid_argumentif a layer names no parameter.

◆ MorrisSample()

std::vector< std::vector< float > > pulsatrix::MorrisSample ( const GlobalSensitivityProblem &  problem,
const MorrisOptions &  options = {} 
)

Morris trajectories (Morris 1991): each starts at a random grid point and moves one feature at a time, in a random order, by the Morris step. Rows are feature values in the problem's ranges, (num_features + 1) per trajectory.

Note
Deterministic for a seed on every platform (no std:: distributions).
Exceptions
std::invalid_argumentfor an invalid problem or options.

◆ MuCommaLambdaReplacement()

template<typename Genotype , typename FitnessT >
std::vector< Individual< Genotype, FitnessT > > pulsatrix::MuCommaLambdaReplacement ( const std::vector< Individual< Genotype, FitnessT > > &  ,
std::vector< Individual< Genotype, FitnessT > >  offspring,
size_t  mu 
)

(mu,lambda) replacement: the next generation is the fittest mu individuals from offspring only (population/parents are always discarded) – more explorative than (mu+lambda), since it cannot get stuck re-selecting the same elite parent forever.

Exceptions
std::invalid_argumentif offspring.size() < mu.

◆ MuPlusLambdaReplacement()

template<typename Genotype , typename FitnessT >
std::vector< Individual< Genotype, FitnessT > > pulsatrix::MuPlusLambdaReplacement ( const std::vector< Individual< Genotype, FitnessT > > &  population,
std::vector< Individual< Genotype, FitnessT > >  offspring,
size_t  mu 
)

(mu+lambda) replacement: the next generation is the fittest mu individuals from population union offspring (parents may survive) – more exploitative than (mu,lambda), since a fit parent is never discarded just for being old.

Exceptions
std::invalid_argumentif population.size() + offspring.size() < mu.

◆ MutualKnnAlignment()

double pulsatrix::MutualKnnAlignment ( const Tensor &  a,
const Tensor &  b,
const NeighborOptions &  options = {} 
)

Mutual-kNN alignment (Huh et al. 2024): how far two representations of the same inputs agree on which inputs are alike. For each input, the fraction of its k nearest neighbors under a that are also among its k nearest under b, averaged over the inputs.

Parameters
a,bthe same n inputs in the same order, of any widths.
Returns
Between 0 and 1. Two unrelated representations score about k / (n - 1) by chance.
Note
With the default options (cosine, no centering) this is Huh et al.'s mutual_knn.
Exceptions
std::invalid_argumentas NearestNeighbors() does, or if the row counts differ.

◆ MutualNearestNeighbors()

std::vector< std::pair< int64_t, int64_t > > pulsatrix::MutualNearestNeighbors ( const Tensor &  a,
const Tensor &  b,
const NeighborOptions &  options = {} 
)

The pairs (i, j), a[i] from a and b[j] from b, where b[j] is among a[i]'s k nearest in b and a[i] is among b[j]'s k nearest in a. Used to match items across two sets in the same space, such as the same concepts in two batches.

Returns
The pairs sorted by i, then j. With center, both sets are centered on the mean of the two together.
Exceptions
std::invalid_argumentas NearestNeighbors() does, or if the widths differ.

◆ NamedModules()

std::vector< NamedModuleRef > pulsatrix::NamedModules ( Module &  root)
inline

Every module under root, depth first with each parent before its children, named by their full dotted path (layers.0.mha.q_proj); root itself isn't included.

◆ Ndcg()

double pulsatrix::Ndcg ( const std::vector< double > &  true_scores,
const std::vector< double > &  predicted,
double  top_percent = 10.0 
)

ProteinGym's NDCG: gains are the true scores min-max scaled to [0, 1]; the variants the model ranks in the top top_percent (floor of the count) contribute gain / log2(rank + 1), normalized by the same sum for the truly best ones. Zero gains are dropped.

Note
Tied predicted scores are ranked in input order (a stable sort). numpy's default argsort isn't stable, so ProteinGym may order exact ties differently.

◆ NearestNeighbors() [1/2]

Neighbors pulsatrix::NearestNeighbors ( const Tensor &  points,
const NeighborOptions &  options = {} 
)

Each point's k nearest other points (a point is never its own neighbor).

Parameters
pointsshape (n, ...): a row per point. Dimensions after the first are flattened.
Note
Ties keep the lower index first, as top_k() does, so results are the same everywhere.
Exceptions
std::invalid_argumentif points has rank below 2 or a NaN or infinity, or k is not between 1 and n - 1.

◆ NearestNeighbors() [2/2]

Neighbors pulsatrix::NearestNeighbors ( const Tensor &  queries,
const Tensor &  points,
const NeighborOptions &  options = {} 
)

Each query's k nearest points from another set of the same width, for example new inputs against a reference set. With center, both are centered on the points' mean.

Exceptions
std::invalid_argumentas the one-set version does, if the widths differ, or if k is not between 1 and the number of points.

◆ NeuronCodes()

SparseCodes pulsatrix::NeuronCodes ( const std::vector< float > &  rows,
int64_t  dim 
)

Dense values as codes, each dimension d twice: as feature 2d (its positive part) and 2d + 1 (its negative part, flipped), so single neurons can be matched to concepts the same way as features.

◆ next_seed()

uint64_t pulsatrix::next_seed ( )

The next seed in the global stream: a distinct, well-mixed 64-bit value per call, reproducible for a given global seed. Components built without an explicit seed take theirs from here, so two of them never share a random stream by accident.

◆ NormalizeSigned()

float pulsatrix::NormalizeSigned ( float  value,
float  max_abs 
)

Normalizes value into [-1, 1] against a known maximum absolute magnitude, for signed quantities such as attribution direction (positive/negative contribution).

Parameters
valueThe raw value to normalize. Values outside [-max_abs, max_abs] are clamped.
max_absThe absolute value that should map to +/-1.0. If 0, returns 0.0 rather than dividing by zero.

◆ NormalizeUnsigned()

float pulsatrix::NormalizeUnsigned ( float  value,
float  max_abs 
)

Normalizes value into [0, 1] against a known maximum magnitude, for unsigned (magnitude-only) quantities such as saliency intensity or ablation effect.

Parameters
valueThe raw value to normalize. Values outside [0, max_abs] are clamped.
max_absThe value that should map to 1.0. If 0 (a degenerate all-zero series), returns 0.0 rather than dividing by zero.

◆ NSGA2Replacement()

template<typename Genotype >
std::vector< Individual< Genotype, Objectives > > pulsatrix::NSGA2Replacement ( const std::vector< Individual< Genotype, Objectives > > &  population,
std::vector< Individual< Genotype, Objectives > >  offspring,
size_t  mu 
)

NSGA-II survivor selection: combines population and offspring, fast-non-dominated- sorts the pool, includes whole fronts (best first) until the next front would overflow mu, then fills the remainder from that final front by crowding distance (largest first – more diverse/isolated solutions preferred).

Exceptions
std::invalid_argumentif population.size() + offspring.size() < mu.
Note
Same (population, offspring, mu) -> next-generation-population signature as GenerationalReplacement/MuPlusLambdaReplacement/MuCommaLambdaReplacement (survivor_selection.hpp) – directly usable as RunEvolutionaryLoop's SurvivorFn.

◆ NullModelBaseline() [1/2]

template<typename Analysis >
auto pulsatrix::NullModelBaseline ( Module &  model,
Analysis &&  analysis,
uint64_t  seed 
) -> NullModelComparison<std::decay_t<std::invoke_result_t<Analysis&>>>

Runs analysis() on model, then again after ReinitializeParameters(model, seed), then restores the model exactly (also if analysis throws).

Parameters
analysisAnything callable with no arguments that reads the model: an explainer run, a probe's accuracy, a featurizer's statistics. Its return type is the result type.

◆ NullModelBaseline() [2/2]

AttributionNullReport pulsatrix::NullModelBaseline ( Module &  model,
const ExplainFn &  explain,
const Tensor &  input,
uint64_t  seed 
)

Explains input with the trained and the null model and compares the two.

◆ Occlusion()

Attribution pulsatrix::Occlusion ( const std::function< Tensor(const Tensor &)> &  predict,
const Tensor &  input,
int64_t  target_index,
const std::vector< int64_t > &  window,
const std::vector< int64_t > &  strides,
float  baseline = 0.0f 
)

Occlusion (Zeiler and Fergus 2014) with Captum 0.9's semantics: a window slides over the input with the given strides, everything under it is set to baseline, and each element's attribution is the drop in the target output, f(x) - f(occluded), averaged over the windows that covered it.

Parameters
windowOne size per input dimension (for an instance shaped (C, H, W), for example (C, 3, 3) occludes 3x3 patches across all channels; for a (L, d) sequence, (k, d) occludes spans of k tokens).
stridesOne per dimension, each >= 1 and no larger than the window where the window is smaller than the input. The last window in a dimension is cropped at the edge, as in Captum.
Returns
Attribution "occlusion", shaped like the input, beside it (same backend and device).
Exceptions
std::invalid_argumentif window or strides have the wrong length or invalid sizes, or the target index is out of range.

◆ OnePointCrossover()

template<typename T , typename RNG >
std::pair< std::vector< T >, std::vector< T > > pulsatrix::OnePointCrossover ( const std::vector< T > &  parent1,
const std::vector< T > &  parent2,
RNG &  rng 
)

RNG-driven wrapper: draws an interior point in [1, size-1] uniformly.

Exceptions
std::invalid_argumentif parent sizes differ or parent size < 2 (no interior point exists to draw).

◆ OnePointCrossoverAtPoint()

template<typename T >
std::pair< std::vector< T >, std::vector< T > > pulsatrix::OnePointCrossoverAtPoint ( const std::vector< T > &  parent1,
const std::vector< T > &  parent2,
size_t  point 
)

Splits both parents at point and swaps tails.

Exceptions
std::invalid_argumentif parent sizes differ or point > parent1.size().
Note
point == 0 or point == size() are valid (degenerate, fully-swapped/no-swap) cases – this pure core does not restrict to "interior" points; OnePointCrossover (the RNG wrapper, below) does, since a degenerate point is never a useful recombination.

◆ OptimalWindow()

std::pair< int64_t, int64_t > pulsatrix::OptimalWindow ( int64_t  position,
int64_t  length,
int64_t  window 
)

ProteinGym's get_optimal_window: the token range [begin, end) around position in a sequence of length tokens, for a model that sees window tokens.

◆ OptimizerStatePath()

std::string pulsatrix::OptimizerStatePath ( const std::string &  checkpoint_path)

Where the optimizer state for checkpoint_path is stored: model.safetensors becomes model.optim.safetensors; any other name gets .optim.safetensors appended.

◆ OpTypeFromName()

OpType pulsatrix::OpTypeFromName ( std::string_view  name)
Exceptions
std::invalid_argumentif name isn't an OpType name.

◆ OpTypeName()

const char * pulsatrix::OpTypeName ( OpType  op_type)

The name ToCircuitGraphDocument writes for op_type, for example "Linear".

◆ OrthonormalizeLoReFT()

void pulsatrix::OrthonormalizeLoReFT ( CausalLM &  model)

orthonormalize() on every LoReFT intervention of the model: call it after each optimizer step.

◆ PadCollate()

CollateFn pulsatrix::PadCollate ( float  pad_index = 0.0f)

Builds a CollateFn that right-pads variable-length token sequences (sample.fields[0], shape (1, seq_len) – TextDataset::get()'s output) to the batch's own max length, producing one (N, max_len) Tensor, plus a (N,) length field recording each sample's real (pre-padding) length. This is the CollateFn extension point Phase 1's architecture design reserved for ragged/variable-length modalities (PyTorch's collate_fn equivalent) – exercised here for the first time, with zero changes needed to Dataset/DataLoader/Batch themselves.

Parameters
pad_indexValue used to fill padding positions (as a float, matching Decision Point 6's token-as-float32 representation). Defaults to 0 – note this numerically collides with <unk>'s reserved index; a consumer that needs to distinguish real <unk> tokens from padding must use the length field, not the token value itself, to locate padding positions.
Returns
A CollateFn producing Batch{ {padded_tokens (N,max_len), lengths (N,)} }.
Exceptions
std::invalid_argument(from the returned CollateFn, at call time) if samples is empty – matching DefaultCollate's own external-boundary convention.

◆ PairwiseDistances() [1/2]

DistanceMatrix pulsatrix::PairwiseDistances ( const PointCloud &  cloud,
DeviceBackend *  backend,
const DistanceOptions &  options = {} 
)

Euclidean distances between every pair of a cloud's points, on the given backend.

Exceptions
std::invalid_argumentas above.

◆ PairwiseDistances() [2/2]

DistanceMatrix pulsatrix::PairwiseDistances ( const Tensor &  points,
const DistanceOptions &  options = {} 
)

Euclidean distances between every pair of rows.

Parameters
pointsshape (n, ...): a row per point, dimensions after the first flattened. With DistanceMethod::Gemm the products run on points' own backend.
Exceptions
std::invalid_argumentif points has rank below 2, fewer than 2 rows, a NaN or infinity, block_rows below 0, or (with normalize) a row of zeros after centering.

◆ ParseAnnotatedProteins()

std::vector< AnnotatedProtein > pulsatrix::ParseAnnotatedProteins ( std::string_view  jsonl)

Reads JSON lines, one protein per line: {"accession", "sequence", "features": [{"type", "start", "end"}]} (tools/plm/fetch_swissprot_annotations.py writes them). Blank lines are skipped.

Exceptions
std::invalid_argumentfor a line that isn't such an object, or a feature outside its sequence.

◆ ParseAttributionDocument()

AttributionDocument pulsatrix::ParseAttributionDocument ( std::string_view  json)

◆ ParseBenchmarkReport()

BenchmarkReport pulsatrix::ParseBenchmarkReport ( std::string_view  json)

Reads a report, following the viz document rules (docs/visualization): schema and version checks, unknown fields ignored, "nonfinite" for NaN and infinity, and errors that name the JSON Pointer of the problem.

◆ ParseCircuitGraphDocument()

CircuitGraphDocument pulsatrix::ParseCircuitGraphDocument ( std::string_view  json)

◆ ParseClassificationReport()

ClassificationReport pulsatrix::ParseClassificationReport ( std::string_view  json)

Reads a pulsatrix.classification_report.v1 document, as ToJson(ClassificationReport) writes it.

Exceptions
std::invalid_argumentif it isn't one, or doesn't hold together: a score outside its range, bins out of order or whose counts don't sum to n, or a confusion matrix or per-class list that isn't classes long.

◆ ParseContactMapDocument()

ContactMapDocument pulsatrix::ParseContactMapDocument ( std::string_view  json)

◆ ParseCounterfactualDocument()

CounterfactualDocument pulsatrix::ParseCounterfactualDocument ( std::string_view  json)

◆ ParseEsmConfig()

EncoderLMConfig pulsatrix::ParseEsmConfig ( std::string_view  json)

Reads an ESM config.json.

Exceptions
std::invalid_argumentfor malformed JSON, a missing size, or a model this class doesn't run yet: anything but EsmForMaskedLM/EsmModel, absolute position embeddings (ESM-1b), emb_layer_norm_before, ESMFold, or an activation other than GELU.

◆ ParseFasta()

std::vector< FastaRecord > pulsatrix::ParseFasta ( std::string_view  text)

Parses FASTA text: records start with >, sequences may span lines, and blank lines and ; comment lines are skipped. Line endings may be \n or \r\n.

Exceptions
std::invalid_argumentfor sequence text before the first header, or an empty header.

◆ ParseFeatureDashboardDocument()

FeatureDashboardDocument pulsatrix::ParseFeatureDashboardDocument ( std::string_view  json)

◆ ParseHeatmapDocument()

HeatmapDocument pulsatrix::ParseHeatmapDocument ( std::string_view  json)

◆ ParseHfConfig()

HfModelConfig pulsatrix::ParseHfConfig ( std::string_view  json)

Parses config.json text. A multimodal config's text_config is read for the language model.

Exceptions
std::invalid_argumentif the text isn't a JSON object, a required size is missing or not a positive integer (hidden_size, intermediate_size, num_hidden_layers, num_attention_heads, vocab_size), a field has the wrong type, or the head counts don't fit together.

◆ ParseJson()

JsonValue pulsatrix::ParseJson ( std::string_view  text)

Parses one JSON document.

Note
Strict: no comments, trailing commas, NaN or Infinity literals, duplicate object keys, invalid UTF-8, unpaired surrogate escapes or trailing content. Nesting deeper than 256 levels is rejected, so a hostile file can't exhaust the stack.
Exceptions
std::invalid_argumentnaming the byte offset of the first error.

◆ ParseMdlmConfig()

EncoderLMConfig pulsatrix::ParseMdlmConfig ( std::string_view  json)

Reads an MDLM config.json (kuleshov-group/mdlm-owt and models trained with the same code): a bidirectional transformer with rotate-half RoPE, LayerNorms without biases, bias-free attention, a tanh-GELU MLP four times the width, and an untied linear output layer. The mask token is the vocabulary's last id.

Exceptions
std::invalid_argumentfor malformed JSON, a missing size, or time_conditioning: a model whose adaLN modulation depends on the noise level can't be folded into constant weights, and needs DIFF-6's adaLN module.

◆ ParseMmcif()

ProteinStructure pulsatrix::ParseMmcif ( std::string_view  text)

Reads mmCIF text: the _atom_site loop, with the same choices as ParsePdb. Chains and residue numbers are the author's (auth_asym_id, auth_seq_id), as in PDB files, so both formats of one entry give the same structure.

Exceptions
std::invalid_argumentfor malformed CIF, an _atom_site loop missing a needed column, or no protein residues.

◆ ParseMorrisDocument()

MorrisDocument pulsatrix::ParseMorrisDocument ( std::string_view  json)

◆ ParseMutationMapDocument()

MutationMapDocument pulsatrix::ParseMutationMapDocument ( std::string_view  json)

◆ ParseMutations()

std::vector< Mutation > pulsatrix::ParseMutations ( std::string_view  text)

Parses a variant, A23G, or several joined by :, A23G:L45P (ProteinGym's format).

Exceptions
std::invalid_argumentfor anything else.

◆ ParseNeuronpediaGraph()

AttributionGraph pulsatrix::ParseNeuronpediaGraph ( std::string_view  json)

Reads a graph written by ToNeuronpediaJson, circuit-tracer or Neuronpedia. Unknown fields are ignored.

Exceptions
std::invalid_argumentfor a missing required field.

◆ ParseNpy()

Tensor pulsatrix::ParseNpy ( const std::vector< uint8_t > &  bytes,
DeviceBackend *  backend 
)

A .npy file as a float32 tensor on backend, with the file's shape.

Reads what numpy writes for a float array: format versions 1.0, 2.0 and 3.0, little-endian float32 (<f4) or float64 (<f8, rounded to float32), in C or Fortran order, with up to 8 dimensions.

Exceptions
std::invalid_argumentfor anything else: another dtype or byte order, a pickled object array, a malformed header, a size that doesn't match the data, or a float64 value too large for float32.

◆ ParsePartialDependenceDocument()

PartialDependenceDocument pulsatrix::ParsePartialDependenceDocument ( std::string_view  json)

◆ ParsePdb()

ProteinStructure pulsatrix::ParsePdb ( std::string_view  text)

Reads PDB-format text: the ATOM records, and the HETATM records of selenomethionine, of the first model.

  • A residue is kept when it has a Cα atom, so nucleic acids and stray atoms are left out.
  • Waters, ions and ligands (other HETATM records) are left out.
  • Of alternate locations, each atom's first is kept.
    Exceptions
    std::invalid_argumentfor a malformed coordinate, or no protein residues.

◆ ParsePersistenceDiagramDocument()

PersistenceDiagramDocument pulsatrix::ParsePersistenceDiagramDocument ( std::string_view  json)

Reads a document ToJson() wrote.

Exceptions
std::invalid_argumentnaming the JSON Pointer of the first problem.

◆ ParseProjectionDocument()

ProjectionDocument pulsatrix::ParseProjectionDocument ( std::string_view  json)

◆ ParseResidueTracksDocument()

ResidueTracksDocument pulsatrix::ParseResidueTracksDocument ( std::string_view  json)

◆ ParseSensitivityDocument()

SensitivityDocument pulsatrix::ParseSensitivityDocument ( std::string_view  json)

◆ ParseSequenceLogoDocument()

SequenceLogoDocument pulsatrix::ParseSequenceLogoDocument ( std::string_view  json)

◆ ParseSeriesDocument()

SeriesDocument pulsatrix::ParseSeriesDocument ( std::string_view  json)
Exceptions
std::invalid_argumentnaming the JSON Pointer of the first problem, including every rule ToJson() checks.

◆ ParseSliceErrorReport()

SliceErrorReport pulsatrix::ParseSliceErrorReport ( std::string_view  json)

Reads a pulsatrix.slice_error.v1 document, as ToJson(SliceErrorReport) writes it.

Exceptions
std::invalid_argumentif it isn't one, or doesn't hold together: no slices, counts that don't sum to n, an error outside its interval, a p-value outside [0, 1] or alpha outside (0, 1).

◆ ParseSobolDocument()

SobolDocument pulsatrix::ParseSobolDocument ( std::string_view  json)

◆ ParseTokenizerJson()

TextTokenizer pulsatrix::ParseTokenizerJson ( std::string_view  json)

Builds the tokenizer a tokenizer.json describes.

Supported components (anything else is refused by name, never approximated):

  • normalizers: NFC, Replace, Prepend, Sequence
  • pre-tokenizers: Split (regex or string pattern, every behavior, invert), Digits, ByteLevel, Metaspace, Sequence
  • models: BPE (merges as "a b" strings or ["a", "b"] pairs, ignore_merges, subword prefix and suffix, unk_token, byte_fallback, fuse_unk; not dropout), WordLevel
  • post-processors: ByteLevel, TemplateProcessing (single sequences), Sequence
  • decoders: ByteLevel, ByteFallback, Fuse, Replace, Strip, Metaspace, Sequence
  • added tokens without lstrip, rstrip or single_word, and with normalized only when there is no normalizer
Exceptions
std::invalid_argumentfor malformed JSON or an unsupported component or option.

◆ ParseTokenRelevanceDocument()

TokenRelevanceDocument pulsatrix::ParseTokenRelevanceDocument ( std::string_view  json)

◆ ParseTrainingLogDocument()

TrainingLogDocument pulsatrix::ParseTrainingLogDocument ( std::string_view  json)

◆ ParseXaiQuestion()

std::optional< XaiQuestion > pulsatrix::ParseXaiQuestion ( std::string_view  text)

◆ ParseXaiReason()

std::optional< XaiReason > pulsatrix::ParseXaiReason ( std::string_view  text)

◆ PcaComponent()

std::vector< float > pulsatrix::PcaComponent ( const Pca &  pca,
int64_t  index 
)

Component index as a unit vector of floats, for SteeringHook(). One standard deviation along it is sqrt(explained_variance[index]), a natural unit for the coefficient.

Exceptions
std::invalid_argumentif index is out of range.

◆ PcaProject()

Tensor pulsatrix::PcaProject ( const Pca &  pca,
const Tensor &  x,
bool  whiten = false 
)

Each row's coordinates on the components: (x - mean) components^T, shape (n, components), on x's backend.

Parameters
whitenDivide each coordinate by its component's standard deviation, so every axis has variance 1 on the fitted data.
Exceptions
std::invalid_argumentif x's rows aren't pca.width wide, or have a NaN or infinity.

◆ PcaReconstruct()

Tensor pulsatrix::PcaReconstruct ( const Pca &  pca,
const Tensor &  scores 
)

The rows that coordinates map back to: mean + scores components, shape (n, width). Projecting and reconstructing keeps only what the components hold.

Exceptions
std::invalid_argumentif scores isn't (n, pca.num_components()), or has a NaN or infinity.

◆ PcaSplitHalfOverlap()

double pulsatrix::PcaSplitHalfOverlap ( const Tensor &  x,
int64_t  k,
uint64_t  seed = 0 
)

Fits k components on each half of the rows, split at random, and returns their SubspaceOverlap(). Near 1 means the k-dimensional picture is a property of the data; well below 1 means it depends on which inputs happened to be drawn.

Exceptions
std::invalid_argumentif x has fewer than 4 rows, or as FitPca() does for each half.

◆ PearsonCorrelation()

double pulsatrix::PearsonCorrelation ( const std::vector< float > &  x,
const std::vector< float > &  y 
)

Pearson correlation of two equal-length vectors; 0 if either is constant.

◆ Percentile()

double pulsatrix::Percentile ( std::vector< double >  values,
double  q 
)

The q-th percentile (0 to 100) with linear interpolation (numpy's default).

◆ PermuteDarkKnowledge()

Tensor pulsatrix::PermuteDarkKnowledge ( const Tensor &  teacher_logits,
uint64_t  seed,
DeviceBackend *  backend 
)

The teacher's logits with each row's non-maximal entries shuffled among themselves by a portable generator seeded with seed: the same result on every platform. The largest entry (the first, if tied) stays in place.

Exceptions
std::invalid_argumentif the rank is below 2.

◆ PersistentEntropy()

double pulsatrix::PersistentEntropy ( const PersistenceDiagram &  diagram)

Persistent entropy (Chintakunta et al. 2015; Rucco et al. 2016): the Shannon entropy, in nats, of the finite points' persistences divided by their sum. 0 for one point; log n for n points of equal persistence; 0 for an empty diagram.

◆ PerSliceError() [1/2]

SliceErrorReport pulsatrix::PerSliceError ( const std::vector< double > &  errors,
const std::vector< std::string > &  slices,
const SliceErrorOptions &  options = {} 
)

The error on each slice of a dataset, each tested against the rest.

Parameters
errorsEach input's error: 0 or 1 for right or wrong, or a loss.
slicesThe slice each input belongs to, such as a group or a data source.
Exceptions
std::invalid_argumentif errors is empty, slices has another length, an error isn't finite, options.test is FisherExact and an error isn't 0 or 1, alpha isn't in (0, 1), or permutations < 1.

◆ PerSliceError() [2/2]

SliceErrorReport pulsatrix::PerSliceError ( const Tensor &  probabilities,
const std::vector< int64_t > &  labels,
const std::vector< std::string > &  slices,
const SliceErrorOptions &  options = {} 
)

A classifier's error rate on each slice: an input is wrong when its most probable class isn't its label.

Exceptions
std::invalid_argumentas EvaluateClassifier() and PerSliceError() do.

◆ Pgd()

AttackResult pulsatrix::Pgd ( const DifferentiableClassifier &  model,
const Tensor &  input,
const std::vector< int64_t > &  labels,
DeviceBackend *  backend,
const AttackOptions &  options = {},
bool  targeted = false 
)

Projected gradient descent: random start, then steps steps, each projected onto the epsilon-ball around the input and into [clip_min, clip_max]. Returns the last iterate.

Exceptions
std::invalid_argumentas Fgsm() does, or if steps < 1 or step_size is negative or not finite.

◆ Plausibility()

float pulsatrix::Plausibility ( const Tensor &  counterfactual,
const std::vector< Tensor > &  background,
const std::vector< float > &  scale = {},
int  k = 5 
)

How typical a counterfactual is of real data: its mean scaled L1 distance to its k nearest instances in background (lower is more plausible), the kNN measure of the CARLA benchmark. A counterfactual far from every real instance may be valid but describe nobody.

Parameters
scalePer-feature scale, as in CounterfactualConstraints; empty means 1.
Exceptions
std::invalid_argumentif background is empty or its shapes differ from the counterfactual's, k < 1, or scale has the wrong length or a non-positive entry.

◆ PolyakUpdate()

void pulsatrix::PolyakUpdate ( Module &  source,
Module &  destination,
float  tau 
)

Soft target-network update (Lillicrap et al. 2016 / Haarnoja et al. 2018): destination_param[i] = tau * source_param[i] + (1 - tau) * destination_param[i], element-wise and in place.

A genuinely different mechanism from SyncTargetNetwork's hard periodic copy, not a rename of it. The hard copy leaves the target network frozen for k steps and then moves it a long way at once; this moves it a little on every step, which is what the off-policy actor-critic algorithms (DDPG/TD3/SAC) depend on for a slowly-drifting bootstrapping target. Both are shipped, neither supersedes the other, and tau is not a flag bolted onto the existing function – the formula, not a mode, is the difference.

Parameters
sourceNetwork to blend parameter values from – typically the online network.
destinationNetwork to blend into – typically the target network.
tauBlending coefficient, in (0, 1]. tau near 0 (SAC's usual 0.005) means the target barely moves per step; tau == 1 degenerates to exactly SyncTargetNetwork's hard copy, which is legal (and directly cross-checked in the tests) though an unusual choice for a soft update.
Exceptions
std::invalid_argumentif tau is not in (0, 1] – external boundary. tau == 0 is rejected rather than accepted as a no-op: a target network that provably never moves is a real caller error (typically an uninitialized hyperparameter), and silently doing nothing forever is the worst possible way to report it. NaN is rejected by the same check.
std::invalid_argumentif the two networks expose a different number of parameters, or if any parameter pair's shapes differ, naming the offending index and shapes – the identical validation SyncTargetNetwork performs, deliberately not weakened. Two independently-constructed networks genuinely can have mismatched architectures, and a silent partial blend would leave the target network quietly wrong for the rest of training. A rejected update leaves the offending parameter untouched.
Note
The blend writes element-wise into destination's existing parameter buffers, never replacing its Tensor objects – the same discipline SyncTargetNetwork established. destination's parameters must remain the same objects its own parameters() (and any optimizer already holding ParamRefs into it) point at. Replacing the Tensors would dangle every outstanding ParamRef. Doubly load-bearing here: a soft update reads the destination's current value as an input, so it is the one place where the destination's buffer identity across successive calls is what makes the exponential moving average an average at all.
Gradients are untouched. This is a pure value blend and has nothing to do with zero_grad(); a target network is never backpropagated through.
Device-generic (GPU-native-kernels Mission 7): one DeviceBackend::rl_rows(PolyakBlend) pass per parameter through the destination parameter's own backend, evaluating tau * source + (1 - tau) * destination per element exactly as the original host loop did. A source parameter on a different device is staged onto the destination's first.

◆ PolynomialMutation()

template<typename RNG >
std::vector< double > pulsatrix::PolynomialMutation ( const std::vector< double > &  genotype,
const std::vector< double > &  lower_bounds,
const std::vector< double > &  upper_bounds,
double  eta,
double  mutation_probability,
RNG &  rng 
)

RNG-driven wrapper: each gene independently mutates (via PolynomialMutationByDraw) with probability mutation_probability.

Exceptions
std::invalid_argumentif genotype/lower_bounds/upper_bounds sizes are not all equal, or mutation_probability is outside [0, 1] – per-gene bound/eta validity is enforced by PolynomialMutationByDraw itself.

◆ PolynomialMutationByDraw()

double pulsatrix::PolynomialMutationByDraw ( double  x,
double  lower,
double  upper,
double  eta,
double  u 
)
inline

Polynomial-mutates a single bounded gene given an explicit draw.

Parameters
xCurrent gene value, must be in [lower, upper].
lowerLower bound (must be strictly less than upper).
upperUpper bound.
etaDistribution index (non-negative; larger values concentrate mutations closer to x).
uDraw in [0, 1].
Returns
The mutated, bound-clipped gene value.
Exceptions
std::invalid_argumentif lower >= upper, x is outside [lower, upper], eta is negative, or u is outside [0, 1].
Note
Three draw values give exact, eta-independent results, all algebraically derivable from the formula: u == 0 -> exactly lower; u == 0.5 -> exactly x (unchanged); u == 1 -> exactly upper. Unlike SimulatedBinaryCrossoverByDraw, this formula has no 1/(1-u) term, so u == 1 is a valid, safe draw here (not excluded).

◆ PowerIteration()

DominantEigenResult pulsatrix::PowerIteration ( const Tensor &  a,
int64_t  max_iterations = 1000,
float  tolerance = 1e-6f,
uint64_t  seed = 0 
)

The dominant eigenpair of a symmetric matrix by power iteration – cheaper than SymmetricEigen() when only the top eigenpair is needed (spectral norm, stable rank).

Parameters
aSquare symmetric (n, n) CPU tensor, all finite.
max_iterationsIteration budget; must be >= 1.
toleranceConverged when successive unit vectors differ (up to sign) by at most this.
seedSeeds the deterministic LCG that draws the starting vector.
Note
Converges at the rate |lambda2 / lambda1|. When the two largest eigenvalues tie in magnitude (e.g. +1 and -1) the dominant vector is not unique: the iteration does not settle and the result reports converged = false rather than an arbitrary answer.
Exceptions
std::invalid_argumentfor the same inputs SymmetricEigen() rejects, a max_iterations below 1, or a tolerance that is not positive.

◆ PrecisionAtL()

ContactPrecisions pulsatrix::PrecisionAtL ( const ContactMap &  predicted,
const ContactMap &  truth,
SeparationRange  range 
)

◆ PredictionIntervals() [1/2]

std::vector< PredictionInterval > pulsatrix::PredictionIntervals ( const ConformalRegressor &  regressor,
const std::vector< double > &  lower,
const std::vector< double > &  upper 
)

The intervals for a quantile regressor's predictions (cqr).

Exceptions
std::invalid_argumentif the regressor isn't CQR's, the two have different lengths, or a value isn't finite.

◆ PredictionIntervals() [2/2]

std::vector< PredictionInterval > pulsatrix::PredictionIntervals ( const ConformalRegressor &  regressor,
const std::vector< double > &  predictions 
)

The intervals for a point regressor's predictions (absolute_residual).

Exceptions
std::invalid_argumentif the regressor is CQR's, or a prediction isn't finite.

◆ PredictionSets()

std::vector< std::vector< int64_t > > pulsatrix::PredictionSets ( const ConformalClassifier &  classifier,
const Tensor &  probabilities 
)

The prediction set of each input: the classes, most probable first.

Parameters
probabilities(N, K), with the K of the calibration.
Exceptions
std::invalid_argumentas CalibrateConformalClassifier() does for probabilities.

◆ ProbabilityOfImprovement()

double pulsatrix::ProbabilityOfImprovement ( double  mean,
double  variance,
double  best_value,
double  xi = 0.01 
)
inline

Probability of Improvement: P(candidate's value > best_value + xi) under the posterior N(mean, variance).

Exceptions
std::invalid_argumentif variance < 0.
Note
If sigma is ~0, PI is defined as the degenerate limit: 1 if mean already exceeds best_value + xi, else 0.

◆ ProcessLogits()

void pulsatrix::ProcessLogits ( std::vector< float > &  logits,
const std::vector< int64_t > &  tokens,
int64_t  num_new_tokens,
const GenerationConfig &  config 
)

Applies the configured logit processing, in Hugging Face's order: repetition penalty, the EOS ban before min_new_tokens, then (when sampling) temperature, top-k, top-p and min-p. Removed tokens get -infinity. With do_sample false only the first two apply.

Parameters
tokensThe sequence so far (for the repetition penalty).
num_new_tokensHow many tokens have been generated so far (for min_new_tokens).
Exceptions
std::invalid_argumentfor an invalid config.

◆ ProjectorMetadataTsv()

std::string pulsatrix::ProjectorMetadataTsv ( const std::vector< MetadataColumn > &  columns)

The Embedding Projector's metadata file: a line per point, a column per entry of columns, separated by tabs.

With two or more columns the first line holds their names, as the projector expects; with one, it doesn't, since the projector would read the name as a point. Tabs and line breaks in a value or name are replaced by spaces.

Exceptions
std::invalid_argumentif there are no columns, or they hold different numbers of values.

◆ ProjectorVectorsTsv()

std::string pulsatrix::ProjectorVectorsTsv ( const Tensor &  x)

The Embedding Projector's tensor file: a line per row of x, its values separated by tabs. Dimensions after the first are flattened.

Note
Values are written with 9 significant digits, enough to read back the same float32.
Exceptions
std::invalid_argumentif x has rank below 2 or a NaN or infinite value, which the projector can't read.

◆ ProtoDash()

ProtoDashResult pulsatrix::ProtoDash ( const std::vector< Tensor > &  source,
const std::vector< Tensor > &  target,
const ProtoDashOptions &  options = {} 
)

ProtoDash: chooses up to options.count points of source, with weights, whose weighted kernel mean best matches the kernel mean of target (an MMD criterion).

Greedy, as in the paper: each step adds the source point with the largest gradient of l(w) = w'mu - w'Kw/2, where mu_j is point j's mean kernel similarity to the target and K the kernel between source points, then re-fits the weights of the chosen points under w >= 0. It stops early when no point would raise the objective. Use the same set for both to summarize a dataset; a target of one class and a source of all data to find what represents that class.

Exceptions
std::invalid_argumentif either set is empty, the sizes differ, count < 1 or sigma < 0.

◆ PruneLinks()

void pulsatrix::PruneLinks ( AttributionGraph &  graph,
double  edge_threshold 
)

Keeps the fewest links, largest |weight| first, whose |weight| sums to at least edge_threshold of the total; ties keep their order. Links into a logit node are always kept.

Exceptions
std::invalid_argumentunless 0 < edge_threshold <= 1.

◆ QR()

QRResult pulsatrix::QR ( const Tensor &  a)

Thin QR factorization by Householder reflections.

Parameters
a(m, n) CPU tensor with m >= n, all finite. Rank-deficient input is fine.
Exceptions
std::invalid_argumentif a is not rank 2, is wide (m < n), is not on the CPU, or has a non-finite entry.

◆ QualityFitness()

float pulsatrix::QualityFitness ( const Tensor &  logits)
inline

E-GAN's own quality fitness Fq: mean sigmoid(D(fake)) over the batch – how convincingly "real" the discriminator currently rates these samples. Higher is better (the discriminator being fooled more).

◆ QuestionText()

std::string_view pulsatrix::QuestionText ( XaiQuestion  question)

The question as Liao et al. phrase it, for example "Why is this instance given this prediction?".

◆ RandomizationCheck()

RandomizationCheckResult pulsatrix::RandomizationCheck ( EncoderExplainer &  explainer,
std::string_view  sequence,
const EncoderTarget &  target,
uint64_t  seed = 0 
)

Cascading model randomization (Adebayo et al. 2018) over the encoder's own layers, top down: the LM head, then each layer from the last to the first, then the embeddings. Each step redraws the group's weight matrices (Gaussian, each with its own standard deviation) and re-explains. Norm gains and biases are kept: redrawn from their own small spread, a pre-LN block's gains shrink toward zero and the block becomes its residual connection, which would hide the randomization. The model's parameters are restored before returning.

Note
A copy of every parameter is held while it runs.

◆ RandomSample()

template<typename RNG >
Configuration pulsatrix::RandomSample ( const SearchSpace &  space,
RNG &  rng 
)

Draws one configuration uniformly at random from space: Continuous parameters uniform over [lower, upper]; LogUniform parameters uniform in log-space (so e.g. [0.001, 1.0] gives 0.001-0.01, 0.01-0.1, and 0.1-1.0 equal probability, not the top decade 90% of the draws); Integer parameters uniform over the inclusive integer range; Categorical parameters uniform over the category list.

◆ RangeBounds()

SensitivityBounds pulsatrix::RangeBounds ( const std::vector< Tensor > &  background,
float  lower_percentile = 0.05f,
float  upper_percentile = 0.95f 
)

Each feature's lower and upper percentile over background (linear interpolation, as numpy.percentile): the classic tornado-diagram range, a typical low and high value.

Exceptions
std::invalid_argumentif background is empty, its shapes differ, or the percentiles aren't 0 <= lower < upper <= 1.

◆ RankContactHeads()

std::vector< HeadPrecision > pulsatrix::RankContactHeads ( ContactPredictor &  predictor,
const std::vector< LabeledProtein > &  proteins,
SeparationRange  range = kLongRange 
)

Every head, best first, by its features' mean precision at L in range over proteins. The top K make an unsupervised predictor with ContactPredictor::average_heads (arXiv 2606.21876 chooses them with 10 labeled proteins). Choose heads on proteins you won't evaluate on.

Exceptions
std::invalid_argumentfor no proteins, or a contact map that doesn't fit its sequence.

◆ RankSelect()

template<typename Genotype , typename FitnessT , typename RNG >
size_t pulsatrix::RankSelect ( const std::vector< Individual< Genotype, FitnessT > > &  population,
RNG &  rng 
)

RNG-driven wrapper around RankSelectByDraw: draws uniformly from [0, total_weight) and selects accordingly.

Exceptions
std::invalid_argument– see RankSelectByDraw.

◆ RankSelectByDraw()

template<typename Genotype , typename FitnessT >
size_t pulsatrix::RankSelectByDraw ( const std::vector< Individual< Genotype, FitnessT > > &  population,
double  draw 
)

Linear-rank selection given an explicit draw in [0, total_weight). Individuals are ranked ascending by fitness (worst = rank 1, best = rank population.size()); each rank's selection weight equals its rank, so the best individual is population.size() times as likely to be drawn as the worst. Pure and deterministic – the hand-testable core RankSelect wraps with an RNG-generated draw.

Parameters
populationNon-empty population.
drawA value in [0, total_weight), where total_weight = n*(n+1)/2 for n individuals.
Returns
Index into population of the individual occupying the drawn rank.
Exceptions
std::invalid_argumentif population is empty or draw is outside [0, total_weight).

◆ ReadAnnotatedProteins()

std::vector< AnnotatedProtein > pulsatrix::ReadAnnotatedProteins ( const std::string &  path)

ParseAnnotatedProteins on a file.

Exceptions
std::runtime_errorif it can't be read.

◆ ReadDmsVariants()

DmsVariants pulsatrix::ReadDmsVariants ( const std::string &  path)

Reads an assay's CSV.

Exceptions
std::runtime_error/ std::invalid_argument as above.

◆ ReadEsmConfig()

EncoderLMConfig pulsatrix::ReadEsmConfig ( const std::string &  path)

ParseEsmConfig on a file.

Exceptions
std::runtime_errorif it can't be read.

◆ ReadFasta()

std::vector< FastaRecord > pulsatrix::ReadFasta ( const std::string &  path)

ParseFasta on a file.

Exceptions
std::runtime_errorif it can't be read.

◆ ReadHfConfig()

HfModelConfig pulsatrix::ReadHfConfig ( const std::string &  path)

ParseHfConfig on a file.

Exceptions
std::runtime_errorif it can't be read.

◆ ReadJsonl()

std::vector< JsonValue > pulsatrix::ReadJsonl ( const std::string &  path)

Reads a JSONL file: one JSON value a line. Blank lines are skipped.

Exceptions
std::runtime_errorif the file can't be read, naming the line that doesn't parse.

◆ ReadNpy()

Tensor pulsatrix::ReadNpy ( const std::string &  path,
DeviceBackend *  backend 
)

ParseNpy() of the file at path.

Exceptions
std::runtime_errorif the file can't be read; otherwise as ParseNpy().

◆ ReadProteinGymReference()

std::vector< ProteinGymAssay > pulsatrix::ReadProteinGymReference ( const std::string &  path)

Every assay in a reference file.

Exceptions
std::runtime_errorif it can't be read; std::invalid_argument if a needed column is missing.

◆ ReadStructure()

ProteinStructure pulsatrix::ReadStructure ( const std::string &  path)

Reads a structure file: mmCIF for .cif or .mmcif, PDB format otherwise (.pdb, .ent).

Exceptions
std::runtime_errorif it can't be read; what ParsePdb or ParseMmcif throws.

◆ ReasonText()

std::string_view pulsatrix::ReasonText ( XaiReason  reason)

One sentence on the reason.

◆ ReconstructionSeed()

std::vector< float > pulsatrix::ReconstructionSeed ( const std::vector< float > &  sample,
const std::vector< float > &  reference 
)

The reconstruction error ||x_0 - reference||^2, as LRP for autoencoders seeds it (Kobayashi et al. 2023): relevance (x0_i - ref_i)^2 on each element.

Exceptions
std::invalid_argumentif the sizes differ.

◆ RegionSeed()

std::vector< float > pulsatrix::RegionSeed ( const std::vector< float > &  sample,
const std::vector< int64_t > &  region 
)

The sum of sample over region: relevance x0_i on the region's elements, 0 elsewhere.

Exceptions
std::invalid_argumentfor an index outside the sample.

◆ ReinitializeParameters()

void pulsatrix::ReinitializeParameters ( Module &  model,
uint64_t  seed,
const std::string &  prefix = "" 
)

Replaces each parameter tensor with Gaussian noise of mean 0 and that tensor's own standard deviation, from a portable generator seeded by seed.

Parameters
prefixOnly parameters named prefix or under it (dot boundaries); empty means all.
Note
Keeps each tensor's scale, so activations stay in a realistic range. A tensor whose values are all equal (a zero bias, say) has standard deviation 0 and becomes all zeros. Buffers, such as BatchNorm's running statistics, are left alone.

◆ release_tensor()

void pulsatrix::release_tensor ( Tensor &  t)
inline

Frees t's buffer: it becomes an empty tensor on the same backend and device.

◆ RelevanceProfile()

std::vector< float > pulsatrix::RelevanceProfile ( EncoderExplainer &  explainer,
std::string_view  sequence,
const std::function< void(int64_t done, int64_t total)> &  progress = {} 
)

How much the model draws on each residue when it predicts the others: the mean, over every residue's masked wild-type logit (EncoderTarget::MaskedToken), of each residue's share of the explanation's total |relevance|. A per-protein explanation to compare with per-residue signals such as DMS sensitivity or conservation.

Note
Cost: one explanation per residue. progress, if set, is called after each.

◆ RemoveIA3()

void pulsatrix::RemoveIA3 ( Module &  model)

Removes every vector; merged ones stay in the weights.

◆ RemoveLora()

void pulsatrix::RemoveLora ( Module &  model)

Removes every adapter. Merged ones stay in the weights (PEFT's merge_and_unload() is MergeLora() then this); unmerged ones are dropped (PEFT's unload()).

◆ RenderBarChartHtml()

std::string pulsatrix::RenderBarChartHtml ( const AttributionDocument &  doc,
int  top_k = 10,
const HtmlOptions &  options = {} 
)

◆ RenderBarChartSvg()

std::string pulsatrix::RenderBarChartSvg ( const AttributionDocument &  doc,
int  top_k = 10,
const SvgOptions &  options = {} 
)

Horizontal bars of the top_k features with the largest |attribution|, largest first, on an axis through zero, each colored by its signed value and labeled with it. Labels come from metadata["feature_names"] (comma-separated) when present.

Exceptions
std::invalid_argumentfor the same inputs ToFeatureImportanceBars rejects, a non-finite value, or options with width < 200 or font_size < 1.

◆ RenderBarcodeSvg()

std::string pulsatrix::RenderBarcodeSvg ( const PersistenceDiagramDocument &  doc,
const PersistenceViewOptions &  view = {},
const SvgOptions &  options = {} 
)

One bar per feature, from its birth to its death, grouped by dimension and longest first. Each end has a whisker of ±the certified error bound; essential bars end in an arrow. Features that failed an attached test are drawn faint.

Exceptions
std::invalid_argumentas RenderPersistenceDiagramSvg() does, or if max_bars < 1.

◆ RenderBeeswarmHtml()

std::string pulsatrix::RenderBeeswarmHtml ( const std::vector< AttributionDocument > &  docs,
const std::vector< int64_t > &  feature_indices,
const HtmlOptions &  options = {} 
)

◆ RenderBeeswarmSvg()

std::string pulsatrix::RenderBeeswarmSvg ( const std::vector< AttributionDocument > &  docs,
const std::vector< int64_t > &  feature_indices,
const SvgOptions &  options = {} 
)

One beeswarm row per feature in feature_indices: each point is one document's value for that feature, placed by value on a shared axis through zero, spread vertically so points don't overlap (ToBeeswarmPoints's deterministic layout), and colored by value. Labels come from the first document's metadata["feature_names"] when present.

Parameters
docsAttributions of the same shape for different inputs.
Exceptions
std::invalid_argumentif docs or feature_indices is empty, a feature index is out of range for any document, a value is non-finite, or for invalid options.

◆ RenderBettiCurveSvg()

std::string pulsatrix::RenderBettiCurveSvg ( const PersistenceDiagramDocument &  doc,
const PersistenceViewOptions &  view = {},
const SvgOptions &  options = {} 
)

The Betti curve of each dimension: how many features are alive at each scale (BettiCurve()).

Note
The curve isn't covered by the error bound: features near the diagonal can appear or vanish under a small change in the distances, and the figure says so.
Exceptions
std::invalid_argumentas RenderPersistenceDiagramSvg() does, or if grid_points < 2.

◆ RenderContactMapHtml()

std::string pulsatrix::RenderContactMapHtml ( const ContactMapDocument &  doc,
const ContactMapViewOptions &  view = {},
const HtmlOptions &  options = {} 
)

◆ RenderContactMapSvg()

std::string pulsatrix::RenderContactMapSvg ( const ContactMapDocument &  doc,
const ContactMapViewOptions &  view = {},
const SvgOptions &  options = {} 
)

A contact map: one square, residue against residue. Above the diagonal, the predicted scores (white to dark blue). Below it, the true contacts in gray, and the L best-scored pairs at least min_separation apart as dots: blue where the structure has a contact, red where it doesn't, hollow where it's unknown. A caption gives the precision at L for those pairs and for long-range ones (24 apart and more), as ContactPrecision computes it. Without a structure, the lower triangle shows the dots alone.

Exceptions
std::invalid_argumentfor a document ToJson rejects, min_separation < 1, or unusable options.

◆ RenderCounterfactualHtml()

std::string pulsatrix::RenderCounterfactualHtml ( const CounterfactualDocument &  doc,
int  max_rows = 12,
const HtmlOptions &  options = {} 
)

◆ RenderCounterfactualSetHtml()

std::string pulsatrix::RenderCounterfactualSetHtml ( const std::vector< CounterfactualDocument > &  docs,
const HtmlOptions &  options = {} 
)

◆ RenderCounterfactualSetSvg()

std::string pulsatrix::RenderCounterfactualSetSvg ( const std::vector< CounterfactualDocument > &  docs,
const SvgOptions &  options = {} 
)

Several counterfactuals of one input side by side (CFS-7): a column for the input and one per counterfactual (headed by whether it reaches the target), and a row for every feature that at least one of them changes. Changed values are on a background colored by the change's direction and size in scale units; unchanged ones are blank.

Exceptions
std::invalid_argumentif docs is empty, the documents describe different inputs (feature names or original values differ), a value is non-finite, or the options are unusable.

◆ RenderCounterfactualSvg()

std::string pulsatrix::RenderCounterfactualSvg ( const CounterfactualDocument &  doc,
int  max_rows = 12,
const SvgOptions &  options = {} 
)

What a counterfactual changed: a verdict line (whether it reaches the target, and the output before and after), then one row per changed feature, costliest first, with its old and new value and a bar of its change in units of its scale, colored by direction. A feature counts as changed when it moved by more than 1e-3 of its scale.

Parameters
max_rowsAt most this many changed features are listed; a line says how many more.
Exceptions
std::invalid_argumentfor a non-finite value, max_rows < 1, or unusable options.

◆ RenderFeatureDashboardHtml() [1/2]

std::string pulsatrix::RenderFeatureDashboardHtml ( const FeatureDashboardDocument &  doc,
const HtmlOptions &  options = {},
const std::string &  extra_html = "" 
)

The feature's statistics, its activation histogram, and its top examples with each token shaded by its activation. extra_html is appended as is, such as a structure panel (StructurePanelHtml, PLM-8).

◆ RenderFeatureDashboardHtml() [2/2]

std::string pulsatrix::RenderFeatureDashboardHtml ( const FeatureDashboardDocument &  doc,
const std::string &  structure,
const std::string &  chain,
size_t  example,
const HtmlOptions &  options = {} 
)

A feature dashboard (RenderFeatureDashboardHtml) with a structure panel (PLM-8): top example example drawn on structure's chain, colored by the feature's activation. The example's tokens must be single residues matching the chain one for one, as an AlphaFold DB model of the protein does.

Exceptions
std::invalid_argumentfor no such example, tokens that aren't residues, or what StructurePanelHtml throws.

◆ RenderHeatmapHtml()

std::string pulsatrix::RenderHeatmapHtml ( const HeatmapDocument &  doc,
const HtmlOptions &  options = {} 
)

◆ RenderHeatmapSvg()

std::string pulsatrix::RenderHeatmapSvg ( const HeatmapDocument &  doc,
const SvgOptions &  options = {} 
)

The heatmap's grid with square cells and a color bar. Signed grids use the diverging map on a range symmetric about zero, unsigned grids Viridis on [0, max] (ComputeHeatmapColorScale's rule). Non-finite cells are gray and left out of the scale. Row and column labels are drawn when the document has them.

Note
Grids up to 4096 cells are drawn as one rectangle per cell. Larger grids, such as a 224 x 224 saliency map, are embedded as a lossless PNG image drawn with sharp pixel edges, which keeps the file small.
Exceptions
std::invalid_argumentif the document is inconsistent (see ToJson) or empty, or for invalid options.

◆ RenderMorrisHtml()

std::string pulsatrix::RenderMorrisHtml ( const MorrisDocument &  doc,
const HtmlOptions &  options = {} 
)

◆ RenderMorrisSvg()

std::string pulsatrix::RenderMorrisSvg ( const MorrisDocument &  doc,
const SvgOptions &  options = {} 
)

Morris screening as a scatter of mu* (importance) against sigma (how much the effect varies), one labeled point per feature with a horizontal bar for mu*'s confidence interval. Points above the dashed line sigma = mu* have effects that vary more than their average: nonlinear, or interacting with other features.

Exceptions
std::invalid_argumentfor an empty document, a non-finite or negative mu*, sigma or confidence half-width, or unusable options.

◆ RenderMutationMapHtml()

std::string pulsatrix::RenderMutationMapHtml ( const MutationMapDocument &  doc,
const HtmlOptions &  options = {} 
)

◆ RenderMutationMapSvg()

std::string pulsatrix::RenderMutationMapSvg ( const MutationMapDocument &  doc,
const SvgOptions &  options = {} 
)

A mutation map: a row per letter of the alphabet, a column per residue, each cell colored by its score (diverging, scaled to the largest |score|). The wild type's cell has a dot, and the sequence runs along the top. Unscored cells are gray.

Note
Up to 12,000 cells are drawn as one rectangle each, with a tooltip such as K11R: -2.31; larger maps are drawn as images, without tooltips.
Exceptions
std::invalid_argumentfor a document ToJson rejects, or unusable options.

◆ RenderPartialDependenceHtml()

std::string pulsatrix::RenderPartialDependenceHtml ( const PartialDependenceDocument &  doc,
const PartialDependenceSvgOptions &  pd = {},
const HtmlOptions &  options = {} 
)

◆ RenderPartialDependenceSvg()

std::string pulsatrix::RenderPartialDependenceSvg ( const PartialDependenceDocument &  doc,
const PartialDependenceSvgOptions &  pd = {},
const SvgOptions &  options = {} 
)

A partial dependence plot: thin ICE curves under the bold average, over the feature's grid, with a rug of the instances' own feature values along the bottom. For IceStyle::Centered and IceStyle::Derivative the average is recomputed from the transformed curves, and a dashed line marks zero.

Exceptions
std::invalid_argumentfor a document ToJson rejects, a non-finite value, a style other than Raw for a document without ICE curves, negative max_curves, or unusable options.

◆ RenderPersistenceDiagramSvg()

std::string pulsatrix::RenderPersistenceDiagramSvg ( const PersistenceDiagramDocument &  doc,
const PersistenceViewOptions &  view = {},
const SvgOptions &  options = {} 
)

Birth against death, one point per feature. Points far above the diagonal persist long. A shaded band along the diagonal marks persistence within twice the certified error bound, which the distances' own error could explain. Essential features sit on a dashed line marked ∞. When tests are attached, significant features are filled and the others hollow; a bootstrap band is drawn as a dashed line parallel to the diagonal.

Exceptions
std::invalid_argumentfor a document ToJson() rejects, a dimension it doesn't hold, or unusable options.

◆ RenderProjectionHtml()

std::string pulsatrix::RenderProjectionHtml ( const ProjectionDocument &  doc,
const HtmlOptions &  options = {} 
)

◆ RenderProjectionSvg()

std::string pulsatrix::RenderProjectionSvg ( const ProjectionDocument &  doc,
int  x_axis = 0,
int  y_axis = 1,
const SvgOptions &  options = {} 
)

A projection as a scatter plot of two of its axes (INT-5), both on one scale so distances on the page are distances in the projection. Points are colored by group with a legend, else by value on Viridis with a color bar (gray where a value isn't finite), and each has a tooltip with its label and coordinates. Lines mark zero, the mean of a PCA.

Parameters
x_axis,y_axisWhich of the document's axes to plot: PC1 against PC2 by default. For a third dimension, draw the other pairs too.
Exceptions
std::invalid_argumentfor a document ToJson() rejects, one with no points, or axes that aren't two different axes of the document.

◆ RenderReliabilityDiagramSvg() [1/2]

std::string pulsatrix::RenderReliabilityDiagramSvg ( const ClassificationReport &  report,
const SvgOptions &  options = {} 
)

The diagram of one classifier.

◆ RenderReliabilityDiagramSvg() [2/2]

std::string pulsatrix::RenderReliabilityDiagramSvg ( const std::vector< ReliabilitySeries > &  series,
const SvgOptions &  options = {} 
)

A reliability diagram (Guo et al., ICML 2017): each confidence bin's accuracy against its mean confidence, one line per classifier. A calibrated classifier lies on the diagonal; points below it are overconfident, above it underconfident. The marks grow with the bin's share of the inputs, and a strip below shows that share, since a bin of three inputs can sit far from the diagonal by chance. The legend gives each one's ECE.

Exceptions
std::invalid_argumentif there are no series, more than 10, a report has no reliability bins, or the options are unusable.

◆ RenderResidueTracksHtml()

std::string pulsatrix::RenderResidueTracksHtml ( const ResidueTracksDocument &  doc,
const HtmlOptions &  options = {} 
)

◆ RenderResidueTracksSvg()

std::string pulsatrix::RenderResidueTracksSvg ( const ResidueTracksDocument &  doc,
const SvgOptions &  options = {} 
)

Residue tracks: a ruler and the sequence, then a row of colored cells per track (signed tracks diverging around zero, others Viridis from their minimum or zero), then a row of labeled spans per feature category. Each track has its own scale, shown in a legend.

Exceptions
std::invalid_argumentfor a document ToJson rejects, or unusable options.

◆ RenderSequenceLogoHtml()

std::string pulsatrix::RenderSequenceLogoHtml ( const SequenceLogoDocument &  doc,
const HtmlOptions &  options = {} 
)

◆ RenderSequenceLogoSvg()

std::string pulsatrix::RenderSequenceLogoSvg ( const SequenceLogoDocument &  doc,
const SvgOptions &  options = {} 
)

A sequence logo: at each position, the letters stacked to the position's information content in bits (InformationContent), each as tall as its share, the likeliest on top. Letters are colored by chemistry, as WebLogo does: hydrophobic black, polar green, amide purple, basic blue, acidic red. The sequence's own letters run underneath.

Note
Letters are bold sans-serif text stretched to their box, so a glyph's ink fills it to within a few percent depending on the installed font (Helvetica, Arial or Liberation Sans).
Exceptions
std::invalid_argumentfor a document ToJson rejects, or unusable options.

◆ RenderSeriesHtml()

std::string pulsatrix::RenderSeriesHtml ( const SeriesDocument &  doc,
const SeriesViewOptions &  view = {},
const HtmlOptions &  options = {} 
)

◆ RenderSeriesSvg()

std::string pulsatrix::RenderSeriesSvg ( const SeriesDocument &  doc,
const SeriesViewOptions &  view = {},
const SvgOptions &  options = {} 
)

The panels stacked top to bottom, each a line per series with a marker per point and a whisker per interval; one legend for all panels. Every marker has a tooltip with its values.

Note
On a log axis every value must be positive, except that a lower interval bound at or below zero runs the whisker to the bottom of the axis.
Exceptions
std::invalid_argumentfor an invalid document (see ToJson()), a non-finite value, a value that can't go on a log axis, or options with width < 200 or font_size < 1.

◆ RenderSliceErrorSvg()

std::string pulsatrix::RenderSliceErrorSvg ( const SliceErrorReport &  report,
const SliceErrorViewOptions &  view = {},
const SvgOptions &  options = {} 
)

The error on each slice, worst first: a point with its interval, the error of the whole dataset as a dashed line, and each slice's p-value. Slices worse than the rest, after Bonferroni's correction, are red.

Exceptions
std::invalid_argumentif the report has no slices, max_slices < 1, the reference is infinite or negative, or the options are unusable.

◆ RenderSobolHtml()

std::string pulsatrix::RenderSobolHtml ( const SobolDocument &  doc,
int  top_k = 10,
const HtmlOptions &  options = {} 
)

◆ RenderSobolSvg()

std::string pulsatrix::RenderSobolSvg ( const SobolDocument &  doc,
int  top_k = 10,
const SvgOptions &  options = {} 
)

Sobol indices: one row per feature, the top_k with the largest total order first, with a bar for the first-order index, a lighter bar for the total-order index behind it, and whiskers for both confidence intervals. The gap between the two bars is the share of variance the feature explains only through interactions.

Exceptions
std::invalid_argumentfor an empty document, a non-finite value, top_k < 1, or unusable options.

◆ RenderStructureHtml()

std::string pulsatrix::RenderStructureHtml ( const std::string &  structure,
const std::string &  chain,
const ResidueTracksDocument &  tracks,
const HtmlOptions &  options = {} 
)

A 3D structure, drawn as a cartoon with 3Dmol.js, with the residues of chain colored by one of tracks' tracks at a time (a menu switches between them). Hovering a residue shows its name, number and value. Other chains are light gray, ligands are sticks, and water is hidden.

Track values reach residues through ResidueTracksDocument::residue_ids when it has them; without them, the chain's residues (ProteinStructure's reading of the file) must have the tracks' sequence, one for one.

Parameters
structureThe text of a PDB or mmCIF file (mmCIF when it starts with data_), embedded in the page.
optionsHtmlScripts::Cdn loads 3Dmol.js from jsDelivr, pinned and checked with a Subresource Integrity hash; HtmlScripts::Inline copies 3Dmol-min.js from script_dir (tools/render/fetch_vega.sh downloads it).
Note
Insertion codes are matched in PDB files only: 3Dmol.js doesn't read them from mmCIF.
Exceptions
std::invalid_argumentif the structure can't be read, has no chain chain, a residue id isn't in the chain, the sequences don't match, or tracks has no track; std::runtime_error if inline scripts can't be read.

◆ RenderTokenRelevanceHtml()

std::string pulsatrix::RenderTokenRelevanceHtml ( const TokenRelevanceDocument &  doc,
const HtmlOptions &  options = {} 
)

The text with each piece (token or word) on a background colored by its relevance, as plain HTML with no scripts: the browser lays out and shapes the text, so every script reads correctly (right-to-left, joined Arabic, Indic conjuncts), and wraps it. Hovering a piece shows its score; unscored pieces are plain text. Scripts option is ignored.

Exceptions
std::invalid_argumentfor the problems RenderTokenStripSvg rejects.

◆ RenderTokenStripSvg()

std::string pulsatrix::RenderTokenStripSvg ( const TokenRelevanceDocument &  doc,
const SvgOptions &  options = {} 
)

The text's pieces (tokens or words) in reading order, wrapped across lines, each on a background colored by its relevance (diverging, scaled to the largest |relevance|). Pieces are drawn in a monospace font, so their widths are exact, with whitespace kept. Unscored pieces (context such as the spaces between words) are plain text and don't count toward the scale; non-finite relevance is drawn gray. The target and the unassigned relevance, when set, are shown after the text.

Exceptions
std::invalid_argumentif tokens and relevance (or scored) differ in length, there are no tokens, or for invalid options.

◆ RenderTornadoHtml()

std::string pulsatrix::RenderTornadoHtml ( const SensitivityDocument &  doc,
int  top_k = 10,
const HtmlOptions &  options = {} 
)

◆ RenderTornadoSvg()

std::string pulsatrix::RenderTornadoSvg ( const SensitivityDocument &  doc,
int  top_k = 10,
const SvgOptions &  options = {} 
)

A tornado chart: one row per feature, the top_k with the largest swing first. Each row has two bars from the unchanged output, one to the output at the feature's high value (red) and one to its low value (blue), labeled with those values; a dashed line marks the unchanged output.

Exceptions
std::invalid_argumentfor an empty document, a non-finite value, top_k < 1, or unusable options.

◆ RenderTrainingLogHtml()

std::string pulsatrix::RenderTrainingLogHtml ( const TrainingLogDocument &  doc,
const HtmlOptions &  options = {} 
)

◆ RenderWaterfallHtml()

std::string pulsatrix::RenderWaterfallHtml ( const AttributionDocument &  doc,
float  baseline_value,
const HtmlOptions &  options = {} 
)

◆ RenderWaterfallSvg()

std::string pulsatrix::RenderWaterfallSvg ( const AttributionDocument &  doc,
float  baseline_value,
const SvgOptions &  options = {} 
)

A waterfall from baseline_value through each feature's contribution, in the document's feature order, to the final value: red columns raise the running total, blue columns lower it, with the baseline and the final value marked.

Exceptions
std::invalid_argumentfor the same inputs ToWaterfallSteps rejects, a non-finite value or baseline, or invalid options.

◆ ReplayCommitmentValue()

double pulsatrix::ReplayCommitmentValue ( const DenoiserFn &  model,
const MaskedDiffusionResult &  trajectory,
const std::vector< int64_t > &  input,
const MaskedDiffusionConfig &  config,
const std::vector< CommitmentTarget > &  targets,
const std::vector< int64_t > &  skipped = {} 
)

The explained value on a replay (ReplayMaskedDiffusion): each target's logit at the step that wrote it in trajectory, for the token the trajectory wrote there (or the target's fixed token), summed. A target in skipped still counts at that step.

Exceptions
std::invalid_argumentas ReplayMaskedDiffusion, or for a target the trajectory didn't write.

◆ ReplayMaskedDiffusion()

MaskedDiffusionResult pulsatrix::ReplayMaskedDiffusion ( const DenoiserFn &  model,
const MaskedDiffusionResult &  trajectory,
const std::vector< int64_t > &  input,
const MaskedDiffusionConfig &  config,
const std::vector< int64_t > &  skipped = {} 
)

Reruns trajectory from input with its write order frozen: each step writes the same positions as before, each taking the model's most likely allowed token for the new sequence (greedy, as explanation runs are). Positions in skipped are never written, and a position input masks that the trajectory never wrote (a deleted prompt token) stays masked, so the result may keep mask tokens.

Parameters
configOnly mask_token_id and suppressed_token_ids are used.
Exceptions
std::invalid_argumentif input's length differs from the trajectory's, or the model's output doesn't fit.

◆ ReplayTrainingLog()

void pulsatrix::ReplayTrainingLog ( const TrainingLogDocument &  doc,
MetricsSink &  sink 
)

Logs every scalar in doc to sink in the order recorded, then every histogram (at step 0, since the log keeps only the latest one), so any sink can show a saved run: an ImPlotMetricsSink for the training dashboard, for example.

Exceptions
std::invalid_argumentfor the same problems ToJson rejects.

◆ ReportExplanation()

Explanation pulsatrix::ReportExplanation ( const ExplanationRequest &  request,
std::optional< Attribution >  attribution,
std::vector< CheckResult >  checks 
)

The report for an explanation whose checks ran elsewhere: plans request.question and request.reason, matches checks to the planned ones by name (each takes the planned priority), marks the planned checks missing from checks NotRun, and derives the caveats.

Parameters
attributionWhat the explainer returned; empty for explainers that don't return an attribution. request.target, baseline and dataset aren't used.
Exceptions
std::invalid_argumentif request.method isn't in the catalog or doesn't answer request.question.

◆ RepresentationalDissimilarity()

Rdm pulsatrix::RepresentationalDissimilarity ( const Tensor &  x,
RdmMetric  metric = RdmMetric::Correlation 
)

The RDM of a representation, shape (n, ...): a row per input, later dimensions flattened.

Note
Computed in double precision on the host. Correlation and cosine distances are clipped to [0, 2], as scipy clips them, so rounding can't make them negative.
Exceptions
std::invalid_argumentif x has rank below 2, fewer than 3 rows, or a NaN or infinite value, or if a row is constant (for Correlation) or zero (for Cosine), where the distance is undefined.

◆ ReproduceOffspring()

template<typename RNG >
NEATGenome pulsatrix::ReproduceOffspring ( const NEATGenome &  parent,
InnovationTracker &  tracker,
RNG &  rng,
double  weight_mutation_sigma,
double  weight_mutation_probability,
double  add_connection_probability,
double  add_node_probability 
)

RNG-driven wrapper: clones parent, then applies weight mutation (gated per-connection by weight_mutation_probability inside MutateWeights itself) and, independently, one attempt each at the two structural mutations, each gated by its own probability.

◆ require_device()

void pulsatrix::require_device ( const Tensor &  t,
DeviceType  expected,
const char *  where 
)
inline

Throws unless t lives on expected – the check every module and loss runs on the tensors handed to it (roadmap FND-8, gpu_review #1).

Parameters
whereNames the entry point in the error message, e.g. "LinearModule::backward".
Exceptions
std::invalid_argumenton a mismatch. Without it, a CPU tensor reaching a GPU kernel is an uncatchable memory fault (HSA abort on gfx1151, a sticky CUDA error), and a GPU tensor reaching the CPU backend segfaults.

◆ ResidueDistances()

ContactMap pulsatrix::ResidueDistances ( const StructureChain &  chain,
ContactAtom  atom = ContactAtom::Beta 
)

Distances between the residues of chain, in Ångström, L x L for its L residues. A residue missing the atoms atom needs gives NaN in its row and column.

◆ ResidueIds()

std::vector< std::string > pulsatrix::ResidueIds ( const StructureChain &  chain)

chain's residue ids, for ResidueTracksDocument::residue_ids.

◆ ResidueMask()

Tensor pulsatrix::ResidueMask ( const Tensor &  ids,
const Tensor *  keep,
const TextTokenizer &  tokenizer,
DeviceBackend *  backend 
)

The residue mask for SequenceHead::Pooling::Mean from token ids and a padding mask (or none): 1 for every real token that isn't <cls> or <eos>.

◆ RestoreParameters()

void pulsatrix::RestoreParameters ( Module &  module,
const std::vector< float > &  flat 
)
inline

Overwrites every parameter tensor module.parameters() reports (in that order) from flat – the inverse of FlattenParameters.

Exceptions
std::invalid_argumentif flat's size doesn't exactly match the total parameter count module.parameters() reports.

◆ RobustAccuracyCurve()

RobustnessCurve pulsatrix::RobustAccuracyCurve ( const DifferentiableClassifier &  model,
const Tensor &  input,
const std::vector< int64_t > &  labels,
const std::vector< double > &  epsilons,
DeviceBackend *  backend,
const AttackOptions &  options = {} 
)

Robust accuracy against untargeted PGD at each budget: how fast the accuracy falls as the attacker gets more room. options.epsilon is ignored; options.step_size, when set, is a fraction of each epsilon (0 keeps 2.5 / steps).

Exceptions
std::invalid_argumentas Pgd() does, or if epsilons is empty or holds a value that isn't finite and positive.

◆ RocAuc()

double pulsatrix::RocAuc ( const std::vector< int > &  labels,
const std::vector< double > &  scores 
)

Area under the ROC curve of scores for labels (0 or 1), ties counted half (sklearn's roc_auc_score). NaN if only one class is present.

◆ RopeInverseFrequencies()

std::vector< double > pulsatrix::RopeInverseFrequencies ( const HfModelConfig &  config)

The RoPE frequency of each pair, head_dim / 2 of them, as Hugging Face computes them: rope_theta^(-2i / head_dim), then rescaled by rope_scaling when it is "linear" (all divided by the factor) or "llama3" (low frequencies divided by the factor, high ones kept, the band between interpolated; LLM-6).

Exceptions
std::invalid_argumentfor any other rope_scaling type.

◆ RouletteSelect()

template<typename Genotype , typename FitnessT , typename RNG >
size_t pulsatrix::RouletteSelect ( const std::vector< Individual< Genotype, FitnessT > > &  population,
RNG &  rng 
)

RNG-driven wrapper around RouletteSelectByDraw: draws uniformly from [0, total_fitness) and selects accordingly.

Exceptions
std::invalid_argument– see RouletteSelectByDraw (validation happens there; this wrapper adds no separate checks so the two never disagree on what is malformed).

◆ RouletteSelectByDraw()

template<typename Genotype , typename FitnessT >
size_t pulsatrix::RouletteSelectByDraw ( const std::vector< Individual< Genotype, FitnessT > > &  population,
FitnessT  draw 
)

Fitness-proportionate ("roulette wheel") selection given an explicit draw in [0, total_fitness). Pure and deterministic – the hand-testable core RouletteSelect wraps with an RNG-generated draw.

Parameters
populationNon-empty population with strictly non-negative fitness values summing to a strictly positive total.
drawA value in [0, total_fitness), where total_fitness = sum of population fitness.
Returns
Index into population whose cumulative-fitness bucket contains draw.
Exceptions
std::invalid_argumentif population is empty, any fitness is negative, the total fitness is not strictly positive, or draw is outside [0, total_fitness).

◆ Rsa()

double pulsatrix::Rsa ( const Tensor &  x,
const Tensor &  y,
RdmMetric  metric = RdmMetric::Correlation,
RdmComparison  comparison = RdmComparison::Spearman 
)

RSA between two representations of the same inputs: CompareRdms(RepresentationalDissimilarity(x), RepresentationalDissimilarity(y)).

Exceptions
std::invalid_argumentas those two do, or if x and y have different numbers of rows.

◆ RsaPermutationTest()

RsaTestResult pulsatrix::RsaPermutationTest ( const Rdm &  a,
const Rdm &  b,
RdmComparison  comparison = RdmComparison::Spearman,
int64_t  permutations = 999,
uint64_t  seed = 0 
)

Whether two RDMs agree more than chance: the Mantel test RSA uses.

The inputs of b are relabeled at random (rows and columns together, so each relabeling is an RDM the same representation could have given in another order) and compared with a again. Distances within an RDM aren't independent, which is why a correlation's usual p-value doesn't apply and relabeling does.

Parameters
permutationsHow many relabelings; 999 resolves p-values down to 0.001.
seedThe relabelings come from it: the same seed, the same p-value on every platform.
Exceptions
std::invalid_argumentas CompareRdms() does, or if permutations is below 1.

◆ Rtd()

RtdResult pulsatrix::Rtd ( const Tensor &  a,
const Tensor &  b,
const RtdOptions &  options = {} 
)

Representation Topology Divergence between two representations of the same inputs (the paper's Algorithm 2): in each batch, Euclidean distances within a and within b, each divided by its 0.9 quantile so that scale doesn't count, then the total H1 length of both cross-barcodes.

Parameters
a,bshape (n, ...) each, rows for the same n inputs in the same order; widths may differ.
Note
Each batch is a Vietoris-Rips computation on 2 x sample_size points.
Exceptions
std::invalid_argumentif the row counts differ, there are fewer than 4 rows, sample_size is below 4 or trials below 1, or a representation's distances are all 0.

◆ RunASHA()

template<typename RNG >
ASHAResult pulsatrix::RunASHA ( const SearchSpace &  space,
const TrialFactory &  make_trial,
size_t  max_configs_started,
int  initial_epoch_budget,
double  eta,
int  num_rungs,
RNG &  rng 
)

RNG-driven wrapper: draws max_configs_started configurations from space via RandomSample to serve as the queue, then runs RunASHAOnConfigQueue.

Exceptions
std::invalid_argumentif max_configs_started == 0.

◆ RunASHAOnConfigQueue()

ASHAResult pulsatrix::RunASHAOnConfigQueue ( std::vector< Configuration >  config_queue,
const TrialFactory &  make_trial,
int  initial_epoch_budget,
double  eta,
int  num_rungs 
)
inline

Runs ASHA, drawing new configurations from an explicit, ordered queue (rather than sampling indefinitely) – the pure, deterministic core; RunASHA (below) is the thin SearchSpace/RNG-sampling wrapper around it.

Parameters
initial_epoch_budgetRung 0's epoch budget; rung k's budget is initial_epoch_budget * eta^k.
num_rungsTotal number of rungs (>= 2 – at least one promotion opportunity must exist).
Note
Each step does exactly one of: (a) promote the single best-qualifying candidate at the highest rung with a promotable candidate (scanned top-down, so nearly-finished candidates are preferred over starting fresh ones – ASHA's own stated preference), or (b) if no promotion is possible, start the next queued configuration at rung 0. A rung only becomes eligible for promotion decisions once at least eta candidates have completed it (not enough data to identify a meaningful top fraction before that).
Exceptions
std::invalid_argumentif config_queue is empty, initial_epoch_budget <= 0, eta <= 1.0, or num_rungs < 2.

◆ RunEGANGeneration()

template<typename MakeGenerator , typename DOptimizerT >
std::vector< float > pulsatrix::RunEGANGeneration ( GeneratorPopulation &  population,
Module &  discriminator,
const Tensor &  real_batch,
const std::vector< Tensor > &  noise_per_generator,
const std::vector< MutationObjective > &  objectives,
MakeGenerator  make_generator,
float  g_learning_rate,
DOptimizerT &  d_optimizer,
DeviceBackend *  backend,
float  gamma = 0.05f 
)

Runs one E-GAN generation: for every population member, attempts every objective in objectives (each against a fresh weight-copy offspring built by make_generator + RestoreParameters), keeps the best-combined-fitness offspring, replaces that population slot with it, then trains discriminator on real_batch plus the now-mutated population's own pooled fake output.

Parameters
make_generatorConstructs a fresh generator instance with the same architecture as every population member.
g_learning_rateLearning rate for the SGDOptimizer each mutation attempt trains with.
Returns
Each population member's own winning objective's fitness, in population order.
Exceptions
std::invalid_argumentif noise_per_generator.size() != population.size(), or objectives is empty.

◆ RunEGANTraining()

template<typename MakeGenerator , typename DOptimizerT , typename RNG >
void pulsatrix::RunEGANTraining ( GeneratorPopulation &  population,
Module &  discriminator,
const Tensor &  real_batch,
int  num_generations,
int64_t  noise_dim,
int64_t  per_generator_batch,
const std::vector< MutationObjective > &  objectives,
MakeGenerator  make_generator,
float  g_learning_rate,
DOptimizerT &  d_optimizer,
DeviceBackend *  backend,
RNG &  rng,
float  gamma = 0.05f 
)

RNG-driven wrapper: draws fresh standard-normal noise for every population member every generation, then runs RunEGANGeneration num_generations times.

Exceptions
std::invalid_argumentif num_generations is not positive (delegates to RunEGANGeneration for its own preconditions each generation).

◆ RunEvolutionaryLoop()

template<typename Genotype , typename FitnessT , typename FitnessFn , typename OffspringFn , typename SurvivorFn >
std::vector< Individual< Genotype, FitnessT > > pulsatrix::RunEvolutionaryLoop ( std::vector< Individual< Genotype, FitnessT > >  population,
size_t  num_generations,
size_t  lambda_size,
FitnessFn  fitness_fn,
OffspringFn  produce_offspring_genotype,
SurvivorFn  survivor_selector,
DataThreadPool *  thread_pool = nullptr 
)

Runs num_generations of the shared evolutionary-loop skeleton: evaluate -> produce lambda_size offspring (via produce_offspring_genotype, called once per offspring) -> evaluate offspring -> survivor-select mu individuals for the next generation.

Parameters
populationInitial population (its own fitness values are (re-)computed, not trusted, before the loop begins). mu = population.size().
produce_offspring_genotypeCallable Genotype(const std::vector<Individual<Genotype, FitnessT>>& current_population) – composes whichever selection + crossover + mutation recipe the caller wants; called once per offspring needed.
survivor_selectorCallable std::vector<Individual<Genotype, FitnessT>>(const std::vector<Individual<Genotype, FitnessT>>& population, std::vector<Individual<Genotype, FitnessT>> offspring, size_t mu) – pass GenerationalReplacement, MuPlusLambdaReplacement, or MuCommaLambdaReplacement (survivor_selection.hpp) directly, or any compatible callable.
thread_poolOptional – see EvaluatePopulation.
Returns
The final generation's population (fitness values populated).

◆ RunEvolutionStrategies()

template<typename FitnessFn , typename RNG >
ESResult pulsatrix::RunEvolutionStrategies ( std::vector< double >  theta,
FitnessFn  fitness_fn,
int  num_iterations,
int  population_size,
double  sigma,
double  alpha,
RNG &  rng 
)

Runs num_iterations of Evolution Strategies starting from theta, tracking the best (theta, fitness) pair seen across every evaluated center point (global elitism, the same precedent this campaign's NEAT evolutionary loop already established) – vanilla ES itself has no such tracking, but a returnable "best point found" is genuinely necessary for this to be usable as an optimizer, so it is added here as a small, logged addition beyond the paper's own bare update rule.

Exceptions
std::invalid_argumentif theta is empty or num_iterations is not positive (ESStep's own guards apply to population_size/sigma).

◆ RunGPBOLoop()

template<typename ObjectiveFn , typename RNG >
std::vector< Trial > pulsatrix::RunGPBOLoop ( const SearchSpace &  space,
ObjectiveFn  objective_fn,
size_t  num_initial_random,
size_t  num_iterations,
AcquisitionKind  acquisition,
size_t  num_candidates,
RNG &  rng 
)

Runs GP-BO: num_initial_random uniformly-random trials, then num_iterations trials each chosen by fitting a GP to every trial so far and maximizing acquisition over num_candidates random points in the unit hypercube.

Parameters
objective_fnCallable double(const Configuration&) – the value to maximize (a caller minimizing a loss negates it first, per this file's maximization convention).
Returns
Every Trial run, in order (the initial random trials first, then each GP-BO- proposed trial), each with one "objective" metric recorded.
Exceptions
std::invalid_argumentif num_initial_random == 0, or (propagated from UnitCubeToConfiguration) space contains an Integer/Categorical parameter.

◆ RunHyperband()

template<typename RNG >
HyperbandResult pulsatrix::RunHyperband ( const SearchSpace &  space,
const TrialFactory &  make_trial,
int  max_resource,
double  eta,
RNG &  rng 
)

Runs one Successive Halving bracket (successive_halving.hpp) per ComputeHyperbandBrackets(max_resource, eta), keeping the best result across all of them.

Exceptions
std::invalid_argument– propagated from ComputeHyperbandBrackets.

◆ RunMutationStep()

template<typename OptimizerT >
float pulsatrix::RunMutationStep ( Module &  offspring,
Module &  discriminator,
const Tensor &  noise,
MutationObjective  objective,
OptimizerT &  g_optimizer,
DeviceBackend *  backend,
float  gamma = 0.05f 
)

Runs one E-GAN mutation training step: trains offspring (an already-independent Module instance – typically initialized as a copy of some parent's current weights, which this function does not itself construct or assume anything about) for one step against discriminator using the given objective, then scores the mutated result via CombinedFitness on offspring's own post-mutation samples.

Note
Caller must zero_grad discriminator's own optimizer immediately after calling this function – both the objective's own backward-through-discriminator call and DiversityFitness's own probe backward accumulate into discriminator's gradient buffers, exactly like a generator step in this codebase's existing GAN training loop.

◆ RunNEATEvolution()

template<typename FitnessFn , typename RNG >
NEATEvolutionResult pulsatrix::RunNEATEvolution ( std::vector< NEATGenome >  population,
FitnessFn  fitness_fn,
int  num_generations,
double  compatibility_threshold,
double  c1,
double  c2,
double  c3,
double  weight_mutation_sigma,
double  weight_mutation_probability,
double  add_connection_probability,
double  add_node_probability,
InnovationTracker &  tracker,
RNG &  rng 
)

Runs num_generations of speciated, mutation-only NEAT evolution. Each generation: evaluates every genome's fitness via fitness_fn, tracks the best genome seen across the whole run so far (global elitism – best_fitness never decreases generation to generation), speciates the population, applies fitness sharing, allocates each species a share of the next generation proportional to its adjusted-fitness sum, and fills that share with one unmutated species-champion copy plus mutated copies of uniformly-randomly chosen species members.

Exceptions
std::invalid_argumentif population is empty or num_generations is not positive.

◆ RunPBT()

template<typename RNG >
PBTResult pulsatrix::RunPBT ( std::vector< std::unique_ptr< PBTResumableTrial > > &  trials,
const SearchSpace &  space,
int  num_generations,
int  epochs_per_generation,
double  truncation_fraction,
RNG &  rng 
)

Runs num_generations of RunPBTGeneration in sequence.

Exceptions
std::invalid_argumentif num_generations is not positive (delegates to RunPBTGeneration for its own preconditions).

◆ RunPBTGeneration()

template<typename RNG >
std::vector< double > pulsatrix::RunPBTGeneration ( std::vector< std::unique_ptr< PBTResumableTrial > > &  trials,
const SearchSpace &  space,
int  num_epochs,
double  truncation_fraction,
RNG &  rng 
)

Runs one PBT generation: trains every live trial for num_epochs, then exploits+explores the bottom truncation_fraction of the population from a uniformly-randomly-chosen member of the top truncation_fraction. Individuals outside both groups are left running untouched. Returns each trial's metric as of this generation (post exploit/explore for any trial that was replaced) – the value to feed into the next generation's own truncation.

Exceptions
std::invalid_argumentif trials is empty or num_epochs is not positive (delegates to ComputeTruncationGroups for its own preconditions once trials.size() >= 2).

◆ RunSuccessiveHalving()

template<typename RNG >
SuccessiveHalvingResult pulsatrix::RunSuccessiveHalving ( const SearchSpace &  space,
const TrialFactory &  make_trial,
size_t  num_configs,
int  initial_epoch_budget,
double  eta,
RNG &  rng 
)

RNG-driven wrapper: draws num_configs configurations from space via RandomSample, then runs RunSuccessiveHalvingOnConfigs.

Exceptions
std::invalid_argumentif num_configs == 0 – see RunSuccessiveHalvingOnConfigs for the other validated preconditions.

◆ RunSuccessiveHalvingOnConfigs()

SuccessiveHalvingResult pulsatrix::RunSuccessiveHalvingOnConfigs ( std::vector< Configuration >  configs,
const TrialFactory &  make_trial,
int  initial_epoch_budget,
double  eta 
)
inline

Runs Successive Halving over an explicit, caller-supplied list of configurations – the pure, deterministic core; RunSuccessiveHalving (below) is the thin SearchSpace/RNG-sampling wrapper around it.

Parameters
initial_epoch_budgetEpochs trained in the first rung.
etaReduction factor: after each rung, floor(count / eta) configurations survive (at least 1), and the next rung's budget is the previous budget * eta.
Exceptions
std::invalid_argumentif configs is empty, initial_epoch_budget <= 0, or eta <= 1.0.

◆ RunTcav()

TcavResult pulsatrix::RunTcav ( ExplainerContext &  ctx,
NodeId  layer,
int64_t  target,
const Tensor &  class_inputs,
const Tensor &  concept_inputs,
const std::vector< Tensor > &  random_inputs,
DeviceBackend *  backend,
const TcavOptions &  options = {} 
)

TCAV with Kim et al.'s significance test, for one concept, layer and class.

Parameters
ctxThe model, as an ExplainerContext; its output is (n, classes).
layerThe node whose output is the layer: module i's output is node i + 1.
targetThe class whose logit is explained.
class_inputsInputs of that class, the model's input shape with a leading batch.
concept_inputsExamples of the concept.
random_inputsAt least 3 sets of random examples. CAV i is the concept against set i; random CAV i is set i against set i + 1 (the last against the first).
Exceptions
std::invalid_argumentif layer isn't a node of the model, target is out of range, there are fewer than 3 random sets, or for what TrainCav() rejects.

◆ RunTPELoop()

template<typename ObjectiveFn , typename RNG >
std::vector< Trial > pulsatrix::RunTPELoop ( const SearchSpace &  space,
ObjectiveFn  objective_fn,
size_t  num_initial_random,
size_t  num_iterations,
double  gamma,
size_t  num_candidates,
RNG &  rng 
)

Runs TPE: num_initial_random uniformly-random trials (RandomSample), then num_iterations trials each chosen by splitting all trials so far into good/bad by the gamma quantile (maximization convention: good = highest objective values) and picking, among num_candidates uniformly-random candidates, the one maximizing LogDensityRatio.

Parameters
gammaFraction of trials-so-far classified "good" (e.g. 0.2 = top 20%); at least one trial is always classified good and at least one bad, regardless of gamma, once num_initial_random >= 2.
Exceptions
std::invalid_argumentif num_initial_random < 2 (a quantile split needs at least one good and one bad observation), or gamma is outside (0, 1).

◆ sample_gflownet_trajectory()

GFlowNetTrajectory pulsatrix::sample_gflownet_trajectory ( HyperGridEnv &  env,
GFlowNetForwardPolicy &  forward_policy 
)

Samples one full trajectory: resets env, then repeatedly samples a masked action from forward_policy and steps env until termination (an explicit stop or env's own max_steps cap).

Parameters
envThe environment to roll out on. Reset internally; any existing episode in progress is discarded.
forward_policyThe forward policy sampling each step's action.
Returns
The full trajectory, per GFlowNetTrajectory's fields above.
Note
Host boundary (GPU-native-kernels Mission 7): the rollout loop is host control flow. env and forward_policy may use any backend; each step reads the sampled action back with one device->host copy.

◆ sample_to_json()

std::string pulsatrix::sample_to_json ( const SystemSample &  sample)

Encodes sample as one JSON object (no trailing newline), the JSON Lines log record.

◆ SampleContinuousDiffusion()

ContinuousTrajectory pulsatrix::SampleContinuousDiffusion ( ContinuousDenoiser &  model,
const NoiseSchedule &  schedule,
const std::vector< float > &  x_T,
const ContinuousSamplerConfig &  config 
)

Runs the reverse process from x_T and records it.

Exceptions
std::invalid_argumentfor an empty x_T, steps < 1, a negative eta, or a prediction of the wrong size.

◆ SampleMaskedDiffusion()

MaskedDiffusionResult pulsatrix::SampleMaskedDiffusion ( const DenoiserFn &  model,
const std::vector< int64_t > &  tokens,
const MaskedDiffusionConfig &  config 
)

Fills every masked position of tokens over the configured steps.

Note
Sampling draws from std::mt19937_64's raw output, so a seed gives the same trajectory on every platform as long as the model's logits are the same.
Exceptions
std::invalid_argumentfor an invalid config, an input with no masked position or a token outside the vocabulary the model's output implies, logits of the wrong size or not finite, or a position where every token is suppressed.

◆ SaveCheckpoint() [1/2]

void pulsatrix::SaveCheckpoint ( const std::string &  path,
Module &  model,
const AdamOptimizer &  optimizer,
const std::map< std::string, std::string > &  metadata = {} 
)

SaveCheckpoint(), plus optimizer's per-parameter state in OptimizerStatePath(path).

Note
The optimizer file records a checksum of the model file, so a later model-only save to the same path can't be silently resumed with stale optimizer state.

◆ SaveCheckpoint() [2/2]

void pulsatrix::SaveCheckpoint ( const std::string &  path,
Module &  model,
const std::map< std::string, std::string > &  metadata = {} 
)

Writes every parameter and buffer of model, under their hierarchical names, to a safetensors file with format = "pulsatrix" and format_version metadata.

Parameters
metadataExtra string metadata to store; format and format_version are reserved.
Exceptions
std::invalid_argumentif a parameter and a buffer share a name, or metadata uses a reserved key.
std::runtime_errorif the file can't be written.

◆ SaveIA3Adapter()

void pulsatrix::SaveIA3Adapter ( Module &  model,
const std::string &  directory,
const std::vector< WeightMapping > &  mapping = {} 
)

Writes the model's IA³ vectors as a PEFT adapter directory (adapter_model.safetensors with base_model.model.<module>.ia3_l, (out, 1) or (1, in), and adapter_config.json).

Parameters
mappingAs for SaveLoraAdapter(): the base model's weight manifest, or empty for pulsatrix's names.
Exceptions
std::invalid_argumentif there are none, one is merged, or a layer has no whole-weight mapping.

◆ SaveLoraAdapter()

void pulsatrix::SaveLoraAdapter ( Module &  model,
const std::string &  directory,
const std::vector< WeightMapping > &  mapping = {} 
)

Writes the model's adapters as a PEFT adapter directory: adapter_model.safetensors and adapter_config.json, which PEFT's PeftModel.from_pretrained() loads onto the Hugging Face model.

Parameters
mappingHow the model's parameter names become checkpoint names, the manifest used to load the base model (HuggingFaceMapping() for a CausalLM, EsmMapping() for an EncoderLM). A layer whose .weight it maps whole names the adapter after the source. Empty keeps pulsatrix's names.
Note
Keys are base_model.model.<module>.lora_A.weight (r, in) and ...lora_B.weight (out, r), float32.
Exceptions
std::invalid_argumentif the model has no adapters, the adapters' rank, alpha or dropout differ, a merged adapter is saved (its update is in the base weight), or a layer has no whole-weight mapping; std::runtime_error if the files can't be written.

◆ SaveLoReFT()

void pulsatrix::SaveLoReFT ( CausalLM &  model,
const std::string &  path 
)

Saves the model's LoReFT interventions as safetensors: per layer i, pyreft's state dict under layer.<i>.rotate_layer, layer.<i>.learned_source.weight and layer.<i>.learned_source.bias, in pyreft's layouts, with metadata first and last.

Exceptions
std::invalid_argumentif the model has none, or they edit different positions.

◆ ScaledDeltaBounds()

SensitivityBounds pulsatrix::ScaledDeltaBounds ( const Tensor &  input,
const std::vector< Tensor > &  background,
float  num_std = 1.0f 
)

x -/+ num_std standard deviations of each feature over background, so every feature moves by a comparable amount whatever its units. A feature constant over the background doesn't move.

Exceptions
std::invalid_argumentif num_std <= 0, background is empty, or a background instance's shape differs from input's.

◆ ScoreChoices()

ChoiceScores pulsatrix::ScoreChoices ( CausalLM &  model,
const std::vector< std::vector< int64_t > > &  prompts,
const std::vector< int64_t > &  choice_tokens,
DeviceBackend *  backend,
int64_t  batch_size = 8 
)

Scores the next token after each prompt against a fixed set of single-token choices, such as " Yes" and " No". For two choices, choice_log_probs[n][0] - choice_log_probs[n][1] is the log-odds of the first.

Exceptions
std::invalid_argumentif prompts or choice_tokens is empty, a prompt is empty, a choice is outside the vocabulary, or batch_size < 1.

◆ ScoreCircuit()

CircuitScores pulsatrix::ScoreCircuit ( const CircuitTrace &  trace)

Circuit-tracer's replacement and completeness scores (graph.py).

◆ ScoringPassBytes()

int64_t pulsatrix::ScoringPassBytes ( const EncoderLMConfig &  config,
int64_t  length 
)

Roughly the most memory one sequence of length tokens takes in a forward pass of config's model that keeps no activations (EncoderLM::set_keep_activations(false)): one layer's attention scores and their softmax copies, its projections and MLP, and the logits. The weights aren't counted.

◆ SecondaryStructureLabels()

std::vector< int > pulsatrix::SecondaryStructureLabels ( const AnnotatedProtein &  protein)

Three-state secondary structure per residue: 0 helix (Helix), 1 strand (Beta strand), 2 anything else (turns and coil).

◆ SequenceWindowFeatures()

std::vector< float > pulsatrix::SequenceWindowFeatures ( const std::vector< std::string > &  sequences,
int64_t  window 
)

The control a residue probe has to beat: each residue's local sequence, one-hot over the 20 amino acids at every position within window of it (20 * (2 window + 1) values, zeros past the ends and for other letters). A linear probe that reads a concept from a layer no better than from this hasn't shown the model adds anything beyond nearby sequence.

Note
Hewitt and Liang's control task (ControlTaskLabels()), labels fixed per token type, is no control here: with only 20 amino acids, a linear probe on any representation that encodes identity learns it perfectly. Local sequence plays its role instead, through CompareToBaseline().
Returns
residues x 20 (2 window + 1), the sequences' residues one after another.

◆ SerializeNpy()

std::vector< uint8_t > pulsatrix::SerializeNpy ( const Tensor &  x)

A tensor as a .npy file: format version 1.0, little-endian float32 (<f4), C order, with the tensor's shape.

Note
Copies the tensor to the host first, whatever device it is on.

◆ SerializeSafetensors()

std::vector< uint8_t > pulsatrix::SerializeSafetensors ( const std::vector< std::pair< std::string, const Tensor * > > &  tensors,
const std::map< std::string, std::string > &  metadata = {} 
)

Serializes tensors (as F32) and string metadata into safetensors bytes.

Parameters
tensorsName and tensor pairs, stored in this order. Tensors on a GPU are copied back.
metadataStored as __metadata__; omitted when empty.
Note
The header is padded with spaces so the data section starts on an 8-byte boundary, as the reference implementation does.
Exceptions
std::invalid_argumentif a name repeats, is __metadata__, or (like any metadata key or value) is not valid UTF-8.

◆ set_deterministic()

void pulsatrix::set_deterministic ( bool  enabled)

Turns deterministic mode on (the default) or off.

Note
On: the GPU backends forbid atomics in their BLAS libraries (hipBLAS / cuBLAS), and any code path that would give run-to-run different results refuses to run (check_deterministic_allowed()). Off: those paths may run, possibly faster. pulsatrix's own kernels use no atomics and are deterministic either way.

◆ set_seed()

void pulsatrix::set_seed ( uint64_t  seed)

Sets the global seed and restarts the seed stream next_seed() draws from.

Note
Like torch.manual_seed: after set_seed(s), building the same objects in the same order gives the same initial weights, dropout masks and shuffles. Components that take an explicit seed ignore the global one. The default global seed is 0, so a program that never calls set_seed() is reproducible too.
Process-wide state. Call it before building models, not while other threads are constructing seeded components.

◆ SetIA3Enabled()

void pulsatrix::SetIA3Enabled ( Module &  model,
bool  enabled 
)

Turns every vector on or off.

Exceptions
std::logic_errorwhile one is merged.

◆ SetLoraEnabled()

void pulsatrix::SetLoraEnabled ( Module &  model,
bool  enabled 
)

Turns every adapter on or off, so one model runs as the base or as the fine-tune.

◆ SimulatedBinaryCrossover()

template<typename RNG >
std::pair< std::vector< double >, std::vector< double > > pulsatrix::SimulatedBinaryCrossover ( const std::vector< double > &  parent1,
const std::vector< double > &  parent2,
double  eta,
RNG &  rng 
)

RNG-driven wrapper: draws u_i ~ Uniform(0, 1) per gene (std::uniform_real_distribution is documented to produce values in [0, 1), matching the pure core's requirement).

Exceptions
std::invalid_argument– see SimulatedBinaryCrossoverByDraw.

◆ SimulatedBinaryCrossoverByDraw()

std::pair< std::vector< double >, std::vector< double > > pulsatrix::SimulatedBinaryCrossoverByDraw ( const std::vector< double > &  parent1,
const std::vector< double > &  parent2,
double  eta,
const std::vector< double > &  draws 
)
inline

Simulated binary crossover (Deb & Agrawal 1995; DEAP's cxSimulatedBinary), given an explicit per-gene draw in [0, 1).

Exceptions
std::invalid_argumentif parent1/parent2/draws sizes are not all equal, eta is negative, or any draw is outside [0, 1).
Note
draws must exclude 1.0: the u > 0.5 branch divides by (1 - u), which is exactly zero at u == 1 – excluded by validation rather than silently producing inf/nan.
child1_i + child2_i == parent1_i + parent2_i for any beta_q (and therefore any eta, draw) – an algebraic invariant independent of the specific draw, useful for testing the RNG-driven wrapper.

◆ SingleLinkageClusters()

std::vector< int64_t > pulsatrix::SingleLinkageClusters ( const std::vector< MstEdge > &  edges,
int64_t  points,
double  threshold 
)

The clusters of single linkage cut at a scale: points joined by tree edges no longer than threshold share a label.

Parameters
pointsThe number of points the edges span.
Returns
One label per point, numbered 0, 1, ... in order of each cluster's lowest point.
Exceptions
std::invalid_argumentif an edge has an endpoint outside [0, points).

◆ SingleTokenId()

int64_t pulsatrix::SingleTokenId ( const TextTokenizer &  tokenizer,
const std::string &  text 
)

The id of a string that must tokenize to exactly one token, such as " Yes".

Exceptions
std::invalid_argumentif it tokenizes to anything else.

◆ SinusoidalTimestepEmbedding()

Tensor pulsatrix::SinusoidalTimestepEmbedding ( int64_t  t,
int64_t  embedding_dim,
DeviceBackend *  backend,
float  base = 10000.0f 
)

Standard Transformer-style sinusoidal encoding of a diffusion timestep t: emb[2i] = sin(t / base^(2i/embedding_dim)), emb[2i+1] = cos(t / base^(2i/embedding_dim)) for i in [0, embedding_dim/2).

This is how a DDPM denoiser is told which noise level it is looking at. It is a plain deterministic function of t – nothing is learned, nothing is cached, and no gradient flows into it. The same fixed-positional-quantity disposition RoPEModule already established for its rotation angles, one step further: RoPE is at least a Module because it transforms a tensor, whereas this produces one from an integer and so is a free function, not a class.

Parameters
tThe timestep to encode. Any value is legal, including 0 and negatives – sin/cos are defined everywhere and a schedule's valid range is NoiseSchedule's contract to enforce, not this function's.
embedding_dimSize of the produced embedding. Must be positive and even (the encoding fills sin/cos pairs, so an odd size has no valid pairing – the same even-dimension requirement, for the same structural reason, as RoPEModule's head_dim).
backendBackend to allocate the result through. Not owned; must outlive the returned Tensor.
baseFrequency base of the geometric wavelength schedule; 10000.0 is the standard convention shared by the Transformer and DDPM papers.
Returns
The embedding, shape (1, embedding_dim).
Exceptions
std::invalid_argumentif embedding_dim <= 0 or embedding_dim is odd – external boundary, same classification as RoPEModule's head_dim check.
Note
Shape is (1, embedding_dim), not rank-1 (embedding_dim,). This codebase is always-batched (a single example is N = 1, not a structurally different case – campaign_exai_dl_library_batch_dimension_support), and the one thing callers do with this result is concatenate it onto each row of an (N, D) batch of noisy samples. A (1, embedding_dim) row is directly that row; a rank-1 result would make every caller reshape first.
Host boundary (GPU-native-kernels Mission 7): the embedding is computed on the host in double (one sin/cos pair per frequency) and uploaded once through backend, so a GPU backend receives a device-resident result.

◆ SliceBatch()

Tensor pulsatrix::SliceBatch ( const Tensor &  t,
int64_t  start,
int64_t  count,
DeviceBackend *  backend 
)
inline

Extracts rows [start, start+count) along t's leading dimension into a new Tensor – the inverse of Tensor::Stack, needed to split a pooled discriminator gradient back into each population member's own slice.

Exceptions
std::invalid_argumentif t has rank 0, count <= 0, start < 0, or start+count exceeds t's own leading dimension.

◆ SliceErrorCheck()

CheckResult pulsatrix::SliceErrorCheck ( const SliceErrorReport &  report)

The per_slice_error check's result for a report PerSliceError() made: Failed when a slice is worse than the rest, Passed otherwise. For ReportExplanation(), or a model BuildExplanation() can't score, such as a regressor.

◆ SolveLinearSystem()

std::vector< float > pulsatrix::SolveLinearSystem ( std::vector< std::vector< float > >  a,
std::vector< float >  b 
)
inline

Solves A*x = b via Gaussian elimination with partial pivoting.

Exceptions
std::runtime_errorif a pivot is too close to zero (a near-singular system) – a legitimate, caller-triggerable condition (e.g. degenerate/duplicate sample points), not a programmer error, per this codebase's assert-vs-throw convention.
Note
A, b are taken by value – elimination is done in place on the local copies.
Scoped to the small, dense, well-conditioned systems this codebase's callers actually produce – not a general-purpose numerics library.

◆ Sparseness()

float pulsatrix::Sparseness ( const Attribution &  attribution)

Gini index of the attribution magnitudes (Chalasani et al. 2020; Quantus Sparseness): 0 when relevance is spread evenly, approaching 1 when one feature holds it all.

Returns
0 for an all-zero attribution (Quantus would return NaN).

◆ SpearmanCorrelation()

double pulsatrix::SpearmanCorrelation ( const std::vector< double > &  x,
const std::vector< double > &  y 
)

Spearman's rank correlation, ties given their average rank (scipy's spearmanr). NaN if either input is constant.

Exceptions
std::invalid_argumentfor sizes that differ or < 2.

◆ SpearmanRankCorrelation()

float pulsatrix::SpearmanRankCorrelation ( const std::vector< float > &  x,
const std::vector< float > &  y 
)

Spearman rank correlation, with tied values given their average rank.

Returns
0 when either input is constant.
Exceptions
std::invalid_argumentif the sizes differ or are below 2.

◆ SpeciatePopulation()

SpeciesAssignment pulsatrix::SpeciatePopulation ( const std::vector< NEATGenome > &  population,
double  compatibility_threshold,
double  c1,
double  c2,
double  c3 
)
inline

Groups population into species: each genome joins the first existing species whose representative (that species' own first member) it is compatible with (distance < compatibility_threshold); otherwise it founds a new species with itself as representative.

Exceptions
std::invalid_argumentif population is empty or compatibility_threshold <= 0.

◆ SpliceHook()

HiddenStateHook pulsatrix::SpliceHook ( Featurizer &  featurizer,
int64_t  position,
std::vector< bool >  rows = {} 
)

Splices the featurizer in at one position: a hook that replaces the hidden states there, (N, L, input_dim), by their reconstructions, and leaves other positions alone.

Parameters
rowsWhich of the N * L rows to replace (all when empty), for example only residues, not special tokens or padding, if that is what the featurizer was trained on.
Note
The hook throws std::invalid_argument if the hidden size isn't input_dim or rows has the wrong length.

◆ SplitWords() [1/2]

std::vector< Offset > pulsatrix::SplitWords ( std::string_view  text,
const UnicodeRegex &  pattern 
)

The words of text: every match of pattern.

◆ SplitWords() [2/2]

std::vector< Offset > pulsatrix::SplitWords ( std::string_view  text,
WordSplit  split = WordSplit::WordsAndPunctuation 
)

The words of valid UTF-8 text, as byte ranges in order. Scripts written without spaces (Chinese, Japanese, Thai) come out as long runs; pass a pattern for those.

Exceptions
std::invalid_argumentif text isn't valid UTF-8.

◆ StandardNormal()

std::vector< float > pulsatrix::StandardNormal ( size_t  n,
uint64_t  seed 
)

Draws n standard normal values from seed, as SampleContinuousDiffusion does.

◆ StandardNormalCdf()

double pulsatrix::StandardNormalCdf ( double  z)
inline

Standard normal CDF, Phi(z) = 0.5 * (1 + erf(z / sqrt(2))).

◆ StandardNormalPdf()

double pulsatrix::StandardNormalPdf ( double  z)
inline

Standard normal PDF, phi(z) = (1/sqrt(2*pi)) * exp(-z^2/2).

◆ SteeringHook()

HiddenStateHook pulsatrix::SteeringHook ( int64_t  position,
std::vector< float >  direction,
float  coefficient,
std::vector< bool >  rows = {} 
)

A hook that adds coefficient * direction to the hidden states at position (0 is the embeddings, i layer i's output), for the rows in rows (every row when empty). Install it with CausalLM::set_hidden_state_hook() or EncoderLM::set_hidden_state_hook().

Note
The hook throws std::invalid_argument if the hidden size isn't the direction's, or rows has the wrong length.

◆ StructurePanelHtml()

std::string pulsatrix::StructurePanelHtml ( const std::string &  structure,
const std::string &  chain,
const ResidueTracksDocument &  tracks,
const HtmlOptions &  options,
const std::string &  id 
)

RenderStructureHtml's viewer as a fragment to place in any page: the track menu, the legend, the 3D view and its scripts. Its elements' ids start with id, so a page can hold several.

Exceptions
whatRenderStructureHtml throws, or std::invalid_argument for an id that isn't lowercase letters, digits and hyphens.

◆ StudentTTest()

TTestResult pulsatrix::StudentTTest ( const std::vector< double > &  a,
const std::vector< double > &  b 
)

Student's two-sample t-test with pooled variance, two-sided, as scipy.stats.ttest_ind computes by default and the TCAV library uses.

Note
When both samples have no variance, t is 0 and p is 1 if their means are equal, and t is infinite and p is 0 if not.
Exceptions
std::invalid_argumentif either sample has fewer than 2 values, or a value isn't finite.

◆ SubDistanceMatrix()

DistanceMatrix pulsatrix::SubDistanceMatrix ( const DistanceMatrix &  distances,
const std::vector< int64_t > &  indices 
)

A sub-matrix of a distance matrix: the distances among the given points (repeats allowed), in the given order.

◆ SubspaceOverlap()

double pulsatrix::SubspaceOverlap ( const Pca &  a,
const Pca &  b,
int64_t  k 
)

How much two PCAs' first k components span the same space: the mean squared cosine of the principal angles between them, |A_k B_k^T|_F^2 / k. 1 when the spans are the same (whatever the order or rotation inside them), 0 when they are orthogonal, and about k / width for unrelated random subspaces.

Exceptions
std::invalid_argumentif the widths differ or k is not between 1 and both PCAs' num_components().

◆ SummarizeTimings()

TimingStats pulsatrix::SummarizeTimings ( std::vector< double >  samples_ms)

Summarizes timings. Percentiles interpolate linearly between the sorted samples.

Exceptions
std::invalid_argumentif samples_ms is empty or has a negative or non-finite value.

◆ Svcca()

SvccaResult pulsatrix::Svcca ( const Tensor &  x,
const Tensor &  y,
const SvccaOptions &  options = {} 
)

SVCCA: CanonicalCorrelations() between each representation's top singular directions.

Exceptions
std::invalid_argumentas CanonicalCorrelations() does for the kept directions, or if an option is out of range.

◆ SVD()

SVDResult pulsatrix::SVD ( const Tensor &  a)

Thin singular value decomposition by one-sided (Hestenes) Jacobi rotations.

Note
Accurate to high relative precision for small singular values. About 50 ms for a 256 x 128 matrix and 1.6 s for 512 x 256 (Release, one core).
Parameters
a(m, n) CPU tensor of any shape, all finite. Rank-deficient input is fine: left singular vectors for zero singular values are completed to an orthonormal set.
Exceptions
std::invalid_argumentif a is not rank 2, is not on the CPU, or has a non-finite entry.

◆ SymmetricEigen()

EigenResult pulsatrix::SymmetricEigen ( const Tensor &  a)

All eigenvalues and eigenvectors of a symmetric matrix, by Householder reduction to tridiagonal form followed by QL with implicit shifts.

Parameters
aSquare (n, n) CPU tensor, symmetric to within a relative 1e-5, all finite.
Note
O(n^3): about 60 ms at n = 256 and 0.8 s at n = 512 (Release, one core). For a repeated eigenvalue, any orthonormal basis of its eigenspace is returned.
Exceptions
std::invalid_argumentif a is not square rank 2, is not on the CPU, has a non-finite entry, or is not symmetric.
std::runtime_errorif QL fails to converge in 60 iterations for some eigenvalue, which does not happen for finite symmetric input in practice.

◆ SymmetricEigenInDouble()

DoubleEigenResult pulsatrix::SymmetricEigenInDouble ( std::vector< double >  a,
int64_t  n 
)

SymmetricEigen() in double precision from end to end, eigenvectors included: PCA's directions and variances from a covariance or Gram matrix computed in double.

Parameters
aRow-major (n, n), symmetric to within a relative 1e-5, all finite.
Exceptions
std::invalid_argumentas SymmetricEigenvalues() does.

◆ SymmetricEigenvalues()

std::vector< double > pulsatrix::SymmetricEigenvalues ( std::vector< double >  a,
int64_t  n 
)

SymmetricEigen()'s eigenvalues, in double precision from end to end: for a matrix computed in double, such as a Gram matrix, whose small eigenvalues a float copy would lose.

Parameters
aRow-major (n, n), symmetric to within a relative 1e-5, all finite.
Returns
The n eigenvalues, largest first.
Exceptions
std::invalid_argumentif a doesn't hold n * n values, n < 1, it has a non-finite entry, or it isn't symmetric.

◆ SyncTargetNetwork()

void pulsatrix::SyncTargetNetwork ( Module &  source,
Module &  destination 
)

Hard target-network update: copies every parameter value of source into destination, element-wise and in place (Mnih et al. 2015's periodic full copy).

Parameters
sourceNetwork to copy parameter values from – typically the online Q-network.
destinationNetwork to copy into – typically the frozen target network.
Exceptions
std::invalid_argumentif the two networks expose a different number of parameters, or if any parameter pair's shapes differ, naming the offending index and shapes. External boundary: two independently-constructed networks genuinely can have mismatched architectures, and a silent partial copy would leave the target network quietly wrong for the rest of training.
Note
A hard copy, not Polyak/soft averaging – classic DQN. A soft variant would be a different function with an extra tau, not a flag on this one.
The copy is element-wise into destination's existing parameter buffers, not a replacement of its Tensor objects. destination's parameters must remain the same objects its own parameters() (and any optimizer already holding ParamRefs into it) point at, so subsequent forward passes see the synced values through the same storage. Replacing the Tensors would dangle every outstanding ParamRef.
Gradients are untouched. This is a pure value copy and has nothing to do with zero_grad(); a target network is never backpropagated through in DQN anyway.
Device-generic (GPU-native-kernels Mission 7): each parameter is one buffer copy through the destination parameter's own backend (HostToHost / DeviceToDevice), staged through the host only when source and destination live on different devices.

◆ TaggingAccuracy()

float pulsatrix::TaggingAccuracy ( TinyTagger &  tagger,
TaggingRule  rule,
int64_t  num_sequences 
)

Fraction of real tokens tagged correctly on num_sequences fresh sequences.

◆ TcavScore()

double pulsatrix::TcavScore ( const std::vector< double > &  sensitivities)

The fraction of sensitivities above zero.

Exceptions
std::invalid_argumentif empty.

◆ TellGivenSamples()

CMAESState pulsatrix::TellGivenSamples ( const CMAESState &  state,
const std::vector< std::vector< double > > &  z_samples,
const std::vector< std::vector< double > > &  offspring,
const std::vector< double > &  fitness,
double  step_size_learning_rate,
double  scale_learning_rate 
)
inline

Pure core: given the offspring AskGivenSamples produced (same order), their maximization-convention fitness values, and the z_samples that produced them, returns the next generation's state.

Parameters
step_size_learning_rate,scale_learning_rateFixed adaptation rates (this variant's own simplification – full CMA-ES derives these from mu_eff/n instead).
Exceptions
std::invalid_argumentif z_samples/offspring/fitness sizes disagree, or fewer than 2 samples are given (mu = size/2 must be >= 1).

◆ TimeIt()

TimingStats pulsatrix::TimeIt ( const std::function< void()> &  fn,
int  warmup,
int  repeats 
)

Runs fn warmup times untimed, then repeats times timed with a steady clock.

Note
A HIP op can return before the GPU finishes (CUDA ops currently wait), so fn must end by waiting for its device work, for example by reading a result to the host. Otherwise this may time only kernel launches.
Exceptions
std::invalid_argumentif warmup < 0 or repeats < 1.

◆ to_json() [1/2]

template<class Json >
void pulsatrix::to_json ( Json &  j,
const JsonValue &  value 
)

Converts a JsonValue to another JSON library's value type by its common interface (assignment from null, bool, number and string; object(), array(), operator[], push_back). nlohmann::json finds it by argument-dependent lookup, so nlohmann::json j = value; works without pulsatrix including nlohmann.

Note
Integers (number text without '.', 'e' or 'E' that fits int64_t) stay integers.

◆ to_json() [2/2]

template<class Json >
void pulsatrix::to_json ( Json &  j,
const MimeBundle &  bundle 
)

The bundle as a JSON object of MIME type to data (see to_json(Json&, const JsonValue&)).

◆ to_string() [1/9]

std::string_view pulsatrix::to_string ( CaveatSeverity  severity)

◆ to_string() [2/9]

std::string_view pulsatrix::to_string ( CheckOutcome  outcome)

◆ to_string() [3/9]

std::string_view pulsatrix::to_string ( CheckPriority  priority)

◆ to_string() [4/9]

std::string_view pulsatrix::to_string ( ExplanationScope  scope)

◆ to_string() [5/9]

std::string_view pulsatrix::to_string ( InputKind  input)

◆ to_string() [6/9]

std::string_view pulsatrix::to_string ( ModelAccess  access)

◆ to_string() [7/9]

std::string_view pulsatrix::to_string ( SurrogateTask  task)

◆ to_string() [8/9]

std::string_view pulsatrix::to_string ( XaiQuestion  question)

◆ to_string() [9/9]

std::string_view pulsatrix::to_string ( XaiReason  reason)

◆ ToAttentionConfig() [1/2]

AttentionConfig pulsatrix::ToAttentionConfig ( const HfModelConfig &  config)

The attention layer the config describes: rotate-half RoPE (with its scaling), causal unless the config says otherwise, its head counts, biases, QK-Norm and epsilon, and Gemma's score scale and QK-Norm offset. For a model whose layers differ, this is a full-attention layer.

◆ ToAttentionConfig() [2/2]

AttentionConfig pulsatrix::ToAttentionConfig ( const HfModelConfig &  config,
int64_t  layer 
)

Layer layer's attention (LLM-9): a sliding-window layer gets its window and its own RoPE base, unscaled; a full-attention layer is ToAttentionConfig(config).

◆ ToAttribution()

Attribution pulsatrix::ToAttribution ( const AttributionDocument &  doc,
DeviceBackend *  backend 
)

Rebuilds an Attribution whose values live on backend.

◆ ToAttributionDocument()

AttributionDocument pulsatrix::ToAttributionDocument ( const Attribution &  attr)

Copies attr into a document, reading its values to the host.

◆ ToAttributionGraph()

AttributionGraph pulsatrix::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 indirect influence on the logits (node_threshold), then edges by influence-weighted score (edge_threshold), then nodes left without edges. Node ids, types and labels follow circuit-tracer ("<layer>_<feature>_<position>", "cross layer transcoder", "mlp reconstruction error", "E_<token>_<position>", "<L+1>_<token>_<position>" for logits).

◆ ToBeeswarmPoints()

std::vector< BeeswarmPoint > pulsatrix::ToBeeswarmPoints ( const std::vector< Attribution > &  runs,
int64_t  feature_index 
)

Converts one feature's attribution value across many repeated/independent runs into jittered (x, y) points for a beeswarm plot – the global-explanation distribution view (hc_information_visualization.md SS5: "SHAP beeswarm plot... each point is one prediction; x-position is the SHAP value"). Deterministic, density-based jitter: points are binned along x, then colliding points within a bin are alternately offset above/below y=0 so they read as spread rather than overlapping – not a random jitter, so two calls with the same input always produce the same layout.

Parameters
runsAttribution results across many samples/predictions (not necessarily repeated runs on one input – unlike ComputeAttributionStability, this is the global view across many different inputs).
feature_indexWhich feature (element position) to plot.
Exceptions
std::invalid_argumentif runs is empty.
std::out_of_rangeif feature_index is out of range for any run's Attribution.

◆ ToCircuitGraph()

CircuitGraph pulsatrix::ToCircuitGraph ( const CircuitGraphDocument &  doc)
Exceptions
std::invalid_argumentif a node's op_type isn't an OpType name.

◆ ToCircuitGraphDocument()

CircuitGraphDocument pulsatrix::ToCircuitGraphDocument ( const CircuitGraph &  graph)

◆ ToCounterfactualDocument()

CounterfactualDocument pulsatrix::ToCounterfactualDocument ( const Tensor &  input,
const CounterfactualResult &  result,
const std::vector< std::string > &  names = {},
const std::vector< float > &  scale = {},
std::string  target = "" 
)

Pairs input with result's counterfactual. names and scale, if not empty, have one entry per feature; scale should be the one the search used.

Exceptions
std::invalid_argumentif the counterfactual's size differs from the input's, or a list has the wrong length.

◆ ToFeatureImportanceBars()

BarSeries pulsatrix::ToFeatureImportanceBars ( const Attribution &  attr,
int  top_k 
)

Converts an Attribution's per-feature values into labeled, magnitude-sorted bars for a horizontal bar chart – the canonical XAI feature-importance encoding (hc_information_visualization.md SS5: position on a shared axis, Cleveland-McGill rank 1).

Parameters
attrA rank-1 Attribution (one value per feature), or a rank-2 Attribution whose leading (batch) dimension is 1 – every native/surrogate explainer in this codebase is always-batched post campaign_exai_dl_library_batch_dimension_support, so a single-prediction explanation is shape (1, num_features), not (num_features,).
top_kNumber of highest-|value| features to keep, in descending |value| order.
Returns
Bars sorted by descending absolute value, truncated to top_k (or fewer, if attr has fewer features than top_k). Labels come from attr.metadata["feature_names"] (comma-separated) when present, otherwise "feature_<index>".
Exceptions
std::invalid_argumentif attr.values is not rank 1 or batch-1 rank 2, or if top_k <= 0.

◆ ToFieldHistogramBins()

HistogramBins pulsatrix::ToFieldHistogramBins ( const Dataset &  dataset,
int64_t  field_index,
int  num_bins 
)

Bins one Sample field's values (flattened across every sample's Tensor at that field position, mirroring DatasetValidator's aggregation convention) into num_bins equal-width bins, for a per-field distribution histogram (hc_information_visualization.md's data-preview touchpoint).

Parameters
datasetThe dataset to scan. Must be non-empty.
field_indexWhich Sample field position to bin.
num_binsNumber of equal-width bins, must be positive.
Exceptions
std::invalid_argumentif dataset is empty or num_bins <= 0.
std::out_of_rangeif field_index is out of range for the dataset's samples.
Note
A constant field (max == min) places every value in the first bin rather than dividing by a zero-width bin range.

◆ ToHeatmapDocument() [1/2]

HeatmapDocument pulsatrix::ToHeatmapDocument ( const HeatmapGrid &  grid,
std::string  title = "" 
)

◆ ToHeatmapDocument() [2/2]

HeatmapDocument pulsatrix::ToHeatmapDocument ( const PartialDependence2D &  pd,
std::string  title = "" 
)

A two-feature partial dependence as a heatmap: rows follow grid_y, columns grid_x, and the labels are the grid values.

◆ ToHeatmapGrid()

HeatmapGrid pulsatrix::ToHeatmapGrid ( const HeatmapDocument &  doc)

◆ ToIceResult()

IceResult pulsatrix::ToIceResult ( const PartialDependenceDocument &  doc)

Rebuilds the ICE curves for their centered and derivative views.

Exceptions
std::invalid_argumentif the document holds no ICE curves.

◆ ToJson() [1/37]

JsonValue pulsatrix::ToJson ( const AgreementReport &  report)

The report as a pulsatrix.explanation_agreement.v1 document. NaNs are written as null.

◆ ToJson() [2/37]

JsonValue pulsatrix::ToJson ( const Anchor &  anchor,
const std::vector< std::string > &  feature_names = {} 
)

The anchor as a pulsatrix.anchor.v1 document; an infinite bound is null.

◆ ToJson() [3/37]

JsonValue pulsatrix::ToJson ( const AttackResult &  result,
const AttackOptions &  options 
)

The result as a pulsatrix.attack.v1 document, without the adversarial inputs.

◆ ToJson() [4/37]

std::string pulsatrix::ToJson ( const AttributionDocument &  doc)
Exceptions
std::invalid_argumentif values.size() isn't the product of shape.

◆ ToJson() [5/37]

std::string pulsatrix::ToJson ( const BenchmarkReport &  report)
Exceptions
std::invalid_argumentif two records share a name and device.

◆ ToJson() [6/37]

std::string pulsatrix::ToJson ( const CircuitGraphDocument &  doc)
Exceptions
std::invalid_argumentif node ids repeat or are negative, or an edge names a node that isn't in the list.

◆ ToJson() [7/37]

JsonValue pulsatrix::ToJson ( const ClassificationReport &  report)

The report as a pulsatrix.classification_report.v1 document.

◆ ToJson() [8/37]

std::string pulsatrix::ToJson ( const ContactMapDocument &  doc)
Exceptions
std::invalid_argumentif the sequence is empty, predicted isn't L x L, or truth is neither empty nor L x L of 0, 1 and NaN.

◆ ToJson() [9/37]

JsonValue pulsatrix::ToJson ( const ContrastiveResult &  result,
const std::string &  kind 
)

The result as a pulsatrix.contrastive.v1 document; kind is "pertinent_negative" or "pertinent_positive".

◆ ToJson() [10/37]

std::string pulsatrix::ToJson ( const CounterfactualDocument &  doc)
Exceptions
std::invalid_argumentif a scale is not positive.

◆ ToJson() [11/37]

JsonValue pulsatrix::ToJson ( const CoverageReport &  report)

The report as a pulsatrix.coverage.v1 document, without the per-input misses.

◆ ToJson() [12/37]

JsonValue pulsatrix::ToJson ( const ExplainerCapabilities &  capabilities)

The declaration as a JSON object, with the enums as their to_string() names.

◆ ToJson() [13/37]

JsonValue pulsatrix::ToJson ( const Explanation &  explanation)

The explanation as a pulsatrix.explanation.v1 document, attribution values included.

◆ ToJson() [14/37]

JsonValue pulsatrix::ToJson ( const ExplanationPlan &  plan)

The plan as a pulsatrix.explanation_plan.v1 document. Each explainer appears by name, with its header and entry points, so the document stands alone.

◆ ToJson() [15/37]

std::string pulsatrix::ToJson ( const FeatureDashboardDocument &  doc)
Exceptions
std::invalid_argumentif the histogram's lengths don't match, a count is negative, or an example has tokens and a different number of activations.

◆ ToJson() [16/37]

std::string pulsatrix::ToJson ( const HeatmapDocument &  doc)
Exceptions
std::invalid_argumentif values.size() != rows * cols or a label list has the wrong length.

◆ ToJson() [17/37]

JsonValue pulsatrix::ToJson ( const LogOddsErrorReport &  report)

The report as a JSON object: clip, overall, and bands.

◆ ToJson() [18/37]

std::string pulsatrix::ToJson ( const MorrisDocument &  doc)

◆ ToJson() [19/37]

std::string pulsatrix::ToJson ( const MutationMapDocument &  doc)
Exceptions
std::invalid_argumentif the sequence or alphabet is empty, a letter repeats in the alphabet, or values isn't residues x alphabet.

◆ ToJson() [20/37]

std::string pulsatrix::ToJson ( const PartialDependenceDocument &  doc)
Exceptions
std::invalid_argumentif the grid is empty or not strictly increasing, a length doesn't match it, the method is unknown, or an ALE document has ICE curves.

◆ ToJson() [21/37]

std::string pulsatrix::ToJson ( const PersistenceDiagramDocument &  doc)

Writes the document.

Exceptions
std::invalid_argumentnaming the JSON Pointer of the first problem.

◆ ToJson() [22/37]

std::string pulsatrix::ToJson ( const ProjectionDocument &  doc)
Exceptions
std::invalid_argumentif there are fewer than two axes, coordinates isn't whole rows of them, a coordinate isn't finite, or a per-point list or the ratios have the wrong length.

◆ ToJson() [23/37]

JsonValue pulsatrix::ToJson ( const PrototypeResult &  result)

The result as a pulsatrix.prototypes.v1 document.

◆ ToJson() [24/37]

JsonValue pulsatrix::ToJson ( const RegressionReport &  report)

The report as a pulsatrix.regression_report.v1 document.

◆ ToJson() [25/37]

std::string pulsatrix::ToJson ( const ResidueTracksDocument &  doc)
Exceptions
std::invalid_argumentif the sequence is empty, a track's length isn't the sequence's, a name is empty, a feature's start is after its end or outside the sequence, or residue_ids is neither empty nor one per residue.

◆ ToJson() [26/37]

JsonValue pulsatrix::ToJson ( const RobustnessCurve &  curve)

The curve as a pulsatrix.robustness_curve.v1 document.

◆ ToJson() [27/37]

std::string pulsatrix::ToJson ( const SensitivityDocument &  doc)

◆ ToJson() [28/37]

JsonValue pulsatrix::ToJson ( const SensitivityReport &  report)

The report as a pulsatrix.explanation_sensitivity.v1 document.

◆ ToJson() [29/37]

std::string pulsatrix::ToJson ( const SequenceLogoDocument &  doc)
Exceptions
std::invalid_argumentif the alphabet is empty or repeats a letter, the probabilities aren't positions x alphabet, a row isn't a distribution, or a non-empty sequence has another length.

◆ ToJson() [30/37]

std::string pulsatrix::ToJson ( const SeriesDocument &  doc)
Exceptions
std::invalid_argumentfor a document that breaks the rules above: no panels, a panel with no series, a series with no points or no name, two series with the same name in a panel, y (or lo, hi) of a different length from x, or lo > hi.

◆ ToJson() [31/37]

JsonValue pulsatrix::ToJson ( const SliceErrorReport &  report)

The report as a pulsatrix.slice_error.v1 document.

◆ ToJson() [32/37]

std::string pulsatrix::ToJson ( const SobolDocument &  doc)

◆ ToJson() [33/37]

JsonValue pulsatrix::ToJson ( const SurrogateTreeResult &  result,
const std::vector< std::string > &  feature_names = {} 
)

The result as a pulsatrix.surrogate_tree.v1 document.

◆ ToJson() [34/37]

std::string pulsatrix::ToJson ( const TokenRelevanceDocument &  doc)
Exceptions
std::invalid_argumentif tokens and relevance (or scored, when set) differ in length, or granularity is neither "token" nor "word".

◆ ToJson() [35/37]

std::string pulsatrix::ToJson ( const TrainingLogDocument &  doc)
Exceptions
std::invalid_argumentif a series' steps and values differ in length, or a tag repeats.

◆ ToJson() [36/37]

JsonValue pulsatrix::ToJson ( const TreeRules &  rules)

The rules as a pulsatrix.tree_rules.v1 document: each rule's text, conditions, class, support and confidence.

◆ ToJson() [37/37]

JsonValue pulsatrix::ToJson ( const UncertaintyDecomposition &  decomposition)

The decomposition as a pulsatrix.uncertainty.v1 document, without the mean probabilities.

◆ TokenizePromptCompletions()

std::vector< PromptCompletion > pulsatrix::TokenizePromptCompletions ( const std::vector< JsonValue > &  rows,
const TextTokenizer &  tokenizer,
const std::string &  prompt_key = "prompt",
const std::string &  completion_key = "completion",
bool  add_special_tokens = false 
)

Tokenizes each row's prompt and completion strings (objects with those keys). The two are tokenized separately, so a completion like " Yes" keeps its own tokens whatever the prompt ends with.

Parameters
add_special_tokensPassed to TextTokenizer::encode() for the prompt (a BOS token, for tokenizers that add one); never for the completion.
Exceptions
std::invalid_argumentif a row isn't an object with both strings, or a prompt or completion tokenizes to nothing.

◆ ToMorrisDocument()

MorrisDocument pulsatrix::ToMorrisDocument ( const MorrisResult &  result,
const std::vector< std::string > &  names = {},
std::string  target = "" 
)

names, if not empty, has one name per entry of result.features (the varied features, in order); otherwise features are called feature_<index>.

Exceptions
std::invalid_argumentif names has the wrong length.

◆ ToNeuronpediaJson()

std::string pulsatrix::ToNeuronpediaJson ( const AttributionGraph &  graph)

The graph as Neuronpedia/circuit-tracer JSON, including circuit-tracer's optional node fields (token_prob, is_target_logit) and an empty qParams.

Exceptions
std::invalid_argumentif a required string is empty, node ids repeat, a link names an unknown node, a number isn't finite, a node's position is outside the prompt, or a logit's label lacks (p=...).

◆ top_k()

TopKResult pulsatrix::top_k ( const Tensor &  input,
int64_t  k,
bool  largest = true 
)

Selects the k largest (or smallest) entries of every row along the last dimension.

Parameters
inputTensor of any rank >= 1. Every slice along its last dimension is one row.
kEntries kept per row; 1 <= k <= the last dimension's size.
largesttrue for the k largest (default), false for the k smallest.
Returns
Values and indices of shape (..., k), in rank order, on input's device.
Note
Order is fully deterministic and identical on every backend: NaN ranks above every number (first when largest, last when smallest), and equal values keep the lower index first. Indices are whole-number floats, like every other index tensor in this library, and so are exact only below 2^24; longer rows are rejected.
Selection only – no gradient. A module that routes gradients through a top-k (a TopK sparse autoencoder, a mixture-of-experts router) scatters through indices itself.
Exceptions
std::invalid_argumentif input is empty or rank 0, k is outside [1, last dimension], or the last dimension exceeds 2^24 – external boundary.

◆ ToPartialDependenceDocument() [1/2]

PartialDependenceDocument pulsatrix::ToPartialDependenceDocument ( const AleResult &  result,
std::string  feature = "",
std::string  target = "" 
)

An ALE curve as a document with method "ale": the bin edges as the grid, the effects as the curve, and the instances' feature values for the rug.

◆ ToPartialDependenceDocument() [2/2]

PartialDependenceDocument pulsatrix::ToPartialDependenceDocument ( const IceResult &  result,
std::string  feature = "",
std::string  target = "" 
)

Copies result, its partial dependence curve included.

◆ ToPersistenceDiagramDocument() [1/2]

PersistenceDiagramDocument pulsatrix::ToPersistenceDiagramDocument ( const RipsResult &  result,
std::string  title = "" 
)

The same, from ComputeRipsPersistence(), with its threshold.

◆ ToPersistenceDiagramDocument() [2/2]

PersistenceDiagramDocument pulsatrix::ToPersistenceDiagramDocument ( const std::vector< PersistenceDiagram > &  diagrams,
std::string  title = "" 
)

The diagrams as a document: births, deaths and each diagram's error bound.

Exceptions
std::invalid_argumentfor a diagram the document can't hold (a NaN, a death before its birth, a dimension given twice).

◆ TopRecall()

double pulsatrix::TopRecall ( const std::vector< double > &  true_scores,
const std::vector< double > &  predicted,
double  top_true = 10.0,
double  top_model = 10.0 
)

ProteinGym's top recall: of the variants at or above the true scores' (100 - top) percentile, the fraction also at or above the predicted scores' percentile. Percentiles interpolate linearly, as numpy's do.

◆ ToRgbImageBuffer()

RgbImageBuffer pulsatrix::ToRgbImageBuffer ( const Tensor &  image_chw)

Converts a decoded image Tensor into an interleaved-RGB byte buffer for GPU texture upload (the data-preview "image grid" touchpoint's pure half – the actual glTexImage2D call lives in TextureCache, which is GL-dependent and untestable here).

Parameters
image_chwA rank-3 (C, H, W) tensor, or a rank-4 tensor with a leading batch dimension of 1 ((1, C, H, W) – ImageFolderDataset::get()'s convention). C must be 1 (replicated across R/G/B) or 3.
Note
Values are assumed already normalized to [0, 1] and clamped before scaling to [0, 255] – out-of-range input (e.g. an un-normalized decoder output) is clamped rather than wrapped, since a wrapped byte would silently invert bright/dark regions.
Exceptions
std::invalid_argumentif image_chw's rank/channel count don't match the above.

◆ ToSaliencyHeatmap()

HeatmapGrid pulsatrix::ToSaliencyHeatmap ( const Attribution &  attr)

Reshapes an Attribution's values into a 2D grid for a saliency overlay heatmap.

Parameters
attrA rank-2 Attribution, a rank-3 Attribution whose leading (channel or batch) dimension is 1 (single-channel saliency map, or Grad-CAM's batch-1 (1, H, W) map, squeezed), or a rank-4 Attribution of shape (1, 1, H, W) – the shape every input-space image explainer (Saliency, IntegratedGradients, LRP, LIME, KernelSHAP) returns for a single batched single-channel image such as an MNIST digit.
Exceptions
std::invalid_argumentif attr.values is not reshapable to a 2D grid by the rules above (e.g. rank 1, rank 3 with more than one channel, or rank 4 with a batch or channel dimension other than 1).

◆ ToSensitivityDocument()

SensitivityDocument pulsatrix::ToSensitivityDocument ( const LocalSensitivityResult &  result,
const std::vector< std::string > &  names = {},
std::string  target = "" 
)

Copies result. names, if not empty, has one name per input feature (flat index); features without a name are called feature_<index>.

◆ ToSobolDocument()

SobolDocument pulsatrix::ToSobolDocument ( const SobolResult &  result,
const std::vector< std::string > &  names = {},
std::string  target = "" 
)

names, if not empty, has one name per entry of result.features (the varied features, in order); otherwise features are called feature_<index>.

Exceptions
std::invalid_argumentif names has the wrong length.

◆ ToTrainingLogDocument()

TrainingLogDocument pulsatrix::ToTrainingLogDocument ( const ImPlotMetricsSink &  sink)

Copies everything sink has logged, sorted by tag.

◆ TournamentSelect()

template<typename Genotype , typename FitnessT , typename RNG >
size_t pulsatrix::TournamentSelect ( const std::vector< Individual< Genotype, FitnessT > > &  population,
size_t  tournament_size,
RNG &  rng 
)

Tournament selection: draw tournament_size individuals without replacement from population and return the index of the fittest among them.

Parameters
populationNon-empty population to select from.
tournament_sizeNumber of distinct competitors, in [1, population.size()].
rngAny UniformRandomBitGenerator (e.g. std::mt19937).
Returns
Index into population of the selected individual.
Exceptions
std::invalid_argumentif population is empty, tournament_size is 0, or tournament_size exceeds population.size() – external-boundary malformed input (caller-supplied population/config), not an internal invariant.
Note
tournament_size == population.size() draws every individual exactly once (without replacement), so it always returns the global-best index regardless of the RNG stream – this operator's own hand-verifiable correctness case, independent of which RNG or seed is used.

◆ ToVegaLiteBarChart()

JsonValue pulsatrix::ToVegaLiteBarChart ( const AttributionDocument &  doc,
int  top_k = 10,
const HtmlOptions &  options = {} 
)

Horizontal bars of the top_k features with the largest |attribution|, colored by sign on the SVG renderer's diverging scale.

◆ ToVegaLiteBeeswarm()

JsonValue pulsatrix::ToVegaLiteBeeswarm ( const std::vector< AttributionDocument > &  docs,
const std::vector< int64_t > &  feature_indices,
const HtmlOptions &  options = {} 
)

One row per feature in feature_indices: every document's value for it, spread so points don't overlap (ToBeeswarmPoints).

◆ ToVegaLiteCircuitGraph()

JsonValue pulsatrix::ToVegaLiteCircuitGraph ( const CircuitGraphDocument &  doc)

A Vega-Lite node-link view of a circuit graph: nodes in columns by depth (longest path from a source), colored by ablation effect, edges as lines weighted by |weight|.

Exceptions
std::invalid_argumentfor an empty graph or an edge naming a missing node.

◆ ToVegaLiteCounterfactual()

JsonValue pulsatrix::ToVegaLiteCounterfactual ( const CounterfactualDocument &  doc,
int  max_rows = 12,
const HtmlOptions &  options = {} 
)

The changed features of a counterfactual, costliest first, as bars of their change in scale units; the tooltip has the old and new values.

◆ ToVegaLiteCounterfactualSet()

JsonValue pulsatrix::ToVegaLiteCounterfactualSet ( const std::vector< CounterfactualDocument > &  docs,
const HtmlOptions &  options = {} 
)

Several counterfactuals of one input: a grid of features (rows) by counterfactuals (columns), each cell colored by the change in scale units and labeled with the new value.

◆ ToVegaLiteFeatureHistogram()

JsonValue pulsatrix::ToVegaLiteFeatureHistogram ( const FeatureDashboardDocument &  doc,
const HtmlOptions &  options = {} 
)

A feature's activation histogram (the dashboard's chart; RenderFeatureDashboardHtml adds the top examples).

◆ ToVegaLiteHeatmap()

JsonValue pulsatrix::ToVegaLiteHeatmap ( const HeatmapDocument &  doc,
const HtmlOptions &  options = {} 
)

A heatmap: diverging around zero when any value is negative, Viridis otherwise. Non-finite cells are gray.

◆ ToVegaLiteMorris()

JsonValue pulsatrix::ToVegaLiteMorris ( const MorrisDocument &  doc,
const HtmlOptions &  options = {} 
)

Morris screening: mu* against sigma per feature, with mu*'s confidence interval and the sigma = mu* line.

◆ ToVegaLitePartialDependence()

JsonValue pulsatrix::ToVegaLitePartialDependence ( const PartialDependenceDocument &  doc,
const PartialDependenceSvgOptions &  pd = {},
const HtmlOptions &  options = {} 
)

A partial dependence plot: ICE curves under the average, and a rug of the instances' feature values. Zoom with the mouse wheel; drag to pan.

◆ ToVegaLiteProjection()

JsonValue pulsatrix::ToVegaLiteProjection ( const ProjectionDocument &  doc,
const HtmlOptions &  options = {} 
)

A projection as a zoomable scatter plot, colored as RenderProjectionSvg colors it, with each point's label on hover. With three or more axes, three panels: PC1 against PC2, PC1 against PC3 and PC2 against PC3, the views of a 3D projection.

◆ ToVegaLiteSeries()

JsonValue pulsatrix::ToVegaLiteSeries ( const SeriesDocument &  doc,
const SeriesViewOptions &  view = {},
const HtmlOptions &  options = {} 
)

A series document (VIZ-9): one zoomable chart per panel, stacked, each a line per series with points and interval rules, colored as RenderSeriesSvg colors them.

Exceptions
std::invalid_argumentfor what RenderSeriesSvg() rejects.

◆ ToVegaLiteSobol()

JsonValue pulsatrix::ToVegaLiteSobol ( const SobolDocument &  doc,
int  top_k = 10,
const HtmlOptions &  options = {} 
)

Sobol indices: first-order bars in front of total-order ones, with confidence whiskers.

◆ ToVegaLiteTornado()

JsonValue pulsatrix::ToVegaLiteTornado ( const SensitivityDocument &  doc,
int  top_k = 10,
const HtmlOptions &  options = {} 
)

A tornado chart of the top_k features with the largest swing.

◆ ToVegaLiteTrainingLog()

JsonValue pulsatrix::ToVegaLiteTrainingLog ( const TrainingLogDocument &  doc,
const HtmlOptions &  options = {} 
)

A training log: one zoomable line chart per scalar tag, and one histogram per histogram tag.

◆ ToVegaLiteWaterfall()

JsonValue pulsatrix::ToVegaLiteWaterfall ( const AttributionDocument &  doc,
float  baseline_value,
const HtmlOptions &  options = {} 
)

A waterfall from baseline_value through the features' contributions to the prediction (ToWaterfallSteps).

◆ ToWaterfallBars()

std::vector< WaterfallBar > pulsatrix::ToWaterfallBars ( const std::vector< WaterfallStep > &  steps,
float  baseline_value 
)

Converts waterfall steps into floating bars, each spanning from the previous running total to its own running total – i.e. bar i covers [min(c_{i-1}, c_i), max(c_{i-1}, c_i)] with c_{-1} = baseline_value. Correct for any sign of baseline or running total: a cascade that starts below zero, crosses zero, or stays negative (e.g. explaining a negative logit) floats exactly where the running total is, rather than being anchored at zero the way stacked bar segments are.

Parameters
stepsToWaterfallSteps's output.
baseline_valueThe same baseline passed to ToWaterfallSteps.

◆ ToWaterfallSteps()

std::vector< WaterfallStep > pulsatrix::ToWaterfallSteps ( const Attribution &  attr,
float  baseline_value 
)

Converts an Attribution's per-feature values into a cascading waterfall from a real baseline to the final prediction (hc_information_visualization.md SS5/SS6: the one case where a bar chart legitimately does not start at zero, since the baseline itself is the meaningful reference point – Tufte's lie-factor rule is satisfied relative to that baseline, not to zero).

Parameters
attrA rank-1 Attribution (one value per feature), or a rank-2 Attribution whose leading (batch) dimension is 1 (see ToFeatureImportanceBars's note on always-batched explainer output), in the explainer's own feature order – deliberately NOT sorted by magnitude, since a waterfall's narrative is the accumulation path, not a ranking.
baseline_valueThe starting reference value (e.g. Integrated Gradients' baseline prediction, or the model's mean output).
Exceptions
std::invalid_argumentif attr.values is not rank 1 or batch-1 rank 2.

◆ TraceCircuit()

CircuitTrace pulsatrix::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 logits and every active feature through the frozen model.

  • The forward pass is the model's own: reconstruction plus error is the MLP's output, so the logits are unchanged.
  • Frozen: attention patterns, every RMSNorm's scale (pre- and post-norms, the final norm). Gradients don't pass through the MLPs; with a skip they pass through it.
  • Edges come from batched backward passes from each target's input vector, contracted at every layer's MLP output with the sources' output vectors (a_s times decoders, errors) and at the embeddings with the scaled token embeddings.
    Note
    Gemma's final logit softcap is outside the linearization.
    Exceptions
    std::invalid_argumentif the transcoder's layers or width don't match the model, or the prompt is empty.

◆ TrainCav()

Cav pulsatrix::TrainCav ( const Tensor &  concept_activations,
const Tensor &  random_activations,
const CavOptions &  options = {} 
)

Trains a CAV from a layer's activations on concept examples and on random examples.

Parameters
concept_activations,random_activationsshape (n, ...), a row per example, the same width. Each needs at least 2 rows (3 with the default holdout).
Exceptions
std::invalid_argumentif the widths differ, a set is too small, or a value isn't finite.

◆ TrainDecomposition()

template<typename Optimizer >
DecompositionLoss pulsatrix::TrainDecomposition ( ParameterDecomposition &  d,
const Tensor &  x,
Optimizer &  optimizer 
)

One training step: zero the gradients, loss_and_backward(), one optimizer step.

◆ TrainFeaturizer() [1/2]

template<typename Optimizer >
FeaturizerLoss pulsatrix::TrainFeaturizer ( Featurizer &  featurizer,
const Tensor &  x,
const Tensor &  target,
Optimizer &  optimizer,
bool  unit_norm_decoder = true,
FeatureActivityTracker *  tracker = nullptr 
)

TrainFeaturizer for a transcoder: one step on predicting target from x.

◆ TrainFeaturizer() [2/2]

template<typename Optimizer >
FeaturizerLoss pulsatrix::TrainFeaturizer ( Featurizer &  featurizer,
const Tensor &  x,
Optimizer &  optimizer,
bool  unit_norm_decoder = true,
FeatureActivityTracker *  tracker = nullptr 
)

One training step for any featurizer: zero the gradients, loss_and_backward(), one optimizer step, then normalize_decoder() when unit_norm_decoder. When tracker is given it observes the batch's codes.

Template Parameters
OptimizerSGDOptimizer, AdamOptimizer or AdamWOptimizer: anything with zero_grad(Module&) and step(Module&).

◆ TrainLinearProbe()

ProbeResult pulsatrix::TrainLinearProbe ( const std::vector< float > &  features,
int64_t  dim,
const std::vector< int > &  labels,
int  classes,
const std::vector< bool > &  train,
const std::vector< bool > &  test,
DeviceBackend *  backend,
const ProbeOptions &  options = {} 
)

Trains a linear softmax probe (standardized features, AdamW, cross-entropy) on the rows marked in train and scores it on those marked in test.

Parameters
featuresrows x dim, row-major.
labelsone class in [0, classes) per row.
Exceptions
std::invalid_argumentif the sizes don't agree, classes < 2, or either set is empty.

◆ TrainTagger()

std::vector< float > pulsatrix::TrainTagger ( TinyTagger &  tagger,
TaggingRule  rule,
const FineTuneConfig &  config,
DeviceBackend *  backend 
)

Trains every parameter of tagger on rule with the whole v1.1 training stack: AdamW with parameter groups, warmup plus cosine, gradient accumulation normalized by the window's token count, and gradient clipping.

Returns
The loss of each step run (the window mean over its real tokens).
Note
Each step's data depends only on (data_seed, step), so a resumed run sees exactly the batches an uninterrupted one would.

◆ TrajectoryNetworkRules()

LRPRuleConfig pulsatrix::TrajectoryNetworkRules ( )

The network rules ConcatDenoiser uses unless told otherwise: the epsilon rule with the bias in the denominator (Zennit's), so the biases absorb their share. The codebase's default pre-bias rule divides by x W alone, which a hidden layer's bias can leave near zero while the unit is active; chained over the steps of a sampler its relevance blew up (DIFF-5's planted DDPM: conditioning shares up to 570 times the explained value).

◆ TrueContacts()

ContactMap pulsatrix::TrueContacts ( const StructureChain &  chain,
double  threshold = 8.0,
ContactAtom  atom = ContactAtom::Beta 
)

True contacts: 1 where two residues are closer than threshold (8 Å by convention), 0 where they aren't, and NaN where a distance is unknown.

◆ TwoNNDimension()

TwoNNResult pulsatrix::TwoNNDimension ( const Tensor &  x,
double  discard_fraction = 0.1 
)

TwoNN intrinsic dimension (Facco, d'Errico, Rodriguez and Laio, Scientific Reports 2017): from each point's distances to its two nearest neighbors, mu = r2 / r1, whose distribution depends only on the dimension the points vary in locally.

Parameters
xshape (n, ...): a row per point, under Euclidean distance.
discard_fractionThe share of the largest mu values the fit leaves out, 0.1 in the paper.
Note
Repeated rows are removed first, as DADApy's remove_identical_points() does: a zero distance makes mu infinite. The search is exact, at n^2 x width multiply-adds.
The estimate is biased low when the dimension is high for the number of points (tens of dimensions need thousands of points), and it measures the scale of the nearest neighbors only: noise on a low-dimensional manifold raises it.
Exceptions
std::invalid_argumentif x has rank below 2, a NaN or infinity, fewer than 3 distinct rows, or discard_fraction isn't in (0, 1), or leaves fewer than 2 points to fit.

◆ TwoPointCrossover()

template<typename T , typename RNG >
std::pair< std::vector< T >, std::vector< T > > pulsatrix::TwoPointCrossover ( const std::vector< T > &  parent1,
const std::vector< T > &  parent2,
RNG &  rng 
)

RNG-driven wrapper: draws two points in [0, size], sorted ascending.

Exceptions
std::invalid_argumentif parent sizes differ or parent size < 2.

◆ TwoPointCrossoverAtPoints()

template<typename T >
std::pair< std::vector< T >, std::vector< T > > pulsatrix::TwoPointCrossoverAtPoints ( const std::vector< T > &  parent1,
const std::vector< T > &  parent2,
size_t  point1,
size_t  point2 
)

Swaps the [point1, point2) segment between both parents.

Exceptions
std::invalid_argumentif parent sizes differ, point1 > point2, or point2 exceeds parent size.

◆ UniformCrossover()

template<typename T , typename RNG >
std::pair< std::vector< T >, std::vector< T > > pulsatrix::UniformCrossover ( const std::vector< T > &  parent1,
const std::vector< T > &  parent2,
double  swap_probability,
RNG &  rng 
)

RNG-driven wrapper: each gene swaps independently with probability swap_probability.

Exceptions
std::invalid_argumentif parent sizes differ or swap_probability is outside [0, 1].
Note
swap_probability == 0.0 or 1.0 make std::bernoulli_distribution deterministic (always false / always true respectively) – exact, RNG-independent correctness cases.

◆ UniformCrossoverByMask()

template<typename T >
std::pair< std::vector< T >, std::vector< T > > pulsatrix::UniformCrossoverByMask ( const std::vector< T > &  parent1,
const std::vector< T > &  parent2,
const std::vector< bool > &  swap_mask 
)

Swaps each gene independently wherever swap_mask is true.

Exceptions
std::invalid_argumentif parent1/parent2/swap_mask sizes are not all equal.

◆ UnitCubeToConfiguration()

Configuration pulsatrix::UnitCubeToConfiguration ( const SearchSpace &  space,
const std::vector< float > &  t 
)
inline

Maps a unit-hypercube point (one value per parameter, each in [0, 1]) to a Configuration, using space's own declared bounds.

Exceptions
std::invalid_argumentif t.size() != space.size(), any t[i] is outside [0, 1], or space contains a parameter kind other than Continuous/LogUniform.

◆ UniversalNullTest()

UniversalNullResult pulsatrix::UniversalNullTest ( const PersistenceDiagram &  diagram,
double  alpha = 0.05 
)

Bobrowski and Skraba's universal null test for every feature of a Vietoris-Rips diagram in dimension 1 or above: ell = log log(death / birth) - L-bar - (Euler-Mascheroni's constant), compared with the left-skewed Gumbel, whose survival function is exp(-e^ell).

Parameters
alphaThe family-wise significance level, split over the features by Bonferroni.
Note
A = 1 and B = -gamma - L-bar are the paper's values for Vietoris-Rips filtrations. The test assumes the diagram is mostly noise: with only a handful of features, L-bar is set by the signal itself and the test loses its power. Use diagrams of hundreds of points or more. Point sets spaced too evenly (lattices, repulsive processes) don't follow the null.
Exceptions
std::invalid_argumentif the diagram is H0 (all births are 0), has fewer than 2 finite features with birth above 0, or alpha is outside (0, 1).

◆ UnmergeIA3()

void pulsatrix::UnmergeIA3 ( Module &  model)

Divides it back out, as PEFT does. Entries of l within 1e-8 of 0 can't be undone exactly.

◆ UnmergeLora()

void pulsatrix::UnmergeLora ( Module &  model)

Takes every merged adapter out of its base weight again.

◆ UpperConfidenceBound()

double pulsatrix::UpperConfidenceBound ( double  mean,
double  variance,
double  kappa = 2.0 
)
inline

GP-Upper-Confidence-Bound: mean + kappa * sqrt(variance).

Parameters
kappaExploration weight (default 2.0, a common practical default – larger values favor exploring high-uncertainty regions over exploiting the current best mean).
Exceptions
std::invalid_argumentif variance < 0.

◆ VegaLitePage()

std::string pulsatrix::VegaLitePage ( const JsonValue &  spec,
const std::string &  heading,
const HtmlOptions &  options = {},
const std::string &  extra_html = "" 
)

A complete page that draws spec with vega-embed, which adds the PNG/SVG export menu.

Parameters
headingShown above the chart.
extra_htmlAppended after it, as is.
Exceptions
std::runtime_errorif inline scripts are asked for and can't be read.

◆ ViridisColormap()

RgbColor pulsatrix::ViridisColormap ( float  normalized_value)

Viridis colormap – perceptually uniform, colorblind-safe – for sequential/unsigned magnitude (hc_information_visualization.md SS4: "Recommended Color Systems").

Parameters
normalized_valuePosition along the colormap, expected in [0, 1]; values outside this range are clamped to the nearest end anchor.
Note
Deliberately never a rainbow/jet map – see the design doc's SS4 "Rainbow (Jet) Colormap Problem". Approximates matplotlib's Viridis via a small set of anchor colors with linear interpolation between them; exact per-channel fidelity against ImPlot's own built-in ImPlotColormap_Viridis is an open verification item (plan Open Risk 4), not assumed here.

◆ VizDocumentKind()

std::string pulsatrix::VizDocumentKind ( std::string_view  json)

Reads only a document's "schema" member and returns its kind (for example "attribution"), so a viewer can pick the matching reader.

Exceptions
std::invalid_argumentif json isn't a JSON object with a "schema" of the form pulsatrix.<kind>.v<N>, or if N isn't kVizDocumentVersion.

◆ VizFontsUseFreeType()

bool pulsatrix::VizFontsUseFreeType ( )

Whether this build's ImGui uses FreeType (color emoji) rather than stb_truetype.

◆ WassersteinDistance()

double pulsatrix::WassersteinDistance ( const PersistenceDiagram &  a,
const PersistenceDiagram &  b,
double  order = 2 
)

The q-Wasserstein distance between two diagrams of the same dimension, with the L-infinity norm between points.

Parameters
orderq, at least 1. Infinity gives the bottleneck distance's value.
Returns
Infinite if the numbers of essential features differ.
Note
Exact, by the Hungarian algorithm on n1 + n2 rows: (n1 + n2)^3 time, so up to about a thousand points in all. Unlike the bottleneck distance it isn't certified: an error of e in every distance can move it by up to e times the q-th root of the number of points.
Exceptions
std::invalid_argumentif the dimensions differ or order is below 1 or NaN.

◆ WithSubsamplingBound()

PersistenceDiagram pulsatrix::WithSubsamplingBound ( PersistenceDiagram  diagram,
const Landmarks &  landmarks 
)

A diagram of the landmarks re-certified against the whole cloud: its error_bound becomes its own plus the subsampling term, a bound on its bottleneck distance from the diagram of all the points (with exact distances).

◆ WriteFasta()

std::string pulsatrix::WriteFasta ( const std::vector< FastaRecord > &  records,
size_t  width = 60 
)

FASTA text for records, sequences wrapped at width residues (0: one line).

◆ WriteJson()

std::string pulsatrix::WriteJson ( const JsonValue &  value)

Writes value as JSON, indented by two spaces and ending with a newline.

Note
Deterministic: the same value always gives the same bytes on every platform. Arrays that hold only numbers, booleans and nulls go on one line, so long value arrays stay compact. Strings are written as UTF-8, with ", \ and control characters escaped.
Exceptions
std::invalid_argumentif a string isn't valid UTF-8.

◆ WriteJsonCompact()

std::string pulsatrix::WriteJsonCompact ( const JsonValue &  value)

Writes value as JSON on one line, with no whitespace and no trailing newline.

Note
For HTTP request bodies and newline-delimited protocols such as MCP over stdio: newlines inside strings are escaped, so the result never contains a newline. Deterministic, like WriteJson().
Exceptions
std::invalid_argumentif a string isn't valid UTF-8.

◆ WriteNpy()

void pulsatrix::WriteNpy ( const std::string &  path,
const Tensor &  x 
)

SerializeNpy() written to path.

Exceptions
std::runtime_errorif the file can't be written.

◆ WriteSafetensors()

void pulsatrix::WriteSafetensors ( const std::string &  path,
const std::vector< std::pair< std::string, const Tensor * > > &  tensors,
const std::map< std::string, std::string > &  metadata = {} 
)

SerializeSafetensors() written to path.

Exceptions
std::runtime_errorif the file can't be written; otherwise as SerializeSafetensors().

◆ XORFitness()

double pulsatrix::XORFitness ( const NEATGenome &  genome)
inline

Evaluates genome's phenotype on all four XOR patterns ((0,0)->0, (0,1)->1, (1,0)->1, (1,1)->0, in that order) and scores it as 4.0 minus the sum of squared errors – a perfect fit scores 4.0; a genome producing exactly 0.5 for every pattern (e.g. a fresh, all-zero-weight genome, before any weight differentiation has emerged) scores exactly 3.0 (4.0 - 4*0.25).

Exceptions
WhateverEvaluateNEATPhenotype throws if genome's Input node count isn't 2.

◆ ZeroModuleGradients()

void pulsatrix::ZeroModuleGradients ( Module &  module)
inline

Zeros every gradient tensor module.parameters() reports – a standalone alternative to calling some optimizer's own zero_grad(module) when no persistent per-module optimizer instance is being kept around (Phase 5 Mission 2's own mutation-attempt loop constructs a fresh optimizer per attempt, so there is no single optimizer instance left to call zero_grad on between generations).

Variable Documentation

◆ k3DmolVersion

constexpr const char* pulsatrix::k3DmolVersion = "2.5.5"
inlineconstexpr

The 3Dmol.js version the structure page loads.

◆ kAminoAcids

constexpr const char* pulsatrix::kAminoAcids = "ACDEFGHIKLMNPQRSTVWY"
inlineconstexpr

The 20 standard amino acids, in the order SingleMutantScan's columns use.

◆ kCheckpointFormatVersion

constexpr int pulsatrix::kCheckpointFormatVersion = 1
inlineconstexpr

The checkpoint format this build writes. Files record it as format_version; a file without one (any plain safetensors file) is version 0. Older versions load through a migration table; newer ones are rejected.

◆ kFixedTopologyXORNumParams

constexpr size_t pulsatrix::kFixedTopologyXORNumParams = 9
inlineconstexpr

Total flat-parameter count: 2*2 (input->hidden weights) + 2 (hidden biases) + 2 (hidden->output weights) + 1 (output bias) = 9.

◆ kLongRange

constexpr SeparationRange pulsatrix::kLongRange {24, 0}
inlineconstexpr

◆ kMediumRange

constexpr SeparationRange pulsatrix::kMediumRange {12, 24}
inlineconstexpr

◆ kShortRange

constexpr SeparationRange pulsatrix::kShortRange {6, 12}
inlineconstexpr

CASP's and ESM's ranges: short 6–11, medium 12–23, long 24 and up.

◆ kVegaEmbedVersion

constexpr const char* pulsatrix::kVegaEmbedVersion = "7.3.0"
inlineconstexpr

◆ kVegaLiteMimeType

constexpr const char* pulsatrix::kVegaLiteMimeType = "application/vnd.vegalite.v5+json"
inlineconstexpr

The MIME type Jupyter front ends (JupyterLab, Notebook 7, VS Code) render Vega-Lite from. pulsatrix's specs use only Vega-Lite 5 features, so they're sent as version 5.

◆ kVegaLiteVersion

constexpr const char* pulsatrix::kVegaLiteVersion = "6.4.3"
inlineconstexpr

◆ kVegaVersion

constexpr const char* pulsatrix::kVegaVersion = "6.4.0"
inlineconstexpr

The versions of Vega, Vega-Lite and vega-embed the pages load (BSD-3-Clause).

◆ kVizDocumentVersion

constexpr int pulsatrix::kVizDocumentVersion = 1
inlineconstexpr

The document format version this build writes and reads.