Limitations and scope

Hydronnx has a defined scope, and the scope is not "every ONNX model". This chapter is the single honest account of what Hydronnx does not do. If you have a model and Hydronnx is not the right tool for it, this chapter is meant to tell you that directly, so you can pick ONNX Runtime instead.

Where Hydronnx fits

Hydronnx's value is type discipline, property verification, and composition, not inference throughput.

• Use Hydronnx when you want compile-time shape checking on a small to moderate tabular model, want to attach a @property and run chelis prove, want to compose the model with hand-written Chelis end to end, or want AD on the weighted tabular Gemm surface Hydronnx gates.
• Use ONNX Runtime when you want raw inference throughput on a large model, want to run a broad vision or detection model, want AD on an operator surface Hydronnx has not gated, or want to deploy on hardware Hydronnx does not cover (GPU, mobile NPU).

chelis's pipeline does not fuse operators, so the throughput story is not where Hydronnx leads. The migration guide covers the trade-off in more detail.

Operator coverage

The emit set covers tabular, encoder-only, elementwise, zero-pad windowed pooling, and small single-Conv image-classifier graphs. The full description of which operators emit, with their domain constraints, and which are deferred, is in Supported ONNX surface. In brief:

• Conv, ConvTranspose, MaxPool, AveragePool, GlobalAveragePool, GlobalMaxPool, Flatten, Cos, Tan, Floor, and Ceil emit, each within a documented constraint set.
• Round, ScatterElements, ScatterND, and MultiHeadAttention are deferred. Each rejects with UnsupportedOperator. The reasons and the recommended workarounds are in Supported ONNX surface.

Large Conv-dependent vision categories (ResNet- and MobileNet-scale classifiers, object detection like YOLO) need more model-surface work and a sidecar weight format for numeric parity. A small generated image-classifier example ships in examples/image_classifier/; larger vision models need their own operator-surface parity gates.

Dtype coverage

The dtype set is f32, f64, i32, i64, bool.

• f64 weight-literal precision. chelis lexes every float literal at f32 precision, so an f64 weight initializer is emitted at f32 precision regardless of the original tensor's dtype. The fixtures are f32, so this rarely bites; an f64 model declares the problem in its weight emit. The numeric-source weight path (see Weights and large models) stores f64 bytes directly and would not lose precision.
• No uint8, int8, bf16, fp16, complex, or string dtypes. Each rejects at parse time with UnsupportedDtype. Cast at export time.

Shape coverage

• Static shapes map directly.
• Symbolic ONNX dim_params map to chelis dim variables in the emitted sig. The symbolic_batch.onnx fixture is the canonical exercise: a [batch, 5] input emits as tensor[batch, 5, f32].
• Dynamic dims with no dim_param name are rare; they render as ? in inspect. The emit path rejects them with InternalInconsistency carrying cannot derive signature: value '<name>' has an anonymous dynamic dimension, which Chelis's type system cannot express. Re-export with the dim named (dim_param = "batch") or pinned to a static value.

Symbolic batch through Gemm and MatMul

Rank-2 MatMul and default Gemm can preserve a symbolic graph-input batch dim, and a rank-1 Gemm bias expands with shape(x, cast(0, int32)).

The support is deliberately narrow. Runtime-sized coefficient tensors for non-unit alpha or beta reject unless the coefficient shape is fully static, because Hydronnx would otherwise need a runtime fill or broadcast pattern for a constant tensor. Symbolic dims derived from intermediate operations are also outside this path; the runtime extent must originate from a graph input axis.

Runtime reshape with symbolic dims

Hydronnx emits cast(shape(x, cast(axis, int32)), int64) for ONNX Reshape 0 dims copied from a symbolic graph input. -1 inference with symbolic dims rejects, because the missing product cannot be resolved statically.

Automatic differentiation on weighted models

Hydronnx gates AD through a weighted tabular Gemm model against the real chelis grad builtin and a central finite-difference check. The emitter localizes Gemm/MatMul weight literals in forward and materializes static Gemm bias broadcasts as same-shape constants so chelis AD can lower the body. The weight-free diff_mlp AD test remains as a separate control.

This is not a blanket guarantee for every weighted ONNX model. chelis AD is operator-dependent, and Hydronnx only claims AD for emitted operator surfaces that have an explicit AD gate. Run chelis-hydronnx-inspect to screen for mathematically non-differentiable operators first, then add an AD parity or finite-difference gate for the model surface you intend to use.

The image-classifier surface is not AD-gated. A synthetic Conv -> Relu -> GlobalAveragePool -> Reshape -> Gemm -> Softmax probe has no mathematically non-differentiable operators, but chelis does not lower grad(...) for that surface, reporting grad(...) lowering requires a scalar floating forward output. A test pins this so Hydronnx does not overclaim Conv-family AD.

A clean detector output is not a claim of AD-readiness. The detector's scope is mathematical non-differentiability (ArgMax, Floor, and so on), not full chelis AD operator coverage. The non-differentiable section of inspect and the emit warning say so explicitly.

Large-model emit size

Hydronnx emits weights as Chelis source literals, so the emitted .ch grows linearly with the parameter count. That works for small models and does not fit a multi-megabyte model, whose emitted source would exceed chelis's practical lex/parse ceiling.

The practical guidance: the inline-emit path fits tabular models, small MLPs, small transformer encoders, and toy or test models. It does not fit ResNet, MobileNet, BERT-base, or any production-scale vision or NLP model. The small-model guidance is independent of Conv operator availability: even with the static 2D Conv path, a multi-million-parameter Conv model is too big for inline-weight emit. The placeholder-emit mode and the runtime path lift this ceiling for the type-discipline and runtime use cases respectively; see Weights and large models.

Spec-excluded scope

Outside Hydronnx's scope by design, not deferred work:

• Training graphs. ONNX has a separate training-graph schema; Hydronnx is inference-only.
• Control-flow operators. If, Loop, Scan, SequenceAt, and similar. Chelis's pure-functional surface admits these awkwardly; out of scope.
• Quantized models. QLinearConv, QLinearMatMul, and similar. Quantized dtypes are not in the dtype set.
• Round-trip ONNX export. Hydronnx is one-way (.onnx to .ch). There is no .ch to .onnx path.
• Custom operators. ONNX permits user-extended operators; Hydronnx rejects them at parse time.