RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

What does the hypot function do in MATLAB / RunMat?

z = hypot(x, y) computes the element-wise Euclidean norm sqrt(|x|.^2 + |y|.^2) with overflow-resistant arithmetic. It accepts scalars, vectors, matrices, N-D tensors, and complex inputs, following MATLAB's implicit expansion (broadcasting) rules.

How does the hypot function behave in MATLAB / RunMat?

  • Real inputs return non-negative doubles even when the operands are negative.
  • Complex arguments are converted to their magnitudes before forming sqrt(|x|.^2 + |y|.^2), matching MATLAB's definition since R2020b.
  • Scalars broadcast across the other operand when shapes are compatible; otherwise an error is raised.
  • Empty inputs propagate emptiness according to MATLAB's size rules.
  • Inf operands return Inf; NaN operands propagate NaN.

hypot Function GPU Execution Behaviour

When tensors already reside on the GPU, RunMat asks the active acceleration provider for the elem_hypot hook:

  • Hook available and shapes match: the Euclidean norm executes in a single fused GPU kernel.
  • Hook missing or implicit expansion required: RunMat gathers the data to the host, computes the MATLAB-compatible result, and reuses the host tensor downstream.
  • Fusion-enabled expressions: the fusion planner can emit a WGSL hypot(a, b) node so long as the active provider marks the group as supported; otherwise the execution seamlessly falls back to the host path.

Providers can implement elem_hypot by emitting a single WGSL/compute shader that calls hypot(a, b); the included WGPU backend demonstrates this pattern.

Examples of using the hypot function in MATLAB / RunMat

Computing the hypotenuse of two scalars

result = hypot(3, 4);

Expected output:

result = 5;

Using hypot with vectors and implicit expansion

x = [-3, 0, 4];
y = 4;
norms = hypot(x, y);

Expected output:

norms = [5 4 5];

Calculating per-element distances between two matrices

X = [1 2; 3 4];
Y = [0 1; 1 0];
dist = hypot(X, Y);

Expected output:

dist = [1.0000 2.2361; 3.1623 4.0000];

Working with complex numbers

a = [1+2i, 3-4i];
b = [2-1i, -1+1i];
mag = hypot(a, b);

Expected output:

mag = [3.1623 5.1962];

Applying hypot to character data

codes = hypot('A', zeros(1, 1));

Expected output:

codes = 65.0000;

Executing hypot on GPU arrays

Gx = gpuArray([3 4; 5 12]);
Gy = gpuArray([4 3; 12 5]);
distance_gpu = hypot(Gx, Gy);
distance = gather(distance_gpu);

Expected output:

distance = [5 5; 13 13];

GPU residency in RunMat (Do I need gpuArray?)

Manual gpuArray calls are typically unnecessary. RunMat's planner keeps tensors on the GPU when profitable and automatically gathers data when the active provider lacks elem_hypot. You can still force residency with explicit gpuArray/gather to mirror MATLAB workflows or when interoperating with custom kernels.

FAQ

Does hypot overflow for large inputs?

No. Like MATLAB, RunMat uses a stable algorithm that scales the operands to avoid overflow and underflow. Very large inputs return finite results when mathematically possible.

What happens when the inputs are negative?

hypot always returns a non-negative result because it squares the magnitudes first. Signs on the inputs only matter when NaN or Inf is involved.

Can I mix real and complex inputs?

Yes. Complex inputs are converted to magnitudes before forming the norm, so you can freely combine real, complex, and logical data.

Does hypot accept logical or character arrays?

Yes. Logical values map to 0 and 1, while character arrays use their Unicode code points (as doubles), matching MATLAB semantics.

How does broadcasting work?

The function applies MATLAB's implicit expansion: singleton dimensions expand to match the other operand. If a non-singleton dimension differs, RunMat raises a dimension mismatch error.

Are GPU results identical to CPU results?

For double precision providers the results match bit-for-bit. Single precision providers (e.g., wgpu in F32 mode) may differ by typical floating-point rounding.

What if only one operand lives on the GPU?

The runtime gathers the GPU operand, computes the norm on the host, and continues execution. Future providers may implement scalar expansion directly on the device.

Does hypot allocate a new array?

Yes. The builtin returns a fresh tensor. Fusion may elide intermediate buffers when the expression participates in a larger GPU kernel.

How can I compute the magnitude of a vector of components?

Use hypot repeatedly: hypot(x, hypot(y, z)) computes the Euclidean norm of (x, y, z) element-wise without manual squaring.

See Also

sqrt, abs, sin, gpuArray, gather

Source & Feedback