angle — Phase angle (argument) of real and complex values in MATLAB and RunMat.
angle(x) returns the phase angle (argument) of each real or complex single- or double-precision element in x, in radians. Complex inputs use atan2(imag(x), real(x)), and real-valued arrays are handled element-wise.
Syntax
theta = angle(X)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Real or complex single- or double-precision input. |
Returns
| Name | Type | Description |
|---|---|---|
theta | NumericArray | Phase angle in radians. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:angle:InvalidInput | Input is not real or complex single- or double-precision data. | angle: invalid input |
RunMat:angle:Internal | Internal tensor conversion/allocation/provider interaction failed. | angle: internal error |
How angle works
- Complex inputs use
atan2(imag(x), real(x)), yielding values in[-π, π]. - Real inputs are treated as complex numbers with zero imaginary part. Positive numbers map to
0, negative numbers map toπ, and zeros return0. - Single-precision input produces single-precision output; double-precision input produces double-precision output, with input shape preserved.
- All eight integer classes, logical arrays, character arrays, and strings are outside the supported input domain and raise
RunMat:angle:InvalidInput. - Real and componentwise-complex typed-integer arrays reject before any floating-point materialization.
- NaN propagation follows IEEE rules:
angle(NaN)returnsNaN.
Does RunMat run angle on the GPU?
When RunMat Accelerate is active, tensors that already reside on the GPU remain on the device. Providers that implement the unary_angle hook execute the phase computation directly on the GPU, using atan2(0, real) for real storage and atan2(imag, real) for complex-interleaved storage. If the hook is missing or an input requires host-only conversion, RunMat gathers the data, evaluates the phase angle on the CPU, and then honors any downstream fusion or residency decisions automatically.
GPU memory and residency
You usually do not need to call gpuArray explicitly. RunMat's fusion planner and Accelerate layer manage residency automatically, keeping tensors on the GPU whenever device execution is advantageous. Explicit gpuArray / gather calls remain available for MATLAB compatibility or when you need deterministic residency control.
Examples
Computing the phase of a complex scalar
z = 3 + 4i;
theta = angle(z);
disp(theta)Expected output:
theta = 0.9273Extracting angles from a complex vector
Z = [1+1i, -1+1i, -1-1i, 1-1i];
phases = angle(Z);
disp(phases)Expected output:
phases = [0.7854 2.3562 -2.3562 -0.7854]Determining angles of negative real numbers
vals = [-2 -1 0 1 2];
phi = angle(vals);
disp(phi)Expected output:
phi = [3.1416 3.1416 0 0 0]Working with GPU-resident arrays
G = gpuArray([1 -1; -1 1]);
theta = gather(angle(G));
disp(theta)Expected output:
theta =
0.0000 3.1416
3.1416 0.0000Using angle with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how angle changes the result.
Run a small angle example, explain the result, then change one input and compare the output.
FAQ
Does angle return values in radians?⌄
Yes. Results are reported in radians within the interval [-π, π], matching MATLAB's definition.
What happens with zeros?⌄
angle(0) returns 0. Complex zeros (0 + 0i) also yield 0.
How does angle handle NaN inputs?⌄
NaNs propagate. angle(NaN) evaluates to NaN, honoring IEEE arithmetic.
Can I pass integers, logical arrays, character arrays, or strings to angle?⌄
No. The supported input classes are single and double, with real or complex values. Convert unsupported data explicitly when that conversion expresses the intended calculation.
Does angle allocate a new array?⌄
Yes. The builtin produces a dense array with the input's single or double precision. Fusion may eliminate the allocation when the surrounding expression can be fused safely.
What about GPU execution for complex tensors?⌄
Host complex tensors execute on the CPU. Complex-interleaved gpuArrays stay GPU-resident when the active provider implements unary_angle, computing the phase angle directly on device.
Will GPU results match CPU results exactly?⌄
Yes for double-precision providers. Single-precision backends may exhibit minor rounding differences, but they remain within typical IEEE tolerance.
Related Math functions
Elementwise
abs · 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 · realsqrt · 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 angle is executed, line by line, in Rust.
- View the source for angle 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.