Skip to content

f64::atan2 documentation error #136275

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gantha-shiva opened this issue Jan 30, 2025 · 4 comments · May be fixed by #140487
Open

f64::atan2 documentation error #136275

gantha-shiva opened this issue Jan 30, 2025 · 4 comments · May be fixed by #140487
Assignees
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-floating-point Area: Floating point numbers and arithmetic C-bug Category: This is a bug. E-easy Call for participation: Easy difficulty. Experience needed to fix: Not much. Good first issue. T-libs Relevant to the library team, which will review and decide on the PR/issue.

Comments

@gantha-shiva
Copy link

gantha-shiva commented Jan 30, 2025

Location

library/std/src/f64.rs:793

Summary

The f64::atan2 function documentation specifies that the output could be in the range (-PI, PI]. However its not true. It could return -PI as well.
Following is from the function documentation:

/// * `x = 0`, `y = 0`: `0`
/// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]`
/// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]`
/// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`

Example case:
f64::atan2(-0.0, -1.0) returns -f64::PI

@gantha-shiva gantha-shiva added the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label Jan 30, 2025
@rustbot rustbot added the needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. label Jan 30, 2025
@saethlin saethlin added C-bug Category: This is a bug. T-libs Relevant to the library team, which will review and decide on the PR/issue. and removed needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. labels Jan 30, 2025
@fmease fmease added the A-floating-point Area: Floating point numbers and arithmetic label Jan 30, 2025
@GrigorenkoPV
Copy link
Contributor

From my testing, f32::atan2(y, x).is_sign_positive() == y.is_sign_positive(). I was even able to make kani prove that for the libm implementation.

use kani::*;

#[kani::proof]
fn nan() {
    let x: f32 = any();
    let y: f32 = any();
    assume(x.is_nan() || y.is_nan());
    let res = libm::atan2f(y, x);
    assert!(res.is_nan());
}

#[kani::proof]
fn atan2() {
    let x: f32 = any();
    assume(!x.is_nan());
    let y: f32 = any();
    assume(!y.is_nan());
    let res = libm::atan2f(y, x);
    assert!(res.is_finite());
    assert_eq!(res.is_sign_positive(), y.is_sign_positive());
    assert!(res <= core::f32::consts::PI);
    assert!(res >= -core::f32::consts::PI);
}

@rustbot claim

I think I'll put up a PR adjusting documentation.

@lolbinarycat
Copy link
Contributor

triage: @GrigorenkoPV still planning on working on this?

also note that this should be updated for other float types too (f16, f32, and f128)

@GrigorenkoPV
Copy link
Contributor

triage: @GrigorenkoPV still planning on working on this?

I do, but not sure when I will have time, so I should probably unclaim this for now.

@rustbot release-assignment

Also, I think the fix here is pretty easy: as I see it, one just needs to mention that the sign of the result is the same as the sign of the first argument, and that -0 & +0 both exist with floats and are two slightly different things.

So probably just specify the output ranges for four of the cases:
x >= +0, y >= +0
x <= -0, y >= +0
x >= +0, y <= -0
x <= -0, y <= -0

@rustbot label +E-easy

@rustbot rustbot added the E-easy Call for participation: Easy difficulty. Experience needed to fix: Not much. Good first issue. label Apr 14, 2025
@whirlwindaster
Copy link

@rustbot claim

@whirlwindaster whirlwindaster linked a pull request Apr 29, 2025 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-floating-point Area: Floating point numbers and arithmetic C-bug Category: This is a bug. E-easy Call for participation: Easy difficulty. Experience needed to fix: Not much. Good first issue. T-libs Relevant to the library team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

7 participants