In
computing
Computing is any goal-oriented activity requiring, benefiting from, or creating computing machinery. It includes the study and experimentation of algorithmic processes, and development of both hardware and software. Computing has scientific, ...
and
mathematics, the
function
Function or functionality may refer to:
Computing
* Function key, a type of key on computer keyboards
* Function model, a structured representation of processes in a system
* Function object or functor or functionoid, a concept of object-oriente ...
atan2 is the 2-
argument arctangent. By definition,
is the
angle measure
In Euclidean geometry, an angle is the figure formed by two rays, called the '' sides'' of the angle, sharing a common endpoint, called the ''vertex'' of the angle.
Angles formed by two rays lie in the plane that contains the rays. Angles ar ...
(in
radian
The radian, denoted by the symbol rad, is the unit of angle in the International System of Units (SI) and is the standard unit of angular measure used in many areas of mathematics. The unit was formerly an SI supplementary unit (before tha ...
s, with
) between the positive
-axis and the
ray from the
origin to the point
in the
Cartesian plane
A Cartesian coordinate system (, ) in a plane is a coordinate system that specifies each point uniquely by a pair of numerical coordinates, which are the signed distances to the point from two fixed perpendicular oriented lines, measured in ...
. Equivalently,
is the
argument (also called ''phase'' or ''angle'') of the
complex number
In mathematics, a complex number is an element of a number system that extends the real numbers with a specific element denoted , called the imaginary unit and satisfying the equation i^= -1; every complex number can be expressed in the fo ...
The
function first appeared in the programming language
Fortran in 1961. It was originally intended to return a correct and unambiguous value for the angle in converting from Cartesian coordinates to
polar coordinates
In mathematics, the polar coordinate system is a two-dimensional coordinate system in which each point on a plane is determined by a distance from a reference point and an angle from a reference direction. The reference point (analogous to th ...
. If
and
, then
and
If , the desired angle measure is
However, when , the angle
is
diametrically opposite
In mathematics, antipodal points of a sphere are those diametrically opposite to each other (the specific qualities of such a definition are that a line drawn from the one to the other passes through the center of the sphere so forms a true d ...
the desired angle, and ± (a half
turn) must be added to place the point in the correct
quadrant. Using the
function does away with this correction, simplifying code and mathematical formulas.
Motivation
The ordinary single-argument
arctangent function only returns angle measures in the interval
and when invoking it to find the angle measure between the -axis and an arbitrary vector in the
Cartesian plane, there is no simple way to indicate a direction in the left half-plane (that is, a point
with
).
Diametrically opposite
In mathematics, antipodal points of a sphere are those diametrically opposite to each other (the specific qualities of such a definition are that a line drawn from the one to the other passes through the center of the sphere so forms a true d ...
angle measures have the same tangent because
so the tangent
is not in itself sufficient to uniquely specify an angle.
To determine an angle measure using the arctangent function given a point or vector
mathematical formulas or computer code must handle multiple cases; at least one for positive values of
and one for negative values of
and sometimes additional cases when
is negative or one coordinate is zero. Finding angle measures and converting Cartesian to
polar coordinates
In mathematics, the polar coordinate system is a two-dimensional coordinate system in which each point on a plane is determined by a distance from a reference point and an angle from a reference direction. The reference point (analogous to th ...
are common in scientific computing, and this code is redundant and error-prone.
To remedy this, computer
programming language
A programming language is a system of notation for writing computer programs. Most programming languages are text-based formal languages, but they may also be graphical. They are a kind of computer language.
The description of a programming ...
s introduced the function, at least as early as the
Fortran IV language of the 1960s. The quantity is the angle measure between the -axis and a ray from the origin to a point anywhere in the Cartesian plane. The
signs of and are used to determine the
quadrant of the result and select the correct branch of the
multivalued function
In mathematics, a multivalued function, also called multifunction, many-valued function, set-valued function, is similar to a function, but may associate several values to each input. More precisely, a multivalued function from a domain to a ...
.
The function is useful in many applications involving
Euclidean vector
In mathematics, physics, and engineering, a Euclidean vector or simply a vector (sometimes called a geometric vector or spatial vector) is a geometric object that has magnitude (or length) and direction. Vectors can be added to other vectors ...
s such as finding the direction from one point to another or converting a
rotation matrix In linear algebra, a rotation matrix is a transformation matrix that is used to perform a rotation in Euclidean space. For example, using the convention below, the matrix
:R = \begin
\cos \theta & -\sin \theta \\
\sin \theta & \cos \theta
\en ...
to
Euler angles.
The function is now included in many other programming languages, and is also commonly found in mathematical formulas throughout science and engineering.
Argument order
In 1961, Fortran introduced the function with argument order
so that the
argument (phase angle) of a complex number is
This follows the left-to-right order of a fraction written
so that
for positive values of
However, this is the opposite of the conventional component order for complex numbers,
or as coordinates
See section
Definition and computation
A definition is a statement of the meaning of a term (a word, phrase, or other set of symbols). Definitions can be classified into two large categories: intensional definitions (which try to give the sense of a term), and extensional definitio ...
.
Some other programming languages (see §
Realizations of the function in common computer languages
Realization or realisation may refer to:
* ''Realization'' (album), a 1973 album by Eddie Henderson
* ''Realization'' (climb), a sport climbing route in Ceüse, France
* Realization (figured bass), the creating of a musical accompaniment from a ...
) picked the opposite order instead. For example
Microsoft Excel
Microsoft Excel is a spreadsheet developed by Microsoft for Windows, macOS, Android and iOS. It features calculation or computation capabilities, graphing tools, pivot tables, and a macro programming language called Visual Basic for App ...
uses
OpenOffice Calc uses
and
Mathematica uses
defaulting to one-argument arctangent if called with one argument.
Definition and computation
The function computes the
principal value of the
argument function applied to the
complex number
In mathematics, a complex number is an element of a number system that extends the real numbers with a specific element denoted , called the imaginary unit and satisfying the equation i^= -1; every complex number can be expressed in the fo ...
. That is, . The argument could be changed by an arbitrary multiple of (corresponding to a complete turn around the origin) without making any difference to the angle, but to define uniquely one uses the principal value in the
range , that is, .
In terms of the standard function, whose range is , it can be expressed as follows to define a surface that has no discontinuities except along the semi-infinite line x<0 y=0:
A compact expression with four overlapping half-planes is
The
Iverson bracket notation allows for an even more compact expression:
[ Assuming the definitions and
for any ]
Formula without apparent
conditional construct:
The following expression derived from the
tangent half-angle formula can also be used to define :
This expression may be more suited for symbolic use than the definition above. However it is unsuitable for general
floating-point computational use, as the effect of rounding errors in
expand near the region (this may even lead to a division of ''y'' by zero).
A variant of the last formula that avoids these inflated rounding errors:
Notes:
* This produces results in the range .
[One can apply the periodicity of the result to map to another desired range, e.g. mapping to by adding to the negative results.]
* As mentioned above, the principal value of the argument can be related to by trigonometry. The derivation goes as follows: If , then . It follows that
Note that in the domain in question.
Derivative
As the function is a function of two variables, it has two
partial derivatives. At points where these derivatives exist, is, except for a constant, equal to . Hence for or ,
:
Thus the
gradient
In vector calculus, the gradient of a scalar-valued differentiable function of several variables is the vector field (or vector-valued function) \nabla f whose value at a point p is the "direction and rate of fastest increase". If the gr ...
of atan2 is given by
:
Informally representing the function as the angle function (which is only defined up to a constant) yields the following formula for the
total differential
In calculus, the differential represents the principal part of the change in a function ''y'' = ''f''(''x'') with respect to changes in the independent variable. The differential ''dy'' is defined by
:dy = f'(x)\,dx,
where f'(x) is the ...
:
:
While the function is discontinuous along the negative -axis, reflecting the fact that angle cannot be continuously defined, this derivative is continuously defined except at the origin, reflecting the fact that infinitesimal (and indeed local) ''changes'' in angle can be defined everywhere except the origin. Integrating this derivative along a path gives the total change in angle over the path, and integrating over a closed loop gives the
winding number
In mathematics, the winding number or winding index of a closed curve in the plane around a given point is an integer representing the total number of times that curve travels counterclockwise around the point, i.e., the curve's number of t ...
.
In the language of
differential geometry, this derivative is a
one-form
In differential geometry, a one-form on a differentiable manifold is a smooth section of the cotangent bundle. Equivalently, a one-form on a manifold M is a smooth mapping of the total space of the tangent bundle of M to \R whose restriction to e ...
, and it is
closed (its derivative is zero) but not
exact (it is not the derivative of a 0-form, i.e., a function), and in fact it generates the first
de Rham cohomology of the
punctured plane
This is a glossary of some terms used in the branch of mathematics known as topology. Although there is no absolute distinction between different areas of topology, the focus here is on general topology. The following definitions are also funda ...
. This is the most basic example of such a form, and it is fundamental in differential geometry.
The partial derivatives of do not contain trigonometric functions, making it particularly useful in many applications (e.g. embedded systems) where trigonometric functions can be expensive to evaluate.
Illustrations
This figure shows values of atan2 along selected rays from the origin, labelled at the unit circle. The values, in radians, are shown inside the circle. The diagram uses the standard mathematical convention that angles increase
counterclockwise
Two-dimensional rotation can occur in two possible directions. Clockwise motion (abbreviated CW) proceeds in the same direction as a clock's hands: from the top to the right, then down and then to the left, and back up to the top. The opposite ...
from zero along the ray to the right. Note that the order of arguments is reversed; the function computes the angle corresponding to the point .
This figure shows the values of
along with
for
. Both functions are odd and periodic with periods
and
, respectively, and thus can easily be supplemented to any region of real values of
. One can clearly see the
branch cuts of the
-function at
, and of the
-function at
.
The two figures below show 3D views of respectively and over a region of the plane. Note that for , ''rays'' in the ''X''/''Y''-plane emanating from the origin have constant values, but for ''lines'' in the ''X''/''Y''-plane passing through the origin have constant values. For , the two diagrams give identical values.
Angle sum and difference identity
Sums of
may be collapsed into a single operation according to the following identity
:
...provided that
.
The proof involves considering two cases, one where
or
and one where
and
.
We only consider the case where
or
. To start, we make the following observations:
#
provided that
or
.
#
, where
is the
Argument (complex analysis)#Computation, complex argument function.
#
whenever
, a consequence of
Euler's formula
Euler's formula, named after Leonhard Euler, is a mathematical formula in complex analysis that establishes the fundamental relationship between the trigonometric functions and the complex exponential function. Euler's formula states that fo ...
.
#
.
To see (4), we have the
identity where
, hence
. Furthermore, since
for any positive real value
, then if we let
and
then we have
.
From these observations have following equivalences:
:
Corollary: if
and
are 2-dimensional vectors, the difference formula is frequently used in practice to compute the angle between those vectors with the help of
, since the resulting computation behaves benign in the range
and can thus be used without range checks in many practical situations.
East-counterclockwise, north-clockwise and south-clockwise conventions, etc.
The
function was originally designed for the convention in pure mathematics that can be termed ''east-counterclockwise''. In practical applications, however, the ''north-clockwise'' and ''south-clockwise'' conventions are often the norm. In atmospheric sciences, for instance, the
wind direction
Wind direction is generally reported by the direction from which it originates. For example, a ''north'' or ''northerly'' wind blows from the north to the south. The exceptions are onshore winds (blowing onto the shore from the water) and offsho ...
can be calculated using the
function with the east- and north-components of the wind vector as its arguments; the
solar azimuth angle can be calculated similarly with the east- and north-components of the solar vector as its arguments. The wind direction is normally defined in the north-clockwise sense, and the solar azimuth angle uses both the north-clockwise and south-clockwise conventions widely. These different conventions can be realized by swapping the positions and changing the signs of the x- and y-arguments as follows:
*
(East-Counterclockwise Convention)
*
(North-Clockwise Convention)
*
. (South-Clockwise Convention)
As an example, let
and
, then the east-counterclockwise format gives
, the north-clockwise format gives
, and the south-clockwise format gives
.
Apparently, changing the sign of the x- and/or y-arguments and swapping their positions can create 8 possible variations of the
function and they, interestingly, correspond to 8 possible definitions of the angle, namely, clockwise or counterclockwise starting from each of the 4
cardinal directions, north, east, south and west.
Realizations of the function in common computer languages
The realization of the function differs from one computer language to another:
* In
Microsoft Excel
Microsoft Excel is a spreadsheet developed by Microsoft for Windows, macOS, Android and iOS. It features calculation or computation capabilities, graphing tools, pivot tables, and a macro programming language called Visual Basic for App ...
,
OpenOffice.org Calc
OpenOffice.org (OOo), commonly known as OpenOffice, is a discontinued open-source office suite. Active successor projects include LibreOffice (the most actively developed), Apache OpenOffice, Collabora Online (enterprise ready LibreOffice) a ...
,
LibreOffice Calc
LibreOffice Calc is the spreadsheet component of the LibreOffice software package.
After forking from OpenOffice.org in 2010, LibreOffice Calc underwent a massive re-work of external reference handling to fix many defects in formula calculation ...
,
Google Spreadsheets,
iWork Numbers, and
ANSI SQL:2008 standard, the 2-argument arctangent function has the two arguments in the standard sequence
(reversed relative to the convention used in the discussion above).
* In
Mathematica, the form
ArcTan 'x'', ''y''/code> is used where the one parameter form supplies the normal arctangent. Mathematica classifies ArcTan , 0/code> as an indeterminate expression.
* On most TI graphing calculators (excluding the TI-85
The TI-85 is a graphing calculator made by Texas Instruments based on the Zilog Z80 microprocessor. Designed in 1992 as TI's second graphing calculator (the first was the TI-81), it was replaced by the TI-86, which has also been discontinued ...
and TI-86
The TI-86 is a programmable graphing calculator introduced in 1996 which was produced by Texas Instruments. The TI-86 uses the Zilog Z80 microprocessor. It is partially backwards-compatible with its predecessor, the TI-85.
In addition to ha ...
), the equivalent function is called R►Pθ and has the arguments .
* On TI-85 the function is called angle(x,y)
and although it appears to take two arguments, it really only has one complex argument which is denoted by a pair of numbers: .
The convention is used by:
* The C function atan2
, and most other computer implementations, are designed to reduce the effort of transforming cartesian to polar coordinates and so always define atan2(0, 0)
. On implementations without signed zero
Signed zero is zero with an associated sign. In ordinary arithmetic, the number 0 does not have a sign, so that −0, +0 and 0 are identical. However, in computing, some number representations allow for the existence of two zeros, often denoted by ...
, or when given positive zero arguments, it is normally defined as 0. It will always return a value in the range rather than raising an error or returning a NaN
Nan or NAN may refer to:
Places China
* Nan County, Yiyang, Hunan, China
* Nan Commandery, historical commandery in Hubei, China
Thailand
* Nan Province
** Nan, Thailand, the administrative capital of Nan Province
* Nan River
People Given name
...
(Not a Number).
* In Common Lisp, where optional arguments exist, the atan
function allows one to optionally supply the ''x'' coordinate: (atan ''y'' ''x'')
.
* In Julia
Julia is usually a feminine given name. It is a Latinate feminine form of the name Julio and Julius. (For further details on etymology, see the Wiktionary entry "Julius".) The given name ''Julia'' had been in use throughout Late Antiquity (e.g ...
, the situation is similar to Common Lisp: instead of atan2
, the language has a one-parameter and a two-parameter form for atan
. However, it has many more than two methods, to allow for aggressive optimisation at compile time (see the section "Why don't you compile Matlab/Python/R/… code to Julia?" ).
* For systems implementing signed zero
Signed zero is zero with an associated sign. In ordinary arithmetic, the number 0 does not have a sign, so that −0, +0 and 0 are identical. However, in computing, some number representations allow for the existence of two zeros, often denoted by ...
, infinities, or Not a Number (for example, IEEE floating point
The IEEE Standard for Floating-Point Arithmetic (IEEE 754) is a technical standard for floating-point arithmetic established in 1985 by the Institute of Electrical and Electronics Engineers (IEEE). The standard addressed many problems found in ...
), it is common to implement reasonable extensions which may extend the range of values produced to include − and −0 when = −0. These also may return NaN or raise an exception when given a NaN argument.
* In the Intel x86 Architecture assembler code, atan2
is known as the FPATAN
(floating-point partial arctangent) instruction. It can deal with infinities and results lie in the closed interval , e.g. atan2(∞, ''x'')
= +/2 for finite ''x''. Particularly, FPATAN
is defined when both arguments are zero:
*: atan2(+0, +0)
= +0;
*: atan2(+0, −0)
= +;
*: atan2(−0, +0)
= −0;
*: atan2(−0, −0)
= −.
: This definition is related to the concept of signed zero
Signed zero is zero with an associated sign. In ordinary arithmetic, the number 0 does not have a sign, so that −0, +0 and 0 are identical. However, in computing, some number representations allow for the existence of two zeros, often denoted by ...
.
* In mathematical writings other than source code, such as in books and articles, the notations Arctan and Tan−1 have been utilized; these are capitalized variants of the regular arctan and tan−1. This usage is consistent with the complex argument notation, such that .
* On HP calculators, treat the coordinates as a complex number and then take the ARG
. Or << C->R ARG >> 'ATAN2' STO
.
* On scientific calculators the function can often be calculated as the angle given when is converted from rectangular coordinates
A Cartesian coordinate system (, ) in a plane is a coordinate system that specifies each point uniquely by a pair of numerical coordinates, which are the signed distances to the point from two fixed perpendicular oriented lines, measured in ...
to polar coordinates
In mathematics, the polar coordinate system is a two-dimensional coordinate system in which each point on a plane is determined by a distance from a reference point and an angle from a reference direction. The reference point (analogous to th ...
.
* Systems supporting symbolic mathematics normally return an undefined value for or otherwise signal that an abnormal condition has arisen.
* The free math library FDLIBM (Freely Distributable LIBM) available from netlib has source code showing how it implements atan2
including handling the various IEEE exceptional values.
* For systems without a hardware multiplier the function can be implemented in a numerically reliable manner by the CORDIC
CORDIC (for "coordinate rotation digital computer"), also known as Volder's algorithm, or: Digit-by-digit method Circular CORDIC (Jack E. Volder), Linear CORDIC, Hyperbolic CORDIC (John Stephen Walther), and Generalized Hyperbolic CORDIC (GH C ...
method. Thus implementations of will probably choose to compute .
See also
* hypot
References
External links
ATAN2 Online calculator
atan2
at Everything2
PicBasic Pro solution
atan2 for a PIC18F
;Other implementations/code for atan2
*
*
*
Notes
{{Trigonometric and hyperbolic functions
Inverse trigonometric functions