Skip to main content

ClikaRT::nn::Conv

class

Header: ClikaRT/nn/conv.h
Inherits: ClikaRT::nn::Module

A bound, weight-packing convolution, the public face of the runtime's packed conv, exposed as an nn::Module leaf. Unlike the stateless ops::conv* free functions (which re-pack the weight on every call), a Conv binds its weight ONCE and packs it into the backend's kernel layout (a GEMM panel, a depthwise/stem transpose, an alignment-padded device copy, whichever the geometry rides); every forward reuses that packed weight. Build one Conv per layer at load, reuse it every step.

The lifecycle (uniform across every weight-bearing nn module):

  1. make(in, out, kernel, options, ...), the ONE constructor: declares storage-free weight / bias slots under their canonical names.
  2. set_weights(w[, b]) (tensors in hand) or load_state_dict(...) (a checkpoint, by dotted name) binds the slots.
  3. forward(x) packs ON FIRST CALL (once, thread-safe), then serves the packed form every step. initialize() remains available as an optional warm-up to pay the pack at load time instead of on the first input.

Layout: activations are channels-last [N, D1..Dn, C]; the weight is OHWI [out_channels, K1..Kn, in_channels/groups] (output-channel-first). The kernel size vector fixes the spatial rank (1-D/2-D/3-D from one class). Held via std::shared_ptr (an nn::Module leaf); copy/move are pinned by the base.

N-dimensional convolution module (1-D/2-D/3-D by the weight's rank).

Channels-last: input [N, spatial.., C], weight OHWI [O, K.., C/groups], output [N, out-spatial.., O], the module form of ops::conv1d/2d/3d with an optional fused pad + activation epilogue. The module owns its weights: construct with make(...), or declare shapes and bind a checkpoint via load_state_dict. After the first forward (or initialize()) the weight lives ONLY in the backend's packed form (one resident copy); to(dtype) restores, casts, and repacks on the next forward.

auto conv = ClikaRT::nn::Conv::make(W, b);      // W: [O, Kh, Kw, C/groups]
auto y    = conv->forward(x);               // [N, H, W, C] -> [N, H', W', O]

Static member functions​

make()​

static std::shared_ptr<Conv> make(
    std::int64_t in_channels,
    std::int64_t out_channels,
    Span<const std::int64_t> kernel,
    Span<const std::int64_t> stride = {},
    Span<const std::int64_t> padding = {},
    Span<const std::int64_t> dilation = {},
    std::int64_t groups = 1,
    bool bias = false,
    ops::PadMode mode = ops::PadMode::Constant,
    std::optional<double> value = std::nullopt,
    std::optional<ops::Activation> activation = std::nullopt,
    DataType dtype = DataType::Float32,
    Device device = Device::cpu()
)

Defaults: stride / padding / dilation = empty (unit stride, no pad, unit dilation), groups = 1, bias = false (no bias slot), mode = PadMode::Constant, value = unset (zero fill), activation = none, dtype = Float32, device = CPU, so the three counts alone make a plain unit-stride convolution.

Throws

  • ClikaRT::Error: as stated above.

Declared in ClikaRT/nn/conv.h, line 89

Member functions​

~Conv()​

~Conv() override

Declared in ClikaRT/nn/conv.h, line 103

set_weights()​

void set_weights(Tensor weight, OptionalTensor bias = {})

Bind the declared slots positionally: weight (OHWI [out, K.., in/groups]) and, when the module was made with one, bias ([out]). The declared placement wins (the tensors move to it); shapes must match the declaration. Re-binding after a pack drops the pack; the next forward re-packs from the new weights. Raises ClikaRT::Error on a geometry mismatch or a bias without a declared bias slot.

Declared in ClikaRT/nn/conv.h, line 113

initialize_impl()​

virtual Result<void> initialize_impl() override

Optional warm-up: run the first-forward pack NOW (idempotent, thread-safe) so a serving process pays it at load time instead of on the first input. Every declared slot must hold a real (loaded) tensor; a still-fake slot is a clean error. After the pack the weight slot is released (the packed form is the single resident copy, no raw+packed doubling), so named_parameters() enumerates only the unpacked slots (the bias); a re-bind re-inserts and the next pack re-releases.

Declared in ClikaRT/nn/conv.h, line 125

to_impl(StreamOrDevice)​

virtual Result<void> to_impl(StreamOrDevice where) override

Move to a placement (a Device, or a Stream, the lane this Conv computes on and lands its outputs on) or cast to a dtype. Before the pack this moves the registry slots (a still-fake slot re-declares its metadata there). Once packed, a placement move REBUILDS the pack on the target; a dtype cast restores the raw weight from the pack, casts, and re-packs on the next forward, never a stale packed form computing on the old placement.

Declared in ClikaRT/nn/conv.h, line 134

to_impl(DataType)​

virtual Result<void> to_impl(DataType dtype) override

Declared in ClikaRT/nn/conv.h, line 135

forward()​

Tensor forward(Tensor x) const

Apply the bound weight: x [N, D1..Dn, in] -> [N, O1..On, out] (then bias + activation if configured). The first call packs the weight into the backend kernel layout (once, thread-safe); every later call reuses the pack. Raises ClikaRT::Error on a shape/dtype mismatch or a still-fake slot.

Declared in ClikaRT/nn/conv.h, line 143