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

a pure Spec meaning, and
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”.

source

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} {hStride : stride ≠ 0} :

Primitive [Spec.Shape.dim outC (Spec.Shape.dim inC (Spec.Shape.dim kH (Spec.Shape.dim kW Spec.Shape.scalar))), Spec.Shape.dim outC Spec.Shape.scalar] (Spec.Shape.dim inC (Spec.Shape.dim inH (Spec.Shape.dim inW Spec.Shape.scalar))) (Spec.Shape.dim outC (Spec.Shape.dim (Spec.Shape.slidingWindowOutDim inH kH stride padding) (Spec.Shape.dim (Spec.Shape.slidingWindowOutDim inW kW stride padding) Spec.Shape.scalar)))

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 = Spec.Shape.slidingWindowOutDim inH kH stride padding and similarly for outW.

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

Instances For

source

def NN.GraphSpec.Primitive.maxPool2d (kH kW inH inW inC stride : ℕ) {h_kH : kH ≠ 0} {h_kW : kW ≠ 0} {hStride : stride ≠ 0} :

Primitive [] (Spec.Shape.dim inC (Spec.Shape.dim inH (Spec.Shape.dim inW Spec.Shape.scalar))) (Spec.Shape.dim inC (Spec.Shape.dim (Spec.poolOutDim inH kH stride 0) (Spec.Shape.dim (Spec.poolOutDim inW kW stride 0) Spec.Shape.scalar)))

MaxPool2D on CHW tensors (parameter-free).

Output shapes follow the standard pooling size formulas:

outH = Spec.poolOutDim inH kH stride 0 and similarly for outW.

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

Instances For

source

def NN.GraphSpec.Primitive.flatten (s : Tensor.Shape) :

Primitive [] s (Spec.Shape.dim (Spec.Shape.size s) Spec.Shape.scalar)

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

Output shape is .dim (Spec.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).

Instances For

source

def NN.GraphSpec.Primitive.batchnormChw (channels height width : ℕ) (h_c : channels > 0) (h_h : height > 0) (h_w : width > 0) :

Primitive [Spec.Shape.dim channels Spec.Shape.scalar, Spec.Shape.dim channels Spec.Shape.scalar] (Spec.Shape.dim channels (Spec.Shape.dim height (Spec.Shape.dim width Spec.Shape.scalar))) (Spec.Shape.dim channels (Spec.Shape.dim height (Spec.Shape.dim width Spec.Shape.scalar)))

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

Instances For

source