Skip to main content

Output Modes And Write Surfaces

This note records the output-update vocabulary shared by tensor, einsum, and dot/GEMM APIs. Since the 0.12 call grammar (#2552) the public operation spellings are generated from the operation registries; the authoritative list of which operation declares which output mode is docs/spec/generated/api-ops.md.

Public Suffix Vocabulary

Form Meaning
op(..., exec) -> T Default options; the backend allocates the output.
op_with(..., &opts, exec) -> T Explicit XxxOptions; the backend allocates the output.
op_into(..., &opts, exec, dest) -> Result<()> Writes into a caller-provided Dest, only where the registry declares it.
op_in_place(...) Consuming destructive update (exception E01, in-place FFT). This is separate from _into.

Whether an input is owned, borrowed, typed, or a strided view is the receiver type (Tensor, TensorRead, TypedTensor<T>, TypedTensorView<T>), never a suffix. There is no public _read, _add_to, or _into_accum operation name.

_into takes a Dest, whose mode is the output-update semantics:

Dest Meaning
Dest::overwrite(out) Overwrite the caller output; the previous value is never read.
Dest::accumulate(out) Read-modify-write, out += op(...).
Dest::scaled(out, alpha, beta) out = alpha * op(...) + beta * out; beta = 0 never reads out.

The load-bearing rule is that any semantic use of the previous output value is visible in the Dest value, not hidden in the method. A mode the registry does not declare for an operation is Unsupported before anything is written. All _into paths validate output dtype and shape before writing and never resize the destination.

Dot And Einsum

DotGeneralConfig describes contraction dimensions only. Conjugation is an operation option (DotGeneralOptions, EinsumOptions::conj); the output-update coefficients are the Dest value. Einsum’s einsum_into and ConcreteEinsumPlan::execute_into declare Overwrite, Accumulate, and Scaled.

Typed inputs take typed destinations (an owned TypedTensor<T> or a mutable typed view) because the dtype is statically known; erased inputs take TensorWrite<'_>, so dtype and view validation happen at the backend boundary.

Provider Hooks

Backend and provider traits (Engine, TensorDot, LinalgBackend, FftBackend) keep their own hook vocabulary; these are provider contracts (exception E10), not public operation grammar:

Hook form Meaning
op_read(...) Borrowed TensorRead inputs; output is allocated.
op_read_into(..., out: TensorWrite) Borrowed inputs plus overwritten caller output. This is the main backend hook shape.
op_read_into_accum(..., accum, out: TensorWrite) Dot/GEMM-only update, out = alpha * op(lhs, rhs) + beta * out, with DotGeneralAccumulation carrying conjugation flags and alpha/beta.

A public Dest::accumulate or Dest::scaled on a dot/GEMM-shaped operation is lowered onto the _read_into_accum hook (Dest::into_accumulation, exception E06); there is no separate _linear_into vocabulary.

Elementwise

_into writes are overwrite unless the Dest says otherwise. _in_place methods are allowed only when the aliased input/output contract is explicitly implemented and tested. Generic *_into kernels must not be assumed alias-safe unless their owner documents that guarantee.