realsqrt — Compute real square roots element-wise and reject values that require complex results.
Y = realsqrt(X) computes sqrt(X) for real nonnegative inputs. Unlike sqrt, it rejects negative real values and complex inputs instead of producing complex results.
Syntax
Y = realsqrt(X)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Real single or double numeric input. |
Returns
| Name | Type | Description |
|---|---|---|
Y | NumericArray | Real elementwise square-root result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:realsqrt:InvalidInput | Input is not real single or double numeric data. | realsqrt: invalid input |
RunMat:realsqrt:ComplexResult | At least one real input value is negative and would require a complex result. | realsqrt: input must be nonnegative |
RunMat:realsqrt:Internal | Internal tensor construction or provider interaction failed. | realsqrt: internal error |
How realsqrt works
realsqrt(X)applies the operation element-wise and preserves the input shape.- Only real single and double numeric inputs are accepted. Logical, character, and every integer class reject before numeric coercion or provider dispatch.
- Sparse inputs preserve sparsity: stored values are square-rooted and unstored zeros remain zero.
- Negative real values raise a domain error because the result would be complex.
- Complex scalar and complex tensor inputs are rejected, even if their imaginary parts are zero.
- NaNs and positive infinities propagate according to IEEE real square-root arithmetic.
Does RunMat run realsqrt on the GPU?
realsqrt is GPU-aware but not fused. Provider execution is used only after a nonnegative-domain check. This preserves MATLAB-compatible error behavior for negative inputs while still allowing nonnegative gpuArray inputs to remain device-resident.
GPU memory and residency
RunMat keeps real gpuArray inputs on the active provider when it can prove the values are nonnegative and the provider exposes the required reduce_min and unary square-root hooks. Complex gpuArray inputs are rejected before provider execution. If the nonnegative proof is unavailable, if NaNs prevent a reduction proof, or if the provider lacks the hook, RunMat gathers to host and applies the same real-domain validation as CPU inputs.
Examples
Taking the real square root of a scalar
y = realsqrt(9)Expected output:
y = 3Square roots of a matrix
A = [1 4 9; 16 25 36];
R = realsqrt(A)Expected output:
R = [1 2 3; 4 5 6]Rejecting negative values
realsqrt([-1 4])Expected output:
Error using realsqrt
Input must be nonnegative.Preserving sparse storage
S = sparse([1 3], [1 2], [4 9], 3, 2);
R = realsqrt(S)Expected output:
R = sparse([1 3], [1 2], [2 3], 3, 2)Running on GPU data
G = gpuArray([0 1; 4 9]);
out = realsqrt(G);
result = gather(out)Expected output:
result = [0 1; 2 3]Using realsqrt with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how realsqrt changes the result.
Run a small realsqrt example, explain the result, then change one input and compare the output.
FAQ
How is realsqrt different from sqrt?⌄
sqrt promotes negative real values to complex results. realsqrt stays in the real domain and raises an error when an element is negative.
Does realsqrt accept complex inputs with zero imaginary part?⌄
No. Complex inputs are rejected because the function is a real-domain helper.
Can realsqrt run on GPU data?⌄
Yes. RunMat first rejects complex GPU buffers, then proves that the GPU tensor has no negative values. If that proof succeeds and the provider exposes both reduce_min and sqrt hooks, the operation runs on the provider; otherwise RunMat gathers to host and validates the real-domain contract there.
Does realsqrt fuse into larger GPU expressions?⌄
No. The builtin is treated as a fusion sink because negative inputs must raise a domain error rather than becoming NaN inside a fused shader.
What happens to NaN values?⌄
NaN values remain NaN. They are not treated as negative, but they can force RunMat to validate GPU inputs on the host before execution.
Related Math functions
Elementwise
abs · angle · bsxfun · complex · conj · double · erf · erfcinv · exp · expm1 · factorial · flintmax · gamma · gammaln · heaviside · hypot · idivide · imag · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · rescale · sign · single · sqrt · swapbytes · times · typecast · uint16 · uint32 · uint8
Trigonometry
acos · acosh · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Reduction
all · any · bounds · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · maxk · mean · median · min · mink · movmax · movmean · movmedian · movmin · movprod · movstd · movsum · movvar · nnz · prod · rms · std · sum · trapz · var
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Optim
coneprog · fminbnd · fminunc · fsolve · fzero · integral · linprog · lsqcurvefit · lsqnonlin · optimoptions · optimset · quad · secondordercone
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how realsqrt is executed, line by line, in Rust.
- View the source for realsqrt in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.