classification
Title: fma documentation should provide better example.
Type: enhancement Stage:
Components: Documentation Versions: Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, jayanthkoushik, mark.dickinson, pitrou, rhettinger, skrah
Priority: normal Keywords:

Created on 2014-05-15 05:19 by jayanthkoushik, last changed 2020-10-26 20:05 by rhettinger.

Messages (6)
msg218592 - (view) Author: Jayanth Koushik (jayanthkoushik) Date: 2014-05-15 05:19
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')
msg218604 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2014-05-15 11:37
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).
msg218606 - (view) Author: Jayanth Koushik (jayanthkoushik) Date: 2014-05-15 11:41
@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.
msg229311 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2014-10-14 16:37
I have no strong opinion, except that the docs appear clear:

"Return self*other+third with no rounding of the intermediate product self*other."
msg229313 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2014-10-14 16:48
Just for the record, I think that an example also helps educate a non-expert reader (such as me ;-)) about the rounding problem.
msg379684 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-10-26 20:05
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.
History
Date User Action Args
2020-10-26 20:05:33rhettingersetnosy: + rhettinger
messages: + msg379684
2020-10-26 11:46:35iritkatrielsetversions: + Python 3.9, Python 3.10, - Python 3.1, Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5
2014-10-14 16:48:33pitrousetnosy: + pitrou
messages: + msg229313
2014-10-14 16:37:06skrahsetmessages: + msg229311
2014-05-15 11:41:03jayanthkoushiksetmessages: + msg218606
2014-05-15 11:37:04mark.dickinsonsetmessages: + msg218604
2014-05-15 11:35:11mark.dickinsonsetnosy: + mark.dickinson, skrah
2014-05-15 05:19:05jayanthkoushikcreate