[issue21510] fma documentation should provide better example.

[Raymond Hettinger]

Raymond Hettinger  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21510] fma documentation should provide better example.

[Irit Katriel]

Change by Irit Katriel :


--
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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21510] fma documentation should provide better example.

[Antoine Pitrou]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21510] fma documentation should provide better example.

[Stefan Krah]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21510] fma documentation should provide better example.

[Jayanth Koushik]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21510] fma documentation should provide better example.

[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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21510] fma documentation should provide better example.

[Mark Dickinson]

Changes by Mark Dickinson :


--
nosy: +mark.dickinson, skrah

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21510] fma documentation should provide better example.

[Jayanth Koushik]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com