[issue21510] fma documentation should provide better example.
New submission from Jayanth Koushik: The documentation for decimal.fma provides an example which fails to illustrate the most important feature of the function i.e. single rounding. In fact: Decimal(2).fma(3, 5) == Decimal(2)*3 + 5 An example such as this would make it much more clear: >>> getcontext().prec = 2 >>> getcontext().rounding = ROUND_DOWN >>> Decimal('1.5')*Decimal('1.5') + Decimal('1.05') Decimal('3.2') >>> Decimal('1.5').fma(Decimal('1.5'), Decimal('1.05')) Decimal('3.3') ---------- assignee: docs@python components: Documentation messages: 218592 nosy: docs@python, jayanthkoushik priority: normal severity: normal status: open title: fma documentation should provide better example. type: enhancement versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21510> _______________________________________
Changes by Mark Dickinson <dickinsm@gmail.com>: ---------- nosy: +mark.dickinson, skrah _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21510> _______________________________________
Mark Dickinson added the comment: I wouldn't want to drop the simple example: I suspect that many of those looking at fma won't have the first idea what it does, and that first example shows clearly that it's a fused multiply-add. But +1 for an example that demonstrates the single rounding, either in the online docs or the docstring (or both). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21510> _______________________________________
Jayanth Koushik added the comment: @Mark: I agree. And perhaps it is also worth mentioning (on an unrelated note), that the decimal fma is not based on the internal cmath fma (it could not be) and unlike the cmath fma, it is no faster than an unfused multiply-add. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21510> _______________________________________
Stefan Krah added the comment: I have no strong opinion, except that the docs appear clear: "Return self*other+third with no rounding of the intermediate product self*other." ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21510> _______________________________________
Antoine Pitrou added the comment: Just for the record, I think that an example also helps educate a non-expert reader (such as me ;-)) about the rounding problem. ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue21510> _______________________________________
Change by Irit Katriel <iritkatriel@yahoo.com>: ---------- versions: +Python 3.10, Python 3.9 -Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue21510> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: I suggest using the text and example from the spec: http://speleotrove.com/decimal/daops.html#reffma ===================================================== fused-multiply-add takes three operands; the first two are multiplied together, using multiply, with sufficient precision and exponent range that the result is exact and unrounded.[4] No flags are set by the multiplication unless one of the first two operands is a signaling NaN or one is a zero and the other is an infinity. Unless the multiplication failed, the third operand is then added to the result of that multiplication, using add, under the current context. In other words, fused-multiply-add(x, y, z) delivers a result which is (x × y) + z with only the one, final, rounding. Examples: fused-multiply-add(’3’, ’5’, ’7’) ==> ’22’ fused-multiply-add(’3’, ’-5’, ’7’) ==> ’-8’ fused-multiply-add(’888565290’, ’1557.96930’, ’-86087.7578’) ==> ’1.38435736E+12’ Note that the last example would have given the result ’1.38435735E+12’ if the operation had been carried out as a separate multiply followed by an add. ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue21510> _______________________________________
participants (6)
-
Antoine Pitrou -
Irit Katriel
-
Jayanth Koushik
-
Mark Dickinson
-
Raymond Hettinger
-
Stefan Krah