RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

sqrt — Element-wise square root of scalars, vectors, matrices, or N-D tensors.

Y = sqrt(X) computes the principal square root of every element in X. Results follow MATLAB semantics for scalars, vectors, matrices, logical arrays, character arrays, and complex inputs. Negative real values automatically promote to complex results so that the output remains exact.

How does the sqrt function behave in MATLAB / RunMat?

  • sqrt(X) applies the operation element-wise with MATLAB broadcasting rules.
  • Logical values convert to doubles (true → 1.0, false → 0.0) before the square root is taken.
  • Character arrays are interpreted as their numeric code points and return dense double tensors.
  • Negative real inputs yield purely imaginary outputs: sqrt([-1 4]) returns [0 + 1i, 2].
  • Complex inputs follow MATLAB's definition and stay on the principal branch of the complex square root, ensuring continuity across the negative real axis.
  • Zeros (including -0) remain zero in the output; infinities and NaNs propagate according to IEEE arithmetic.

GPU behavior

RunMat Accelerate keeps tensors on the GPU when the active provider implements both unary_sqrt and reduce_min, allowing the runtime to prove that every element is non-negative before launching the kernel. When the dataset contains negative values (and therefore requires complex promotion) or when either hook is missing, RunMat gathers the data to the host, computes the MATLAB-compatible result, and updates residency metadata so subsequent operations see the correct value.

GPU residency

You typically do **not** need to call gpuArray manually. The acceleration planner and fusion engine keep tensors on the GPU when profitable. If your data contains negative values, RunMat automatically gathers the tensor, produces the complex result on the host, and keeps residency metadata in sync. You can still use gpuArray/gather to mirror MathWorks MATLAB workflows.

Examples of using sqrt in MATLAB / RunMat

Taking the square root of a positive scalar

y = sqrt(9)

Expected output:

y = 3

Square roots of a matrix

A = [1 4 9; 16 25 36];
R = sqrt(A)

Expected output:

R = [1 2 3; 4 5 6]

Square roots of negative inputs produce complex results

values = [-1 -4 9];
roots = sqrt(values)

Expected output:

roots = [0.0000 + 1.0000i, 0.0000 + 2.0000i, 3.0000 + 0.0000i]

Element-wise square root on GPU data

G = gpuArray([0 1; 4 9]);
out = sqrt(G);
result = gather(out)

Expected output:

result = [0 1; 2 3]

Square root of complex numbers

z = [3 + 4i, -1 + 2i];
w = sqrt(z)

Expected output:

w = [2 + 1i, 0.7862 + 1.2720i]

Square root of character codes

C = 'AB';
numericRoots = sqrt(C)

Expected output:

numericRoots = [8.0623 8.2462]

FAQ

Does sqrt return complex results for negative inputs?

Yes. Negative real numbers produce purely imaginary outputs that match MATLAB. Mixed-sign tensors automatically promote to complex tensors.

How are logical inputs handled?

Logical arrays convert to doubles before the square root is applied, so sqrt([true false]) returns [1 0].

Can the GPU handle negative inputs?

Providers currently operate on real buffers. When negative values are present, RunMat gathers the tensor to the host to compute the correct complex result before continuing execution.

Does sqrt preserve the input shape?

Yes. The output has the same shape as the input, with element-wise results.

How are NaNs and infinities treated?

They follow IEEE rules: sqrt(NaN) is NaN, sqrt(Inf) is Inf, and sqrt(-Inf) is 0 + Inf·i.

What about complex inputs with small imaginary parts?

The implementation uses the principal square root branch and rounds very small real or imaginary components to zero to avoid -0 artefacts.

Will future providers support complex tensors directly?

Yes. The current design promotes to host computation when complex results are needed. Future providers may expose complex buffers, and the builtin will automatically benefit from those hooks.

See also

abs, exp, log, gpuArray, gather

Source & Feedback