Draft PEP: Imaginary type and IEC 60559-compatible complex arithmetic

peps/pep-9999.rst

@@ -0,0 +1,150 @@
+PEP: 9999
+Title: Imaginary type and IEC 60559-compatible complex arithmetic
+Author: Sergey B Kirpichev <skirpichev@gmail.com>
+Sponsor: Pending
+Discussions-To: Pending
+Status: Draft
+Type: Standards Track
+Created: 05-Dec-2023
+Python-Version: 3.15
+Post-History: `10-Sep-2023 <https://discuss.python.org/t/33433>`__,
+              `14-Jan-2025 <https://discuss.python.org/t/77073>`__
+
+
+Abstract
+========
+
+Introduce new imaginary type and mixed rules for complex/imaginary/real
+arithmetics.
+
+
+Motivation
+==========
+
+Too much special casing, rectangular notation, brain split wrt repr() & str
+input, fix eval-repr round-trip, fix simple invariants in docs.
+
+* C standard since C99
+* GSL
+* MPC has special cases for real operand
+
+Examples:
+
+at z = ±2±0j
+
+* atan = lambda z: 1j*(cmath.log(1 - 1j*z) - cmath.log(1 + 1j*z))/2
+* asin = lambda z: -1j*cmath.asinh(1j*z)
+
+at z = +2±0j
+
+* asin = lambda z: -1j*cmath.log(1j*z + cmath.sqrt(1 - z*z))
+
+at z = -2±0j
+
+* asin = lambda z: 1j*cmath.log(cmath.sqrt(1 - z*z) - 1j*z)
+
+
+Not a replacement to limit() in CAS!
+
+.. code-block:: pycon
+
+   >>> log1p = lambda z: +z - z*z/2  # ln(1+z) up to O(z^3)
+   >>> log1m = lambda z: -z - z*z/2  # ln(1-z) up to O(z^3)
+   >>> log1p(0.25-0j)  # wrong sign!
+   (0.21875+0j)
+   >>> log1p(0.25-1e-10j)
+   (0.21875-7.5e-11j)
+   >>> log1p(0.25-1e-30j)
+   (0.21875-7.500000000000001e-31j)
+   >>> log1p(0.25-1e-300j)
+   (0.21875-7.5e-301j)
+   >>> log1m(0.25-0j)  # correct sign
+   (-0.28125+0j)
+   >>> log1m(0.25-1e-300j)
+   (-0.28125+1.25e-300j)
+
+
+Rationale
+=========
+
+C17 Annex G
+
+Note that removing from C2y is irrelevant for us.
+
+
+Specification
+=============
+
++----------+------------+--------------+--------------------+
+| lhs\/rhs | u          | iv           | u + iv             |
++----------+------------+--------------+--------------------+
+| x        | x ± u      | x ± iv       | (x ± u) ± iv       |
++----------+------------+--------------+--------------------+
+| iy       | ±u + iy    | i(y ± v)     | ±u + i(y ± v)      |
++----------+------------+--------------+--------------------+
+| x + iy   | x ± u + iy | x + i(y ± v) | (x ± u) + i(y ± v) |
++----------+------------+--------------+--------------------+
+
++----------+----------------+-----------------+----------------------------+
+| lhs\/rhs | u              | iv              | u + iv                     |
++----------+----------------+-----------------+----------------------------+
+| x        | x * u          | i(x*v)          | (x*u) + i(x*v)             |
++----------+----------------+-----------------+----------------------------+
+| iy       | i(y*u)         | -y*v            | (-y*v) + i(y*u)            |
++----------+----------------+-----------------+----------------------------+
+| x + iy   | (x*u) + i(y*u) | (-y*v) + i(x*v) | (x*u - y*v) + i(y*u + x*v) |
++----------+----------------+-----------------+----------------------------+
+
++----------+----------------+-----------------+
+| lhs\/rhs | u              | iv              |
++----------+----------------+-----------------+
+| x        | x / u          | i(-x/v)         |
++----------+----------------+-----------------+
+| iy       | i(y/u)         | y/v             |
++----------+----------------+-----------------+
+| x + iy   | (x/u) + i(y/u) | (y/v) + i(-x/v) |
++----------+----------------+-----------------+
+
+
+Backwards Compatibility
+=======================
+
+[Describe potential impact and severity on pre-existing code.]
+
+
+How to Teach This
+=================
+
+[How to teach users, new and experienced, how to apply the PEP to their work.]
+
+
+Reference Implementation
+========================
+
+https://github.com/skirpichev/cpython/pull/1
+
+
+Rejected Ideas
+==============
+
+[Why certain ideas that were brought while discussing this PEP were not
+ultimately pursued.]
+
+
+Footnotes
+=========
+
+.. [1] https://www.gnu.org/software/gsl/doc/html/complex.html#complex-arithmetic-operators
+
+.. [2] /home/sk/ToDo/n3215.pdf
+
+.. [3] /home/sk/ToDo/n3274.pdf
+
+.. [4] https://github.com/llvm/llvm-project/issues/60269
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.