atan2 — Compute a real four-quadrant inverse tangent in radians.
atan2 combines both coordinate signs, applies implicit expansion, preserves supported floating precision and container identity, and validates provider-resident execution.
Syntax
Z = atan2(Y, X)Inputs
Y- Type
Any- Required
- Yes
- Description
- Real single, double, table, or timetable y-coordinate; integer, logical, and character forms are RunMat extensions.
X- Type
Any- Required
- Yes
- Description
- Compatible real x-coordinate or scalar-expansion operand.
Returns
Z- Type
NumericArray- Description
- Four-quadrant angle in radians with the broadcasted input shape.
Errors
RunMat:atan2:InvalidInput- When
- An input is not a supported real numeric, logical, character, table, or timetable value, or paired tabular inputs do not have compatible containers and variables.
- Message
atan2: invalid input
RunMat:atan2:ComplexUnsupported- When
- At least one operand is complex.
- Message
atan2: complex inputs are not supported
RunMat:atan2:SizeMismatch- When
- Numeric operands are not broadcast-compatible.
- Message
atan2: input sizes are not compatible for implicit expansion
Angles, quadrants, and signed zero
atan2(Y, X) computes the four-quadrant inverse tangent of the coordinate pair (X, Y) element by element. Results are radians in the closed interval [-pi, pi]; using both coordinate signs distinguishes quadrants that atan(Y ./ X) cannot.
RunMat follows MATLAB's signed-zero convention. atan2(0, -0) and atan2(-0, -0) return positive zero, while atan2(-0, 0) retains negative zero. NaN propagates and infinite coordinate pairs follow the corresponding quadrant limits.
Classes, shapes, and containers
Documented inputs are real single, double, table, or timetable values. Scalar, vector, matrix, and N-D numeric inputs use implicit expansion. A single input on either side selects single output; otherwise the numeric result is double. Complex and sparse inputs are not accepted.
Tables and timetables apply atan2 to corresponding variables and retain their container metadata. The two containers must have the same identity, variable names, and variable order; a compatible numeric scalar or array can supply the other operand.
RunMat mode also accepts all eight real fixed-width integer classes, logical arrays, and character arrays. Integer storage remains authoritative until the floating-point angle calculation. Logical values contribute zero or one and characters contribute their Unicode code points. These forms are rejected in MATLAB compatibility mode.
Accelerated, fused, and distributed execution
Real floating arrays may be placed on the CPU or a provider automatically. Shape-matched real floating operands owned by one provider can use its direct elem_atan2 operation. The returned handle is accepted only when its shape, real storage, precision, owner, device, and aliasing satisfy the contract. Only a typed unsupported result enters host fallback; other provider failures remain visible.
Broadcasting, mixed physical types, and admitted integer or logical storage gather through the exact owner, compute with the canonical host rule, and restore the floating result to that owner when possible. Real floating expressions may also participate in elementwise fusion, including the signed-zero correction.
Distributed inputs currently use the declared materialization path before the same canonical operation is applied. This preserves behavior without claiming a partition-local binary mapping primitive that the execution service does not yet provide.
Examples
Find the angle of a point
theta = atan2(4, 3)Expected output:
theta = 0.9273Resolve quadrants from coordinate signs
Y = [-1 0 1];
X = [-1 -1 -1];
angles = atan2(Y, X)Expected output:
angles = [-2.3562 3.1416 2.3562]Expand a denominator across a matrix
A = [1 2 3; 4 5 6];
angles = atan2(A, 2)Expected output:
angles has the same 2-by-3 shape as AApply the signed-zero convention
negativeZero = -0.0;
theta = atan2([0 negativeZero negativeZero], [negativeZero negativeZero 0])Expected output:
theta contains positive zero, positive zero, and negative zeroRetain single precision
Y = single([1 -1]);
P = atan2(Y, -2)Expected output:
P is a 1-by-2 single row vectorApply atan2 to table variables
Y = table([1; -1], [0; 1], 'VariableNames', {'A', 'B'});
P = atan2(Y, -1)Expected output:
P retains variables A and BUse character code points in RunMat mode
theta = atan2('A', 100)Expected output:
theta = 0.5764Compute four-quadrant angles on resident values
Gy = gpuArray([1 1; -1 -1]);
Gx = gpuArray([1 -1; 1 -1]);
anglesDevice = atan2(Gy, Gx);
angles = gather(anglesDevice)Expected output:
angles = [pi/4 3*pi/4; -pi/4 -3*pi/4]Using atan2 with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how atan2 changes the result.
Run a small atan2 example, explain the result, then change one input and compare the output.
FAQ
How is atan2 different from atan?⌄
atan2(Y, X) uses both coordinate signs to select a quadrant and returns angles in [-pi, pi]. atan(Y ./ X) loses that sign information and is limited to [-pi/2, pi/2].
Can atan2 accept complex input?⌄
No. Both operands must be real. Use angle(Z) or atan2(imag(Z), real(Z)) for a complex value.
What happens when X is zero?⌄
A positive Y returns pi/2, a negative Y returns -pi/2, and zero pairs follow the documented signed-zero convention.
Does atan2 preserve shape?⌄
The output has the shape produced by MATLAB-style implicit expansion of Y and X. Table and timetable forms retain their container identity and variable layout.
What class does atan2 return?⌄
A single input on either side selects single output; otherwise numeric output is double. RunMat integer, logical, and character extensions return double unless paired with single.
Can the result remain provider-resident?⌄
Yes. A valid direct provider result remains resident. Unsupported or broadcast forms gather through the exact owner and restore the result when its representation is supported.
How do I convert the result to degrees?⌄
Use rad2deg(atan2(Y, X)) or multiply by 180/pi.
Related Math functions
Trigonometry
acos · acosd · acosh · acotd · acscd · asecd · asin · asind · asinh · atan · atan2d · atand · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Elementwise
abs · angle · besselj · bsxfun · complex · conj · double · eps · erf · erfcinv · exp · expm1 · flintmax · gamma · gammaln · heaviside · hypot · imag · int16 · int32 · int64 · int8 · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · times · typecast · uint16 · uint32 · uint64 · uint8
Optim
acceptancesa · annealingboltz · annealingfast · coneprog · crossoverarithmetic · crossoverheuristic · crossoverintermediate · crossoverlaplace · crossoverscattered · crossoversinglepoint · crossovertwopoint · eqnproblem · EquationProblem.solve · EquationProblem.subsasgn · EquationProblem.subsref · evaluate · fgoalattain · fitscalingprop · fitscalingrank · fitscalingshiftlinear · fitscalingtop · fminbnd · fmincon · fminimax · fminsearch · fminunc · fseminf · fsolve · fzero · ga · gacreationlinearfeasible · gacreationnonlinearfeasible · gacreationsobol · gacreationuniform · gacreationuniformint · gaplotbestf · gaplotbestindiv · gaplotdistance · gaplotexpectation · gaplotgenealogy · gaplotmaxconstr · gaplotrange · gaplotscorediversity · gaplotscores · gaplotselection · gaplotstopping · integerConstraint · integral · intlinprog · linprog · lsqcurvefit · lsqlin · LsqlinWarmStart.subsasgn · LsqlinWarmStart.subsref · lsqnonlin · lsqnonneg · mutationadaptfeasible · mutationgaussian · mutationpositivebasis · mutationpower · mutationuniform · optimexpr · optimget · OptimizationConstraint.evaluate · OptimizationConstraint.subsasgn · OptimizationConstraint.subsref · OptimizationExitflag.double · OptimizationExitflag.eq · OptimizationExitflag.ne · OptimizationExitflag.string · OptimizationExpression.acos · OptimizationExpression.acosh · OptimizationExpression.acot · OptimizationExpression.acoth · OptimizationExpression.acsc · OptimizationExpression.acsch · OptimizationExpression.asec · OptimizationExpression.asech · OptimizationExpression.asin · OptimizationExpression.asinh · OptimizationExpression.atan · OptimizationExpression.atanh · OptimizationExpression.cat · OptimizationExpression.cos · OptimizationExpression.cosh · OptimizationExpression.cot · OptimizationExpression.coth · OptimizationExpression.csc · OptimizationExpression.csch · OptimizationExpression.ctranspose · OptimizationExpression.cumprod · OptimizationExpression.cumsum · OptimizationExpression.diag · OptimizationExpression.diff · OptimizationExpression.dot · OptimizationExpression.eq · OptimizationExpression.evaluate · OptimizationExpression.exp · OptimizationExpression.ge · OptimizationExpression.horzcat · OptimizationExpression.ldivide · OptimizationExpression.le · OptimizationExpression.log · OptimizationExpression.mean · OptimizationExpression.minus · OptimizationExpression.mldivide · OptimizationExpression.mpower · OptimizationExpression.mrdivide · OptimizationExpression.mtimes · OptimizationExpression.norm · OptimizationExpression.plus · OptimizationExpression.power · OptimizationExpression.prod · OptimizationExpression.rdivide · OptimizationExpression.reshape · OptimizationExpression.sec · OptimizationExpression.sech · OptimizationExpression.sin · OptimizationExpression.sinh · OptimizationExpression.sqrt · OptimizationExpression.subsasgn · OptimizationExpression.subsref · OptimizationExpression.sum · OptimizationExpression.tan · OptimizationExpression.tanh · OptimizationExpression.times · OptimizationExpression.trace · OptimizationExpression.transpose · OptimizationExpression.uminus · OptimizationExpression.uplus · OptimizationExpression.vertcat · OptimizationExpression.zeros · OptimizationExpression.zerosLike · OptimizationProblem.solve · OptimizationProblem.subsasgn · OptimizationProblem.subsref · OptimizationVariable.subsasgn · OptimizationVariable.subsref · optimoptions · optimplotconstrviolation · optimplotfirstorderopt · optimplotfunccount · optimplotfval · optimplotfvalconstr · optimplotmilp · optimplotstepsize · optimplotx · optimproblem · optimset · optimvar · optimwarmstart · particleswarm · patternsearch · psplotbestf · psplotbestx · psplotfuncount · psplotmaxconstr · psplotmeshsize · pswcreationuniform · pswplotbestf · quad · quadprog · QuadprogWarmStart.subsasgn · QuadprogWarmStart.subsref · saplotbestf · saplotbestx · saplotf · saplotstopping · saplottemperature · saplotx · savemilpsolutions · secondordercone · selectionremainder · selectionroulette · selectionstochunif · selectiontournament · selectionuniform · simulannealbnd · solve · surrogateopt · surrogateoptplot · temperatureboltz · temperatureexp · temperaturefast
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
Factor
chol · decomposition · decomposition.ctranspose · decomposition.mldivide · decomposition.mrdivide · decomposition.mtimes · decomposition.rdivide · decomposition.subsref · decomposition.times · decomposition.uminus · decomposition.uplus · eig · eigs · gmres · ichol · ilu · lu · ordeig · ordqz · ordschur · pcg · qr · qz · rsf2csf · schur · svd
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Interpolation
griddedInterpolant · griddedInterpolant.subsref · interp1 · interp1q · interp2 · pchip · ppval · spline
Integer Division
Source you can read
Every RunMat function's source is public. Read exactly how atan2 is executed, line by line, in Rust.
- View the source for atan2 in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.