{
"title": "dot",
"category": "math/linalg/ops",
"keywords": [
"dot",
"inner product",
"linear algebra",
"gpu",
"dimension"
],
"summary": "Compute dot products (inner products) of real or complex inputs, optionally along a chosen dimension.",
"references": [
"https://www.mathworks.com/help/matlab/ref/dot.html"
],
"gpu_support": {
"elementwise": false,
"reduction": true,
"precisions": [
"f32",
"f64"
],
"broadcasting": "none",
"notes": "Prefers a provider-side dot hook; the WGPU backend currently handles 2-D tensors along dimensions 1 or 2 and falls back to the host otherwise. When no hook is available RunMat gathers operands, evaluates the MATLAB reference path, and re-uploads real results when possible."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 2,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::math::linalg::ops::dot::tests",
"integration": "builtins::math::linalg::ops::dot::tests::dot_gpu_roundtrip"
},
"description": "`dot(A, B)` evaluates the inner product between matching slices of `A` and `B`. Inputs must have the same size, and complex vectors follow MATLAB's convention `sum(conj(A) .* B)`.",
"behaviors": [
"Treats vectors, matrices, and N-D tensors identically as long as `A` and `B` share the same size.",
"When no dimension is supplied, the function reduces along the first non-singleton dimension (`dim = 1` when all dimensions are singleton).",
"`dot(A, B, dim)` collapses dimension `dim` (1-based) while leaving every other dimension untouched.",
"Complex inputs conjugate the first argument before multiplication; real inputs use a straight element-wise product.",
"Empty reductions yield zeros of the appropriate shape; length mismatches raise `A and B must be the same size`.",
"Logical and integer inputs are promoted to double precision automatically so the result is always floating point (or complex when any input is complex)."
],
"examples": [
{
"description": "Computing the dot product of row vectors",
"input": "A = [1 2 3];\nB = [4 5 6];\nval = dot(A, B)",
"output": "val = 32"
},
{
"description": "Dotting column vectors to obtain a scalar",
"input": "u = [1; 3; 5];\nv = [2; 4; 6];\nval = dot(u, v)",
"output": "val = 44"
},
{
"description": "Applying `dot` along a chosen dimension",
"input": "X = [1 2 3; 4 5 6];\nY = [6 5 4; 3 2 1];\ncols = dot(X, Y, 1) % collapse rows\nrows = dot(X, Y, 2) % collapse columns",
"output": "cols = [18 20 18];\nrows = [28; 28]"
},
{
"description": "Dotting complex vectors uses conjugation on the first input",
"input": "a = [1+2i, 3-4i];\nb = [2-3i, -1+5i];\nval = dot(a, b)",
"output": "val = -27 + 4i"
},
{
"description": "Evaluating `dot` on `gpuArray` inputs",
"input": "G1 = gpuArray([1 2 3 4]);\nG2 = gpuArray([4 3 2 1]);\nG = dot(G1, G2);\nresult = gather(G)",
"output": "result = 20"
}
],
"faqs": [
{
"question": "Does `dot` require vectors?",
"answer": "No. Any pair of tensors with identical sizes works; specifying a dimension lets you dot slices of higher-dimensional arrays."
},
{
"question": "How does the optional dimension behave?",
"answer": "`dot(A, B, dim)` collapses the `dim`th dimension (1-based). Dimensions greater than the array rank have length 1 and therefore leave the data unchanged."
},
{
"question": "What happens with complex numbers?",
"answer": "The first input is conjugated before multiplication so the result matches MATLAB's hermitian inner product."
},
{
"question": "Are empty inputs supported?",
"answer": "Yes. If the reduction dimension has length 0 the result is filled with zeros of the appropriate shape."
},
{
"question": "Will the result stay on the GPU?",
"answer": "When a provider is active the runtime uploads real-valued results back to the device. Complex outputs stay on the host until GPU complex support is available."
},
{
"question": "What error is raised for size mismatches?",
"answer": "When `A` and `B` differ in size `dot` raises: `A and B must be the same size.` matching MATLAB's wording."
},
{
"question": "Does `dot` accept logical or integer inputs?",
"answer": "Yes. Inputs are promoted to double precision before evaluation so you never lose MATLAB's semantics."
},
{
"question": "Can I request conjugation of the second argument instead?",
"answer": "No. MATLAB's `dot` is fixed to conjugate the first argument. Use `sum(A .* conj(B))` manually if you need the opposite orientation."
}
],
"links": [
{
"label": "mtimes",
"url": "./mtimes"
},
{
"label": "mldivide",
"url": "./mldivide"
},
{
"label": "norm",
"url": "./norm"
},
{
"label": "sum",
"url": "./sum"
},
{
"label": "ctranspose",
"url": "./ctranspose"
},
{
"label": "mpower",
"url": "./mpower"
},
{
"label": "mrdivide",
"url": "./mrdivide"
},
{
"label": "trace",
"url": "./trace"
},
{
"label": "transpose",
"url": "./transpose"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/math/linalg/ops/dot.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/linalg/ops/dot.rs"
},
"gpu_residency": "You rarely need to call `gpuArray` explicitly for `dot`. If the provider lacks a dedicated dot kernel, RunMat will gather the operands, compute the host result, and—when the output is real—upload it back to the provider automatically. Complex outputs remain on the host until GPU complex datatypes are implemented; in mixed pipelines consider reintroducing `gpuArray` explicitly after the call if residency is critical.",
"gpu_behavior": [
"RunMat Accelerate keeps GPU-resident tensors on the device whenever the active provider exposes a `dot` hook. When the hook is missing, RunMat gathers both operands to the host, evaluates the reference path, and—when the result is real—uploads it back to the provider so downstream GPU code continues without manual transfers. Complex outputs remain on the host until provider support lands."
]
}