RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

What does the sqrt function do in MATLAB / RunMat?

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.

sqrt Function GPU Execution Behaviour

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.

Examples of using the sqrt function 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];

GPU residency in RunMat (Do I need gpuArray?)

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.

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