|
pulsatrix 1.1.0
|
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 ®ressor, const std::vector< double > &predictions) |
| The intervals for a point regressor's predictions (absolute_residual). | |
| std::vector< PredictionInterval > | PredictionIntervals (const ConformalRegressor ®ressor, 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 > ®ion) |
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 xeus-cpp's
| |
| 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. | |
| 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).
| 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.
| using pulsatrix::ConceptCondition = typedef std::vector<ConceptMask> |
One conditional heatmap's masks, at most one per layer.
| using pulsatrix::Configuration = typedef std::map<std::string, ConfigValue> |
A concrete hyperparameter configuration: parameter name -> concrete value.
| 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).
| using pulsatrix::DenoiserFn = typedef std::function<std::vector<float>(const std::vector<int64_t>& tokens)> |
| using pulsatrix::EmbedFn = typedef std::function<std::vector<float>(const Tensor& input)> |
Maps an input to the vector distances are measured in.
| using pulsatrix::ExplainFn = typedef std::function<Attribution(const Tensor& input)> |
Explains input using the model in its current state.
| 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).
| 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.
| 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.
| 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).
| using pulsatrix::NodeId = typedef size_t |
Stable identifier for a Node within its owning ComputationGraph.
| using pulsatrix::Objectives = typedef std::vector<double> |
| using pulsatrix::ParamSelector = typedef std::function<bool(const std::string& name, const Tensor& value)> |
Picks parameters by their named_parameters() name and value.
| 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.
| using pulsatrix::TextureId = typedef unsigned int |
Opaque GL texture handle, typed to avoid a GL header include in this public header.
| using pulsatrix::TrialFactory = typedef std::function<std::unique_ptr<ResumableTrial>(const Configuration&)> |
Builds a fresh ResumableTrial for a given configuration.
|
strong |
|
strong |
|
strong |
|
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. |
|
strong |
|
strong |
How much a caveat limits what the explanation supports.
|
strong |
How TrainCav() finds the concept direction.
|
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. |
|
strong |
|
strong |
Which estimator of CKA to use.
|
strong |
|
strong |
|
strong |
|
strong |
|
strong |
Direction of a DeviceBackend::copy() call.
| Enumerator | |
|---|---|
| HostToDevice | |
| DeviceToHost | |
| DeviceToDevice | |
| HostToHost | |
|
strong |
|
strong |
|
strong |
Which physical device a Tensor's buffer resides on.
| Enumerator | |
|---|---|
| Cpu | |
| Cuda | |
| Hip | |
|
strong |
How PairwiseDistances() computes the distances.
|
strong |
|
strong |
Unary elementwise operations supported by DeviceBackend::elementwise().
| 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) |
|
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). |
|
strong |
|
strong |
|
strong |
|
strong |
How a page gets the Vega libraries.
|
strong |
|
strong |
What the explainer's input has to be.
|
strong |
|
strong |
Elementwise passes of the fuzzy-logic modules, for DeviceBackend::logic_pointwise.
| Enumerator | |
|---|---|
| ConjunctionForward | |
| ConjunctionBackward | |
| ConjunctionLrp | |
| DisjunctionForward | |
| DisjunctionBackward | |
| DisjunctionLrp | |
|
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. |
|
strong |
Elementwise boolean gate for DeviceBackend::lrp_stabilized_divide().
| Enumerator | |
|---|---|
| None | every element passes |
| Positive | passes where gate > 0 |
| Negative | passes where gate < 0 |
|
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. |
|
strong |
How LRP seeds relevance at the target output.
|
strong |
The MLP's form.
| Enumerator | |
|---|---|
| Plain |
|
| Gated |
|
|
strong |
The least an explainer needs from the model, from least to most access.
| Enumerator | |
|---|---|
| BlackBox | Only a prediction function, |
| 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. |
|
strong |
|
strong |
|
strong |
|
strong |
|
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.
| Enumerator | |
|---|---|
| Linear | |
| Conv | |
| Activation | |
| Elementwise | |
| Reduction | |
| Normalization | |
| Pooling | |
| Embedding | |
| Composite | |
| Recurrent | |
| Attention | Multi-head (scaled dot-product) attention – Phase 3's MultiHeadAttentionModule.
|
|
strong |
|
strong |
|
strong |
How PointCloud turns one sample's activations into points.
|
strong |
|
strong |
How CompareRdms() correlates two RDMs.
|
strong |
How RepresentationalDissimilarity() measures the distance between two inputs.
|
strong |
Fused per-element recurrent-cell passes, for DeviceBackend::recurrent_cell. Slots (in[] / out[]), all (rows x hidden) per timestep unless noted:
| Enumerator | |
|---|---|
| RnnBackward | |
| LstmForward | |
| LstmBackward | |
| LstmLrp | |
| GruBackward | |
| GruLrp | |
|
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. |
|
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[]):
| Enumerator | |
|---|---|
| DqnLoss | |
| DqnGrad | |
| PgLoss | |
| PgGrad | |
| PpoLoss | |
| PpoGrad | |
| DqnTarget | |
| PolyakBlend | |
| TokenCeLoss | |
|
strong |
Which features RoPE rotates together (LLM-1).
|
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 | |
|
strong |
How PerSliceError() tests a slice against the rest.
|
strong |
|
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[]):
|
strong |
|
strong |
|
strong |
How the relevance on x_prev is split across skip, network and noise (h_1, h_2, h_3).
| Enumerator | |
|---|---|
| AbsoluteRatio |
|
| SignedEpsilon | The signed epsilon rule, |
| SignedRatio |
|
|
strong |
How the sampler chooses which masked positions to fill at each step.
|
strong |
|
strong |
How a source tensor becomes a target parameter.
| Enumerator | |
|---|---|
| Identity | |
| Transpose | Swap the two axes of a matrix: PyTorch's |
|
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.
|
strong |
How the text is cut into words.
|
strong |
The nine question categories of Liao, Gruen and Miller's XAI question bank (CHI 2020).
|
strong |
Adadi and Berrada's four reasons to explain a model (IEEE Access, 2018).
| HiddenStateHook pulsatrix::AblationHook | ( | int64_t | position, |
| std::vector< bool > | rows = {} |
||
| ) |
Zero-ablates one position: the same rows set to 0 instead of reconstructed.
| 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).
| 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.
| text | The text the offsets point into. |
| token_offsets | One byte range of text per token (Encoding::offsets). |
| token_scores | One score per token. |
| words | Byte ranges of text, in order and not overlapping (SplitWords()). |
| std::invalid_argument | if the sizes differ, or an offset or word lies outside the text, or the words overlap or are out of order. |
| ComponentAlignment pulsatrix::AlignComponentsToRows | ( | ComponentLinear & | layer | ) |
| 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.
| std::invalid_argument | for no records, or records whose match columns don't line up. |
| std::string pulsatrix::AlignmentQuery | ( | const std::vector< FastaRecord > & | alignment | ) |
The query's residues in alignment's first record: its letters, uppercased.
|
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.
| std::invalid_argument | if species_adjusted_fitness_sums is empty or population_size is not positive. |
| const std::vector< XaiQuestion > & pulsatrix::AllXaiQuestions | ( | ) |
All nine questions, in the enum's order.
| const std::vector< XaiReason > & pulsatrix::AllXaiReasons | ( | ) |
All four reasons, in the enum's order.
| 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.
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | if the outputs don't form whole blocks or an option is invalid. |
| 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.
| x | shape (n, ...): a row per input. Dimensions after the first are flattened. |
| center | Subtract 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. |
(|sum u|^2 - n) / (n (n - 1)). | std::invalid_argument | if x has rank below 2, fewer than 2 rows, a NaN or infinity, or a row of zeros (after centering, if centering). |
|
inline |
Appends child's named buffers to out, each renamed to prefix.name.
|
inline |
Appends child's named parameters to out, each renamed to prefix.name – the one step every container's named_parameters() repeats per child.
prefix.0, prefix.1, ...) so a container never hides them from an optimizer that used to see them. Attaches an IA³ vector to each LinearModule config selects, then freezes everything else, as PEFT's get_peft_model() does.
| std::invalid_argument | if 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. |
| 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().
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | for a layer the model doesn't have, or invalid sizes; std::logic_error if a chosen layer already has an intervention. |
| 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].
| std::invalid_argument | if a position is outside the sequence or its residue isn't the listed wild type. |
|
inline |
Pure core: decodes an explicit set of standard-normal sample vectors into offspring points, x_i = mean + sigma * sqrt(variances) (elementwise) * z_i.
| std::invalid_argument | if any z_sample's dimension doesn't match state.mean's. |
| void pulsatrix::AttachBootstrapBand | ( | PersistenceDiagramDocument & | doc, |
| int | dimension, | ||
| const BootstrapBandResult & | band | ||
| ) |
Adds BootstrapBand()'s band to the entry for dimension.
| std::invalid_argument | if the document has no such dimension. |
| 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.
| test | The test of that dimension's diagram, exactly as the document holds it. |
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | if the rank is below 3. |
| 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.
| 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. |
| const char * pulsatrix::AxisScaleName | ( | AxisScale | scale | ) |
|
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.
| batch_sizes | Each population member's own noise batch's leading-dimension size, in the same order GeneratePooledFakeSamples pooled them (not assumed uniform across members). |
| std::invalid_argument | if 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). |
| std::string pulsatrix::Base64Encode | ( | const std::vector< uint8_t > & | bytes | ) |
Standard base64 (RFC 4648, with padding), for image/png data.
| 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()).
| std::invalid_argument | if baselines is empty or a value is NaN. |
| double pulsatrix::BernoulliKl | ( | double | p, |
| double | q | ||
| ) |
KL divergence between Bernoulli(p) and Bernoulli(q), with p and q clipped to (0, 1).
| 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.
| std::invalid_argument | if a grid value is NaN. |
| 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.
| std::invalid_argument | if mutation_probability is outside [0, 1]. |
|
inline |
Flips each gene where flip_mask is true, leaves the rest unchanged.
| std::invalid_argument | if genotype and flip_mask sizes differ. |
| 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).
| std::invalid_argument | if parent sizes differ or alpha < 0. |
|
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.
| std::invalid_argument | if parent1/parent2/gamma sizes are not all equal. |
| 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.
| distances | The whole cloud's distances; resamples reuse them, so nothing is recomputed. |
| dimension | The homology dimension to test. |
| std::invalid_argument | if resamples < 1, alpha is outside (0, 1), or dimension is above options.rips.max_dimension. |
| Certified< double > pulsatrix::BottleneckDistance | ( | const PersistenceDiagram & | a, |
| const PersistenceDiagram & | b | ||
| ) |
The bottleneck distance between two diagrams of the same dimension.
| std::invalid_argument | if the diagrams' dimensions differ. |
| 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:
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.| input | The input to explain, with a leading batch dimension of 1. |
| explain | Runs 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. |
| predict | The model as a function, as in DeletionCurve(). |
| model | The 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. |
| std::invalid_argument | if request.method isn't in the catalog, doesn't answer request.question, or doesn't return an attribution (use ReportExplanation()). |
| 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.
| ids | The prompt's token ids (one sequence). |
| std::invalid_argument | for an empty or too long prompt, a target outside the vocabulary, or prompt_tokens of the wrong length. |
| 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).
| tokenized_corpus | One token sequence per document/line (e.g. Tokenizer::Tokenize's output for each line of a corpus). |
| max_vocab_size | If >= 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. |
| 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.
A byte offset range of text as a character (code point) range, widened to whole characters, which is how Hugging Face reports offsets.
| 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.
| probabilities | (n, K), each row the model's probabilities for one calibration example. |
| labels | The true class of each. |
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | as CalibrateConformalRegressor() does, for all three. |
| 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.
| std::invalid_argument | if the two are empty, have different lengths or hold a value that isn't finite, or alpha isn't in (0, 1). |
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.
| std::invalid_argument | if 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. |
|
inline |
Laplace(add-one)-smoothed empirical probability of category among observations.
| std::invalid_argument | if num_categories == 0. |
| 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.
| std::invalid_argument | if layer_relevance has rank below 2. |
| void pulsatrix::check_deterministic_allowed | ( | const char * | operation | ) |
Guard for a nondeterministic code path: call it before running one.
| operation | Names the operation in the error message. |
| std::logic_error | if deterministic mode is on. |
|
inline |
Throws std::invalid_argument unless value is finite and non-negative.
| 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.
| 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.
| 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.
| LatentClass pulsatrix::ClassifyLatent | ( | const CrosscoderLatentStats & | stats | ) |
Minder et al.'s bins on Δnorm.
| 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.
| 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.
| 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.
| module | Its parameters with requires_grad() set are counted and scaled; frozen ones are left alone (FND-2). |
| max_norm | Positive, finite limit. |
| error_if_nonfinite | Throw instead of returning when the norm is NaN or infinite. |
| std::invalid_argument | if max_norm isn't positive and finite. |
| std::runtime_error | if error_if_nonfinite is set and the norm is NaN or infinite. |
| 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.
| pad_id | The id written into padding; its value doesn't matter (see the file comment). |
| std::invalid_argument | if examples is empty or an example has an empty prompt or completion. |
|
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.
| 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.
| means | means[m][i]: member m's mean for input i. |
| variances | The same shape, or empty for members that predict only a mean (Monte Carlo dropout of a plain regressor); the aleatoric part is then 0. |
| std::invalid_argument | if there are fewer than 2 members, the members have different lengths or none, a value isn't finite, or a variance is negative. |
| 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.
(steps + 1) * (1 + random_orders) replays. | std::invalid_argument | if prompt_relevance doesn't have one value per position, the input has no prompt, steps < 1 or random_orders < 1. |
| 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.
| graph | ExplainCommitments' result for the same targets, in CommitmentMode::Graph. |
| std::invalid_argument | if graph isn't a Graph result for this trajectory, or as ReplayCommitmentValue. |
| 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).
| std::invalid_argument | if either side has no reports, a tolerance is negative, or the significance is outside (0, 1]. |
| 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.
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | if the sizes don't match L * vocab. |
| 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.
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | as the three measures do. |
| 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).
| std::invalid_argument | if the lengths differ, fewer than 3 residues compare, or top_fraction isn't in (0, 1]. |
| 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.
| threshold | The roadmap's criterion: correlation above 0.99. |
| std::invalid_argument | if the file holds no sequences or its tensors don't fit the model. |
| 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.
| std::invalid_argument | if baseline doesn't have the same rows as features, or for what TrainLinearProbe() rejects. |
| 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).
| threshold | The roadmap's criterion: fp32, every logit within 1e-3 of the reference, relative to the position's largest logit when that exceeds 1. |
| std::invalid_argument | if 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. |
| 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.
| max_examples | How many mismatches to keep in the report. |
| std::runtime_error | if the file can't be read; std::invalid_argument if a line is malformed. |
|
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).
| std::invalid_argument | if either genome has zero connection genes. |
| 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.
| std::invalid_argument | as CollatePromptCompletions(), or if batch_size < 1. |
| 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.
|
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.
| std::invalid_argument | if 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). |
| 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.
| num_bins | Requested number of bins, >= 1; ties in the feature can merge bins. |
| std::invalid_argument | for the same inputs ComputeIce rejects, num_bins < 1, or a feature that takes only one value. |
| 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.
| repeated_runs | Two or more Attribution results from independent calls to the same explainer on the same input (varying only, e.g., a stochastic method's seed). |
| std::invalid_argument | if 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. |
| ConservationResult pulsatrix::ComputeConservation | ( | const Tensor & | relevance_in, |
| const Tensor & | relevance_out | ||
| ) |
Sums relevance_in and relevance_out independently and reports their gap.
| relevance_in | A module's propagate_relevance() input-side relevance tensor. |
| relevance_out | The same call's output-side relevance tensor. |
| 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).
| next_q_online | The online network's Q-values for the next state, shape (N, action_dim) – used for action selection only. |
| next_q_target | The target network's Q-values for the next state, same shape – used for evaluation only. |
| rewards | Immediate rewards, shape (N, 1). |
| dones | Episode-termination flags as 0.0f/1.0f floats, shape (N, 1). |
| gamma | Discount factor, in [0, 1]. |
| backend | Backend to allocate the result through. Not owned; must outlive the result. |
| std::invalid_argument | on the same conditions as ComputeDQNTarget, plus if next_q_online and next_q_target have different shapes – external boundaries. |
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. 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. | 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].
| next_q_target | The 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. |
| rewards | Immediate rewards, shape (N, 1). |
| dones | Episode-termination flags as 0.0f/1.0f floats, shape (N, 1) – ReplayBatch's own encoding, so a sampled batch feeds straight in. |
| gamma | Discount factor, in [0, 1]. |
| backend | Backend 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. |
| std::invalid_argument | if 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. |
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. backend, which must address the inputs' device; the result is allocated through it too. | 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.
| rewards | Immediate rewards, shape (N, 1). |
| dones | Episode-termination flags as 0.0f/1.0f floats, shape (N, 1) – the same encoding ReplayBatch and ComputeDQNTarget use. |
| values | The critic's value estimate V(s_t) for each stored step, shape (N, 1). |
| bootstrap_value | V 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. |
| gamma | Discount factor, in [0, 1]. |
| lambda | GAE trace-decay parameter, in [0, 1]. |
| backend | Backend 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. |
| std::invalid_argument | if 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. |
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. 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(). backend. | H0Result pulsatrix::ComputeH0 | ( | const DistanceMatrix & | distances | ) |
H0 persistence of the Vietoris-Rips filtration on the given distances.
| std::invalid_argument | if distances has fewer than 2 points. |
| 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).
|
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).
| std::invalid_argument | if max_resource <= 0 or eta <= 1.0. |
| 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.
| predict | Forward pass for one instance: input in, output out. |
| instances | The instances to draw curves for, all the same shape. Their mean is the partial dependence over them. |
| feature_index | Flat index of the feature to vary. |
| target_index | Flat index of the output element to read. |
| grid | Values to set the feature to (see FeatureGrid). Non-empty. |
| std::invalid_argument | if instances or grid is empty, the instances differ in shape, or an index is out of range. |
| 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.
| scores | One per node, in node order; embedding and logit entries are ignored. |
| std::invalid_argument | if the sizes differ or a score isn't finite. |
| 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.
| features | Flat feature indices to vary; empty means all of them. |
| std::invalid_argument | if bounds don't have one entry per feature, a feature index or target index is out of range. |
| 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.
| 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.
| std::invalid_argument | for the same inputs ComputeIce rejects, or feature_x == feature_y. |
| 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.
| std::invalid_argument | if width or height is below 1, or the ranges are empty. |
| 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.
| std::invalid_argument | if layers < 1 or a grid value is NaN. |
| 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.
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | for an invalid problem or options, or a target out of range. |
|
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.
| std::invalid_argument | if metrics has fewer than 2 entries, or truncation_fraction is not in (0, 0.5]. |
| 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.
| 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.
| 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.
| candidates | A batch of inputs, the model's input shape with a leading batch dimension. |
| target | The class the relevance explains; unused for ReferenceMode::Activation. |
| std::invalid_argument | if k is below 1, the channel is outside the layer, or for what LayerRelevance() rejects. |
| 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.
| gradients | shape (n, ...): the gradient of the class logit with respect to the layer, a row per input. |
| std::invalid_argument | if the rows aren't the CAV's width. |
| 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.
condition (layer:c,c;...), relevance_in_sum}. | std::invalid_argument | if 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. |
| 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.
L x L features, the input to ESM's regression. | std::invalid_argument | if tokens is under 3. |
| 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.
i < j whose truth is known (not NaN) compete.(i, j), row by row.top such pairs, the missing ones count as wrong, as in ESM's compute_precisions. top is 0. | std::invalid_argument | if the maps' sizes differ, or top is negative. |
| 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.
| token_types | One id per row saying which token type (a word, an amino acid) the row is. |
| labels | The real task's labels, one per row in [0, classes). Only their distribution is used. |
| seed | The 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. |
| std::invalid_argument | if the sizes differ, there are no rows, classes < 2, or a label is outside [0, classes). |
| 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.
| 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):
| w,w_tilde | The two representations' distances, for the same n points in the same order, used as given (Rtd() normalizes them first). |
| dimension | The homology dimension; RTD uses 1. |
| std::invalid_argument | if the sizes differ, there are fewer than 2 points, or dimension is outside [1, 7]. |
| std::vector< CrosscoderLatentStats > pulsatrix::CrosscoderLatents | ( | Crosscoder & | crosscoder, |
| int64_t | a = 0, |
||
| int64_t | b = 1 |
||
| ) |
Every latent's stats for sources a and b.
| std::invalid_argument | for a source out of range or a == b. |
|
inline |
Crowding distance within a single front.
| front_objectives | Objective 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. |
| std::invalid_argument | if the objective vectors are not all the same size. |
|
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).
| std::invalid_argument | if genotype.size() != space.size(), or any gene is outside [0, 1]. |
| 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.
| samples | Two or more (N, K) probability tensors of the same shape, such as McDropoutSamples() or EnsembleSamples() returns. |
| std::invalid_argument | if 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. |
| 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).
| samples | Non-empty list of samples, each with the same field count. |
| backend | Backend to allocate stacked field tensors through. |
| std::invalid_argument | if 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. |
| 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.
| 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.
| std::invalid_argument | if relevance doesn't have one value per residue, steps < 1 or random_orders < 1. |
| 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.
| std::invalid_argument | if the attribution's shape differs from the input's, steps < 1, or target is outside the prediction. |
| SensitivityBounds pulsatrix::DeltaBounds | ( | const Tensor & | input, |
| float | delta | ||
| ) |
x - delta and x + delta for every feature.
| std::invalid_argument | if delta <= 0. |
| std::vector< Caveat > pulsatrix::DeriveCaveats | ( | const Explanation & | explanation | ) |
The caveats an explanation carries, from the report alone:
| 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).
| feature_names | A name per feature; x[3] where missing. |
| 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.
| 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.
| std::string pulsatrix::DescribeSliceError | ( | const SliceErrorReport & | report | ) |
The slices as a plain-text table, worst first, with the test and whether any is worse.
| 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%).
| feature_names | A name per feature; x[3] where missing. |
| bool pulsatrix::deterministic | ( | ) |
Whether deterministic mode is on.
| 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.
| std::invalid_argument | if the model has no enabled adapters, or one is merged (its update is in the weights and can't be switched off). |
| 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.
| std::invalid_argument | for empty sets or rows of different sizes. |
| 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.
| std::invalid_argument | if 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. |
| 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).
| signed_normalized_value | Position along the colormap, expected in [-1, 1]; values outside this range are clamped to the nearest end anchor. |
|
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).
| std::invalid_argument | if discriminator has no parameters. |
| 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.
| std::invalid_argument | if a mutant doesn't parse or doesn't match sequence. |
|
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.
| std::invalid_argument | if a.size() != b.size(). |
| 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.
| std::invalid_argument | for a layer outside [0, num_layers()], or a sequence longer than max_tokens - 2 or holding a character the tokenizer doesn't know. |
| 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.
| 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.
| std::invalid_argument | if logits is empty, a rank is below 2, or the shapes or devices differ. |
| 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.
| members | Each runs one network, in eval mode, and returns probabilities. Train them from different seeds on the same data; Lakshminarayanan et al. used 5. |
| std::invalid_argument | if there are fewer than 2 members. |
| 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).
| 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.
| 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.
| std::invalid_argument | if population_size is not a positive even number, or sigma is not positive. |
|
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)`.
| std::invalid_argument | if epsilons is empty, epsilons.size() != fitnesses.size(), any epsilon's dimension doesn't match theta's, or sigma is not positive. |
| 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.
| std::invalid_argument | if a variant doesn't match the assay's sequence. |
| ClassificationReport pulsatrix::EvaluateClassifier | ( | const Tensor & | probabilities, |
| const std::vector< int64_t > & | labels, | ||
| const ClassificationOptions & | options = {} |
||
| ) |
Scores a classifier's probabilities against the labels.
| 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. |
| labels | The true class of each input, in [0, K). |
| std::invalid_argument | if 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. |
| ContactEvaluation pulsatrix::EvaluateContacts | ( | const ContactMap & | predicted, |
| const ContactMap & | truth | ||
| ) |
| CoverageReport pulsatrix::EvaluateCoverage | ( | const std::vector< PredictionInterval > & | intervals, |
| const std::vector< double > & | targets | ||
| ) |
| std::invalid_argument | if there are no intervals or targets has another length. |
| CoverageReport pulsatrix::EvaluateCoverage | ( | const std::vector< std::vector< int64_t > > & | sets, |
| const std::vector< int64_t > & | labels | ||
| ) |
| std::invalid_argument | if there are no sets or labels has another length. |
| 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.
| 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.
|
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).
| std::invalid_argument | if inputs.size() doesn't match the genome's own number of Input nodes. |
| 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.
| thread_pool | If 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). |
| 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.
| std::invalid_argument | for mismatched shapes. |
| 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.
| dense_rate | A feature firing on more than this share of inputs counts as dense. |
| std::invalid_argument | for a batch that isn't (N, input_dim) with N > 0, or batch < 1. |
| RegressionReport pulsatrix::EvaluateRegressor | ( | const std::vector< double > & | predictions, |
| const std::vector< double > & | targets | ||
| ) |
Scores a regressor's predictions against the targets.
| std::invalid_argument | if the two are empty, have different lengths or hold a value that isn't finite. |
| 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.
|
inline |
Expected Improvement: the expected amount by which a candidate exceeds best_value + xi, under the posterior N(mean, variance).
| variance | Posterior variance (not standard deviation) – must be non-negative. |
| xi | Small 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). |
| std::invalid_argument | if variance < 0. |
| 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.
| std::invalid_argument | for 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. |
| 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)|².
| const ExplainerCapabilities & pulsatrix::ExplainerCapabilitiesOf | ( | std::string_view | name | ) |
The catalog entry named name.
| std::invalid_argument | if there is none. |
| const std::vector< ExplainerCapabilities > & pulsatrix::ExplainerCatalog | ( | ) |
Every explainer pulsatrix has, in a fixed order.
| JsonValue pulsatrix::ExplainerCatalogDocument | ( | ) |
The whole catalog: a pulsatrix.explainer_catalog.v1 document.
| 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.
| 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.
| std::invalid_argument | if the seed's size differs from the sample's, or a model output has the wrong size. |
| std::runtime_error | if 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). |
| 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().
| 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.
| input | One input, (1, ...). |
| explain | The explainer; its attribution's values are compared as one flat vector. |
| predict | The model; the index of its largest output is the predicted class. |
| classifier | The model again as a DifferentiableClassifier, for the adversarial point; nullptr to skip it. |
| backend | Backend to put the perturbed inputs on, on the input's device. |
| std::invalid_argument | if 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. |
| 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.
|
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.
| std::invalid_argument | if config is missing a value for any parameter in space, or factors is missing an entry for any non-categorical parameter in space. |
| 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.
| std::invalid_argument | if 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. |
| SoftTreeRules pulsatrix::ExtractRules | ( | const SoftDecisionTree & | tree, |
| const std::vector< std::string > & | class_names = {} |
||
| ) |
The rules of a soft decision tree.
| std::invalid_argument | if the class names' count is wrong or they aren't distinct. |
| 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.
| feature_names | Names for the features, or empty for x0, x1, ... |
| class_names | Names for the classes, or empty for class0, class1, ... |
| std::invalid_argument | for a regression tree, or names of the wrong count or that aren't distinct. |
| Landmarks pulsatrix::FarthestPointLandmarks | ( | const PointCloud & | cloud, |
| DeviceBackend * | backend, | ||
| const LandmarkOptions & | options | ||
| ) |
Landmarks of a cloud's points, computed on the given backend.
| Landmarks pulsatrix::FarthestPointLandmarks | ( | const Tensor & | points, |
| const LandmarkOptions & | options | ||
| ) |
Picks farthest-point landmarks among the rows of points.
| points | shape (n, ...): a row per point, dimensions after the first flattened; distances are computed on its backend. |
| std::invalid_argument | if 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. |
|
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.
| std::invalid_argument | – propagated from Dominates if objective vectors have inconsistent sizes. |
| 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.
| x | (N, input_dim). |
| labels | 0 or 1 per input. |
| std::invalid_argument | for 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. |
| 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).
| background | Instances to read the feature from; all the same shape. |
| feature_index | Flat index of the feature within an instance. |
| grid_size | Number of points, >= 2. |
| lower_percentile,upper_percentile | In [0, 1], lower < upper. Defaults are scikit-learn's. |
| std::invalid_argument | if 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). |
| std::vector< double > pulsatrix::FeatureImportance | ( | const SurrogateTree & | tree | ) |
Each feature's share of the tree's impurity decrease (scikit-learn's feature_importances_).
| 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).
| 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).
| input | (N, ...): N inputs, any shape after the first dimension. |
| labels | The true class of each input, or with targeted the class to push it to. |
| backend | Backend to put the perturbed inputs on, on the input's device. |
| std::invalid_argument | if 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. |
| 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.
| predict | The model as a function of one input (a leading batch dimension of 1); its class is the index of its largest output. |
| input | The input to explain; every element is a feature. |
| background | Inputs shaped like input, from the data the model sees: the bins, the samples and the coverage all come from them. |
| std::invalid_argument | if 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. |
| 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].
| ctx | The model, run through forward_pass and backward_pass. Parameter gradients accumulate in the model, as with Saliency. |
| input | One instance with its batch dimension, for example (1, F); every element is a feature. |
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | for the inputs FindCounterfactual rejects, or invalid options. |
| std::vector< VizFontFile > pulsatrix::FindFallbackFonts | ( | ) |
The system fonts that together cover as many scripts as this machine has fonts for, best first.
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.
| 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.
| ctx | The 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. |
| input | One input with its batch dimension. |
| std::invalid_argument | if baseline or upper has the wrong length, or an option is out of range. |
| 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.
| std::invalid_argument | as FindPertinentNegative(). |
| 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.
| std::invalid_argument | if 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. |
|
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.
| samples | Each row is one sample's feature vector; every row must be the same length. |
| targets | One target value per sample. Must match samples.size(). |
| weights | One non-negative weight per sample. Must match samples.size(). |
| l2_lambda | Ridge regularization strength. 0 = ordinary weighted least squares. |
| std::runtime_error | if the normal-equations system is near-singular (e.g. degenerate/collinear samples). |
| std::invalid_argument | if 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. |
| 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).
| weights | Per example, such as importance weights; all 1 when empty. |
| std::invalid_argument | if 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. |
| 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.
| num_classes | Classification: the number of classes; every y must be in [0, num_classes). |
| std::invalid_argument | if 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. |
Fits the components directions of most variance.
| x | shape (n, ...): a row per input. Dimensions after the first are flattened. |
| center | Subtract the mean row first, as PCA does. Without it the first component tends to point at the mean, and the "variances" are mean squares. |
| std::invalid_argument | if 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. |
| 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.
| predict | The model as a function of one instance (a leading batch dimension of 1). |
| instances | The inputs to imitate the model on, each flattened to one row of features. |
| std::invalid_argument | if 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. |
| 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.
| logits | One row per example, every row the same length K >= 2. |
| std::invalid_argument | as FitBinaryTemperature(), or if a row has another length or a label is outside [0, K). |
|
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.
|
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).
| std::invalid_argument | if theta.size() != kFixedTopologyXORNumParams. |
|
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.
| 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".
| std::string pulsatrix::FormatRule | ( | const datalog::Rule & | rule | ) |
A rule in Datalog's usual text: head(A, b) :- body1(A), body2(A, c).
| 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.
| std::invalid_argument | for an empty graph or a non-finite effect or weight. |
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.
| points | shape (n, ...): a row per point, n >= 2. |
| std::invalid_argument | if points has rank below 2, fewer than 2 rows, a NaN or infinity, or count < 1. |
|
inline |
Fixed-bandwidth Gaussian KDE: density(x) = mean over every observation o of N(x; o, bandwidth^2).
| std::invalid_argument | if observations is empty or bandwidth <= 0. |
| 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.
| std::invalid_argument | if sigma is negative or mutation_probability is outside [0, 1]. |
|
inline |
Adds noise[i] to genotype[i] wherever apply_mask[i] is true, leaves the rest unchanged.
| std::invalid_argument | if genotype/noise/apply_mask sizes are not all equal. |
| 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.
| std::invalid_argument | if 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. |
|
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.
| std::invalid_argument | if noise_per_generator.size() != population.size() (delegates to each generator's own forward() and to Tensor::Stack for their own preconditions). |
| 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).
| std::invalid_argument | if offspring.size() != mu. |
| uint64_t pulsatrix::global_seed | ( | ) |
The seed most recently passed to set_seed() (0 by default).
|
inline |
Enumerates the full cartesian-product grid over space.
| points_per_continuous_dimension | Number 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. |
| std::invalid_argument | if points_per_continuous_dimension < 2 (fewer than 2 points cannot include both bounds). |
| 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.
| predict | One instance in, outputs out. Works for models that aren't differentiable (trees, rules, thresholds) or aren't pulsatrix modules at all. |
rounds counts the balls and shells drawn; final_lambda is 0. | std::invalid_argument | for the inputs FindCounterfactual rejects, or invalid options. |
| 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.
| 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.
| 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.
| std::invalid_argument | if removed doesn't have one flag per element, or NoisyLinear is used on an input of rank below 2. |
| 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.
| 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.
| 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.
| 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.
| std::invalid_argument | as DeletionCurve(). |
| 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.
| base,tuned | Weights 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. |
| k | The paper's figures use 10. |
| epsilon | The 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. |
| std::invalid_argument | if the shapes differ or aren't rank 2, k < 1, or epsilon isn't in (0, 1]. |
| 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.
| std::invalid_argument | if they share none. |
| 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.
| 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.
| double pulsatrix::KlLowerBound | ( | double | p, |
| double | level | ||
| ) |
The smallest q <= p with BernoulliKl(p, q) <= level.
| double pulsatrix::KlUpperBound | ( | double | p, |
| double | level | ||
| ) |
The largest q >= p with BernoulliKl(p, q) <= level.
The landmark rows of points, as a (k, ...) tensor on points' backend.
| Tensor pulsatrix::LayerActivations | ( | ExplainerContext & | ctx, |
| const Tensor & | inputs, | ||
| NodeId | layer | ||
| ) |
The layer's activations for inputs, from one forward pass: shape (n, width).
| 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).
| 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, ...).
| std::invalid_argument | if layer isn't between 1 and the number of modules, or for what LRP::explain() rejects. |
| double pulsatrix::LinearCka | ( | const Tensor & | x, |
| const Tensor & | y, | ||
| CkaEstimator | estimator = CkaEstimator::Debiased |
||
| ) |
Linear CKA between two representations of the same inputs.
| x | one representation, shape (n, ...): a row per input. Dimensions after the first are flattened, so a (n, channels, height, width) activation is n vectors. |
| y | another representation of the same n inputs, in the same order, of any width. |
| std::invalid_argument | if 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). |
| 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.
max_gram_bytes, each pair is computed on its own instead. | std::invalid_argument | as LinearCka() does, for any representation, or if a list is empty. |
| 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.
| 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.
| std::invalid_argument | for a config CausalLM refuses or weights that don't match it; std::runtime_error if files can't be read. |
| 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.
| std::runtime_error | if there is no optimizer file. |
| std::invalid_argument | if it belongs to a different save of the model, or doesn't match the model. |
| 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.
model unchanged. Each tensor keeps its device and requires_grad flag. | std::invalid_argument | if 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_error | if the file can't be read. |
| 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), 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), 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.| std::invalid_argument | for an unsupported config or a weight that doesn't fit; std::runtime_error for a missing file. |
| 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).
| std::invalid_argument | if the checkpoint has no contact head, or its size isn't layers * heads of config. |
| TextTokenizer pulsatrix::LoadEsmTokenizer | ( | const std::string & | vocab_path | ) |
MakeEsmTokenizer on a vocab.txt.
| std::runtime_error | if it can't be read. |
| 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.
| std::invalid_argument | for 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. |
| 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.
| mapping | As for SaveLoraAdapter(). |
| std::invalid_argument | for 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. |
| 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.
| std::invalid_argument | for 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. |
| TextTokenizer pulsatrix::LoadTokenizerJson | ( | const std::string & | path | ) |
ParseTokenizerJson on a file.
| std::runtime_error | if it can't be read. |
| 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.
| std::invalid_argument | for a tensor the model doesn't have, a shape that doesn't fit, or a missing parameter other than a convolution bias. |
| 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:
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.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). | num_layers | The model's layers; files are read for 0 .. num_layers − 1. |
| std::invalid_argument | for a missing file or tensor, or shapes that don't agree. |
| 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.
| 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.
| std::invalid_argument | if 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. |
|
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).
| good_configs,bad_configs | Observed configurations split by objective quantile (RunTPELoop's own job); every config must contain every parameter named in space. |
| std::invalid_argument | if good_configs or bad_configs is empty. |
| 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.
| band_edges | Increasing edges strictly inside (0, 1): edges {1e-3} give the bands [0, 1e-3) and [1e-3, 1]. Empty gives one band. |
| clip | Both 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. |
| std::invalid_argument | if 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). |
| 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.
| std::invalid_argument | if the model has no unmerged LoRA adapters. |
| 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.
| 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.
| std::logic_error | if no layer was split. |
|
inline |
Lower-case rule name ("epsilon", "gamma", "alpha_beta", "zbox") for messages/metadata.
| 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).
| 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.
| 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.
| embedding | Maps (1, L) ids to (1, L, d_model). |
| blocks | Run with forward_cached, in order; each gets its own cache of max_length positions. |
| head | Applied to the last position's hidden state (1, d_model): for example a final RMSNormModule and a TiedLMHeadModule; must end in (1, vocab). |
| after_block | Optional; 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. |
| 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. |
| 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.
| std::invalid_argument | as CharModel does. |
| 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.
| std::invalid_argument | if a map isn't L x L for the sequence's L residues. |
| 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.
| std::invalid_argument | if the model is causal: each position would see only the masks before it. |
| 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.
| 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.
MKT<mask>Y gives M, K, T, <mask>, Y.<unk>: lowercase mkta is a single <unk>, as in EsmTokenizer.<cls> before and <eos> after. decode() joins tokens with spaces.| std::invalid_argument | if the vocabulary lacks <cls>, <eos> or <unk>, or a token repeats. |
| 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).
| std::invalid_argument | if scan isn't 20 values per residue of sequence. |
| 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.
| layers | Run in order; not owned, must outlive the function. |
| backend | Where the ids tensor is built. |
| std::invalid_argument | (when called) if the output isn't rank 3 with one row per token. |
| 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.
| std::invalid_argument | as PointCloud::add does, or if snapshots is empty. |
| 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.
| std::invalid_argument | if scores isn't (n, pca.num_components()) with at least two components, or labels, groups or values is neither empty nor one per row. |
| 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.
| coordinates | (n, axes), at least two axes. |
| method | What made them, for example "umap" or "tsne"; IsNeighborEmbedding() reads it. |
| std::invalid_argument | if coordinates isn't (n, 2 or more), method is empty, or as ToJson() does. |
| 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).
| std::invalid_argument | if log_probs doesn't have one row per residue of sequence, or the tokenizer lacks an amino acid. |
| 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'.
backend's device: training it leaves the teacher alone. The teacher's interventions aren't copied. | std::invalid_argument | if 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). |
| 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.
| 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.
| std::invalid_argument | if the scores don't match the tokens or an offset lies outside text. |
| 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.
| 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.
| std::invalid_argument | if a word's span lies outside text or the words are out of order. |
| std::string pulsatrix::MarkdownToHtml | ( | const std::string & | markdown | ) |
Markdown (the subset Report::to_html() supports) as HTML; raw HTML is escaped.
| 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.
| 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.
| std::invalid_argument | if labels doesn't have one value per residue. |
| 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.
| double pulsatrix::MaxPersistence | ( | const PersistenceDiagram & | diagram | ) |
The largest finite persistence in a diagram, 0 if it has none: a common statistic for BaselinePValue().
| 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.
| model | The network predict runs. |
| predict | Runs the network on its argument and returns probabilities, such as a softmax of the logits. |
| std::invalid_argument | if samples < 2 or the model has no dropout layer with p > 0, whose samples would all be the same. |
| 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).
| 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).
| std::invalid_argument | for a size that isn't a whole number of rows, or no rows. |
| 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.
| 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.
| BlockGeometry pulsatrix::MeasureBlockGeometry | ( | Featurizer & | featurizer, |
| const Tensor & | x, | ||
| int64_t | batch = 4096 |
||
| ) |
| std::invalid_argument | for a batch that isn't (N, input_dim). Works for any featurizer: a single-direction featurizer's blocks have rank 1. |
| DescriptionLength pulsatrix::MeasureDescriptionLength | ( | Featurizer & | featurizer, |
| const Tensor & | x, | ||
| double | distortion_fraction = 0.1, |
||
| int64_t | batch = 4096 |
||
| ) |
| std::invalid_argument | for a batch that isn't (N, input_dim) with N >= 2, or a distortion_fraction outside (0, 1). |
| EffectiveRank pulsatrix::MeasureEffectiveRank | ( | const Tensor & | x, |
| bool | center = true |
||
| ) |
How many directions the rows spread along, from the singular values of x.
| center | Subtract 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. |
| std::invalid_argument | if x has rank below 2, fewer than 2 rows, a NaN or infinity, or is all zeros (after centering, if centering). |
Measures hubness in neighbors, which name points 0 to num_points - 1.
| std::invalid_argument | if num_points < 1 or an index is outside it. |
| std::vector< ImportanceStats > pulsatrix::MeasureImportance | ( | ParameterDecomposition & | d, |
| const Tensor & | x | ||
| ) |
| 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.
| std::invalid_argument | for a latent or source out of range, or a == b. |
| 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.
| loss | Runs 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. |
| 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.
| 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.
| std::invalid_argument | for what TrainLinearProbe() and ControlTaskLabels() reject. |
| 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.
| behavior | Returns 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_inputs | How many inputs behavior knows. |
| std::invalid_argument | for no inputs, fewer than two distinct coefficients, an empty or all-zero direction, or random_directions < 0. |
| 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.
| std::invalid_argument | if background is empty or its shapes differ. |
| double pulsatrix::MedianSplitMcc | ( | const std::vector< int > & | labels, |
| const std::vector< double > & | scores | ||
| ) |
ProteinGym's MCC: scores at or above their median predict 1.
| void pulsatrix::MergeIA3 | ( | Module & | model | ) |
Folds every vector into its layer's weights (and an output-scaling layer's bias).
| void pulsatrix::MergeLora | ( | Module & | model | ) |
Merges every adapter into its base weight (LinearModule::merge_lora()).
| MimeBundle pulsatrix::mime_bundle_repr | ( | const Attribution & | attribution | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const AttributionDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const CircuitGraph & | graph | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const CircuitGraphDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const ClassificationReport & | report | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const ContactMapDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const CounterfactualDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const HeatmapDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const MorrisDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const MutationMapDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const PartialDependenceDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const PersistenceDiagramDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const ProjectionDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const ResidueTracksDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const SensitivityDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const SequenceLogoDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const SeriesDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const SliceErrorReport & | report | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const SobolDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const Tensor & | tensor | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const TokenRelevanceDocument & | doc | ) |
| MimeBundle pulsatrix::mime_bundle_repr | ( | const TrainingLogDocument & | doc | ) |
| MlpHook pulsatrix::MlpAblationHook | ( | std::vector< bool > | rows = {} | ) |
Zero-ablates an MLP: its output rows set to 0.
| 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.
| rows | As SpliceHook's: which of the N * L rows to replace, all when empty. |
| 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.
seed. Layers are the first segment of named_parameters() names (a SequentialModule's indices, for example). explain throws. | 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.
| std::invalid_argument | if a layer names no parameter. |
| 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.
| std::invalid_argument | for an invalid problem or options. |
| 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.
| std::invalid_argument | if offspring.size() < mu. |
| 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.
| std::invalid_argument | if population.size() + offspring.size() < mu. |
| 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.
| a,b | the same n inputs in the same order, of any widths. |
mutual_knn. | std::invalid_argument | as NearestNeighbors() does, or if the row counts differ. |
| 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.
center, both sets are centered on the mean of the two together. | std::invalid_argument | as NearestNeighbors() does, or if the widths differ. |
|
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.
| 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.
| Neighbors pulsatrix::NearestNeighbors | ( | const Tensor & | points, |
| const NeighborOptions & | options = {} |
||
| ) |
Each point's k nearest other points (a point is never its own neighbor).
| points | shape (n, ...): a row per point. Dimensions after the first are flattened. |
| std::invalid_argument | if points has rank below 2 or a NaN or infinity, or k is not between 1 and n - 1. |
| 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.
| std::invalid_argument | as the one-set version does, if the widths differ, or if k is not between 1 and the number of points. |
| 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.
| 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.
| 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).
| value | The raw value to normalize. Values outside [-max_abs, max_abs] are clamped. |
| max_abs | The absolute value that should map to +/-1.0. If 0, returns 0.0 rather than dividing by zero. |
| 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.
| value | The raw value to normalize. Values outside [0, max_abs] are clamped. |
| max_abs | The value that should map to 1.0. If 0 (a degenerate all-zero series), returns 0.0 rather than dividing by zero. |
| 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).
| std::invalid_argument | if population.size() + offspring.size() < mu. |
| 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).
| analysis | Anything 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. |
| 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.
| 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.
| window | One 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). |
| strides | One 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. |
| std::invalid_argument | if window or strides have the wrong length or invalid sizes, or the target index is out of range. |
| 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.
| std::invalid_argument | if parent sizes differ or parent size < 2 (no interior point exists to draw). |
| 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.
| std::invalid_argument | if parent sizes differ or point > parent1.size(). |
| 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.
| 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.
| OpType pulsatrix::OpTypeFromName | ( | std::string_view | name | ) |
| std::invalid_argument | if name isn't an OpType name. |
| const char * pulsatrix::OpTypeName | ( | OpType | op_type | ) |
The name ToCircuitGraphDocument writes for op_type, for example "Linear".
| void pulsatrix::OrthonormalizeLoReFT | ( | CausalLM & | model | ) |
orthonormalize() on every LoReFT intervention of the model: call it after each optimizer step.
| 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.
| pad_index | Value 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. |
| std::invalid_argument | (from the returned CollateFn, at call time) if samples is empty – matching DefaultCollate's own external-boundary convention. |
| 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.
| std::invalid_argument | as above. |
| DistanceMatrix pulsatrix::PairwiseDistances | ( | const Tensor & | points, |
| const DistanceOptions & | options = {} |
||
| ) |
Euclidean distances between every pair of rows.
| points | shape (n, ...): a row per point, dimensions after the first flattened. With DistanceMethod::Gemm the products run on points' own backend. |
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | for a line that isn't such an object, or a feature outside its sequence. |
| AttributionDocument pulsatrix::ParseAttributionDocument | ( | std::string_view | json | ) |
| 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.
| CircuitGraphDocument pulsatrix::ParseCircuitGraphDocument | ( | std::string_view | json | ) |
| ClassificationReport pulsatrix::ParseClassificationReport | ( | std::string_view | json | ) |
Reads a pulsatrix.classification_report.v1 document, as ToJson(ClassificationReport) writes it.
| std::invalid_argument | if 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. |
| ContactMapDocument pulsatrix::ParseContactMapDocument | ( | std::string_view | json | ) |
| CounterfactualDocument pulsatrix::ParseCounterfactualDocument | ( | std::string_view | json | ) |
| EncoderLMConfig pulsatrix::ParseEsmConfig | ( | std::string_view | json | ) |
Reads an ESM config.json.
| std::invalid_argument | for 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. |
| 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.
| std::invalid_argument | for sequence text before the first header, or an empty header. |
| FeatureDashboardDocument pulsatrix::ParseFeatureDashboardDocument | ( | std::string_view | json | ) |
| HeatmapDocument pulsatrix::ParseHeatmapDocument | ( | std::string_view | json | ) |
| HfModelConfig pulsatrix::ParseHfConfig | ( | std::string_view | json | ) |
Parses config.json text. A multimodal config's text_config is read for the language model.
| std::invalid_argument | if 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. |
| JsonValue pulsatrix::ParseJson | ( | std::string_view | text | ) |
Parses one JSON document.
| std::invalid_argument | naming the byte offset of the first error. |
| 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.
| std::invalid_argument | for 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. |
| 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.
| std::invalid_argument | for malformed CIF, an _atom_site loop missing a needed column, or no protein residues. |
| MorrisDocument pulsatrix::ParseMorrisDocument | ( | std::string_view | json | ) |
| MutationMapDocument pulsatrix::ParseMutationMapDocument | ( | std::string_view | json | ) |
| std::vector< Mutation > pulsatrix::ParseMutations | ( | std::string_view | text | ) |
Parses a variant, A23G, or several joined by :, A23G:L45P (ProteinGym's format).
| std::invalid_argument | for anything else. |
| AttributionGraph pulsatrix::ParseNeuronpediaGraph | ( | std::string_view | json | ) |
Reads a graph written by ToNeuronpediaJson, circuit-tracer or Neuronpedia. Unknown fields are ignored.
| std::invalid_argument | for a missing required field. |
| 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.
| std::invalid_argument | for 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. |
| PartialDependenceDocument pulsatrix::ParsePartialDependenceDocument | ( | std::string_view | json | ) |
| ProteinStructure pulsatrix::ParsePdb | ( | std::string_view | text | ) |
Reads PDB-format text: the ATOM records, and the HETATM records of selenomethionine, of the first model.
HETATM records) are left out.| std::invalid_argument | for a malformed coordinate, or no protein residues. |
| PersistenceDiagramDocument pulsatrix::ParsePersistenceDiagramDocument | ( | std::string_view | json | ) |
Reads a document ToJson() wrote.
| std::invalid_argument | naming the JSON Pointer of the first problem. |
| ProjectionDocument pulsatrix::ParseProjectionDocument | ( | std::string_view | json | ) |
| ResidueTracksDocument pulsatrix::ParseResidueTracksDocument | ( | std::string_view | json | ) |
| SensitivityDocument pulsatrix::ParseSensitivityDocument | ( | std::string_view | json | ) |
| SequenceLogoDocument pulsatrix::ParseSequenceLogoDocument | ( | std::string_view | json | ) |
| SeriesDocument pulsatrix::ParseSeriesDocument | ( | std::string_view | json | ) |
| std::invalid_argument | naming the JSON Pointer of the first problem, including every rule ToJson() checks. |
| SliceErrorReport pulsatrix::ParseSliceErrorReport | ( | std::string_view | json | ) |
Reads a pulsatrix.slice_error.v1 document, as ToJson(SliceErrorReport) writes it.
| std::invalid_argument | if 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). |
| SobolDocument pulsatrix::ParseSobolDocument | ( | std::string_view | json | ) |
| TextTokenizer pulsatrix::ParseTokenizerJson | ( | std::string_view | json | ) |
Builds the tokenizer a tokenizer.json describes.
Supported components (anything else is refused by name, never approximated):
NFC, Replace, Prepend, SequenceSplit (regex or string pattern, every behavior, invert), Digits, ByteLevel, Metaspace, SequenceBPE (merges as "a b" strings or ["a", "b"] pairs, ignore_merges, subword prefix and suffix, unk_token, byte_fallback, fuse_unk; not dropout), WordLevelByteLevel, TemplateProcessing (single sequences), SequenceByteLevel, ByteFallback, Fuse, Replace, Strip, Metaspace, Sequencelstrip, rstrip or single_word, and with normalized only when there is no normalizer| std::invalid_argument | for malformed JSON or an unsupported component or option. |
| TokenRelevanceDocument pulsatrix::ParseTokenRelevanceDocument | ( | std::string_view | json | ) |
| TrainingLogDocument pulsatrix::ParseTrainingLogDocument | ( | std::string_view | json | ) |
| std::optional< XaiQuestion > pulsatrix::ParseXaiQuestion | ( | std::string_view | text | ) |
| std::optional< XaiReason > pulsatrix::ParseXaiReason | ( | std::string_view | text | ) |
| 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.
| std::invalid_argument | if index is out of range. |
Each row's coordinates on the components: (x - mean) components^T, shape (n, components), on x's backend.
| whiten | Divide each coordinate by its component's standard deviation, so every axis has variance 1 on the fitted data. |
| std::invalid_argument | if x's rows aren't pca.width wide, or have a NaN or infinity. |
The rows that coordinates map back to: mean + scores components, shape (n, width). Projecting and reconstructing keeps only what the components hold.
| std::invalid_argument | if scores isn't (n, pca.num_components()), or has a NaN or infinity. |
| 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.
| std::invalid_argument | if x has fewer than 4 rows, or as FitPca() does for each half. |
| 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.
| double pulsatrix::Percentile | ( | std::vector< double > | values, |
| double | q | ||
| ) |
The q-th percentile (0 to 100) with linear interpolation (numpy's default).
| 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.
| std::invalid_argument | if the rank is below 2. |
| 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.
| 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.
| errors | Each input's error: 0 or 1 for right or wrong, or a loss. |
| slices | The slice each input belongs to, such as a group or a data source. |
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | as EvaluateClassifier() and PerSliceError() do. |
| 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.
| std::invalid_argument | as Fgsm() does, or if steps < 1 or step_size is negative or not finite. |
| 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.
| scale | Per-feature scale, as in CounterfactualConstraints; empty means 1. |
| std::invalid_argument | if background is empty or its shapes differ from the counterfactual's, k < 1, or scale has the wrong length or a non-positive entry. |
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.
| source | Network to blend parameter values from – typically the online network. |
| destination | Network to blend into – typically the target network. |
| tau | Blending 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. |
| std::invalid_argument | if 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_argument | if 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. |
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. 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. | 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.
| std::invalid_argument | if 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. |
|
inline |
Polynomial-mutates a single bounded gene given an explicit draw.
| x | Current gene value, must be in [lower, upper]. |
| lower | Lower bound (must be strictly less than upper). |
| upper | Upper bound. |
| eta | Distribution index (non-negative; larger values concentrate mutations closer to x). |
| u | Draw in [0, 1]. |
| std::invalid_argument | if lower >= upper, x is outside [lower, upper], eta is negative, or u is outside [0, 1]. |
| 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).
| a | Square symmetric (n, n) CPU tensor, all finite. |
| max_iterations | Iteration budget; must be >= 1. |
| tolerance | Converged when successive unit vectors differ (up to sign) by at most this. |
| seed | Seeds the deterministic LCG that draws the starting vector. |
converged = false rather than an arbitrary answer. | std::invalid_argument | for the same inputs SymmetricEigen() rejects, a max_iterations below 1, or a tolerance that is not positive. |
| ContactPrecisions pulsatrix::PrecisionAtL | ( | const ContactMap & | predicted, |
| const ContactMap & | truth, | ||
| SeparationRange | range | ||
| ) |
| 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).
| std::invalid_argument | if the regressor isn't CQR's, the two have different lengths, or a value isn't finite. |
| std::vector< PredictionInterval > pulsatrix::PredictionIntervals | ( | const ConformalRegressor & | regressor, |
| const std::vector< double > & | predictions | ||
| ) |
The intervals for a point regressor's predictions (absolute_residual).
| std::invalid_argument | if the regressor is CQR's, or a prediction isn't finite. |
| 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.
| probabilities | (N, K), with the K of the calibration. |
| std::invalid_argument | as CalibrateConformalClassifier() does for probabilities. |
|
inline |
Probability of Improvement: P(candidate's value > best_value + xi) under the posterior N(mean, variance).
| std::invalid_argument | if variance < 0. |
| 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.
| tokens | The sequence so far (for the repetition penalty). |
| num_new_tokens | How many tokens have been generated so far (for min_new_tokens). |
| std::invalid_argument | for an invalid config. |
| 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.
| std::invalid_argument | if there are no columns, or they hold different numbers of values. |
| 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.
| std::invalid_argument | if x has rank below 2 or a NaN or infinite value, which the projector can't read. |
| 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.
| std::invalid_argument | if either set is empty, the sizes differ, count < 1 or sigma < 0. |
| 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.
| std::invalid_argument | unless 0 < edge_threshold <= 1. |
Thin QR factorization by Householder reflections.
| a | (m, n) CPU tensor with m >= n, all finite. Rank-deficient input is fine. |
| std::invalid_argument | if a is not rank 2, is wide (m < n), is not on the CPU, or has a non-finite entry. |
|
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).
| std::string_view pulsatrix::QuestionText | ( | XaiQuestion | question | ) |
The question as Liao et al. phrase it, for example "Why is this instance given this prediction?".
| 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.
| 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.
| 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.
| std::invalid_argument | if background is empty, its shapes differ, or the percentiles aren't 0 <= lower < upper <= 1. |
| 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.
| std::invalid_argument | for no proteins, or a contact map that doesn't fit its sequence. |
| 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.
| std::invalid_argument | – see RankSelectByDraw. |
| 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.
| population | Non-empty population. |
| draw | A value in [0, total_weight), where total_weight = n*(n+1)/2 for n individuals. |
| std::invalid_argument | if population is empty or draw is outside [0, total_weight). |
| std::vector< AnnotatedProtein > pulsatrix::ReadAnnotatedProteins | ( | const std::string & | path | ) |
ParseAnnotatedProteins on a file.
| std::runtime_error | if it can't be read. |
| DmsVariants pulsatrix::ReadDmsVariants | ( | const std::string & | path | ) |
Reads an assay's CSV.
| std::runtime_error | / std::invalid_argument as above. |
| EncoderLMConfig pulsatrix::ReadEsmConfig | ( | const std::string & | path | ) |
ParseEsmConfig on a file.
| std::runtime_error | if it can't be read. |
| std::vector< FastaRecord > pulsatrix::ReadFasta | ( | const std::string & | path | ) |
ParseFasta on a file.
| std::runtime_error | if it can't be read. |
| HfModelConfig pulsatrix::ReadHfConfig | ( | const std::string & | path | ) |
ParseHfConfig on a file.
| std::runtime_error | if it can't be read. |
| std::vector< JsonValue > pulsatrix::ReadJsonl | ( | const std::string & | path | ) |
Reads a JSONL file: one JSON value a line. Blank lines are skipped.
| std::runtime_error | if the file can't be read, naming the line that doesn't parse. |
| Tensor pulsatrix::ReadNpy | ( | const std::string & | path, |
| DeviceBackend * | backend | ||
| ) |
ParseNpy() of the file at path.
| std::runtime_error | if the file can't be read; otherwise as ParseNpy(). |
| std::vector< ProteinGymAssay > pulsatrix::ReadProteinGymReference | ( | const std::string & | path | ) |
Every assay in a reference file.
| std::runtime_error | if it can't be read; std::invalid_argument if a needed column is missing. |
| ProteinStructure pulsatrix::ReadStructure | ( | const std::string & | path | ) |
Reads a structure file: mmCIF for .cif or .mmcif, PDB format otherwise (.pdb, .ent).
| std::runtime_error | if it can't be read; what ParsePdb or ParseMmcif throws. |
| std::string_view pulsatrix::ReasonText | ( | XaiReason | reason | ) |
One sentence on the reason.
| 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.
| std::invalid_argument | if the sizes differ. |
| 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.
| std::invalid_argument | for an index outside the sample. |
| 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.
| prefix | Only parameters named prefix or under it (dot boundaries); empty means all. |
|
inline |
Frees t's buffer: it becomes an empty tensor on the same backend and device.
| 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.
progress, if set, is called after each. | void pulsatrix::RemoveIA3 | ( | Module & | model | ) |
Removes every vector; merged ones stay in the weights.
| 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()).
| std::string pulsatrix::RenderBarChartHtml | ( | const AttributionDocument & | doc, |
| int | top_k = 10, |
||
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | for the same inputs ToFeatureImportanceBars rejects, a non-finite value, or options with width < 200 or font_size < 1. |
| 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.
| std::invalid_argument | as RenderPersistenceDiagramSvg() does, or if max_bars < 1. |
| std::string pulsatrix::RenderBeeswarmHtml | ( | const std::vector< AttributionDocument > & | docs, |
| const std::vector< int64_t > & | feature_indices, | ||
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| docs | Attributions of the same shape for different inputs. |
| std::invalid_argument | if 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. |
| 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()).
| std::invalid_argument | as RenderPersistenceDiagramSvg() does, or if grid_points < 2. |
| std::string pulsatrix::RenderContactMapHtml | ( | const ContactMapDocument & | doc, |
| const ContactMapViewOptions & | view = {}, |
||
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | for a document ToJson rejects, min_separation < 1, or unusable options. |
| std::string pulsatrix::RenderCounterfactualHtml | ( | const CounterfactualDocument & | doc, |
| int | max_rows = 12, |
||
| const HtmlOptions & | options = {} |
||
| ) |
| std::string pulsatrix::RenderCounterfactualSetHtml | ( | const std::vector< CounterfactualDocument > & | docs, |
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | if docs is empty, the documents describe different inputs (feature names or original values differ), a value is non-finite, or the options are unusable. |
| 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.
| max_rows | At most this many changed features are listed; a line says how many more. |
| std::invalid_argument | for a non-finite value, max_rows < 1, or unusable options. |
| 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).
| 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.
| std::invalid_argument | for no such example, tokens that aren't residues, or what StructurePanelHtml throws. |
| std::string pulsatrix::RenderHeatmapHtml | ( | const HeatmapDocument & | doc, |
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | if the document is inconsistent (see ToJson) or empty, or for invalid options. |
| std::string pulsatrix::RenderMorrisHtml | ( | const MorrisDocument & | doc, |
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | for an empty document, a non-finite or negative mu*, sigma or confidence half-width, or unusable options. |
| std::string pulsatrix::RenderMutationMapHtml | ( | const MutationMapDocument & | doc, |
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
K11R: -2.31; larger maps are drawn as images, without tooltips. | std::invalid_argument | for a document ToJson rejects, or unusable options. |
| std::string pulsatrix::RenderPartialDependenceHtml | ( | const PartialDependenceDocument & | doc, |
| const PartialDependenceSvgOptions & | pd = {}, |
||
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | for 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. |
| 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.
| std::invalid_argument | for a document ToJson() rejects, a dimension it doesn't hold, or unusable options. |
| std::string pulsatrix::RenderProjectionHtml | ( | const ProjectionDocument & | doc, |
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| x_axis,y_axis | Which of the document's axes to plot: PC1 against PC2 by default. For a third dimension, draw the other pairs too. |
| std::invalid_argument | for a document ToJson() rejects, one with no points, or axes that aren't two different axes of the document. |
| std::string pulsatrix::RenderReliabilityDiagramSvg | ( | const ClassificationReport & | report, |
| const SvgOptions & | options = {} |
||
| ) |
The diagram of one classifier.
| 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.
| std::invalid_argument | if there are no series, more than 10, a report has no reliability bins, or the options are unusable. |
| std::string pulsatrix::RenderResidueTracksHtml | ( | const ResidueTracksDocument & | doc, |
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | for a document ToJson rejects, or unusable options. |
| std::string pulsatrix::RenderSequenceLogoHtml | ( | const SequenceLogoDocument & | doc, |
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | for a document ToJson rejects, or unusable options. |
| std::string pulsatrix::RenderSeriesHtml | ( | const SeriesDocument & | doc, |
| const SeriesViewOptions & | view = {}, |
||
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | for 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. |
| 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.
| std::invalid_argument | if the report has no slices, max_slices < 1, the reference is infinite or negative, or the options are unusable. |
| std::string pulsatrix::RenderSobolHtml | ( | const SobolDocument & | doc, |
| int | top_k = 10, |
||
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | for an empty document, a non-finite value, top_k < 1, or unusable options. |
| 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.
| structure | The text of a PDB or mmCIF file (mmCIF when it starts with data_), embedded in the page. |
| options | HtmlScripts::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). |
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | for the problems RenderTokenStripSvg rejects. |
| 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.
| std::invalid_argument | if tokens and relevance (or scored) differ in length, there are no tokens, or for invalid options. |
| std::string pulsatrix::RenderTornadoHtml | ( | const SensitivityDocument & | doc, |
| int | top_k = 10, |
||
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | for an empty document, a non-finite value, top_k < 1, or unusable options. |
| std::string pulsatrix::RenderTrainingLogHtml | ( | const TrainingLogDocument & | doc, |
| const HtmlOptions & | options = {} |
||
| ) |
| std::string pulsatrix::RenderWaterfallHtml | ( | const AttributionDocument & | doc, |
| float | baseline_value, | ||
| const HtmlOptions & | options = {} |
||
| ) |
| 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.
| std::invalid_argument | for the same inputs ToWaterfallSteps rejects, a non-finite value or baseline, or invalid options. |
| 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.
| std::invalid_argument | as ReplayMaskedDiffusion, or for a target the trajectory didn't write. |
| 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.
| config | Only mask_token_id and suppressed_token_ids are used. |
| std::invalid_argument | if input's length differs from the trajectory's, or the model's output doesn't fit. |
| 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.
| std::invalid_argument | for the same problems ToJson rejects. |
| 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.
| attribution | What the explainer returned; empty for explainers that don't return an attribution. request.target, baseline and dataset aren't used. |
| std::invalid_argument | if request.method isn't in the catalog or doesn't answer request.question. |
| Rdm pulsatrix::RepresentationalDissimilarity | ( | const Tensor & | x, |
| RdmMetric | metric = RdmMetric::Correlation |
||
| ) |
The RDM of a representation, shape (n, ...): a row per input, later dimensions flattened.
| std::invalid_argument | if 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. |
| 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.
|
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).
| where | Names the entry point in the error message, e.g. "LinearModule::backward". |
| std::invalid_argument | on 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. |
| 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.
| std::vector< std::string > pulsatrix::ResidueIds | ( | const StructureChain & | chain | ) |
chain's residue ids, for ResidueTracksDocument::residue_ids.
| 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>.
|
inline |
Overwrites every parameter tensor module.parameters() reports (in that order) from flat – the inverse of FlattenParameters.
| std::invalid_argument | if flat's size doesn't exactly match the total parameter count module.parameters() reports. |
| 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).
| std::invalid_argument | as Pgd() does, or if epsilons is empty or holds a value that isn't finite and positive. |
| 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.
| 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).
| std::invalid_argument | for any other rope_scaling type. |
| 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.
| std::invalid_argument | – see RouletteSelectByDraw (validation happens there; this wrapper adds no separate checks so the two never disagree on what is malformed). |
| 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.
| population | Non-empty population with strictly non-negative fitness values summing to a strictly positive total. |
| draw | A value in [0, total_fitness), where total_fitness = sum of population fitness. |
| std::invalid_argument | if population is empty, any fitness is negative, the total fitness is not strictly positive, or draw is outside [0, total_fitness). |
| 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)).
| std::invalid_argument | as those two do, or if x and y have different numbers of rows. |
| 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.
| permutations | How many relabelings; 999 resolves p-values down to 0.001. |
| seed | The relabelings come from it: the same seed, the same p-value on every platform. |
| std::invalid_argument | as CompareRdms() does, or if permutations is below 1. |
| 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.
| a,b | shape (n, ...) each, rows for the same n inputs in the same order; widths may differ. |
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | if max_configs_started == 0. |
|
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.
| initial_epoch_budget | Rung 0's epoch budget; rung k's budget is initial_epoch_budget * eta^k. |
| num_rungs | Total number of rungs (>= 2 – at least one promotion opportunity must exist). |
| std::invalid_argument | if config_queue is empty, initial_epoch_budget <= 0, eta <= 1.0, or num_rungs < 2. |
| 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.
| make_generator | Constructs a fresh generator instance with the same architecture as every population member. |
| g_learning_rate | Learning rate for the SGDOptimizer each mutation attempt trains with. |
| std::invalid_argument | if noise_per_generator.size() != population.size(), or objectives is empty. |
| 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.
| std::invalid_argument | if num_generations is not positive (delegates to RunEGANGeneration for its own preconditions each generation). |
| 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.
| population | Initial population (its own fitness values are (re-)computed, not trusted, before the loop begins). mu = population.size(). |
| produce_offspring_genotype | Callable Genotype(const std::vector<Individual<Genotype, FitnessT>>& current_population) – composes whichever selection + crossover + mutation recipe the caller wants; called once per offspring needed. |
| survivor_selector | Callable 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_pool | Optional – see EvaluatePopulation. |
| 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.
| std::invalid_argument | if theta is empty or num_iterations is not positive (ESStep's own guards apply to population_size/sigma). |
| 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.
| objective_fn | Callable double(const Configuration&) – the value to maximize (a caller minimizing a loss negates it first, per this file's maximization convention). |
| std::invalid_argument | if num_initial_random == 0, or (propagated from UnitCubeToConfiguration) space contains an Integer/Categorical parameter. |
| 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.
| std::invalid_argument | – propagated from ComputeHyperbandBrackets. |
| 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.
| 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.
| std::invalid_argument | if population is empty or num_generations is not positive. |
| 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.
| std::invalid_argument | if num_generations is not positive (delegates to RunPBTGeneration for its own preconditions). |
| 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.
| std::invalid_argument | if trials is empty or num_epochs is not positive (delegates to ComputeTruncationGroups for its own preconditions once trials.size() >= 2). |
| 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.
| std::invalid_argument | if num_configs == 0 – see RunSuccessiveHalvingOnConfigs for the other validated preconditions. |
|
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.
| initial_epoch_budget | Epochs trained in the first rung. |
| eta | Reduction factor: after each rung, floor(count / eta) configurations survive (at least 1), and the next rung's budget is the previous budget * eta. |
| std::invalid_argument | if configs is empty, initial_epoch_budget <= 0, or eta <= 1.0. |
| 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.
| ctx | The model, as an ExplainerContext; its output is (n, classes). |
| layer | The node whose output is the layer: module i's output is node i + 1. |
| target | The class whose logit is explained. |
| class_inputs | Inputs of that class, the model's input shape with a leading batch. |
| concept_inputs | Examples of the concept. |
| random_inputs | At 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). |
| std::invalid_argument | if 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. |
| 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.
| gamma | Fraction 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. |
| std::invalid_argument | if num_initial_random < 2 (a quantile split needs at least one good and one bad observation), or gamma is outside (0, 1). |
| 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).
| env | The environment to roll out on. Reset internally; any existing episode in progress is discarded. |
| forward_policy | The forward policy sampling each step's action. |
| std::string pulsatrix::sample_to_json | ( | const SystemSample & | sample | ) |
Encodes sample as one JSON object (no trailing newline), the JSON Lines log record.
| 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.
| std::invalid_argument | for an empty x_T, steps < 1, a negative eta, or a prediction of the wrong size. |
| 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.
| std::invalid_argument | for 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. |
| 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).
| 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.
| metadata | Extra string metadata to store; format and format_version are reserved. |
| std::invalid_argument | if a parameter and a buffer share a name, or metadata uses a reserved key. |
| std::runtime_error | if the file can't be written. |
| 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).
| mapping | As for SaveLoraAdapter(): the base model's weight manifest, or empty for pulsatrix's names. |
| std::invalid_argument | if there are none, one is merged, or a layer has no whole-weight mapping. |
| 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.
| mapping | How 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. |
base_model.model.<module>.lora_A.weight (r, in) and ...lora_B.weight (out, r), float32. | std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | if the model has none, or they edit different positions. |
| 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.
| std::invalid_argument | if num_std <= 0, background is empty, or a background instance's shape differs from input's. |
| 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.
| std::invalid_argument | if prompts or choice_tokens is empty, a prompt is empty, a choice is outside the vocabulary, or batch_size < 1. |
| CircuitScores pulsatrix::ScoreCircuit | ( | const CircuitTrace & | trace | ) |
Circuit-tracer's replacement and completeness scores (graph.py).
| 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.
| 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).
| 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.
residues x 20 (2 window + 1), the sequences' residues one after another. | 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.
| 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.
| tensors | Name and tensor pairs, stored in this order. Tensors on a GPU are copied back. |
| metadata | Stored as __metadata__; omitted when empty. |
| std::invalid_argument | if a name repeats, is __metadata__, or (like any metadata key or value) is not valid UTF-8. |
| void pulsatrix::set_deterministic | ( | bool | enabled | ) |
Turns deterministic mode on (the default) or off.
| void pulsatrix::set_seed | ( | uint64_t | seed | ) |
Sets the global seed and restarts the seed stream next_seed() draws from.
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. | void pulsatrix::SetIA3Enabled | ( | Module & | model, |
| bool | enabled | ||
| ) |
Turns every vector on or off.
| std::logic_error | while one is merged. |
| 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.
| 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).
| std::invalid_argument | – see SimulatedBinaryCrossoverByDraw. |
|
inline |
Simulated binary crossover (Deb & Agrawal 1995; DEAP's cxSimulatedBinary), given an explicit per-gene draw in [0, 1).
| std::invalid_argument | if parent1/parent2/draws sizes are not all equal, eta is negative, or any draw is outside [0, 1). |
| 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.
| points | The number of points the edges span. |
| std::invalid_argument | if an edge has an endpoint outside [0, points). |
| 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".
| std::invalid_argument | if it tokenizes to anything else. |
| 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.
| t | The 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_dim | Size 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). |
| backend | Backend to allocate the result through. Not owned; must outlive the returned Tensor. |
| base | Frequency base of the geometric wavelength schedule; 10000.0 is the standard convention shared by the Transformer and DDPM papers. |
(1, embedding_dim). | std::invalid_argument | if embedding_dim <= 0 or embedding_dim is odd – external boundary, same classification as RoPEModule's head_dim check. |
(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. backend, so a GPU backend receives a device-resident result.
|
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.
| std::invalid_argument | if t has rank 0, count <= 0, start < 0, or start+count exceeds t's own leading dimension. |
| 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.
|
inline |
Solves A*x = b via Gaussian elimination with partial pivoting.
| std::runtime_error | if 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. |
| 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.
| 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.
| std::invalid_argument | for sizes that differ or < 2. |
| float pulsatrix::SpearmanRankCorrelation | ( | const std::vector< float > & | x, |
| const std::vector< float > & | y | ||
| ) |
Spearman rank correlation, with tied values given their average rank.
| std::invalid_argument | if the sizes differ or are below 2. |
|
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.
| std::invalid_argument | if population is empty or compatibility_threshold <= 0. |
| 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.
| rows | Which 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. |
rows has the wrong length. | std::vector< Offset > pulsatrix::SplitWords | ( | std::string_view | text, |
| const UnicodeRegex & | pattern | ||
| ) |
The words of text: every match of pattern.
| 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.
| std::invalid_argument | if text isn't valid UTF-8. |
| std::vector< float > pulsatrix::StandardNormal | ( | size_t | n, |
| uint64_t | seed | ||
| ) |
Draws n standard normal values from seed, as SampleContinuousDiffusion does.
|
inline |
Standard normal CDF, Phi(z) = 0.5 * (1 + erf(z / sqrt(2))).
|
inline |
Standard normal PDF, phi(z) = (1/sqrt(2*pi)) * exp(-z^2/2).
| 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().
rows has the wrong length. | 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.
| what | RenderStructureHtml throws, or std::invalid_argument for an id that isn't lowercase letters, digits and hyphens. |
| 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.
| std::invalid_argument | if either sample has fewer than 2 values, or a value isn't finite. |
| 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.
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.
| std::invalid_argument | if the widths differ or k is not between 1 and both PCAs' num_components(). |
| TimingStats pulsatrix::SummarizeTimings | ( | std::vector< double > | samples_ms | ) |
Summarizes timings. Percentiles interpolate linearly between the sorted samples.
| std::invalid_argument | if samples_ms is empty or has a negative or non-finite value. |
| SvccaResult pulsatrix::Svcca | ( | const Tensor & | x, |
| const Tensor & | y, | ||
| const SvccaOptions & | options = {} |
||
| ) |
SVCCA: CanonicalCorrelations() between each representation's top singular directions.
| std::invalid_argument | as CanonicalCorrelations() does for the kept directions, or if an option is out of range. |
Thin singular value decomposition by one-sided (Hestenes) Jacobi rotations.
| 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. |
| std::invalid_argument | if a is not rank 2, is not on the CPU, or has a non-finite entry. |
| 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.
| a | Square (n, n) CPU tensor, symmetric to within a relative 1e-5, all finite. |
| std::invalid_argument | if a is not square rank 2, is not on the CPU, has a non-finite entry, or is not symmetric. |
| std::runtime_error | if QL fails to converge in 60 iterations for some eigenvalue, which does not happen for finite symmetric input in practice. |
| 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.
| a | Row-major (n, n), symmetric to within a relative 1e-5, all finite. |
| std::invalid_argument | as SymmetricEigenvalues() does. |
| 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.
| a | Row-major (n, n), symmetric to within a relative 1e-5, all finite. |
| std::invalid_argument | if a doesn't hold n * n values, n < 1, it has a non-finite entry, or it isn't symmetric. |
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).
| source | Network to copy parameter values from – typically the online Q-network. |
| destination | Network to copy into – typically the frozen target network. |
| std::invalid_argument | if 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. |
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. | float pulsatrix::TaggingAccuracy | ( | TinyTagger & | tagger, |
| TaggingRule | rule, | ||
| int64_t | num_sequences | ||
| ) |
Fraction of real tokens tagged correctly on num_sequences fresh sequences.
| double pulsatrix::TcavScore | ( | const std::vector< double > & | sensitivities | ) |
The fraction of sensitivities above zero.
| std::invalid_argument | if empty. |
|
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.
| step_size_learning_rate,scale_learning_rate | Fixed adaptation rates (this variant's own simplification – full CMA-ES derives these from mu_eff/n instead). |
| std::invalid_argument | if z_samples/offspring/fitness sizes disagree, or fewer than 2 samples are given (mu = size/2 must be >= 1). |
| 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.
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. | std::invalid_argument | if warmup < 0 or repeats < 1. |
| 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.
| 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&)).
| std::string_view pulsatrix::to_string | ( | CaveatSeverity | severity | ) |
| std::string_view pulsatrix::to_string | ( | CheckOutcome | outcome | ) |
| std::string_view pulsatrix::to_string | ( | CheckPriority | priority | ) |
| std::string_view pulsatrix::to_string | ( | ExplanationScope | scope | ) |
| std::string_view pulsatrix::to_string | ( | InputKind | input | ) |
| std::string_view pulsatrix::to_string | ( | ModelAccess | access | ) |
| std::string_view pulsatrix::to_string | ( | SurrogateTask | task | ) |
| std::string_view pulsatrix::to_string | ( | XaiQuestion | question | ) |
| std::string_view pulsatrix::to_string | ( | XaiReason | reason | ) |
| 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.
| 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).
| Attribution pulsatrix::ToAttribution | ( | const AttributionDocument & | doc, |
| DeviceBackend * | backend | ||
| ) |
Rebuilds an Attribution whose values live on backend.
| AttributionDocument pulsatrix::ToAttributionDocument | ( | const Attribution & | attr | ) |
Copies attr into a document, reading its values to the host.
| 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).
| 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.
| runs | Attribution results across many samples/predictions (not necessarily repeated runs on one input – unlike ComputeAttributionStability, this is the global view across many different inputs). |
| feature_index | Which feature (element position) to plot. |
| std::invalid_argument | if runs is empty. |
| std::out_of_range | if feature_index is out of range for any run's Attribution. |
| CircuitGraph pulsatrix::ToCircuitGraph | ( | const CircuitGraphDocument & | doc | ) |
| std::invalid_argument | if a node's op_type isn't an OpType name. |
| CircuitGraphDocument pulsatrix::ToCircuitGraphDocument | ( | const CircuitGraph & | graph | ) |
| 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.
| std::invalid_argument | if the counterfactual's size differs from the input's, or a list has the wrong length. |
| 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).
| attr | A 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_k | Number of highest-|value| features to keep, in descending |value| order. |
| std::invalid_argument | if attr.values is not rank 1 or batch-1 rank 2, or if top_k <= 0. |
| 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).
| dataset | The dataset to scan. Must be non-empty. |
| field_index | Which Sample field position to bin. |
| num_bins | Number of equal-width bins, must be positive. |
| std::invalid_argument | if dataset is empty or num_bins <= 0. |
| std::out_of_range | if field_index is out of range for the dataset's samples. |
| HeatmapDocument pulsatrix::ToHeatmapDocument | ( | const HeatmapGrid & | grid, |
| std::string | title = "" |
||
| ) |
| 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.
| HeatmapGrid pulsatrix::ToHeatmapGrid | ( | const HeatmapDocument & | doc | ) |
| IceResult pulsatrix::ToIceResult | ( | const PartialDependenceDocument & | doc | ) |
Rebuilds the ICE curves for their centered and derivative views.
| std::invalid_argument | if the document holds no ICE curves. |
| JsonValue pulsatrix::ToJson | ( | const AgreementReport & | report | ) |
The report as a pulsatrix.explanation_agreement.v1 document. NaNs are written as null.
| 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.
| JsonValue pulsatrix::ToJson | ( | const AttackResult & | result, |
| const AttackOptions & | options | ||
| ) |
The result as a pulsatrix.attack.v1 document, without the adversarial inputs.
| std::string pulsatrix::ToJson | ( | const AttributionDocument & | doc | ) |
| std::invalid_argument | if values.size() isn't the product of shape. |
| std::string pulsatrix::ToJson | ( | const BenchmarkReport & | report | ) |
| std::invalid_argument | if two records share a name and device. |
| std::string pulsatrix::ToJson | ( | const CircuitGraphDocument & | doc | ) |
| std::invalid_argument | if node ids repeat or are negative, or an edge names a node that isn't in the list. |
| JsonValue pulsatrix::ToJson | ( | const ClassificationReport & | report | ) |
The report as a pulsatrix.classification_report.v1 document.
| std::string pulsatrix::ToJson | ( | const ContactMapDocument & | doc | ) |
| std::invalid_argument | if the sequence is empty, predicted isn't L x L, or truth is neither empty nor L x L of 0, 1 and NaN. |
| 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".
| std::string pulsatrix::ToJson | ( | const CounterfactualDocument & | doc | ) |
| std::invalid_argument | if a scale is not positive. |
| JsonValue pulsatrix::ToJson | ( | const CoverageReport & | report | ) |
The report as a pulsatrix.coverage.v1 document, without the per-input misses.
| JsonValue pulsatrix::ToJson | ( | const ExplainerCapabilities & | capabilities | ) |
The declaration as a JSON object, with the enums as their to_string() names.
| JsonValue pulsatrix::ToJson | ( | const Explanation & | explanation | ) |
The explanation as a pulsatrix.explanation.v1 document, attribution values included.
| 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.
| std::string pulsatrix::ToJson | ( | const FeatureDashboardDocument & | doc | ) |
| std::invalid_argument | if the histogram's lengths don't match, a count is negative, or an example has tokens and a different number of activations. |
| std::string pulsatrix::ToJson | ( | const HeatmapDocument & | doc | ) |
| std::invalid_argument | if values.size() != rows * cols or a label list has the wrong length. |
| JsonValue pulsatrix::ToJson | ( | const LogOddsErrorReport & | report | ) |
The report as a JSON object: clip, overall, and bands.
| std::string pulsatrix::ToJson | ( | const MorrisDocument & | doc | ) |
| std::string pulsatrix::ToJson | ( | const MutationMapDocument & | doc | ) |
| std::invalid_argument | if the sequence or alphabet is empty, a letter repeats in the alphabet, or values isn't residues x alphabet. |
| std::string pulsatrix::ToJson | ( | const PartialDependenceDocument & | doc | ) |
| std::invalid_argument | if 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. |
| std::string pulsatrix::ToJson | ( | const PersistenceDiagramDocument & | doc | ) |
Writes the document.
| std::invalid_argument | naming the JSON Pointer of the first problem. |
| std::string pulsatrix::ToJson | ( | const ProjectionDocument & | doc | ) |
| std::invalid_argument | if 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. |
| JsonValue pulsatrix::ToJson | ( | const PrototypeResult & | result | ) |
The result as a pulsatrix.prototypes.v1 document.
| JsonValue pulsatrix::ToJson | ( | const RegressionReport & | report | ) |
The report as a pulsatrix.regression_report.v1 document.
| std::string pulsatrix::ToJson | ( | const ResidueTracksDocument & | doc | ) |
| std::invalid_argument | if 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. |
| JsonValue pulsatrix::ToJson | ( | const RobustnessCurve & | curve | ) |
The curve as a pulsatrix.robustness_curve.v1 document.
| std::string pulsatrix::ToJson | ( | const SensitivityDocument & | doc | ) |
| JsonValue pulsatrix::ToJson | ( | const SensitivityReport & | report | ) |
The report as a pulsatrix.explanation_sensitivity.v1 document.
| std::string pulsatrix::ToJson | ( | const SequenceLogoDocument & | doc | ) |
| std::invalid_argument | if 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. |
| std::string pulsatrix::ToJson | ( | const SeriesDocument & | doc | ) |
| std::invalid_argument | for 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. |
| JsonValue pulsatrix::ToJson | ( | const SliceErrorReport & | report | ) |
The report as a pulsatrix.slice_error.v1 document.
| std::string pulsatrix::ToJson | ( | const SobolDocument & | doc | ) |
| JsonValue pulsatrix::ToJson | ( | const SurrogateTreeResult & | result, |
| const std::vector< std::string > & | feature_names = {} |
||
| ) |
The result as a pulsatrix.surrogate_tree.v1 document.
| std::string pulsatrix::ToJson | ( | const TokenRelevanceDocument & | doc | ) |
| std::invalid_argument | if tokens and relevance (or scored, when set) differ in length, or granularity is neither "token" nor "word". |
| std::string pulsatrix::ToJson | ( | const TrainingLogDocument & | doc | ) |
| std::invalid_argument | if a series' steps and values differ in length, or a tag repeats. |
The rules as a pulsatrix.tree_rules.v1 document: each rule's text, conditions, class, support and confidence.
| JsonValue pulsatrix::ToJson | ( | const UncertaintyDecomposition & | decomposition | ) |
The decomposition as a pulsatrix.uncertainty.v1 document, without the mean probabilities.
| 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.
| add_special_tokens | Passed to TextTokenizer::encode() for the prompt (a BOS token, for tokenizers that add one); never for the completion. |
| std::invalid_argument | if a row isn't an object with both strings, or a prompt or completion tokenizes to nothing. |
| 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>.
| std::invalid_argument | if names has the wrong length. |
| 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.
| std::invalid_argument | if 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=...). |
| 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.
| input | Tensor of any rank >= 1. Every slice along its last dimension is one row. |
| k | Entries kept per row; 1 <= k <= the last dimension's size. |
| largest | true for the k largest (default), false for the k smallest. |
(..., k), in rank order, on input's device. indices itself. | std::invalid_argument | if input is empty or rank 0, k is outside [1, last dimension], or the last dimension exceeds 2^24 – external boundary. |
| 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.
| PartialDependenceDocument pulsatrix::ToPartialDependenceDocument | ( | const IceResult & | result, |
| std::string | feature = "", |
||
| std::string | target = "" |
||
| ) |
Copies result, its partial dependence curve included.
| PersistenceDiagramDocument pulsatrix::ToPersistenceDiagramDocument | ( | const RipsResult & | result, |
| std::string | title = "" |
||
| ) |
The same, from ComputeRipsPersistence(), with its threshold.
| PersistenceDiagramDocument pulsatrix::ToPersistenceDiagramDocument | ( | const std::vector< PersistenceDiagram > & | diagrams, |
| std::string | title = "" |
||
| ) |
The diagrams as a document: births, deaths and each diagram's error bound.
| std::invalid_argument | for a diagram the document can't hold (a NaN, a death before its birth, a dimension given twice). |
| 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.
| 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).
| image_chw | A 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. |
| std::invalid_argument | if image_chw's rank/channel count don't match the above. |
| HeatmapGrid pulsatrix::ToSaliencyHeatmap | ( | const Attribution & | attr | ) |
Reshapes an Attribution's values into a 2D grid for a saliency overlay heatmap.
| attr | A 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. |
| std::invalid_argument | if 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). |
| 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>.
| 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>.
| std::invalid_argument | if names has the wrong length. |
| TrainingLogDocument pulsatrix::ToTrainingLogDocument | ( | const ImPlotMetricsSink & | sink | ) |
Copies everything sink has logged, sorted by tag.
| 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.
| population | Non-empty population to select from. |
| tournament_size | Number of distinct competitors, in [1, population.size()]. |
| rng | Any UniformRandomBitGenerator (e.g. std::mt19937). |
| std::invalid_argument | if 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. |
| 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.
| 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).
| 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|.
| std::invalid_argument | for an empty graph or an edge naming a missing node. |
| 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.
| 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.
| JsonValue pulsatrix::ToVegaLiteFeatureHistogram | ( | const FeatureDashboardDocument & | doc, |
| const HtmlOptions & | options = {} |
||
| ) |
A feature's activation histogram (the dashboard's chart; RenderFeatureDashboardHtml adds the top examples).
| 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.
| 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.
| 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.
| 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.
| 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.
| std::invalid_argument | for what RenderSeriesSvg() rejects. |
| 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.
| 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.
| 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.
| 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).
| 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.
| steps | ToWaterfallSteps's output. |
| baseline_value | The same baseline passed to 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).
| attr | A 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_value | The starting reference value (e.g. Integrated Gradients' baseline prediction, or the model's mean output). |
| std::invalid_argument | if attr.values is not rank 1 or batch-1 rank 2. |
| 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.
a_s times decoders, errors) and at the embeddings with the scaled token embeddings. | std::invalid_argument | if the transcoder's layers or width don't match the model, or the prompt is empty. |
| 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.
| concept_activations,random_activations | shape (n, ...), a row per example, the same width. Each needs at least 2 rows (3 with the default holdout). |
| std::invalid_argument | if the widths differ, a set is too small, or a value isn't finite. |
| DecompositionLoss pulsatrix::TrainDecomposition | ( | ParameterDecomposition & | d, |
| const Tensor & | x, | ||
| Optimizer & | optimizer | ||
| ) |
One training step: zero the gradients, loss_and_backward(), one optimizer step.
| 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.
| 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.
| Optimizer | SGDOptimizer, AdamOptimizer or AdamWOptimizer: anything with zero_grad(Module&) and step(Module&). |
| 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.
| features | rows x dim, row-major. |
| labels | one class in [0, classes) per row. |
| std::invalid_argument | if the sizes don't agree, classes < 2, or either set is empty. |
| 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.
| 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).
| 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.
| 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.
| x | shape (n, ...): a row per point, under Euclidean distance. |
| discard_fraction | The share of the largest mu values the fit leaves out, 0.1 in the paper. |
| std::invalid_argument | if 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. |
| 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.
| std::invalid_argument | if parent sizes differ or parent size < 2. |
| 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.
| std::invalid_argument | if parent sizes differ, point1 > point2, or point2 exceeds parent size. |
| 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.
| std::invalid_argument | if parent sizes differ or swap_probability is outside [0, 1]. |
| 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.
| std::invalid_argument | if parent1/parent2/swap_mask sizes are not all equal. |
|
inline |
Maps a unit-hypercube point (one value per parameter, each in [0, 1]) to a Configuration, using space's own declared bounds.
| std::invalid_argument | if t.size() != space.size(), any t[i] is outside [0, 1], or space contains a parameter kind other than Continuous/LogUniform. |
| 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).
| alpha | The family-wise significance level, split over the features by Bonferroni. |
| std::invalid_argument | if the diagram is H0 (all births are 0), has fewer than 2 finite features with birth above 0, or alpha is outside (0, 1). |
| 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.
| void pulsatrix::UnmergeLora | ( | Module & | model | ) |
Takes every merged adapter out of its base weight again.
|
inline |
GP-Upper-Confidence-Bound: mean + kappa * sqrt(variance).
| kappa | Exploration weight (default 2.0, a common practical default – larger values favor exploring high-uncertainty regions over exploiting the current best mean). |
| std::invalid_argument | if variance < 0. |
| 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.
| heading | Shown above the chart. |
| extra_html | Appended after it, as is. |
| std::runtime_error | if inline scripts are asked for and can't be read. |
| RgbColor pulsatrix::ViridisColormap | ( | float | normalized_value | ) |
Viridis colormap – perceptually uniform, colorblind-safe – for sequential/unsigned magnitude (hc_information_visualization.md SS4: "Recommended Color Systems").
| normalized_value | Position along the colormap, expected in [0, 1]; values outside this range are clamped to the nearest end anchor. |
| 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.
| std::invalid_argument | if json isn't a JSON object with a "schema" of the form pulsatrix.<kind>.v<N>, or if N isn't kVizDocumentVersion. |
| bool pulsatrix::VizFontsUseFreeType | ( | ) |
Whether this build's ImGui uses FreeType (color emoji) rather than stb_truetype.
| 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.
| order | q, at least 1. Infinity gives the bottleneck distance's value. |
| std::invalid_argument | if the dimensions differ or order is below 1 or NaN. |
| 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).
| 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).
| std::string pulsatrix::WriteJson | ( | const JsonValue & | value | ) |
Writes value as JSON, indented by two spaces and ending with a newline.
", \ and control characters escaped. | std::invalid_argument | if a string isn't valid UTF-8. |
| std::string pulsatrix::WriteJsonCompact | ( | const JsonValue & | value | ) |
Writes value as JSON on one line, with no whitespace and no trailing newline.
| std::invalid_argument | if a string isn't valid UTF-8. |
| void pulsatrix::WriteNpy | ( | const std::string & | path, |
| const Tensor & | x | ||
| ) |
SerializeNpy() written to path.
| std::runtime_error | if the file can't be written. |
| 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.
| std::runtime_error | if the file can't be written; otherwise as SerializeSafetensors(). |
|
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).
| Whatever | EvaluateNEATPhenotype throws if genome's Input node count isn't 2. |
|
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).
|
inlineconstexpr |
The 3Dmol.js version the structure page loads.
|
inlineconstexpr |
The 20 standard amino acids, in the order SingleMutantScan's columns use.
|
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.
|
inlineconstexpr |
Total flat-parameter count: 2*2 (input->hidden weights) + 2 (hidden biases) + 2 (hidden->output weights) + 1 (output bias) = 9.
|
inlineconstexpr |
|
inlineconstexpr |
|
inlineconstexpr |
CASP's and ESM's ranges: short 6–11, medium 12–23, long 24 and up.
|
inlineconstexpr |
|
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.
|
inlineconstexpr |
|
inlineconstexpr |
The versions of Vega, Vega-Lite and vega-embed the pages load (BSD-3-Clause).
|
inlineconstexpr |
The document format version this build writes and reads.