Copy all information from thread into PEP by NeilGirdhar · Pull Request #9 · skirpichev/peps

NeilGirdhar · 2025-05-10T18:43:00Z

I copied everything from the thread into the PEP.

Just want to add regarding the list of "possible library members":

I moved it form "open issues" to its own section. It's not an open issue since we are not proposing any of these members, and we don't want these members to be part of the PEP discussion.
The purpose of the list is to illustrate the kinds of things that may be added to imath to illustrate its utility.
Any functions that is eventually added will require its own PEP anyway. We're not trying to make recommendations.

skirpichev · 2025-05-11T04:19:48Z

-This PEP describes new module for number-theoretic functions, like
-:external+py3.14:func:`math.gcd` or :external+py3.14:func:`math.isqrt`.
-
+This PEP proposes a new module for integer-related mathematical functions.


I doubt it's better. Did you classify functions by domain? by codomain? Should math.floor() be moved?

Former variant clearly state module scope. Maybe we can drop examples, but I don't think we should:

Suggested change

This PEP proposes a new module for integer-related mathematical functions.

This PEP proposes new module for number-theoretic functions, like

:external+py3.14:func:`math.gcd` or :external+py3.14:func:`math.isqrt`.

I asked Chat, and it said that things like combinatorics aren't part of number theory. I think we can set the scope farther down. How about "number theory, combinatorics, and integer representations."

I think we should drop the examples in the abstract. The abstract should be as concise as possible.

Sorry, but I doubt we should care about opinion of hallucinating AI.

See e.g. the GMP manual:

comb - mpz_bin_ui

factorial - mpz_fac_ui

gcd - mpz_gcd

lcm - mpz_lcm

All in section 5.9 (Number Theoretic Functions). The isqrt is in more fine-tuned section (root extraction).

We don't need to care about AI, but we should find a good reference. Maybe something a bit more authoritative than the GMP manual? https://en.wikipedia.org/wiki/Combinatorics does not even mention number theory. Do you have a citation that combinatorics is part of number theory?

Maybe something a bit more authoritative than the GMP manual?

For example?

Do you have a citation that combinatorics is part of number theory?

I'm pretty sure that binomial coefficients are part of.

According to Wikipedia: https://en.wikipedia.org/wiki/Mathematics#Areas_of_mathematics number theory and combinatorics are separate? Do you read that differently?

I'm pretty sure that binomial coefficients are part of.

Part of what? I'd say they're part of combinatorics. They're mentioned on the combinatorics page: https://en.wikipedia.org/wiki/Combinatorics

skirpichev · 2025-05-11T20:06:25Z

This has merge conflicts. BTW, could you please avoid force-pushes?

NeilGirdhar · 2025-05-11T20:19:27Z

Sure, I'll rebase now.

NeilGirdhar · 2025-05-11T20:32:13Z

Squashed and rebased.

skirpichev

Squashed and rebased.

Please avoid altering history.

skirpichev · 2025-05-12T05:39:58Z

+This PEP proposes a new module for mathematical functions related to number
+theory and combinatorics.


Could you argue why this is better?

According to Wikipedia:

combinatorics and number theory are different branches of mathematics, and

functions we plan on exposing like the number of combinations (binomial coefficient) and permutations are part of combinatorics.

Therefore, I think our desired scope should be "number theory and combinatorics".

I also think that abstracts should be as concise as possible with details presented in papers/proposals. So I prefer one sentence without examples.

skirpichev · 2025-05-12T05:40:16Z

+The :external+py3.14:mod:`math` module documentation says: "This module provides
+access to the mathematical functions defined by the C standard."  But, over time
+the module was populated with functions that aren't related to those
+mathematical functions defined in the C standard.
+
+Also, the :external+py3.14:mod:`math` module documentation says: "Except when
+explicitly noted otherwise, all return values are floats."  This is no longer
+true:  *None* of the functions listed in the "Number-theoretic functions" [1]_
+subsection of the documentation returns a float, but the documentation doesn't
+say so. In the proposed ``imath`` module, where they belong, a similar
+catch-all: "Except when explicitly noted otherwise, all return values are
+integers." could tell the truth once.
+
+The ``imath`` module would parallel the :external+py3.14:mod:`math` module's
+other siblings: :external+py3.14:mod:`cmath` and the
+:external+py3.14:mod:`statistics`.  It would provide shared context, which
+reduces verbosity in the documentation and conceptual load.  It also aids
+discoverability through grouping related functions and IDEs suggesting helpful
+completions.


First paragraph:

"as a state of the art" is being misused here, I'm not sure what it's trying to even express

It's about discrepancy of the documentation with reality. Since the documentation is about the C standard, there's no reason to also mention "returned values or accepted arguments"—that doesn't conflict with the topic. Every paragraph should be focused. If you want to mention returned types, it should be in the second paragraph, which is about that.

Second para:

"not longer true" -> "no longer true"

I will remove imath etc. from the sentence (I like LHS better there)

I will add some wording from the LHS

"simplify description" -> "simplify the description"

"of accepted arguments" -> "of the accepted arguments"

"for both the...module" -> "for functions in both"

Third para:

"Apparently" is a very odd way to word this. Apparently to whom, and why? I you want to say this, it needs to be reworded.

"Let's make same" is grammatically incorrect.

skirpichev · 2025-05-12T05:41:12Z

 =============

-The PEP proposes moving the following integer-related functions [1]_ in a new
+The PEP proposes exposing the following integer-related functions [1]_ in a new


No, "moving" is a correct word. We move functions, period.

We're not proposing moving the functions though. We're proposing leaving them in math and additionally exposing them in imath. "Moving" would mean removing from math and adding to imath.

Are you talking about the implementations?

skirpichev · 2025-05-12T05:44:12Z

+
+Rationale
+=========
+
+Why not simply update the documentation to broaden math's scope
+---------------------------------------------------------------
+
+Broadening ``math``'s scope would solve the documentation issue, but it would
+neglect the motivation of providing a shared context.  As mentioned, shared
+context reduces verbosity in the documentation and conceptual load.  It also
+aids discoverability through grouping related functions and IDEs suggesting
+helpful completions.


For me it looks like you repeat stuff from the "Motivation" section. I hope, that with a small improvement of the former we can just remove this section.

Oh, I'm happy to remove the Rationale. I thought you wanted it. Should I remove it now?

skirpichev · 2025-05-12T05:45:45Z

+Module scope and possible library members
+=========================================


I think this should be part of the "Open Issues" section.

I think it's not an open issue because we don't want the SC deciding which library members will be added. This is just a way of illustrating scope. We're not looking to start a debate about the choices in this section.

Open issues are for things that the SC needs to decide: Like the name of the library.

skirpichev · 2025-05-12T05:49:08Z

+Limited benefit
+---------------


I don't see counter arguments here.

Should we add one? I thought that our counterargument is that it is useful enough for all the reasons we've already given. Or should we remove this section? Happy with whatever.

skirpichev · 2025-05-12T05:55:48Z

+This PEP proposes a new module with only the six existing functions listed
+above.  However, in order to support the module's possible future utility, and
+to illustrate its scope, we provide an exploratory list of functions that could
+one day find a home in the ``imath`` library:


Sorry, but you again miss my point.

The purpose of this section is to show what can be included eventually to the module and what can't, not classification of the factorial as part of the Combinatorics or whatever else.

classification of the factorial as part of the Combinatorics or whatever else.

But I'm not suggesting the point is classification? Let's go point-by-point:

Do you agree that this section should:

show the module's possible future utility (that there are a lot of functions that could find a home here)?

illustrate the module's scope (what kinds of things would best be in imath and not, say, imath?

Also, you want his section to show "what can be included eventually". What do you mean by this exactly? Is it one of the two things above, or something else?

skirpichev · 2025-05-12T10:29:07Z

Thanks, but if you still wish to do a major rewrite - lets do it for python#4422.

skirpichev self-requested a review May 11, 2025 03:41

skirpichev reviewed May 11, 2025

View reviewed changes

skirpichev added a commit that referenced this pull request May 11, 2025

address sponsor review and cherry-pick few things from #9

e52a149

skirpichev mentioned this pull request May 11, 2025

Draft PEP: imath --- module for number-theoretic functions #8

Closed

skirpichev added a commit that referenced this pull request May 11, 2025

port some stuff from #9

5986156

Copy all information from thread into PEP

969e13e

NeilGirdhar and others added 4 commits May 11, 2025 16:41

Add missing perm

4da81c7

Just use the word undocumented

d04bfd5

Merge branch 'imath' into imath

a2d8b70

Merge branch 'imath' into imath

469823a

skirpichev reviewed May 12, 2025

View reviewed changes

Comment thread peps/pep-9999.rst Outdated

Update peps/pep-9999.rst

1552bea

skirpichev reviewed May 12, 2025

View reviewed changes

skirpichev closed this May 12, 2025

	This PEP proposes a new module for integer-related mathematical functions.
	This PEP proposes new module for number-theoretic functions, like
	:external+py3.14:func:`math.gcd` or :external+py3.14:func:`math.isqrt`.

		This PEP proposes a new module for mathematical functions related to number
		theory and combinatorics.

		Module scope and possible library members
		=========================================

		Limited benefit
		---------------

Conversation

NeilGirdhar commented May 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NeilGirdhar May 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NeilGirdhar May 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NeilGirdhar May 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

skirpichev commented May 11, 2025

Uh oh!

NeilGirdhar commented May 11, 2025

Uh oh!

NeilGirdhar commented May 11, 2025

Uh oh!

Uh oh!

skirpichev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NeilGirdhar May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NeilGirdhar May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NeilGirdhar May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NeilGirdhar May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

skirpichev commented May 12, 2025

Uh oh!

NeilGirdhar commented May 10, 2025 •

edited

Loading

NeilGirdhar May 11, 2025 •

edited

Loading

NeilGirdhar May 11, 2025 •

edited

Loading

NeilGirdhar May 11, 2025 •

edited

Loading

NeilGirdhar May 12, 2025 •

edited

Loading

NeilGirdhar May 12, 2025 •

edited

Loading

NeilGirdhar May 12, 2025 •

edited

Loading

NeilGirdhar May 12, 2025 •

edited

Loading