pulsatrix 1.1.0
Loading...
Searching...
No Matches
pulsatrix::DeviceBackend Class Referenceabstract

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...

#include <device_backend.hpp>

Inheritance diagram for pulsatrix::DeviceBackend:

Public Member Functions

virtual ~DeviceBackend ()=default
 
virtual DeviceType device () const noexcept=0
 Which device this backend's buffers reside on.
 
virtual void * allocate (size_t bytes)=0
 Allocates a buffer of the given size.
 
virtual void free (void *ptr) noexcept=0
 Frees a buffer previously returned by allocate(). Safe to call with nullptr.
 
virtual void copy (void *dst, const void *src, size_t bytes, CopyDirection dir)=0
 Copies bytes between buffers.
 
virtual void fill (void *ptr, float value, size_t n)=0
 Fills every element of a float buffer with a constant value.
 
virtual void gemm (const float *a, const float *b, float *out, size_t m, size_t k, size_t n)=0
 Row-major matrix multiply: out = a * b.
 
virtual void elementwise (ElementwiseOp op, const float *in, float *out, size_t n)=0
 Applies a unary elementwise operation to every element of a buffer.
 
virtual void add (const float *a, const float *b, float *out, size_t n)=0
 Elementwise binary addition: out[i] = a[i] + b[i] for i in [0, n).
 
virtual void mul (const float *a, const float *b, float *out, size_t n)=0
 Elementwise binary (Hadamard) multiplication: out[i] = a[i] * b[i] for i in [0, n).
 
virtual void gemm_ex (const float *a, bool transpose_a, const float *b, bool transpose_b, float *out, size_t m, size_t k, size_t n, float beta)=0
 General row-major matrix multiply: out = op(A) * op(B) + beta * out.
 
virtual void gemm_strided_batched (const float *a, bool transpose_a, size_t stride_a, const float *b, bool transpose_b, size_t stride_b, float *out, size_t stride_out, size_t m, size_t k, size_t n, size_t batch, float beta=0.0f)
 batch independent gemm_ex() products, out_i = op(A_i) op(B_i) (+ beta out_i), with A_i = a + i * stride_a and likewise for b and out; a stride of 0 shares one matrix (HIP-6: a convolution's kernel against every example's patches).
 
virtual void accumulate_parts (const float *parts, size_t count, size_t n, float *acc)
 acc += parts[0], then += parts[1], ... (count blocks of n floats, in order): the sums accumulating one gradient per example gave, one add() each (HIP-6).
 
virtual void column_sums (const float *in, float *out, size_t rows, size_t cols, float beta)=0
 Per-column sum of a (rows x cols) row-major matrix: out[j] = beta*out[j] + sum_i in[i][j].
 
virtual void add_row_vector (const float *in, const float *row, float *out, size_t rows, size_t cols)=0
 Broadcast row add: out[i][j] = in[i][j] + row[j] for a (rows x cols) matrix.
 
virtual void add_row_vector_relu (const float *in, const float *row, float *z, float *out, size_t rows, size_t cols)
 add_row_vector() into z, then ReLU of z into out: a Linear layer's bias and the ReLU after it (HIP-6). Both are written, since the ReLU's backward and LRP read z.
 
virtual void elementwise_backward (ElementwiseOp op, const float *x, const float *grad_out, float *grad_in, size_t n)=0
 Activation backward: grad_in[i] = grad_out[i] * f'(x[i]), f = op, x = the forward input.
 
virtual void axpby (float alpha, const float *x, float beta, const float *y, float *out, size_t n)=0
 out[i] = alpha * x[i] + beta * y[i]. out may alias x or y.
 
virtual float dot (const float *a, const float *b, size_t n)=0
 Dot product sum_i a[i]*b[i], returned to the host.
 
virtual void dot_into (const float *a, const float *b, size_t n, float *out)
 dot() written to out, one float in this backend's memory, instead of returned (HIP-6). Same value as dot(). A GPU backend doesn't wait for it, so many dots cost one read back instead of one each.
 
virtual void softmax_rows (const float *in, float *out, size_t rows, size_t cols)=0
 Row-wise softmax of a (rows x cols) matrix, max-subtracted. out may alias in.
 
virtual void softmax_rows_backward (const float *y, const float *dy, float *dx, size_t rows, size_t cols)=0
 Softmax backward from its output y: dx[i][j] = y[i][j] * (dy[i][j] - sum_k y[i][k]*dy[i][k]).
 
virtual void logsumexp_rows (const float *in, float *out, size_t rows, size_t cols)=0
 Per-row log-sum-exp, max-subtracted: out[i] = log sum_j exp(in[i][j]).
 
virtual void adam_step (float *param, const float *grad, float *m, float *v, size_t n, float lr, float beta1, float beta2, float eps, float bias_correction1, float bias_correction2)=0
 One fused Adam update over n parameters.
 
virtual void adam_step_multi (const AdamTensorStep *tensors, size_t count, float beta1, float beta2, float eps)
 Adam (or AdamW, or Adam with L2 decay) over many parameter tensors at once (HIP-6). Each tensor gets exactly what axpby() then adam_step() would do: the decay decay * param (beta 0), or the step on l2 * param + 1 * grad.
 
virtual float sum (const float *in, size_t n)=0
 sum_i in[i], returned to the host. Same reduction order as dot(). Synchronizes.
 
virtual void dropout_forward (const float *in, float *out, float *mask, size_t n, float p, float scale, uint64_t seed, uint64_t offset)=0
 Inverted dropout with a counter-based RNG: element i is dropped iff uniform(seed, offset + i) < p; kept elements are scaled by scale.
 
virtual void bce_with_logits (const float *logits, const float *target, float *out, size_t n)=0
 Per-element binary cross-entropy with logits: out[i] = max(x, 0) - x*y + log1p(exp(-|x|)), x = logits[i], y = target[i].
 
virtual void bce_with_logits_grad (const float *logits, const float *target, float *grad, size_t n, float scale)=0
 BCE-with-logits gradient: grad[i] = (sigmoid(x) - y) * scale, using the overflow-free sigmoid (exp(x) / (1 + exp(x)) for x < 0).
 
virtual void layer_norm_forward (const float *in, const float *gamma, const float *beta, float *xhat, float *out, float *row_std, size_t rows, size_t cols, float eps)=0
 LayerNorm forward per row: xhat = (x - mean)/sqrt(var + eps), out = gamma*xhat + beta.
 
virtual void layer_norm_backward (const float *grad_out, const float *gamma, const float *xhat, const float *row_std, float *grad_in, size_t rows, size_t cols)=0
 LayerNorm input gradient per row, from the cached xhat and per-row std.
 
virtual void rms_norm_forward (const float *in, const float *gamma, float *out, float *row_rms, size_t rows, size_t cols, float eps)=0
 RMSNorm forward per row: out = gamma * x / sqrt(mean(x^2) + eps).
 
virtual void rms_norm_backward (const float *grad_out, const float *gamma, const float *in, const float *row_rms, float *grad_in, float *gamma_terms, size_t rows, size_t cols)=0
 RMSNorm input gradient per row, plus gamma_terms[r][i] = grad_out * x / rms – the per-row contributions column_sums then reduces into gamma's gradient.
 
virtual void rope_rotate (const float *in, const float *cos_table, const float *sin_table, float *out, size_t num_slices, size_t seq_len, size_t head_dim, bool inverse, bool rotate_half)=0
 Rotary position embedding over (num_slices, seq_len, head_dim) data.
 
virtual void permute_0213 (const float *in, float *out, size_t d0, size_t d1, size_t d2, size_t d3)=0
 Swaps the middle two axes: in (d0, d1, d2, d3) -> out (d0, d2, d1, d3).
 
virtual void attention_mask_fill (float *scores, const float *key_keep, size_t batch, size_t heads, size_t q_len, size_t k_len, bool causal, size_t q_offset, size_t window, float value)=0
 Overwrites the masked entries of (batch, heads, q_len, k_len) attention scores with value, in place (LLM-1).
 
virtual void gather_rows (const float *table, const float *indices, float *out, size_t count, size_t dim)=0
 out[i][:] = table[indices[i]][:] for count rows of width dim.
 
virtual void scatter_add_rows (const float *src, const float *indices, float *table, size_t count, size_t dim)=0
 table[indices[i]][:] += src[i][:] for i = 0..count-1, in increasing i.
 
virtual void tanh_gaussian_forward (const float *mean, const float *log_std, const float *eps, float *action, float *std_cache, float *log_prob, size_t rows, size_t cols, float stabilizer, double half_log_two_pi)=0
 TanhGaussianPolicy sampling per (rows, cols) row: action = tanh(mean + exp(log_std)*eps), std_cache = exp(log_std), log_prob[r] accumulated in double.
 
virtual void tanh_gaussian_backward (const float *action, const float *std_cache, const float *eps, const float *grad_action, const float *grad_log_prob, float *grad_mean, float *grad_log_std, size_t n, float stabilizer)=0
 TanhGaussianPolicy gradients w.r.t. mean and log_std, per element.
 
virtual void lrp_linear (const float *x, const float *w, const float *z, const float *r, float *r_in, size_t rows, size_t in_features, size_t out_features, float eps)=0
 LinearModule epsilon rule: r_in[n][i] = sum_j (x[n][i] w[i][j] / stab(z[n][j])) r[n][j].
 
virtual void lrp_residual_split (const float *a, const float *b, const float *r, float *r_a, float *r_b, size_t n, float eps)=0
 Epsilon split of a residual sum y = a + b: r_a = (a / stab(y)) r, r_b = (b / stab(y)) r.
 
virtual void lrp_bilinear_elementwise (const float *a, const float *b, const float *r, float *r_out, size_t n, float eps)=0
 Eq. 15 for an elementwise product c = a*b: r_out = (a b / (2c + eps sign c)) r (same for both).
 
virtual void lrp_bilinear_matmul (const float *a, const float *b, const float *o, const float *r_o, float *r_a, float *r_b, size_t slices, size_t m, size_t p, size_t q, float eps, bool b_transposed)=0
 Eq. 15 for slices independent matmuls O = A @ B (A (M x P), B (P x Q), O and r_o (M x Q)).
 
virtual void lrp_softmax_rows (const float *x, const float *y, const float *r, float *r_in, size_t rows, size_t cols)=0
 SoftmaxModule rule per row: r_in = x * (r - y * sum(r)).
 
virtual void lrp_rope (const float *x, const float *y, const float *r, const float *cos_table, const float *sin_table, float *r_in, size_t slices, size_t seq_len, size_t head_dim, float eps, bool rotate_half)=0
 RoPEModule epsilon rule over (slices, seq_len, head_dim), tables as for rope_rotate.
 
virtual void logic_pointwise (LogicOp op, int norm, const float *a, const float *b, const float *g_or_r, const float *y, float *out_a, float *out_b, size_t n, float eps)=0
 One elementwise pass of Conjunction/Disjunction for operands a, b.
 
virtual void aggregator_forward (const float *x, float *mean_pow, float *out, size_t n, size_t cols, float p)=0
 AggregatorModule power mean over the leading axis of an (n, cols) input, per column.
 
virtual void aggregator_backward (const float *x, const float *mean_pow, const float *grad_out, float *grad_in, size_t n, size_t cols, float p)=0
 AggregatorModule input gradient, per column.
 
virtual void aggregator_lrp (const float *x, const float *mean_pow, const float *r_out, float *r_in, size_t n, size_t cols, float p, float eps)=0
 AggregatorModule epsilon rule, per column.
 
virtual void im2col (const float *in, float *col, size_t n, size_t c, size_t h, size_t w, const ConvGeometry &geometry)=0
 Unfolds (n, c, h, w) into (n, c*kh*kw, out_h*out_w) patches, with out_h = (h + 2*pad_h - kh) / stride_h + 1 (likewise out_w). Taps that fall in the zero padding read 0.
 
virtual void col2im_add (const float *col, float *out, size_t n, size_t c, size_t h, size_t w, const ConvGeometry &geometry)=0
 Folds (n, c*kh*kw, out_h*out_w) patches back, adding into out (n, c, h, w).
 
virtual void add_channel_vector (const float *in, const float *vec, float *out, size_t n, size_t c, size_t inner)=0
 out[i][ch][k] = in[i][ch][k] + vec[ch] over (n, c, inner). out may alias in.
 
virtual void lrp_conv (const float *col, const float *kernel, const float *pre_bias, const float *r, float *r_col, size_t n, size_t out_channels, size_t p, size_t q, float eps)=0
 Conv2D epsilon rule in patch space: r_col (n, p, q) from the cached patches, the kernel (out_channels, p) and the pre-bias outputs (n, out_channels, q).
 
virtual void lrp_stabilized_divide (const float *r, const float *denom, const float *gate, float *out, size_t n, float eps, LrpGate gate_mode)=0
 Gated stabilized division, the one non-gemm step of the affine LRP rules: out[i] = passes(gate[i]) ? r[i] / (denom[i] + eps sign(denom[i])) : 0, sign(0) = +1.
 
virtual void max_pool_forward (const float *in, float *out, float *argmax, size_t planes, size_t h, size_t w, size_t kh, size_t kw, size_t sh, size_t sw, size_t ph, size_t pw)=0
 Max pool over planes of (h, w) with a (kh, kw) window, stride (sh, sw) and padding (ph, pw); padded positions never win. Output (planes, out_h, out_w) with out = (n + 2 pad - k) / stride + 1. argmax = flat in-plane input index (first max wins).
 
virtual void max_unpool (const float *src, const float *argmax, float *dst, size_t planes, size_t h, size_t w, size_t kh, size_t kw, size_t sh, size_t sw, size_t ph, size_t pw)=0
 The inverse routing: each input position gets the sum of the pooled values whose argmax it is (windows may overlap). dst (planes, h, w) is overwritten.
 
virtual void avg_pool_forward (const float *in, float *out, size_t planes, size_t h, size_t w, size_t kh, size_t kw)=0
 Non-overlapping average pool over planes of (h, w).
 
virtual void avg_pool_backward (const float *grad_out, float *grad_in, size_t planes, size_t h, size_t w, size_t kh, size_t kw)=0
 Spreads grad_out / (kh*kw) over each window; grad_in must be zeroed by the caller.
 
virtual void lrp_avg_pool (const float *x, const float *r, float *r_in, size_t planes, size_t h, size_t w, size_t kh, size_t kw, float eps)=0
 AvgPool2D epsilon rule; r_in must be zeroed by the caller.
 
virtual void batch_norm_forward (const float *in, const float *gamma, const float *beta, float *xhat, float *out, float *channel_std, size_t n, size_t c, size_t spatial, float eps)=0
 BatchNorm over (n, spatial) per channel of (n, c, spatial) data.
 
virtual void batch_norm_backward (const float *grad_out, const float *gamma, const float *xhat, const float *channel_std, float *grad_in, float *gamma_grad, float *beta_grad, size_t n, size_t c, size_t spatial)=0
 BatchNorm input gradient plus this call's gamma/beta gradients (overwritten, per channel).
 
virtual void batch_norm_update_running (const float *in, float *running_mean, float *running_var, size_t n, size_t c, size_t spatial, float momentum)=0
 Folds this batch's per-channel mean and unbiased variance into the running ones (PyTorch's momentum rule; the variance is kept when a channel has one value). FND-5.
 
virtual void batch_norm_eval_forward (const float *in, const float *gamma, const float *beta, const float *running_mean, const float *running_var, float *xhat, float *out, float *channel_std, size_t n, size_t c, size_t spatial, float eps)=0
 Eval-mode BatchNorm from the running statistics: a per-channel affine map. FND-5.
 
virtual void batch_norm_eval_backward (const float *grad_out, const float *gamma, const float *xhat, const float *channel_std, float *grad_in, float *gamma_grad, float *beta_grad, size_t n, size_t c, size_t spatial)=0
 Eval-mode BatchNorm gradient: grad_out * gamma / std, plus gamma/beta gradients (overwritten, per channel). FND-5.
 
virtual void group_norm_forward (const float *in, const float *gamma, const float *beta, float *xhat, float *out, float *group_std, size_t n, size_t c, size_t spatial, size_t num_groups, float eps)=0
 GroupNorm per (example, group) of (n, c, spatial) data; group_std is (n, num_groups).
 
virtual void group_norm_backward (const float *grad_out, const float *gamma, const float *xhat, const float *group_std, float *grad_in, float *gamma_grad, float *beta_grad, size_t n, size_t c, size_t spatial, size_t num_groups)=0
 GroupNorm input gradient plus this call's gamma/beta gradients (overwritten, per channel).
 
virtual void copy_2d (float *dst, size_t dst_stride, const float *src, size_t src_stride, size_t rows, size_t cols)=0
 Strided 2-D copy: rows of cols floats from src (row stride src_stride) to dst (row stride dst_stride) – e.g. one timestep of an (N, L, D) sequence.
 
virtual void accumulate_rows (const float *in, float *out, size_t rows, size_t cols)=0
 out[j] += in[i][j] for i = 0..rows-1 in order, accumulating straight into out.
 
virtual void recurrent_cell (RecurrentCellOp op, const RecurrentCellArgs &args, size_t n)=0
 One fused recurrent-cell pass over n elements (see RecurrentCellOp for slots).
 
virtual void gru_lrp_hprev (const float *h_prev, const float *w_hn, const float *hn, const float *r_term_b, const float *direct, float *r_hprev, size_t rows, size_t hidden, float eps)=0
 GRU's R_hprev for (rows, hidden): the recurrent epsilon-rule sum through W_hn, with each element's direct term inserted where the original loop added it.
 
virtual void ssm_pass (SsmPassOp op, const SsmPassArgs &args)=0
 One fused Mamba / RWKV / RetNet pass (see SsmPassOp for lanes and slots).
 
virtual void rl_rows (RlRowOp op, const RlRowArgs &args)=0
 One fused RL loss / target / Polyak pass (see RlRowOp for lanes and slots).
 
virtual void top_k_rows (const float *in, float *values, float *indices, size_t rows, size_t cols, size_t k, bool largest)=0
 Per row of a row-major (rows, cols) matrix: the k largest (or smallest) values in rank order into values (rows, k), and their column indices into indices (rows, k) as whole-number floats.
 

Detailed Description

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.

Note
Every concrete implementation must honor identical numeric semantics and identical error behavior (throw on failure, never return null from allocate()) — this is the Liskov Substitution contract every DeviceBackend implementation is held to.

Constructor & Destructor Documentation

◆ ~DeviceBackend()

virtual pulsatrix::DeviceBackend::~DeviceBackend ( )
virtualdefault

Member Function Documentation

◆ accumulate_parts()

virtual void pulsatrix::DeviceBackend::accumulate_parts ( const float *  parts,
size_t  count,
size_t  n,
float *  acc 
)
inlinevirtual

acc += parts[0], then += parts[1], ... (count blocks of n floats, in order): the sums accumulating one gradient per example gave, one add() each (HIP-6).

Note
The default is those add() calls; GPU backends do it in one launch, each element adding the parts in the same order.

Reimplemented in pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ accumulate_rows()

virtual void pulsatrix::DeviceBackend::accumulate_rows ( const float *  in,
float *  out,
size_t  rows,
size_t  cols 
)
pure virtual

out[j] += in[i][j] for i = 0..rows-1 in order, accumulating straight into out.

Note
Unlike column_sums(beta = 1), which adds a finished column sum to out, this adds row by row into the running value – the association the recurrent modules' bias gradients always used.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ adam_step()

virtual void pulsatrix::DeviceBackend::adam_step ( float *  param,
const float *  grad,
float *  m,
float *  v,
size_t  n,
float  lr,
float  beta1,
float  beta2,
float  eps,
float  bias_correction1,
float  bias_correction2 
)
pure virtual

One fused Adam update over n parameters.

Parameters
bias_correction11 - beta1^t, computed once on the host per step.
bias_correction21 - beta2^t, likewise.
Note
Same per-element expression order as the pre-campaign AdamOptimizer host loop: m = b1*m + (1-b1)*g; v = b2*v + (1-b2)*g*g; p -= lr * (m/bc1) / (sqrt(v/bc2) + eps).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ adam_step_multi()

virtual void pulsatrix::DeviceBackend::adam_step_multi ( const AdamTensorStep *  tensors,
size_t  count,
float  beta1,
float  beta2,
float  eps 
)
inlinevirtual

Adam (or AdamW, or Adam with L2 decay) over many parameter tensors at once (HIP-6). Each tensor gets exactly what axpby() then adam_step() would do: the decay decay * param (beta 0), or the step on l2 * param + 1 * grad.

Note
The default runs those per-tensor calls. GPU backends override it with a single launch over every tensor, so an optimizer step costs one kernel and one small upload.

Reimplemented in pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ add()

virtual void pulsatrix::DeviceBackend::add ( const float *  a,
const float *  b,
float *  out,
size_t  n 
)
pure virtual

Elementwise binary addition: out[i] = a[i] + b[i] for i in [0, n).

Parameters
aFirst operand, must hold at least n floats.
bSecond operand, must hold at least n floats.
outOutput buffer, must hold at least n floats. May alias a or b for an in-place accumulation.
nNumber of elements.
Note
A separate method from elementwise() rather than extending ElementwiseOp with a binary case – see ElementwiseOp's own
. Added in Mission 3 (Phase 0 autograd) specifically because gradient accumulation (multiple children contributing to a shared parent's gradient) needs it; this is the resolution of the binary-op design decision deferred since Mission 0.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ add_channel_vector()

virtual void pulsatrix::DeviceBackend::add_channel_vector ( const float *  in,
const float *  vec,
float *  out,
size_t  n,
size_t  c,
size_t  inner 
)
pure virtual

out[i][ch][k] = in[i][ch][k] + vec[ch] over (n, c, inner). out may alias in.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ add_row_vector()

virtual void pulsatrix::DeviceBackend::add_row_vector ( const float *  in,
const float *  row,
float *  out,
size_t  rows,
size_t  cols 
)
pure virtual

Broadcast row add: out[i][j] = in[i][j] + row[j] for a (rows x cols) matrix.

Note
out may alias in.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ add_row_vector_relu()

virtual void pulsatrix::DeviceBackend::add_row_vector_relu ( const float *  in,
const float *  row,
float *  z,
float *  out,
size_t  rows,
size_t  cols 
)
inlinevirtual

add_row_vector() into z, then ReLU of z into out: a Linear layer's bias and the ReLU after it (HIP-6). Both are written, since the ReLU's backward and LRP read z.

Note
The default is those two calls; GPU backends do both in one launch with the same arithmetic, so the values are identical.

Reimplemented in pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ aggregator_backward()

virtual void pulsatrix::DeviceBackend::aggregator_backward ( const float *  x,
const float *  mean_pow,
const float *  grad_out,
float *  grad_in,
size_t  n,
size_t  cols,
float  p 
)
pure virtual

AggregatorModule input gradient, per column.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ aggregator_forward()

virtual void pulsatrix::DeviceBackend::aggregator_forward ( const float *  x,
float *  mean_pow,
float *  out,
size_t  n,
size_t  cols,
float  p 
)
pure virtual

AggregatorModule power mean over the leading axis of an (n, cols) input, per column.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ aggregator_lrp()

virtual void pulsatrix::DeviceBackend::aggregator_lrp ( const float *  x,
const float *  mean_pow,
const float *  r_out,
float *  r_in,
size_t  n,
size_t  cols,
float  p,
float  eps 
)
pure virtual

◆ allocate()

virtual void * pulsatrix::DeviceBackend::allocate ( size_t  bytes)
pure virtual

Allocates a buffer of the given size.

Parameters
bytesNumber of bytes to allocate. A request of 0 bytes returns nullptr by convention (not an error) — there is nothing to allocate.
Returns
Pointer to the allocated buffer, or nullptr iff bytes == 0.
Exceptions
std::runtime_errorif a nonzero-size allocation fails. Never silently returns nullptr for a nonzero request.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ attention_mask_fill()

virtual void pulsatrix::DeviceBackend::attention_mask_fill ( float *  scores,
const float *  key_keep,
size_t  batch,
size_t  heads,
size_t  q_len,
size_t  k_len,
bool  causal,
size_t  q_offset,
size_t  window,
float  value 
)
pure virtual

Overwrites the masked entries of (batch, heads, q_len, k_len) attention scores with value, in place (LLM-1).

Parameters
key_keep(batch, k_len): 0 masks that key for every query and head, anything else keeps it. nullptr masks no key.
causalAlso masks key j for query i when j > i + q_offset.
q_offsetAbsolute position of query 0 among the keys (0 unless a cache holds earlier keys).
windowWith causal, a sliding window (LLM-9): also masks key j for query i when j + window <= i + q_offset, so each query sees its last window positions, itself included (Hugging Face's kv_idx > q_idx - sliding_window). 0 is no window.
Note
Attention calls it three times per pass: value = lowest float on the scores before softmax, and value = 0 on the score gradient and on the score relevance.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ avg_pool_backward()

virtual void pulsatrix::DeviceBackend::avg_pool_backward ( const float *  grad_out,
float *  grad_in,
size_t  planes,
size_t  h,
size_t  w,
size_t  kh,
size_t  kw 
)
pure virtual

Spreads grad_out / (kh*kw) over each window; grad_in must be zeroed by the caller.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ avg_pool_forward()

virtual void pulsatrix::DeviceBackend::avg_pool_forward ( const float *  in,
float *  out,
size_t  planes,
size_t  h,
size_t  w,
size_t  kh,
size_t  kw 
)
pure virtual

Non-overlapping average pool over planes of (h, w).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ axpby()

virtual void pulsatrix::DeviceBackend::axpby ( float  alpha,
const float *  x,
float  beta,
const float *  y,
float *  out,
size_t  n 
)
pure virtual

out[i] = alpha * x[i] + beta * y[i]. out may alias x or y.

Note
beta == 0 does not read y (BLAS convention), so out = alpha * x exactly even where y holds inf/NaN – otherwise 0 * inf would turn a scale-only call into NaN.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ batch_norm_backward()

virtual void pulsatrix::DeviceBackend::batch_norm_backward ( const float *  grad_out,
const float *  gamma,
const float *  xhat,
const float *  channel_std,
float *  grad_in,
float *  gamma_grad,
float *  beta_grad,
size_t  n,
size_t  c,
size_t  spatial 
)
pure virtual

BatchNorm input gradient plus this call's gamma/beta gradients (overwritten, per channel).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ batch_norm_eval_backward()

virtual void pulsatrix::DeviceBackend::batch_norm_eval_backward ( const float *  grad_out,
const float *  gamma,
const float *  xhat,
const float *  channel_std,
float *  grad_in,
float *  gamma_grad,
float *  beta_grad,
size_t  n,
size_t  c,
size_t  spatial 
)
pure virtual

Eval-mode BatchNorm gradient: grad_out * gamma / std, plus gamma/beta gradients (overwritten, per channel). FND-5.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ batch_norm_eval_forward()

virtual void pulsatrix::DeviceBackend::batch_norm_eval_forward ( const float *  in,
const float *  gamma,
const float *  beta,
const float *  running_mean,
const float *  running_var,
float *  xhat,
float *  out,
float *  channel_std,
size_t  n,
size_t  c,
size_t  spatial,
float  eps 
)
pure virtual

Eval-mode BatchNorm from the running statistics: a per-channel affine map. FND-5.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ batch_norm_forward()

virtual void pulsatrix::DeviceBackend::batch_norm_forward ( const float *  in,
const float *  gamma,
const float *  beta,
float *  xhat,
float *  out,
float *  channel_std,
size_t  n,
size_t  c,
size_t  spatial,
float  eps 
)
pure virtual

BatchNorm over (n, spatial) per channel of (n, c, spatial) data.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ batch_norm_update_running()

virtual void pulsatrix::DeviceBackend::batch_norm_update_running ( const float *  in,
float *  running_mean,
float *  running_var,
size_t  n,
size_t  c,
size_t  spatial,
float  momentum 
)
pure virtual

Folds this batch's per-channel mean and unbiased variance into the running ones (PyTorch's momentum rule; the variance is kept when a channel has one value). FND-5.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ bce_with_logits()

virtual void pulsatrix::DeviceBackend::bce_with_logits ( const float *  logits,
const float *  target,
float *  out,
size_t  n 
)
pure virtual

Per-element binary cross-entropy with logits: out[i] = max(x, 0) - x*y + log1p(exp(-|x|)), x = logits[i], y = target[i].

Note
Fused rather than composed from elementwise ops: this exact evaluation order is what BCEWithLogitsLoss has always computed, and no composition reproduces its rounding.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ bce_with_logits_grad()

virtual void pulsatrix::DeviceBackend::bce_with_logits_grad ( const float *  logits,
const float *  target,
float *  grad,
size_t  n,
float  scale 
)
pure virtual

BCE-with-logits gradient: grad[i] = (sigmoid(x) - y) * scale, using the overflow-free sigmoid (exp(x) / (1 + exp(x)) for x < 0).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ col2im_add()

virtual void pulsatrix::DeviceBackend::col2im_add ( const float *  col,
float *  out,
size_t  n,
size_t  c,
size_t  h,
size_t  w,
const ConvGeometry &  geometry 
)
pure virtual

Folds (n, c*kh*kw, out_h*out_w) patches back, adding into out (n, c, h, w).

Note
A gather: one GPU thread per output pixel sums its window contributions in the same order the CPU scatter loop adds them – deterministic, no atomics.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ column_sums()

virtual void pulsatrix::DeviceBackend::column_sums ( const float *  in,
float *  out,
size_t  rows,
size_t  cols,
float  beta 
)
pure virtual

Per-column sum of a (rows x cols) row-major matrix: out[j] = beta*out[j] + sum_i in[i][j].

Note
Rows are summed in increasing i on every backend. out must not alias in.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ copy()

virtual void pulsatrix::DeviceBackend::copy ( void *  dst,
const void *  src,
size_t  bytes,
CopyDirection  dir 
)
pure virtual

Copies bytes between buffers.

Parameters
dstDestination buffer, must be large enough to hold bytes.
srcSource buffer.
bytesNumber of bytes to copy.
dirDirection of the copy (informs device-specific implementations which memory space each pointer lives in; CPUBackend ignores it).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ copy_2d()

virtual void pulsatrix::DeviceBackend::copy_2d ( float *  dst,
size_t  dst_stride,
const float *  src,
size_t  src_stride,
size_t  rows,
size_t  cols 
)
pure virtual

Strided 2-D copy: rows of cols floats from src (row stride src_stride) to dst (row stride dst_stride) – e.g. one timestep of an (N, L, D) sequence.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ device()

virtual DeviceType pulsatrix::DeviceBackend::device ( ) const
pure virtualnoexcept

Which device this backend's buffers reside on.

Note
Tensor's constructors that take no explicit DeviceType tag the Tensor with this, so a temporary allocated through a CUDA/HIP backend can no longer be silently labelled Cpu (the default-tag defect found by the GPU-native-kernels campaign recon: a mislabelled tensor makes Tensor pick HostToHost copies on device memory and lets host-only guards pass).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ dot()

virtual float pulsatrix::DeviceBackend::dot ( const float *  a,
const float *  b,
size_t  n 
)
pure virtual

Dot product sum_i a[i]*b[i], returned to the host.

Note
Synchronizes. Fixed-order reduction on every backend, but GPU order differs from CPU's sequential sum, so CPU and GPU agree to rounding, not bitwise.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ dot_into()

virtual void pulsatrix::DeviceBackend::dot_into ( const float *  a,
const float *  b,
size_t  n,
float *  out 
)
inlinevirtual

dot() written to out, one float in this backend's memory, instead of returned (HIP-6). Same value as dot(). A GPU backend doesn't wait for it, so many dots cost one read back instead of one each.

Reimplemented in pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ dropout_forward()

virtual void pulsatrix::DeviceBackend::dropout_forward ( const float *  in,
float *  out,
float *  mask,
size_t  n,
float  p,
float  scale,
uint64_t  seed,
uint64_t  offset 
)
pure virtual

Inverted dropout with a counter-based RNG: element i is dropped iff uniform(seed, offset + i) < p; kept elements are scaled by scale.

Parameters
maskReceives 1.0 (kept) or 0.0 (dropped) per element, for backward().
Note
uniform(seed, k) is splitmix64(seed + (k + 1) * golden_gamma), top 24 bits as a float in [0, 1). Stateless and identical on every backend, so a GPU mask is bit-identical to the CPU one for the same (seed, offset) – the property that lets Dropout be tested CPU-vs-GPU at all. A dropped element is written as 0 (a select, not in * 0), so an inf/NaN input there still yields 0.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ elementwise()

virtual void pulsatrix::DeviceBackend::elementwise ( ElementwiseOp  op,
const float *  in,
float *  out,
size_t  n 
)
pure virtual

Applies a unary elementwise operation to every element of a buffer.

Parameters
opOperation to apply.
inInput buffer, must hold at least n floats.
outOutput buffer, must hold at least n floats. May alias in for an in-place application.
nNumber of elements.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ elementwise_backward()

virtual void pulsatrix::DeviceBackend::elementwise_backward ( ElementwiseOp  op,
const float *  x,
const float *  grad_out,
float *  grad_in,
size_t  n 
)
pure virtual

Activation backward: grad_in[i] = grad_out[i] * f'(x[i]), f = op, x = the forward input.

Note
Derivatives: Relu selects grad_out where x > 0, else 0 (0 at x == 0 and for a non-finite grad_out, matching ReluModule); Neg -1; Tanh 1 - tanh(x)^2; Sigmoid s(1 - s); Silu s + x*s*(1 - s), s = sigmoid(x); Exp exp(x). grad_in may alias grad_out or x.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ fill()

virtual void pulsatrix::DeviceBackend::fill ( void *  ptr,
float  value,
size_t  n 
)
pure virtual

Fills every element of a float buffer with a constant value.

Parameters
ptrBuffer to fill, must hold at least n floats.
valueFill value.
nNumber of elements to fill.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ free()

virtual void pulsatrix::DeviceBackend::free ( void *  ptr)
pure virtualnoexcept

Frees a buffer previously returned by allocate(). Safe to call with nullptr.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ gather_rows()

virtual void pulsatrix::DeviceBackend::gather_rows ( const float *  table,
const float *  indices,
float *  out,
size_t  count,
size_t  dim 
)
pure virtual

out[i][:] = table[indices[i]][:] for count rows of width dim.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ gemm()

virtual void pulsatrix::DeviceBackend::gemm ( const float *  a,
const float *  b,
float *  out,
size_t  m,
size_t  k,
size_t  n 
)
pure virtual

Row-major matrix multiply: out = a * b.

Parameters
aPointer to A (m x k), row-major.
bPointer to B (k x n), row-major.
outPointer to the output buffer (m x n), row-major. Must be pre-allocated by the caller.
mRows of A / rows of out.
kColumns of A / rows of B.
nColumns of B / columns of out.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ gemm_ex()

virtual void pulsatrix::DeviceBackend::gemm_ex ( const float *  a,
bool  transpose_a,
const float *  b,
bool  transpose_b,
float *  out,
size_t  m,
size_t  k,
size_t  n,
float  beta 
)
pure virtual

General row-major matrix multiply: out = op(A) * op(B) + beta * out.

Parameters
aA, stored (m x k) row-major, or (k x m) when transpose_a.
transpose_aUse A^T.
bB, stored (k x n) row-major, or (n x k) when transpose_b.
transpose_bUse B^T.
out(m x n) row-major. Read only when beta != 0 (beta == 0 overwrites, so out may hold garbage). Must not alias a or b.
betaScale on the existing out; 1 accumulates (gradient accumulation).
Note
Replaces the explicit host-side transpose() copies modules built to feed gemm().

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ gemm_strided_batched()

virtual void pulsatrix::DeviceBackend::gemm_strided_batched ( const float *  a,
bool  transpose_a,
size_t  stride_a,
const float *  b,
bool  transpose_b,
size_t  stride_b,
float *  out,
size_t  stride_out,
size_t  m,
size_t  k,
size_t  n,
size_t  batch,
float  beta = 0.0f 
)
inlinevirtual

batch independent gemm_ex() products, out_i = op(A_i) op(B_i) (+ beta out_i), with A_i = a + i * stride_a and likewise for b and out; a stride of 0 shares one matrix (HIP-6: a convolution's kernel against every example's patches).

Note
The default makes the batch's calls one by one (gemm() when nothing is transposed and beta is 0, as the callers did before), so its results are those calls'. GPU backends override it with one strided-batched BLAS call.

Reimplemented in pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ group_norm_backward()

virtual void pulsatrix::DeviceBackend::group_norm_backward ( const float *  grad_out,
const float *  gamma,
const float *  xhat,
const float *  group_std,
float *  grad_in,
float *  gamma_grad,
float *  beta_grad,
size_t  n,
size_t  c,
size_t  spatial,
size_t  num_groups 
)
pure virtual

GroupNorm input gradient plus this call's gamma/beta gradients (overwritten, per channel).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ group_norm_forward()

virtual void pulsatrix::DeviceBackend::group_norm_forward ( const float *  in,
const float *  gamma,
const float *  beta,
float *  xhat,
float *  out,
float *  group_std,
size_t  n,
size_t  c,
size_t  spatial,
size_t  num_groups,
float  eps 
)
pure virtual

GroupNorm per (example, group) of (n, c, spatial) data; group_std is (n, num_groups).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ gru_lrp_hprev()

virtual void pulsatrix::DeviceBackend::gru_lrp_hprev ( const float *  h_prev,
const float *  w_hn,
const float *  hn,
const float *  r_term_b,
const float *  direct,
float *  r_hprev,
size_t  rows,
size_t  hidden,
float  eps 
)
pure virtual

GRU's R_hprev for (rows, hidden): the recurrent epsilon-rule sum through W_hn, with each element's direct term inserted where the original loop added it.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ im2col()

virtual void pulsatrix::DeviceBackend::im2col ( const float *  in,
float *  col,
size_t  n,
size_t  c,
size_t  h,
size_t  w,
const ConvGeometry &  geometry 
)
pure virtual

Unfolds (n, c, h, w) into (n, c*kh*kw, out_h*out_w) patches, with out_h = (h + 2*pad_h - kh) / stride_h + 1 (likewise out_w). Taps that fall in the zero padding read 0.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ layer_norm_backward()

virtual void pulsatrix::DeviceBackend::layer_norm_backward ( const float *  grad_out,
const float *  gamma,
const float *  xhat,
const float *  row_std,
float *  grad_in,
size_t  rows,
size_t  cols 
)
pure virtual

LayerNorm input gradient per row, from the cached xhat and per-row std.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ layer_norm_forward()

virtual void pulsatrix::DeviceBackend::layer_norm_forward ( const float *  in,
const float *  gamma,
const float *  beta,
float *  xhat,
float *  out,
float *  row_std,
size_t  rows,
size_t  cols,
float  eps 
)
pure virtual

LayerNorm forward per row: xhat = (x - mean)/sqrt(var + eps), out = gamma*xhat + beta.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ logic_pointwise()

virtual void pulsatrix::DeviceBackend::logic_pointwise ( LogicOp  op,
int  norm,
const float *  a,
const float *  b,
const float *  g_or_r,
const float *  y,
float *  out_a,
float *  out_b,
size_t  n,
float  eps 
)
pure virtual

One elementwise pass of Conjunction/Disjunction for operands a, b.

Parameters
g_or_rUpstream gradient (Backward) or relevance (Lrp); unused by Forward.
yCached forward output (Lrp only).
out_aForward: the output. Backward/Lrp: a's gradient/relevance.
out_bBackward/Lrp: b's gradient/relevance; unused by Forward.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ logsumexp_rows()

virtual void pulsatrix::DeviceBackend::logsumexp_rows ( const float *  in,
float *  out,
size_t  rows,
size_t  cols 
)
pure virtual

Per-row log-sum-exp, max-subtracted: out[i] = log sum_j exp(in[i][j]).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ lrp_avg_pool()

virtual void pulsatrix::DeviceBackend::lrp_avg_pool ( const float *  x,
const float *  r,
float *  r_in,
size_t  planes,
size_t  h,
size_t  w,
size_t  kh,
size_t  kw,
float  eps 
)
pure virtual

AvgPool2D epsilon rule; r_in must be zeroed by the caller.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ lrp_bilinear_elementwise()

virtual void pulsatrix::DeviceBackend::lrp_bilinear_elementwise ( const float *  a,
const float *  b,
const float *  r,
float *  r_out,
size_t  n,
float  eps 
)
pure virtual

Eq. 15 for an elementwise product c = a*b: r_out = (a b / (2c + eps sign c)) r (same for both).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ lrp_bilinear_matmul()

virtual void pulsatrix::DeviceBackend::lrp_bilinear_matmul ( const float *  a,
const float *  b,
const float *  o,
const float *  r_o,
float *  r_a,
float *  r_b,
size_t  slices,
size_t  m,
size_t  p,
size_t  q,
float  eps,
bool  b_transposed 
)
pure virtual

Eq. 15 for slices independent matmuls O = A @ B (A (M x P), B (P x Q), O and r_o (M x Q)).

Parameters
b_transposedB is stored as B^T (Q x P); r_b is then written in that same layout.
Note
r_a and r_b are overwritten (not accumulated into).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ lrp_conv()

virtual void pulsatrix::DeviceBackend::lrp_conv ( const float *  col,
const float *  kernel,
const float *  pre_bias,
const float *  r,
float *  r_col,
size_t  n,
size_t  out_channels,
size_t  p,
size_t  q,
float  eps 
)
pure virtual

Conv2D epsilon rule in patch space: r_col (n, p, q) from the cached patches, the kernel (out_channels, p) and the pre-bias outputs (n, out_channels, q).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ lrp_linear()

virtual void pulsatrix::DeviceBackend::lrp_linear ( const float *  x,
const float *  w,
const float *  z,
const float *  r,
float *  r_in,
size_t  rows,
size_t  in_features,
size_t  out_features,
float  eps 
)
pure virtual

LinearModule epsilon rule: r_in[n][i] = sum_j (x[n][i] w[i][j] / stab(z[n][j])) r[n][j].

Parameters
z(N, out) pre-bias outputs; w (in, out); x, r_in (N, in); r (N, out).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ lrp_residual_split()

virtual void pulsatrix::DeviceBackend::lrp_residual_split ( const float *  a,
const float *  b,
const float *  r,
float *  r_a,
float *  r_b,
size_t  n,
float  eps 
)
pure virtual

Epsilon split of a residual sum y = a + b: r_a = (a / stab(y)) r, r_b = (b / stab(y)) r.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ lrp_rope()

virtual void pulsatrix::DeviceBackend::lrp_rope ( const float *  x,
const float *  y,
const float *  r,
const float *  cos_table,
const float *  sin_table,
float *  r_in,
size_t  slices,
size_t  seq_len,
size_t  head_dim,
float  eps,
bool  rotate_half 
)
pure virtual

RoPEModule epsilon rule over (slices, seq_len, head_dim), tables as for rope_rotate.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ lrp_softmax_rows()

virtual void pulsatrix::DeviceBackend::lrp_softmax_rows ( const float *  x,
const float *  y,
const float *  r,
float *  r_in,
size_t  rows,
size_t  cols 
)
pure virtual

SoftmaxModule rule per row: r_in = x * (r - y * sum(r)).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ lrp_stabilized_divide()

virtual void pulsatrix::DeviceBackend::lrp_stabilized_divide ( const float *  r,
const float *  denom,
const float *  gate,
float *  out,
size_t  n,
float  eps,
LrpGate  gate_mode 
)
pure virtual

Gated stabilized division, the one non-gemm step of the affine LRP rules: out[i] = passes(gate[i]) ? r[i] / (denom[i] + eps sign(denom[i])) : 0, sign(0) = +1.

Parameters
gateRead only when gate_mode != LrpGate::None (may then be nullptr).
Note
out may alias r or denom.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ max_pool_forward()

virtual void pulsatrix::DeviceBackend::max_pool_forward ( const float *  in,
float *  out,
float *  argmax,
size_t  planes,
size_t  h,
size_t  w,
size_t  kh,
size_t  kw,
size_t  sh,
size_t  sw,
size_t  ph,
size_t  pw 
)
pure virtual

Max pool over planes of (h, w) with a (kh, kw) window, stride (sh, sw) and padding (ph, pw); padded positions never win. Output (planes, out_h, out_w) with out = (n + 2 pad - k) / stride + 1. argmax = flat in-plane input index (first max wins).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ max_unpool()

virtual void pulsatrix::DeviceBackend::max_unpool ( const float *  src,
const float *  argmax,
float *  dst,
size_t  planes,
size_t  h,
size_t  w,
size_t  kh,
size_t  kw,
size_t  sh,
size_t  sw,
size_t  ph,
size_t  pw 
)
pure virtual

The inverse routing: each input position gets the sum of the pooled values whose argmax it is (windows may overlap). dst (planes, h, w) is overwritten.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ mul()

virtual void pulsatrix::DeviceBackend::mul ( const float *  a,
const float *  b,
float *  out,
size_t  n 
)
pure virtual

Elementwise binary (Hadamard) multiplication: out[i] = a[i] * b[i] for i in [0, n).

Parameters
aFirst operand, must hold at least n floats.
bSecond operand, must hold at least n floats.
outOutput buffer, must hold at least n floats. May alias a or b for an in-place application.
nNumber of elements.
Note
Added in Phase 6's SwiGLU mission (mission_swiglu.md) – the third consumer needing a Hadamard product via a raw host loop (after LSTMModule's/GRUModule's gate arithmetic), the trigger point the Risk Register named for finally adding this primitive properly instead of a fourth raw loop. LSTMModule/GRUModule's existing raw loops are not retrofitted to use it – no behavior change needed there, logged as a low-priority future cleanup only.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ permute_0213()

virtual void pulsatrix::DeviceBackend::permute_0213 ( const float *  in,
float *  out,
size_t  d0,
size_t  d1,
size_t  d2,
size_t  d3 
)
pure virtual

Swaps the middle two axes: in (d0, d1, d2, d3) -> out (d0, d2, d1, d3).

Note
Attention's head split ((N, L, H, D) -> (N, H, L, D)) and merge (the reverse) are both this permutation. out must not alias in.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ recurrent_cell()

virtual void pulsatrix::DeviceBackend::recurrent_cell ( RecurrentCellOp  op,
const RecurrentCellArgs &  args,
size_t  n 
)
pure virtual

One fused recurrent-cell pass over n elements (see RecurrentCellOp for slots).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ rl_rows()

virtual void pulsatrix::DeviceBackend::rl_rows ( RlRowOp  op,
const RlRowArgs &  args 
)
pure virtual

One fused RL loss / target / Polyak pass (see RlRowOp for lanes and slots).

Note
One lane per row: a row's softmax, argmax and gradient writes are owned by its lane and walk the columns in the original loop order. Per-row loss terms are reduced by the caller with column_sums, which adds rows in increasing order like the original loop.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ rms_norm_backward()

virtual void pulsatrix::DeviceBackend::rms_norm_backward ( const float *  grad_out,
const float *  gamma,
const float *  in,
const float *  row_rms,
float *  grad_in,
float *  gamma_terms,
size_t  rows,
size_t  cols 
)
pure virtual

RMSNorm input gradient per row, plus gamma_terms[r][i] = grad_out * x / rms – the per-row contributions column_sums then reduces into gamma's gradient.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ rms_norm_forward()

virtual void pulsatrix::DeviceBackend::rms_norm_forward ( const float *  in,
const float *  gamma,
float *  out,
float *  row_rms,
size_t  rows,
size_t  cols,
float  eps 
)
pure virtual

RMSNorm forward per row: out = gamma * x / sqrt(mean(x^2) + eps).

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ rope_rotate()

virtual void pulsatrix::DeviceBackend::rope_rotate ( const float *  in,
const float *  cos_table,
const float *  sin_table,
float *  out,
size_t  num_slices,
size_t  seq_len,
size_t  head_dim,
bool  inverse,
bool  rotate_half 
)
pure virtual

Rotary position embedding over (num_slices, seq_len, head_dim) data.

Parameters
cos_table,sin_table(seq_len, head_dim/2) per-position rotation tables.
inversefalse: forward rotation; true: its transpose (RoPE's backward).
rotate_halffalse: pair i is features (2i, 2i+1). true: pair i is (i, i + head_dim/2), the Hugging Face "rotate half" layout (LLM-1).
Note
out must not alias in.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ scatter_add_rows()

virtual void pulsatrix::DeviceBackend::scatter_add_rows ( const float *  src,
const float *  indices,
float *  table,
size_t  count,
size_t  dim 
)
pure virtual

table[indices[i]][:] += src[i][:] for i = 0..count-1, in increasing i.

Note
Deterministic: the GPU kernel runs one thread per column and walks i in order – repeated indices accumulate in the same order as the CPU, no atomics.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ softmax_rows()

virtual void pulsatrix::DeviceBackend::softmax_rows ( const float *  in,
float *  out,
size_t  rows,
size_t  cols 
)
pure virtual

Row-wise softmax of a (rows x cols) matrix, max-subtracted. out may alias in.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ softmax_rows_backward()

virtual void pulsatrix::DeviceBackend::softmax_rows_backward ( const float *  y,
const float *  dy,
float *  dx,
size_t  rows,
size_t  cols 
)
pure virtual

Softmax backward from its output y: dx[i][j] = y[i][j] * (dy[i][j] - sum_k y[i][k]*dy[i][k]).

Note
dx must not alias y or dy.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ ssm_pass()

virtual void pulsatrix::DeviceBackend::ssm_pass ( SsmPassOp  op,
const SsmPassArgs &  args 
)
pure virtual

One fused Mamba / RWKV / RetNet pass (see SsmPassOp for lanes and slots).

Note
Recurrences run one lane per independent (batch, channel[, state]) sequence, walking time in order inside the lane – parallel over lanes, sequential over time, the CPU's order. Every reduction is owned by one lane and summed in the original loop order.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ sum()

virtual float pulsatrix::DeviceBackend::sum ( const float *  in,
size_t  n 
)
pure virtual

sum_i in[i], returned to the host. Same reduction order as dot(). Synchronizes.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ tanh_gaussian_backward()

virtual void pulsatrix::DeviceBackend::tanh_gaussian_backward ( const float *  action,
const float *  std_cache,
const float *  eps,
const float *  grad_action,
const float *  grad_log_prob,
float *  grad_mean,
float *  grad_log_std,
size_t  n,
float  stabilizer 
)
pure virtual

TanhGaussianPolicy gradients w.r.t. mean and log_std, per element.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ tanh_gaussian_forward()

virtual void pulsatrix::DeviceBackend::tanh_gaussian_forward ( const float *  mean,
const float *  log_std,
const float *  eps,
float *  action,
float *  std_cache,
float *  log_prob,
size_t  rows,
size_t  cols,
float  stabilizer,
double  half_log_two_pi 
)
pure virtual

TanhGaussianPolicy sampling per (rows, cols) row: action = tanh(mean + exp(log_std)*eps), std_cache = exp(log_std), log_prob[r] accumulated in double.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.

◆ top_k_rows()

virtual void pulsatrix::DeviceBackend::top_k_rows ( const float *  in,
float *  values,
float *  indices,
size_t  rows,
size_t  cols,
size_t  k,
bool  largest 
)
pure virtual

Per row of a row-major (rows, cols) matrix: the k largest (or smallest) values in rank order into values (rows, k), and their column indices into indices (rows, k) as whole-number floats.

Note
Order: NaN ranks above every number; equal values keep the lower column index first. One lane per row, pure selection: every backend's output is bit-identical.
Preconditions, validated by the caller (top_k()): 1 <= k <= cols, cols <= 2^24.

Implemented in pulsatrix::CPUBackend, pulsatrix::CUDABackend, and pulsatrix::HIPBackend.


The documentation for this class was generated from the following file: