GraphSpec Vision Primitives

This file extends the sequential GraphSpec core (NN.GraphSpec.Core) with single-input/single-output vision operation adapters used by classic CNN pipelines.

These are not model definitions. They are reusable nodes in the GraphSpec vocabulary:

• Primitive.conv2d wraps Spec.conv2dSpec and Runtime.Autograd.TorchLean.conv2d;
• Primitive.maxPool2d wraps the corresponding Spec/runtime pooling operation;
• Primitive.batchnormChw wraps channel-first BatchNorm;
• Primitive.globalAvgPool2dChw wraps channel-wise global average pooling;
• Primitive.flatten is the bridge from image-like tensors to vector classifiers.

The corresponding model examples live under NN.GraphSpec.Models.

Important scope note:

• These primitives all fit the chain graph language Graph ps σ τ because they have one input tensor and one output tensor (no merging of paths).
• Residual networks require skip connections (y + x), which are multi-input and require sharing. For that, use NN.GraphSpec.DAG, whose DAG primitive constructors reuse these sequential adapters when possible.

Why only these vision ops?

GraphSpec only exposes an operation once we have both sides of the contract in place:

1. a pure Spec meaning, and
2. an executable TorchLean program meaning.

The general always-available primitives (linear, relu, softmax) live in NN.GraphSpec.Core; this file is the current vision extension pack. More packs can be added as we decide which runtime/spec operations should become architecture-level GraphSpec nodes.

Parameter convention (sequential GraphSpec)

Each primitive has an explicit type-level parameter-shape list ps : List Shape.

For example, convolution is parameterized by:

• kernel : OIHW outC inC kH kW
• bias : Vec outC

so the primitive has ps = [OIHW ..., Vec ...]. When you compose graphs with >>>, these ps lists concatenate, giving a typed “ABI” for model parameters.

References / citations (informal pointers)

• Convolutional networks: LeCun et al. (1998), “Gradient-based learning applied to document recognition”.
• BatchNorm: Ioffe & Szegedy (2015), “Batch Normalization: Accelerating Deep Network Training…”.
• Global average pooling: Lin et al. (2013), “Network In Network”.

def NN.GraphSpec.Primitive.conv2d (inC outC kH kW stride padding inH inW : ℕ) {h_inC : inC ≠ 0} {h_kH : kH ≠ 0} {h_kW : kW ≠ 0} : Primitive [Tensor.Shape.OIHW outC inC kH kW, Tensor.Shape.Vec outC] (Tensor.Shape.CHW inC inH inW) (Tensor.Shape.CHW outC ((inH + 2 * padding - kH) / stride + 1) ((inW + 2 * padding - kW) / stride + 1))

2D convolution on CHW tensors (channel-first, no batch).

Inputs:

• parameters kernel, bias (in that order),
• input tensor x : CHW inC inH inW.

Output:

CHW outC outH outW where

outH = (inH + 2*padding - kH) / stride + 1 and similarly for outW.

This is intentionally close to the underlying Spec/TorchLean op. PyTorch analogy: torch.nn.functional.conv2d on an NCHW tensor, specialized here to CHW.

def NN.GraphSpec.Primitive.maxPool2d (kH kW inH inW inC stride : ℕ) {h_kH : kH ≠ 0} {h_kW : kW ≠ 0} {hStride : stride ≠ 0} : Primitive [] (Tensor.Shape.CHW inC inH inW) (Tensor.Shape.CHW inC ((inH - kH) / stride + 1) ((inW - kW) / stride + 1))

MaxPool2D on CHW tensors (parameter-free).

Output shapes follow the standard pooling size formulas:

outH = (inH - kH) / stride + 1 and similarly for outW.

PyTorch analogy: torch.nn.functional.max_pool2d (with matching kernel_size / stride).

def NN.GraphSpec.Primitive.flatten (s : Shape) : Primitive [] s (Spec.Shape.dim (Shape.size s) Spec.Shape.scalar)

Flatten any tensor to a 1D vector (parameter-free).

Output shape is .dim (Shape.size s) .scalar, i.e. a vector whose length is the number of elements of the input shape.

This is a reshape/view operation (no arithmetic), used to connect convolutional features to a vector-valued classifier head.

PyTorch analogy: torch.flatten(x).

def NN.GraphSpec.Primitive.batchnormChw (channels height width : ℕ) (h_c : channels > 0) (h_h : height > 0) (h_w : width > 0) : Primitive [Tensor.Shape.Vec channels, Tensor.Shape.Vec channels] (Tensor.Shape.CHW channels height width) (Tensor.Shape.CHW channels height width)

BatchNorm on CHW tensors (channel-first, no batch).

Parameters are (gamma, beta) vectors of length channels. This models the learnable affine part of batch normalization.

Note: this op does not carry running mean/variance state inside GraphSpec. If/when we model those, they will need an explicit state/effect model outside of this pure graph language.

Reference: Ioffe & Szegedy (2015).

def NN.GraphSpec.Primitive.globalAvgPool2dChw (c h w : ℕ) (h_c : c > 0) (h_h : h ≠ 0) (h_w : w ≠ 0) : Primitive [] (Tensor.Shape.CHW c h w) (Tensor.Shape.Vec c)

Global average pooling over spatial dims (CHW c h w → Vec c).

This is a common classifier head for CNNs: average each channel over the h×w spatial grid.

Reference: Lin et al. (2013), “Network In Network”. PyTorch analogy: torch.nn.AdaptiveAvgPool2d((1,1)) followed by flatten.

def NN.GraphSpec.Graph.conv2d (inC outC kH kW stride padding inH inW : ℕ) {h_inC : inC ≠ 0} {h_kH : kH ≠ 0} {h_kW : kW ≠ 0} : Graph [Tensor.Shape.OIHW outC inC kH kW, Tensor.Shape.Vec outC] (Tensor.Shape.CHW inC inH inW) (Tensor.Shape.CHW outC ((inH + 2 * padding - kH) / stride + 1) ((inW + 2 * padding - kW) / stride + 1))

Graph constructor for Primitive.conv2d.

def NN.GraphSpec.Graph.maxPool2d (kH kW inH inW inC stride : ℕ) {h_kH : kH ≠ 0} {h_kW : kW ≠ 0} {hStride : stride ≠ 0} : Graph [] (Tensor.Shape.CHW inC inH inW) (Tensor.Shape.CHW inC ((inH - kH) / stride + 1) ((inW - kW) / stride + 1))

Graph constructor for Primitive.max_pool2d.

def NN.GraphSpec.Graph.flatten (s : Shape) : Graph [] s (Spec.Shape.dim (Shape.size s) Spec.Shape.scalar)

Graph constructor for Primitive.flatten.

def NN.GraphSpec.Graph.batchnormChw (channels height width : ℕ) (h_c : channels > 0) (h_h : height > 0) (h_w : width > 0) : Graph [Tensor.Shape.Vec channels, Tensor.Shape.Vec channels] (Tensor.Shape.CHW channels height width) (Tensor.Shape.CHW channels height width)

Graph constructor for Primitive.batchnorm_chw.

def NN.GraphSpec.Graph.globalAvgPool2dChw (c h w : ℕ) (h_c : c > 0) (h_h : h ≠ 0) (h_w : w ≠ 0) : Graph [] (Tensor.Shape.CHW c h w) (Tensor.Shape.Vec c)

Graph constructor for Primitive.global_avg_pool2d_chw.