Skip to content

Name what ln_gamma does #114754

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Aug 25, 2023
Merged

Name what ln_gamma does #114754

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion library/std/src/f32.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -978,7 +978,9 @@ impl f32 {
unsafe { cmath::tgammaf(self) }
}

/// Returns the natural logarithm of the gamma function.
/// Natural logarithm of the absolute value of the gamma function
///
/// The integer part of the tuple indicates the sign of the gamma function.
Comment on lines +981 to +983
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be okay to merge this as-is, but since it's worth explaining why this sign is useful in the first place, I decided to write up an explanation about how this can be used to compute the complex-valued logarithm from the returned value:

Suggested change
/// Natural logarithm of the absolute value of the gamma function
///
/// The integer part of the tuple indicates the sign of the gamma function.
/// Natural logarithm of the absolute value of the gamma function.
///
/// Since the gamma function can be negative, its natural logarithm could
/// be complex-valued and thus not normally representable. While the
/// standard library doesn't offer any means to deal with complex values,
/// this function still offers the real part of the resulting complex
/// logarithm, which is equivalent to the logarithm of the absolute value
/// of the input.
///
/// To help construct the full complex value, the sign of the computed gamma
/// function before taking the natural logarithm is offered as a second
/// return value, which can trivially be converted into an imaginary part
/// by multiplying by [`f32::PI`].

(Note that I say "an imaginary part" since the complex logarithm may add additional factors of 2pi, but that's not super important to say here. So, I am still remaining correct while not worrying anyone about it who doesn't really care.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also worth mentioning if you do like this and want to copy it to the f64 version, you should change the link to f32::PI to f64::PI.

This also is an indication of why returning the sign as a float instead of an int might be preferable, as discussed on the issue.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I omitted the period on the initial line because it's not actually a complete sentence, nor does it need to be.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "the sign [...] is offered as a second return value" needs explanation, i.e. -- this returns 1 on positive (or 0) gamma values and -1 on negative values.

Also while we are at it, do we want to change the sign to be represented as an f32? Otherwise it will require somewhat awkward explicit conversion back to a float type.

///
/// # Examples
///
Expand Down
4 changes: 3 additions & 1 deletion library/std/src/f64.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -978,7 +978,9 @@ impl f64 {
unsafe { cmath::tgamma(self) }
}

/// Returns the natural logarithm of the gamma function.
/// Natural logarithm of the absolute value of the gamma function
///
/// The integer part of the tuple indicates the sign of the gamma function.
///
/// # Examples
///
Expand Down