class

`SushiAI::Graph::GraphBuilder`

Emits shape-checked IR nodes into a Graph.

Declared in: include/SushiAI/graph/builder.hpp

Public member functions

explicit GraphBuilder(Graph &graph) noexcept

Wraps graph for emission.

Parameters

graph: The graph to append to; must outlive this builder.

Graph & graph() const noexcept

The graph being built.

ValueId input(Shape shape, std::string_view debug_name, DType dtype=DType::FLOAT32) const

Declares a minibatch input: a leaf rewritten every step.

Parameters

shape: The value's extents.
debug_name: A label for diagnostics; must outlive the graph.
dtype: The element type.

Returns

The new value's id.

ValueId parameter(Shape shape, std::string_view debug_name, DType dtype=DType::FLOAT32) const

Declares a learnable parameter: a leaf that needs a gradient.

Parameters

shape: The value's extents.
debug_name: A label for diagnostics; must outlive the graph.
dtype: The element type.

Returns

The new value's id.

ValueId matmul(ValueId a, ValueId b, bool transpose_a=false, bool transpose_b=false) const

Emits MATMUL: C = op(A) * op(B).

Parameters

a: Left operand matrix.
b: Right operand matrix.
transpose_a: Whether to transpose a.
transpose_b: Whether to transpose b.

Returns

The product value id.

ValueId bias_add(ValueId x, ValueId bias) const

Emits BIAS_ADD: Y = X + 1 * bias^T, over an [N, C] X.

Parameters

x: The [N, C] matrix.
bias: The [C] row added to every row of x.

Returns

The sum's id.

Exceptions

Error: If the ranks or extents do not line up.

ValueId sum_rows(ValueId x) const

Emits SUM_ROWS: the column sums of an [N, C] matrix.

Parameters

x: The [N, C] matrix.

Returns

The [C] result's id.

Exceptions

Error: If x is not rank 2.

ValueId add(ValueId a, ValueId b) const

Emits ADD: elementwise A + B.

Exceptions

Error: on mismatch.

ValueId sub(ValueId a, ValueId b) const

Emits SUB: elementwise A - B.

Exceptions

Error: on mismatch.

ValueId mul(ValueId a, ValueId b) const

Emits MUL: elementwise A * B.

Exceptions

Error: on mismatch.

ValueId div(ValueId a, ValueId b) const

Emits DIV: elementwise a / b.

Parameters

a: The dividend.
b: The divisor; must share the shape and dtype of a.

Returns

The quotient, shaped and laid out like a.

ValueId minimum(ValueId a, ValueId b) const

Emits MINIMUM: the elementwise smaller of a and b.

Parameters

b: Must share the shape and dtype of a.

Returns

The minimum, shaped and laid out like a.

ValueId maximum(ValueId a, ValueId b) const

Emits MAXIMUM: the elementwise larger of a and b.

Parameters

b: Must share the shape and dtype of a.

Returns

The maximum, shaped and laid out like a.

ValueId less_equal(ValueId a, ValueId b) const

Emits LESS_EQUAL: 1 where a <= b and 0 elsewhere.

Parameters

b: Must share the shape and dtype of a.

Returns

The mask, in the shape, dtype and layout of a.

ValueId select(ValueId condition, ValueId a, ValueId b) const

Emits SELECT: a where the condition is non-zero, b elsewhere.

Parameters

condition: A mask holding 0 or 1, in the shape and dtype of a.
b: Must share the shape and dtype of a.

Returns

The selection, shaped and laid out like a.

ValueId scale(ValueId x, double alpha) const

Emits SCALE: Y = alpha * X.

Parameters

x: The operand.
alpha: The host-side constant factor.

Returns

The scaled value's id.

ValueId dynamic_scale(ValueId x, ValueId factor, std::string_view debug_name="dynamic_scale") const

Emits DYNAMIC_SCALE: Y = X * S[0] with S in device memory.

Parameters

x: The tensor to scale.
factor: A 1-element value holding the factor.
debug_name: Diagnostic label for the operation.

Returns

The scaled value id.

Exceptions

Error: If factor is not 1 element or dtypes mismatch.

ValueId exp(ValueId x) const

Emits EXP: elementwise exp(X), out of place.

ValueId abs(ValueId x) const

Emits ABS: elementwise |x|, out of place.

ValueId atan(ValueId x) const

Emits ATAN: elementwise arctangent of x, out of place.

ValueId softplus(ValueId x) const

Emits SOFTPLUS: elementwise log(1 + exp(x)), out of place.

ValueId zeros(Shape shape, DType dtype=DType::FLOAT32) const

Emits ZERO: a fresh all-zero tensor with no operands.

Parameters

shape: The tensor extents.
dtype: The element data type.

Returns

The new value id.

ValueId zeros_like(ValueId like, Shape shape, DType dtype=DType::FLOAT32) const

Emits ZERO adopting the layout of like.

Parameters

like: Value whose layout the zeros adopt.
shape: The tensor extents.
dtype: The element data type.

Returns

The new value id.

ValueId relu(ValueId x) const

Emits RELU.

ValueId gelu(ValueId x) const

Emits GELU (tanh approximation).

ValueId sigmoid(ValueId x) const

Emits SIGMOID.

ValueId tanh(ValueId x) const

Emits TANH.

ValueId silu(ValueId x) const

Emits SILU: elementwise x * sigmoid(x).

ValueId leaky_relu(ValueId x, double slope) const

Emits LEAKY_RELU with the given negative slope.

Parameters

x: The input tensor.
slope: The negative-side slope; must lie in (0, 1).

Returns

The activated value id.

Exceptions

Error: If slope is outside (0, 1).

ValueId activation_backward(OpID op, ValueId dy, ValueId primal, const Attributes &attributes={}) const

Emits an activation gradient operation.

Parameters

op: The activation backward OpID.
dy: The incoming gradient tensor.
primal: The forward input or forward output tensor.
attributes: Optional attributes such as leaky ReLU slope.

Returns

The gradient value id.

ValueId log_softmax(ValueId x) const

Emits LOG_SOFTMAX over the rows of an [N, C] matrix.

Parameters

x: The logits.

Returns

The [N, C] log-probabilities' id.

Exceptions

Error: If x is not rank 2.

ValueId nll_loss(ValueId log_probs, ValueId one_hot) const

Emits NLL_LOSS: the mean negative log-likelihood.

Parameters

log_probs: An [N, C] value, normally a LOG_SOFTMAX result.
one_hot: An [N, C] one-hot target matrix.

Returns

A 1-element loss value's id.

Exceptions

Error: If the two operands disagree in shape or dtype.

ValueId accumulate(ValueId acc, ValueId delta) const

Emits ACCUMULATE: acc_out = acc + delta into buffer of acc.

Parameters

acc: The buffer accumulated into.
delta: The contribution added.

Returns

The accumulated value id.

Exceptions

Error: If operands disagree in shape or dtype.

ValueId layout_convert(ValueId x, TensorLayout layout) const

Emits LAYOUT_CONVERT to permute between NHWC and NCHW layouts.

Parameters

x: The rank-4 value to convert.
layout: The target tensor layout.

Returns

The converted value id.

Exceptions

Error: If x is not rank 4.

ValueId cast(ValueId x, DType dtype, std::string_view debug_name="cast") const

Emits CAST: a copy of x converted to dtype.

Parameters

x: The value to convert.
dtype: The target element type.
debug_name: Diagnostic label for the operation.

Returns

The converted value id.

Exceptions

Error: If either element type is not a real float.

void cast_into(ValueId source, ValueId destination) const

Emits CAST writing directly into an existing value buffer.

Parameters

source: The value to read.
destination: The value to write; must have no producer yet.

Exceptions

Error: If shapes disagree, non-float dtype, or destination exists.

ValueId like(ValueId like, std::string_view debug_name={}) const

Declares a value with the same shape, dtype and lifetime as like.

Parameters

like: The value to copy the description from.
debug_name: A label for diagnostics; must outlive the graph.

Returns

The new value's id.

ValueId declare_like(ValueId like, Shape shape, DType dtype, Lifetime lifetime, std::string_view debug_name) const

Declares a value inheriting the layout of like.

Parameters

like: Value whose layout the result adopts.
shape: Result extents.
dtype: Result element type.
lifetime: Storage arena lifetime.

Returns

The new value id.

ValueId im2col(ValueId x, const ConvGeometry &g) const

Emits IM2COL: expands convolution windows into matrix rows.

Parameters

x: The [N,H,W,C] input tensor.
g: The window geometry.

Returns

The column matrix value id.

Exceptions

Error: If x is not rank 4 NHWC or window does not fit.

ValueId im2col_with_extents(ValueId x, const ConvGeometry &g, int64_t out_h, int64_t out_w) const

Emits IM2COL with explicit output extents.

Parameters

x: The [N,H,W,C] input tensor.
g: The window geometry.
out_h: Number of window rows; out_w Number of window columns.

Returns

The column matrix value id.

ValueId col2im(ValueId cols, Shape image_shape, const ConvGeometry &g) const

Emits COL2IM: the adjoint operation of IM2COL.

Parameters

cols: The column matrix.
image_shape: The [N,H,W,C] image shape to reconstruct.
g: The window geometry used during production.

Returns

The image value id.

Exceptions

Error: If shapes, ranks, or implied dimensions mismatch.

ValueId col2im_with_extents(ValueId cols, Shape image_shape, const ConvGeometry &g, int64_t out_h, int64_t out_w) const

Emits COL2IM with explicit window counts.

Parameters

cols: The column matrix.
image_shape: Reconstructed [N,H,W,C] image shape.
g: Window geometry.
out_h: Window rows; out_w Window columns.

Returns

The reconstructed image value id.

ValueId conv2d(ValueId x, ValueId weight, ValueId bias, const ConvGeometry &g) const

Emits a convolution as IM2COL and MATMUL, with symmetric padding assumed.

Parameters

x: The [N,H,W,C_in] input; must be NHWC.
weight: The [C_out,kernel_h,kernel_w,C_in] filters, matching g and x.
bias: The [C_out] bias, or NO_VALUE to add none.
g: The window geometry; a 1x1 unit-stride unpadded one emits no IM2COL.

Returns

The [N,out_h,out_w,C_out] value id.

PoolResult maxpool2d(ValueId x, const ConvGeometry &g) const

Emits MAXPOOL2D, with symmetric padding assumed.

Parameters

x: The [N,H,W,C] input.
g: The window geometry.

Returns

The pooled value and its argmax indices.

Exceptions

Error: If x is not rank 4, not NHWC, or the window does not fit.

PoolResult maxpool2d_with_extents(ValueId x, const ConvGeometry &g, int64_t out_h, int64_t out_w) const

Emits MAXPOOL2D with explicit output extents.

Parameters

x: The [N,H,W,C] input tensor.
g: The window geometry.
out_h: Pooled height; out_w Pooled width.

Returns

The pooled value and argmax indices.

ValueId avgpool2d(ValueId x, const ConvGeometry &g) const

Emits AVGPOOL2D.

Divides by the full window area.

Parameters

x: The [N,H,W,C] input.
g: The window geometry.

Returns

The pooled value's id.

Exceptions

Error: If x is not rank 4, not NHWC, or the window does not fit.

ValueId upsample2d(ValueId x, int64_t scale_h, int64_t scale_w) const

Emits UPSAMPLE2D using nearest-neighbour integer scaling.

Parameters

x: The [N,H,W,C] input tensor.
scale_h: Vertical replication factor; must be positive.
scale_w: Horizontal replication factor; must be positive.

Returns

The upsampled value id.

Exceptions

Error: If x is not rank 4 NHWC or scales are below 1.

ValueId spatial_mean(ValueId x) const

Emits SPATIAL_MEAN: the mean of every [H,W] plane.

Parameters

x: The [N,H,W,C] input.

Returns

The [N,C] result's id.

Exceptions

Error: If x is not rank 4 or not NHWC.

ValueId maxpool2d_backward(ValueId dy, ValueId indices, Shape input_shape, const ConvGeometry &g) const

Emits MAXPOOL2D_BACKWARD routing gradients through argmax indices.

Parameters

dy: The [N,H_o,W_o,C] output gradient.
indices: The INT64 argmax indices tensor.
input_shape: The [N,H,W,C] shape of the pooled input.
g: The window geometry.

Returns

The input gradient value id.

ValueId avgpool2d_backward(ValueId dy, Shape input_shape, const ConvGeometry &g) const

Emits AVGPOOL2D_BACKWARD: spreads each gradient over its window.

Parameters

dy: The [N,H_o,W_o,C] output gradient.
input_shape: The [N,H,W,C] shape of the pooled input.
g: The window geometry the forward used.

Returns

The [N,H,W,C] input gradient's id.

Exceptions

Error: If dy is not rank 4 or not NHWC.

ValueId upsample2d_backward(ValueId dy, Shape input_shape, int64_t scale_h, int64_t scale_w) const

Emits UPSAMPLE2D_BACKWARD summing replicas into source pixels.

Parameters

dy: The output gradient tensor.
input_shape: The input tensor shape.
scale_h: Vertical factor; scale_w Horizontal factor.

Returns

The input gradient value id.

ValueId spatial_mean_backward(ValueId dy, Shape input_shape) const

Emits SPATIAL_MEAN_BACKWARD broadcasting by 1/(H*W).

Parameters

dy: The [N,C] output gradient.
input_shape: The [N,H,W,C] shape averaged over.

Returns

The [N,H,W,C] input gradient value id.

Exceptions

Error: If dy is not rank 2 or input_shape is not rank 4.

ValueId concat_channels(SushiRuntime::span< const ValueId > parts) const

Emits CONCAT_CHANNELS: joins operands along the channel axis.

Parameters

parts: The [N,H,W,C_i] operands, at least one, sharing N, H, W and dtype.

Returns

The [N,H,W,sum(C_i)] result's id.

Exceptions

Error: If parts is empty, any operand is not rank 4 or not NHWC, or the operands disagree on N, H, W or dtype.

ValueId slice_channels(ValueId x, int64_t offset, int64_t count) const

Emits SLICE_CHANNELS extracting a contiguous channel slice.

Parameters

x: The [N,H,W,C] input tensor.
offset: The starting channel index.
count: The number of channels to extract.

Returns

The [N,H,W,count] sliced tensor id.

Exceptions

Error: If range exceeds channels or x is not rank 4 NHWC.

ValueId channel_affine(ValueId x, ValueId gamma, ValueId beta) const

Emits CHANNEL_AFFINE: per-channel Y = gamma * X + beta.

Parameters

x: The [N,H,W,C] input tensor.
gamma: The [C] per-channel scale parameter.
beta: The [C] per-channel shift parameter.

Returns

The [N,H,W,C] affine result id.

Exceptions

Error: If shapes or parameter dimensions mismatch.

ValueId sum_channels(ValueId x) const

Sums an [N,H,W,C] tensor down to [C] per-channel sums.

Parameters

x: The [N,H,W,C] input tensor.

Returns

The [C] per-channel sum value id.

Exceptions

Error: If x is not rank 4 or not NHWC.

BatchNormResult batchnorm2d(ValueId x, ValueId gamma, ValueId beta, double epsilon) const

Emits BATCHNORM2D normalising across N, H, and W dimensions.

Parameters

x: The [N,H,W,C] input tensor.
gamma: The [C] scale; beta The [C] shift.
epsilon: Small constant added to variance; must be positive.

Returns

The normalised value and saved batch statistics.

BatchNormGrads batchnorm2d_backward(ValueId dy, ValueId x, ValueId gamma, ValueId saved_mean, ValueId saved_inv_std) const

Emits BATCHNORM2D_BACKWARD producing dx, dgamma, and dbeta.

Parameters

dy: Output gradient; x Forward input tensor.
gamma: The [C] scale parameter.
saved_mean: The [C] batch mean computed during forward.
saved_inv_std: The [C] inverse standard deviation.

Returns

The input, scale, and shift gradient value ids.

ValueId reshape(ValueId x, Shape shape) const

Emits RESHAPE: a view of x with different extents.

Parameters

x: The value reshaped.
shape: The result's extents.

Returns

The reshaped value's id.

Exceptions

Error: If shape's element count differs from x's.