acos
Returns the arc cosine of a number in radians, the inverse of cos().
acos(float $num): float- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$num | float | The argument to process. Values outside the range -1 to 1 produce NAN. |
Return value
floatThe arc cosine of num in radians, in the range 0 to PI. Returns NAN when num is outside -1 to 1.
Errors
Throws a TypeError if num cannot be coerced to float. Out-of-domain values return NAN instead of throwing.
acos() answers the question "which angle has this cosine?". It is the inverse of cos(), and it returns radians between 0 and M_PI — that is, 0 to 180 degrees. Wrap the result in rad2deg() when you need degrees.
When to reach for it
Two situations dominate. The first is recovering an angle from a ratio you already computed: the law of cosines, the angle between two vectors from their normalised dot product, or turning a cosine-similarity score into an angular distance. The second is great-circle distance, where acos() converts the dot product of two unit vectors on a sphere into a central angle you multiply by the Earth's radius.
What trips people up
The domain is strictly -1 to 1. Floating point arithmetic routinely produces 1.0000000000000002 from a dot product that should be exactly 1, and acos() then returns NAN rather than 0. Clamp the input first with max(-1.0, min(1.0, $x)). Once NAN enters your data every downstream sum and comparison is contaminated, and NAN == NAN is false, so you must test with is_nan().
Because the range stops at PI, acos() can never tell you which side of a line an angle falls on. Use atan2() when direction matters.
Example
When to use it
- Find the angle between two vectors from their normalised dot product.
- Compute the third angle of a triangle from its three side lengths using the law of cosines.
- Turn a cosine-similarity score from a search index into an angular distance in degrees.
Frequently asked questions
Why does acos() return NAN?
Because the argument was outside the range -1 to 1, which is the only domain the arc cosine is defined on. This usually comes from floating point rounding in a dot product, so clamp the value with max(-1.0, min(1.0, $x)) before calling acos().
How do I get degrees instead of radians from acos()?
Pass the result through rad2deg(), for example rad2deg(acos(0.5)) gives 60. PHP's trigonometric functions all work in radians.
What is the difference between acos() and acosh()?
acos() is the inverse of the circular cosine and accepts values from -1 to 1, returning an angle. acosh() is the inverse of the hyperbolic cosine and accepts values of 1 or more, returning a hyperbolic angle — they are unrelated curves.
More examples
Angle from the law of cosines
For a 3-4-5 triangle the cosine of the angle opposite side c works out to exactly 0, and acos(0) is PI/2, so the output is 90 degrees — the expected right angle.
<?php
$a = 3.0;
$b = 4.0;
$c = 5.0;
$cosC = ($a ** 2 + $b ** 2 - $c ** 2) / (2 * $a * $b);
echo round(rad2deg(acos($cosC)), 1), " degrees", PHP_EOL;Clamp before calling acos()
The raw value is a hair above 1, so acos() returns float(NAN). After clamping to 1.0 the result is 0, the correct angle for identical vectors. The last line shows is_nan() is how you detect the failure, since NAN == NAN is false.
<?php
$dot = 1.0000000002; // rounding error from a dot product
var_dump(acos($dot));
$safe = max(-1.0, min(1.0, $dot));
echo acos($safe), PHP_EOL;
var_dump(is_nan(acos($dot)));
Discussion