[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
Changes by Mark Dickinson
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
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
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
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
Change by Irit Katriel
Raymond Hettinger
participants (6)
-
Antoine Pitrou -
Irit Katriel
-
Jayanth Koushik
-
Mark Dickinson
-
Raymond Hettinger
-
Stefan Krah