Skip to content

Copy all information from thread into PEP #9

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
NeilGirdhar wants to merge 6 commits into from
Closed

Copy all information from thread into PEP #9

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
969e13e
Copy all information from thread into PEP
NeilGirdhar May 10, 2025
4da81c7
Add missing perm
NeilGirdhar May 11, 2025
d04bfd5
Just use the word undocumented
NeilGirdhar May 11, 2025
a2d8b70
Merge branch 'imath' into imath
skirpichev May 12, 2025
469823a
Merge branch 'imath' into imath
skirpichev May 12, 2025
1552bea
Update peps/pep-9999.rst
skirpichev May 12, 2025
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
156 changes: 111 additions & 45 deletions peps/pep-9999.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
PEP: 9999
Title: imath --- module for number-theoretic functions
Author: Sergey B Kirpichev <skirpichev@gmail.com>
Author: Neil Girdhar <misterhsheik@gmail.com>,
Sergey B Kirpichev <skirpichev@gmail.com>
Sponsor: Victor Stinner <vstinner@python.org>
Discussions-To: Pending
Status: Draft
Expand All @@ -14,41 +15,38 @@ Post-History: 02-Jun-2019,
Abstract
========

This PEP proposes a new module for number-theoretical, combinatorial and other
integer-valued functions defined for integer arguments, 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.
Comment on lines +18 to +19
Copy link
Copy Markdown
Owner

@skirpichev skirpichev May 12, 2025

Choose a reason for hiding this comment

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

Could you argue why this is better?

Copy link
Copy Markdown
Author

@NeilGirdhar NeilGirdhar May 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

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.



Motivation
==========

The :external+py3.14:mod:`math` documentaton says: "This module provides access
to the mathematical functions defined by the C standard." But as a state of
art, over time the module was populated with functions that aren't related to
the C standard or floating-point arithmetics. Now it's much harder to describe
module scope, content and interfaces (returned values or accepted arguments).

For example, the :external+py3.14:mod:`math` module documentation says: "Except
when explicitly noted otherwise, all return values are floats." This is not
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 module a similar sentence "All
return values are integers." could tell the truth once. In a similar way we
can simplify description of accepted arguments for both the
:external+py3.14:mod:`math` and the new module.

Apparently, the :external+py3.14:mod:`math` can't serve as a catch-all place
for mathematical functions: we have also the :external+py3.14:mod:`cmath` and
the :external+py3.14:mod:`statistics`. Let's make same for integer-related
functions. 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.
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.
Comment on lines +25 to +43
Copy link
Copy Markdown
Owner

@skirpichev skirpichev May 12, 2025

Choose a reason for hiding this comment

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

Ditto.

Copy link
Copy Markdown
Author

@NeilGirdhar NeilGirdhar May 12, 2025

Choose a reason for hiding this comment

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

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.



Specification
=============

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
Copy link
Copy Markdown
Owner

@skirpichev skirpichev May 12, 2025

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Author

@NeilGirdhar NeilGirdhar May 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

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?

module, called ``imath``:

* :external+py3.14:func:`~math.comb`
Expand All @@ -72,8 +70,20 @@ proposal.
Backwards Compatibility
=======================

As aliases in :external+py3.14:mod:`math` will be kept for indefinite time
(their use would be discouraged), there are no anticipated code breaks.
As aliases in :external+py3.14:mod:`math` will be kept indefinitely, there are
no anticipated code breaks. (The use of these aliases is discouraged.)

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.
Comment on lines +75 to +86
Copy link
Copy Markdown
Owner

@skirpichev skirpichev May 12, 2025

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Author

@NeilGirdhar NeilGirdhar May 12, 2025

Choose a reason for hiding this comment

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

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



Reference Implementation
Expand Down Expand Up @@ -105,27 +115,83 @@ interval math or numerical integration.
Other proposed names include ``ntheory`` (like SymPy's submodule),
``integermath`` and ``imaths``.

Module scope and possible library members
=========================================
Comment on lines +118 to +119
Copy link
Copy Markdown
Owner

@skirpichev skirpichev May 12, 2025

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Author

@NeilGirdhar NeilGirdhar May 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

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.


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:
Comment on lines +121 to +124
Copy link
Copy Markdown
Owner

@skirpichev skirpichev May 12, 2025

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Author

@NeilGirdhar NeilGirdhar May 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

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?


* Number theory

* Divisibility & Modular Arithmetic (see also [5]_)

* ``gcd(a, b)``: Part of proposal.
* ``lcm(a, b)``: Part of proposal.
* ``powmod(a, b, m)``: Modular exponentiation (already in `pow(a, b, m)`,
but renamed for clarity).
* ``is_coprime(a, b)``
* ``modinv(a, m)``: Modular inverse.
* ``gcdext(a, b)``: Solve linear Diophantine equations in two variables (the
:external+py3.14:class:`int` implementation actually includes the extended
Euclidean algorithm).

* Integer Arithmetic and Sequences

* ``isqrt(n)``: Part of proposal.
* ``c_div(a, b)``: Ceiling divide, see [2]_, [3]_.
* ``isqrt_rem(n)``: The integer square root and its remainder.
* ``sqrtmod(n, modulo)``: Square root within a modular group.
* ``ilog(n, base)``: Integer logarihm; currently
:external+py3.14:func:`math.log` has a special handling for integer
arguments. It's unique (wrt other module functions) and undocumented.
See [4]_.
* ``fibonacci(n)``

* Primality & Factorization

* ``is_prime(n)``
* ``is_power_of_two(x)``
* ``prime_factors(n)``: Trial division or Pollard’s rho for small inputs.
* ``totient(n)``: Euler’s totient function.

* Combinatorics

* ``factorial(n)``: Part of proposal.
* ``comb(n, k)``: Part of proposal.
* ``perm(n, k)``: Part of proposal.


Rejected ideas
==============

There was a brief discussion about exposing :external+py3.14:func:`math.isqrt`
as ``imath.sqrt`` in the same way that :external+py3.14:func:`cmath.sqrt` is the
complex version of :external+py3.14:func:`math.sqrt`. However, ``isqrt`` is
ultimately a different function: it is the floor of the square root. It would
be confusing to give it the same name (under a different module).


Comment thread
skirpichev marked this conversation as resolved.
Arguments against
Comment thread
NeilGirdhar marked this conversation as resolved.
=================

Discoverability
---------------

Module scope and possible extensions
------------------------------------
Beginners looking for a math function may instinctively look for it in the math
module. Rather than creating a new module, change the documentation for the
math module to read not mention the C standard or floating-point numbers.

Unless we can just provide bindings to some well supported mathematical library
like the GMP, the module scope should be limited. For example, no primality
testing and factorization.
Countering this, complex math is still math, but we have a separate module for
that. Just as with complex numbers, integers should have their own module too.

There are possible additions, among proposed in the initial discussion thread
(see also [5]_):
Limited benefit
---------------
Comment on lines +189 to +190
Copy link
Copy Markdown
Owner

@skirpichev skirpichev May 12, 2025

Choose a reason for hiding this comment

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

I don't see counter arguments here.

Copy link
Copy Markdown
Author

@NeilGirdhar NeilGirdhar May 12, 2025

Choose a reason for hiding this comment

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

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.


* ``c_div()`` --- for integer ceiling divide, see [2]_, [3]_.
* ``gcdext()`` --- to solve linear Diophantine equation in two variables (the
:external+py3.14:class:`int` implementation actually include extended
Euclidean algorithm)
* ``isqrt_rem()`` --- to return both integer square root and a remainder (if
integer isn't a perfect square)
* ``ilog()`` --- integer logarithm, currently :external+py3.14:func:`math.log`
has a special handling for integer arguments. It's unique (wrt other module
functions) and not documented so far, see [4]_
* ``fibonacci()``.
Whereas the ``cmath`` module is justified by its prevention of a lot of slow
type checks, the ``imath`` module has limited benefit in this regard. The
Comment thread
NeilGirdhar marked this conversation as resolved.
example given: ``sin`` has a place in ``cmath``, but not ``imath``.


Rejected ideas
Expand Down