diff --git a/peps/pep-9999.rst b/peps/pep-9999.rst new file mode 100644 index 00000000000..5f1892b4ab0 --- /dev/null +++ b/peps/pep-9999.rst @@ -0,0 +1,150 @@ +PEP: 9999 +Title: Imaginary type and IEC 60559-compatible complex arithmetic +Author: Sergey B Kirpichev +Sponsor: Pending +Discussions-To: Pending +Status: Draft +Type: Standards Track +Created: 05-Dec-2023 +Python-Version: 3.15 +Post-History: `10-Sep-2023 `__, + `14-Jan-2025 `__ + + +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.