Skip to content

gh-101594: Resolve a disambiguation of math.e vs the Euler's number #102040

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

Closed
wants to merge 2 commits into from
Closed

gh-101594: Resolve a disambiguation of math.e vs the Euler's number #102040

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b21ba08
gh-101594: Resolve a disambiguation of math.e vs the Euler's number
skirpichev Feb 19, 2023
b067d35
Merge branch 'main' into euler-vs-math.e
skirpichev Feb 19, 2023
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
3 changes: 1 addition & 2 deletions Doc/library/cmath.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,7 @@ Power and logarithmic functions

.. function:: exp(x)

Return *e* raised to the power *x*, where *e* is the base of natural
logarithms.
Return the exponential function at *x*.
Copy link
Member

Choose a reason for hiding this comment

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

I don't think this is an improvement. "exponential function" is ambiguous - the function 10**x is an exponential function, for example. (Or at least, many US pre-calculus texts describe it as such.)

We could follow the C standard's lead and use the wording "the base-e exponential function".

Or we could leave as-is. I don't think the existing wording is likely to confuse anyone.

Copy link
Member Author

@skirpichev skirpichev Feb 19, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

"exponential function" is ambiguous - the function 10**x is an exponential function, for example.

Hmm, I wasn't aware. Perhaps, I've checked too few sources...
https://mathworld.wolfram.com/ExponentialFunction.html
https://en.wikipedia.org/wiki/Exponential_function
A&S
encyclopediaofmath
maple
functions.wolfram.com

Less common seems to be "the exponential of" (Mathematica, numpy, matlab, mpfr/mpc).

Or we could leave as-is. I don't think the existing wording is likely to confuse anyone.

You can decide:) Here it is: #101594. If you think that this will not confuse readers - then it's ok to be as-is.



.. function:: log(x[, base])
Expand Down
14 changes: 6 additions & 8 deletions Doc/library/math.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -364,9 +364,8 @@ Power and logarithmic functions

.. function:: exp(x)

Return *e* raised to the power *x*, where *e* = 2.718281... is the base
of natural logarithms. This is usually more accurate than ``math.e ** x``
or ``pow(math.e, x)``.
Return the exponential function at *x*. This is usually more accurate
Copy link
Member

Choose a reason for hiding this comment

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

Again, the new description is ambiguous; I think the existing description is better.

than ``math.e ** x``.


.. function:: exp2(x)
Expand All @@ -378,9 +377,8 @@ Power and logarithmic functions

.. function:: expm1(x)

Return *e* raised to the power *x*, minus 1. Here *e* is the base of natural
logarithms. For small floats *x*, the subtraction in ``exp(x) - 1``
can result in a `significant loss of precision
Return ``exp(x) - 1``. For small floats *x*, the direct subtraction
Copy link
Contributor

Choose a reason for hiding this comment

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

I find this first sentence misleading - it seems to suggest the Python expression exp(x) - 1 is returned. I think a words-only approach is best. Something like

Return the exponential function at *x*, minus 1.

With this change, I also don't think direct is needed.

Thoughts?

in ``exp(x) - 1`` can result in a `significant loss of precision
<https://en.wikipedia.org/wiki/Loss_of_significance>`_\; the :func:`expm1`
function provides a way to compute this quantity to full precision:

Expand All @@ -395,15 +393,15 @@ Power and logarithmic functions

.. function:: log(x[, base])

With one argument, return the natural logarithm of *x* (to base *e*).
With one argument, return the natural logarithm of *x*.

With two arguments, return the logarithm of *x* to the given *base*,
calculated as ``log(x)/log(base)``.


.. function:: log1p(x)

Return the natural logarithm of *1+x* (base *e*). The
Return the natural logarithm of *1+x*. The
result is calculated in a way which is accurate for *x* near zero.


Expand Down
6 changes: 3 additions & 3 deletions Modules/clinic/cmathmodule.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 2 additions & 4 deletions Modules/clinic/mathmodule.c.h
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions Modules/cmathmodule.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -546,12 +546,12 @@ static Py_complex exp_special_values[7][7];
/*[clinic input]
cmath.exp = cmath.acos

Return the exponential value e**z.
Return the exponential function at z.
[clinic start generated code]*/

static Py_complex
cmath_exp_impl(PyObject *module, Py_complex z)
/*[clinic end generated code: output=edcec61fb9dfda6c input=8b9e6cf8a92174c3]*/
/*[clinic end generated code: output=edcec61fb9dfda6c input=87f2c74ee9a8ad46]*/
{
Py_complex r;
double l;
Expand Down Expand Up @@ -957,12 +957,12 @@ cmath.log

log(z[, base]) -> the logarithm of z to the given base.

If the base not specified, returns the natural logarithm (base e) of z.
If the base not specified, returns the natural logarithm of z.
Copy link
Contributor

Choose a reason for hiding this comment

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

Ditto

Copy link
Member

Choose a reason for hiding this comment

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

@OTheDev Good spot! It may be worth creating a separate PR to fix (i.e. a PR that just adds the missing "is"). That at least would be uncontroversial.

As things stand, I'm inclined to reject this PR - I don't think it represents an overall increase in clarity.

[clinic start generated code]*/

static PyObject *
cmath_log_impl(PyObject *module, Py_complex x, PyObject *y_obj)
/*[clinic end generated code: output=4effdb7d258e0d94 input=230ed3a71ecd000a]*/
/*[clinic end generated code: output=4effdb7d258e0d94 input=55c7d74ab7072229]*/
{
Py_complex y;

Expand Down
10 changes: 4 additions & 6 deletions Modules/mathmodule.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1084,7 +1084,7 @@ FUNC1A(erfc, erfc,
"Complementary error function at x.")
FUNC1(exp, exp, 1,
"exp($module, x, /)\n--\n\n"
"Return e raised to the power of x.")
"Return the exponential function at x.")
FUNC1(exp2, exp2, 1,
"exp2($module, x, /)\n--\n\n"
"Return 2 raised to the power of x.")
Expand Down Expand Up @@ -1143,7 +1143,7 @@ FUNC1A(lgamma, m_lgamma,
"Natural logarithm of absolute value of Gamma function at x.")
FUNC1(log1p, m_log1p, 0,
"log1p($module, x, /)\n--\n\n"
"Return the natural logarithm of 1+x (base e).\n\n"
"Return the natural logarithm of 1+x.\n\n"
"The result is computed in a way which is accurate for x near zero.")
FUNC2(remainder, m_remainder,
"remainder($module, x, y, /)\n--\n\n"
Expand Down Expand Up @@ -2186,15 +2186,13 @@ math.log
]
/

Return the logarithm of x to the given base.

If the base not specified, returns the natural logarithm (base e) of x.
Return the logarithm of x to the given base or the natural logarithm of x.
[clinic start generated code]*/

static PyObject *
math_log_impl(PyObject *module, PyObject *x, int group_right_1,
PyObject *base)
/*[clinic end generated code: output=7b5a39e526b73fc9 input=0f62d5726cbfebbd]*/
/*[clinic end generated code: output=7b5a39e526b73fc9 input=e74bd6b80f8d66fd]*/
{
PyObject *num, *den;
PyObject *ans;
Expand Down