Add 'half turns' functions (cospi et al) to math module following C23 & IEEE754-2019

[jepler]

Feature or enhancement

Proposal:

C23 standardized multiple new trig functions in <math.h> that operate on units of “half turns”. These functions are recommended by IEEE754-2019. I propose adding these functions to CPython.

These function can be both more accurate and more performant than the traditional functions which take radian arguments, because inexact range reduction (e.g., modulo 2π) can be replaced by exact calculations (e.g., fmod(x, 2)) that never require excess precision.

Modern Linux systems such as Debian Trixie using glibc 2.41 include an implementation of all these C23 functions (regardless of whether building in C23 mode).

For instance, consider calculating the sine of 500π or 500 half-turns. The result is exactly zero with a proper math.sinpi implementation but nonzero with the traditional math.sin function, because 500π is not an exact FP number:

>>> math.sinpi(500), math.sin(math.pi*500)
(0.0, -1.6070832296378168e-13)

For platforms which do not directly support these functions, for instance because they do not support the C23 standard or do not provide the functions when not building in C23 mode, implementations similar to the existing internal function mathmodule.c function m_sinpi can be used. These perform range reduction with fmod & special value checking before delegating to a platform radians-based routine (e.g., m_sinpi → sin() or cos()) with necessary scaling by a factor of π.

I have prototyped this addition. You can view it on github: https://github.com/python/cpython/compare/main...jepler:cpython:c23-math-pifuns?expand=1#diff

This branch includes new tests & documentation for the new functions.

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

https://discuss.python.org/t/add-half-turns-functions-cospi-et-al-to-math-module/107550 [no replies yet]

[picnixz]

1. A thread without reply is not acceptable for an issue.
2. We do not even include all C11 functions and usually limit ourselves to C99 for now.
3. This should be left to a 3rd party extension.

[jepler]

That was quick. Thank you for your kind consideration.

[Mariatta]

1. why not? Maybe the topic proposed was good enough that didn't need additional "discussion". The discourse topic seem to already have at least 5 "likes" which to me means at least there are supporters to the idea.

[Mariatta]

Reopening, until at least the Discourse thread gain traction or consensus. It is too early to decide because the Discourse thread was just opened on the same day as this issue.

[picnixz]

We already had a discussion on C99 functions that took ages to be included. We honestly do not want to include C23 functions if even C11 are not yet considered.

And we usually close issues and only reope them once DPO has gained traction. Otherwise we have two places where discussions take place instead of one.

So please, let DPO be the place where consensus is built and GH issues be for actionable issues.

I deliberately left out some C99 functions out because even numpy did not include them.

[picnixz]

cc @rhettinger @skirpichev and Mark who I can never tag

If we are to consider C23 functions I would rather have something for including C11 functions first, including configure options so as to ease builds.

And I am against reimplementing them for platforms that do not support it because math is not meant to be a general purpose library. Leave it to numpy or others.

[jepler]

Note that though these functions are standardized in C23, there is no requirement of a C23 runtime because my branch provides implementations of the functions, similar to m_sinpi already existing in the CPython source code and used internally.

mathmodule.c already has at least m_tgamma, m_lgamma, m_log1p, m_log2 and m_remainder implementing standard math functions where there is insufficient platform support. Have these been maintenance burdens?

I did find the previous discussion of missing C99 functions in math here: #135853

I have read the thread's initial comment & skimmed the remainder. My main question is whether it is numpy or CPython who "takes the lead" in adding new mathematical functions. Must it consistently be one or the other, or have both sides sometimes innovated in including a function first?

I also found where m_erf and m_erfc could be removed because C runtime implementations improved sufficiently: https://github.com/python/cpython/pull/101679/changes (the title refers to C11 but my reference suggests erf/erfc are C99, and f/l suffixed versions are C11)

Finally, another question about norms -- is this the type of discussion that should have been taking place on DPO instead of an issue? Knowing the correct venue for a conversation has been a pain-point for me here.

[skirpichev]

Mark who I can never tag

Did Mark asked not to ping him? If not, lets ask - his opinion will be valuable.

We already had a discussion on C99 functions that took ages to be included.

JFR: #135853

We honestly do not want to include C23 functions if even C11 are not yet considered. If we are to consider C23 functions I would rather have something for including C11 functions first

Hmm, I don't remember that C11 added something. Can you be more specific here?

I have prototyped this addition. You can view it on github: https://github.com/python/cpython/compare/main...jepler:cpython:c23-math-pifuns?expand=1#diff

You could open PR against own fork. In such case you could remove the branch later without losing of the work (and breaking links).

BTW, I think you need better testing, like for other functions with custom implementations. See Lib/test/mathdata/math_testcases.txt.

And I am against reimplementing them for platforms that do not support it because math is not meant to be a general purpose library.

In past, the math functions were implemented on all platforms. Lets not break this.

The proposal looks to be motivated by the standard, not real application. This is a weak point for me. We don't require yet C23-compatible compiler to build CPython and can't rely on presence of proposed functions.

JFR: https://discuss.scientific-python.org/t/1193/

mpmath has sinpi/cospi, but nothing else. Given that we already have private sinpi, I think it's fine if we expose this function accompanied with cospi (constructed from sinpi code).

[terryjreedy]

I replied on discuss with the annoying fact the even sin(math.pi) is not 0, and +1, pending reasons not to add. 12 hearts now, 10 hours after posting.

@jepler We are in transition to requiring dpo discussion for sufficiently non-trivial new features. I know, a bit fuzzy. Thank you for your first post there. Next time, start there. A core dev may eventually open or suggest issue and PR.

@skirpichev mpmath.org doc omits doc for sinpi and cospi. Search AI summary suggests mpmath.sinpi(x) = sin(pi * x) if x != int(x) else 0 (or sin(pi * (x - int(x)) for positive x?) which is close to or maybe equal to the proposal. Yes, expose it.

[skirpichev]

mpmath.org doc omits doc for sinpi and cospi.

It doesn't omit it, just exposes stub docs due to my typo. Thanks for the bug, now fixed:
https://mpmath.readthedocs.io/en/latest/functions/trigonometric.html#trigonometric-functions-with-modified-argument