RunMat
GitHub

View all functions

CategoryMath: Elementwise
GPUYes

What does the angle function do in MATLAB / RunMat?

angle(x) returns the phase angle (argument) of each element in x. The values are reported in radians and match MATLAB semantics exactly.

How does the angle function behave in MATLAB / RunMat?

  • 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 return 0.
  • Logical inputs are promoted to doubles (true → 1, false → 0) before computing the angle.
  • Results are always returned as dense double-precision arrays that preserve the shape of the input.
  • Character arrays are interpreted as their numeric code points and produce double arrays of the same size.
  • String arrays are unsupported and raise an error, mirroring MATLAB.
  • NaN propagation follows IEEE rules: angle(NaN) returns NaN.

angle Function GPU Execution Behaviour

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 the same atan2(imag, real) logic as the host path. If the hook is missing—or if the input requires host-side conversions such as complex tensors—RunMat gathers the data, evaluates the phase angle on the CPU, and then honors any downstream fusion or residency decisions automatically.

Examples of using the angle function in MATLAB / RunMat

Computing the phase of a complex scalar

z = 3 + 4i;
theta = angle(z);
disp(theta);

Expected output:

theta = 0.9273;

Extracting 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+1i, -1-1i; -1+1i, 1-1i]);
thetaGPU = angle(G);
theta = gather(thetaGPU);
disp(theta);

Expected output:

theta =

     0.7854   -2.3562
     2.3562    0.7854

When the provider implements unary_angle, the intermediate thetaGPU tensor stays resident on the device and only the explicit gather brings the result back.

Angles of character code arrays

C = ['A' 'B'; 'C' 'D'];
codes = angle(C);
disp(codes);

Expected output:

codes = [0 0; 0 0];

Angles from logical masks

mask = logical([0 1; 1 0]);
phaseMask = angle(mask);
disp(phaseMask);

Expected output:

phaseMask = [0 0; 0 0];

GPU residency in RunMat (Do I need gpuArray?)

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.

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 string arrays to angle?

No. Like MATLAB, angle supports numeric, logical, or character data. Convert strings with double(string) if you need numeric codes first.

Does angle allocate a new array?

Yes. The builtin produces a dense double array. Fusion may eliminate the allocation when the surrounding expression can be fused safely.

What about GPU execution for complex tensors?

Complex runtime tensors currently live on the host. RunMat gathers them automatically, computes the phase angle, and resumes execution. Future providers may add native complex kernels without changing this builtin.

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.

See Also

abs, imag, real, sign, gpuArray, gather

Source & Feedback