User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:asin [2019/07/14 17:00]
cl:functions:asin [2019/07/17 21:00] (current)
Line 1: Line 1:
 +====== Function ASIN, ACOS, ATAN ======
 +
 +====Syntax====
 +  * **asin** //number// → //​radians// ​
 +  * **acos** //number// → //​radians// ​
 +  * **atan** //number1 ''&​optional''​ number2// → //radians//
 +
 +====Arguments and Values====
 +  * //number// - a //​[[CL:​Glossary:​number]]//​.
 +  * //number1// - a //​[[CL:​Glossary:​number]]//​ if //number2// is not supplied, or a //​[[CL:​Glossary:​real]]//​ if //number2// is supplied.
 +  * //number2// - a //​[[CL:​Glossary:​real]]//​.
 +  * //radians// - a //​[[CL:​Glossary:​number]]//​ (of radians).
 +
 +====Description====
 +
 +**asin**, **acos**, and **atan** compute the arc sine, arc cosine, and arc tangent respectively.
 +
 +The arc sine, arc cosine, and arc tangent (with only //number1// supplied) functions can be defined mathematically for //number// or //number1// specified as //x// as in the below table.
 +
 +^ Function ​   ^ Definition ​                                          ^
 +| Arc sine    | ''​-i * log(i * //x// + sqrt(1 - //​x//<​sup>​2</​sup>​))'' ​            |
 +| Arc cosine ​ | ''​(π / 2) - arcsin(//​x//​)'' ​                                      |
 +| Arc tangent | ''​-i * log((1 + i * //x//) * sqrt(1 / (1 + //​x//<​sup>​2</​sup>​)))''​ |
 +
 +These formulae are mathematically correct, assuming completely accurate computation. They are not necessarily the simplest ones for real-valued computations.
 +
 +If both //number1// and //number2// are supplied for **atan**, the result is the arc tangent of //​number1//<​nowiki>/</​nowiki>//​number2//​. The value of **atan** is always between ''​-π''​ (exclusive) and ''​π''​ (inclusive) when minus zero is not supported. The range of the two-argument arc tangent when minus zero is supported includes ''​-π''​.
 +
 +For a //​[[CL:​Glossary:​real]]//​ //​number1//,​ the result is a //​[[CL:​Glossary:​real]]//​ and lies between ''​-π/​2''​ and~''​π/​2''​ (both exclusive). //number1// can be a //​[[CL:​Glossary:​complex]]//​ if //number2// is not supplied. If both are supplied, //number2// can be zero provided //number1// is not zero. 
 +
 +The following definition for arc sine determines the range and branch cuts:
 +
 +<​blockquote>​
 +arcsin(//​z//​) = -i * log(i * //z// + sqrt(1 - //​z//<​sup>​2</​sup>​))
 +</​blockquote>​
 +
 +The branch cut for the arc sine function is in two pieces: one along the negative real axis to the left of~''​-1''​ (inclusive),​ continuous with quadrant II, and one along the positive real axis to the right of~''​1''​ (inclusive),​ continuous with quadrant IV. The range is that strip of the complex plane containing numbers whose real part is between ''​-π/​2''​ and~''​π/​2''​. A number with real part equal to ''​-π/​2''​ is in the range if and only if its imaginary part is non-negative;​ a number with real part equal to ''​π/​2''​ is in the range if and only if its imaginary part is non-positive.
 +
 +The following equivalent definitions for arc cosine determines the range and branch cuts:
 +
 +<​blockquote>​
 +//​arccos//​(//​z//​) = π / 2 - arcsin(//​z//​)
 +
 +//​arccos//​(//​z//​) = -i * log(z + i 8 sqrt(1 - z<​sup>​2</​sup>​))
 +
 +//​arccos//​(//​z//​) = (2 * log(sqrt((1 + //z//) / 2) + i * sqrt((1 - //z//) / 2))) / i
 +</​blockquote>​
 +
 +The branch cut for the arc cosine function is in two pieces: one along the negative real axis to the left of ''​-1''​ (inclusive),​ continuous with quadrant II, and one along the positive real axis to the right of ''​1''​ (inclusive),​ continuous with quadrant IV. This is the same branch cut as for arc sine. The range is that strip of the complex plane containing numbers whose real part is between 0 and~''​π''​. A number with real part equal to 0 is in the range if and only if its imaginary part is non-negative;​ a number with real part equal to ''​π''​ is in the range if and only if its imaginary part is non-positive.
 +
 +The following definition for (one-argument) arc tangent determines the range and branch cuts:
 +
 +<​blockquote>​
 +arctan(//​z//​) = (log(1 + i * z) - log(1 - i * z)) / 2 * i
 +</​blockquote>​
 +
 +Beware of simplifying this formula; "​obvious"​ simplifications are likely to alter the branch cuts or the values on the branch cuts incorrectly. The branch cut for the arc tangent function is in two pieces: one along the positive imaginary axis above ''​i''​ (exclusive),​ continuous with quadrant II, and one along the negative imaginary axis below ''​-i''​ (exclusive),​ continuous with quadrant IV. The points ''​i''​ and ''​-i''​ are excluded from the domain. The range is that strip of the complex plane containing numbers whose real part is between ''​-π/​2''​ and ''​π/​2''​. A number with real part equal to ''​-π/​2''​ is in the range if and only if its imaginary part is strictly positive; a number with real part equal to ''​π/​2''​ is in the range if and only if its imaginary part is strictly negative. Thus the range of arc tangent is identical to that of arc sine with the points ''​-π/​2''​ and ''​π/​2''​ excluded.
 +
 +For **atan**, the signs of //number1// (indicated as ''​x''​) and //number2// (indicated as ''​y''​) are used to derive quadrant information. The next table details various special cases.
 +
 +The asterisk (*) indicates that the entry in the figure applies to implementations that support minus zero.
 +
 +^   ^ ''​y''​ Condition ​ ^ ''​x''​ Condition ​ ^ Cartesian locus ^ Range of result ​          ^
 +|   | ''​y = 0'' ​       | ''​x > 0'' ​       | Positive x-axis |''​ 0'' ​                    |
 +| * | ''​y = +0'' ​      | ''​x > 0'' ​       | Positive x-axis |''​+0'' ​                    |
 +| * | ''​y = -0'' ​      | ''​x > 0'' ​       | Positive x-axis |''​-0'' ​                    |
 +|   | ''​y > 0'' ​       | ''​x > 0'' ​       | Quadrant I      |''​0 < //result// < π/​2'' ​  |
 +|   | ''​y > 0'' ​       | ''​x = 0'' ​       | Positive y-axis |''​π/​2'' ​                   |
 +|   | ''​y > 0'' ​       | ''​x < 0'' ​       | Quadrant II     ​|''​π/​2 < //result// < π'' ​  |
 +|   | ''​y = 0'' ​       | ''​x < 0'' ​       | Negative x-axis |''​ π'' ​                    |
 +| * | ''​y = +0'' ​      | ''​x < 0'' ​       | Negative x-axis |''​+π'' ​                    |
 +| * | ''​y = -0'' ​      | ''​x < 0'' ​       | Negative x-axis |''​-π'' ​                    |
 +|   | ''​y < 0'' ​       | ''​x < 0'' ​       | Quadrant III    |''​-π < //result// < -π/​2''​ |
 +|   | ''​y < 0'' ​       | ''​x = 0'' ​       | Negative y-axis |''​-π/​2'' ​                  |
 +|   | ''​y < 0'' ​       | ''​x > 0'' ​       | Quadrant IV     ​|''​-π/​2 < //result// < 0'' ​ |
 +|   | ''​y = 0'' ​       | ''​x = 0'' ​       | Origin ​         | undefined consequences ​   |
 +| * | ''​y = +0'' ​      | ''​x = +0'' ​      | Origin ​         |''​+0'' ​                    |
 +| * | ''​y = -0'' ​      | ''​x = +0'' ​      | Origin ​         |''​-0'' ​                    |
 +| * | ''​y = +0'' ​      | ''​x = -0'' ​      | Origin ​         |''​+π'' ​                    |
 +| * | ''​y = -0'' ​      | ''​x = -0'' ​      | Origin ​         |''​-π'' ​                    |
 +
 +====Examples====
 +<​blockquote>​
 +(asin 0) <​r>​0.0 </r>
 +(acos #c(0 1)) <​r>#​C(1.5707963267948966 -0.8813735870195432) </r>
 +(/ (atan 1 (sqrt 3)) 6) <​r>​0.087266 </r>
 +(atan #c(0 2)) <​r>#​C(-1.5707964 0.54930615) </r>
 +</​blockquote>​
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +**acos** and **asin** should signal an //​[[CL:​Glossary:​error]]//​ of type **[[CL:​Types:​type-error]]** if //number// is a //​[[CL:​Glossary:​number]]//​. **atan** should signal **[[CL:​Types:​type-error]]** if one argument is supplied and that argument is not a //​[[CL:​Glossary:​number]]//,​ or if two arguments are supplied and both of those arguments are not //​[[CL:​Glossary:​reals]]//​.
 +
 +**acos**, **asin**, and **atan** might signal **[[CL:​Types:​arithmetic-error]]**.
 +
 +====See Also====
 +  * **[[CL:​Functions:​log|Function LOG]]**
 +  * **[[CL:​Functions:​sqrt|Function SQRT]]**
 +  * {\secref\FloatSubstitutability}
 +
 +====Notes====
 +The result of either **asin** or **acos** can be a //​[[CL:​Glossary:​complex]]//​ even if //number// is not a //​[[CL:​Glossary:​complex]]//;​ this occurs when the absolute value of //number// is greater than one.
 +
 +\issue{COMPLEX-ATANH-BOGUS-FORMULA:​TWEAK-MORE} \issue{COMPLEX-ATAN-BRANCH-CUT:​TWEAK} \issue{REAL-NUMBER-TYPE:​X3J13-MAR-89} \issue{REAL-NUMBER-TYPE:​X3J13-MAR-89} \issue{COMPLEX-ATANH-BOGUS-FORMULA:​TWEAK-MORE} \issue{COMPLEX-ATAN-BRANCH-CUT:​TWEAK} \issue{IEEE-ATAN-BRANCH-CUT:​SPLIT} \issue{COMPLEX-ATAN-BRANCH-CUT:​TWEAK}