fma documentation should provide better example.

[jayanthkoushik]

BPO	21510
Nosy	@rhettinger, @mdickinson, @pitrou, @skrah, @jayanthkoushik

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2014-05-15.05:19:05.801>
labels = ['type-feature', '3.9', '3.10', 'docs']
title = 'fma documentation should provide better example.'
updated_at = <Date 2020-10-26.20:05:33.278>
user = 'https://github.com/jayanthkoushik'

bugs.python.org fields:

activity = <Date 2020-10-26.20:05:33.278>
actor = 'rhettinger'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2014-05-15.05:19:05.801>
creator = 'jayanthkoushik'
dependencies = []
files = []
hgrepos = []
issue_num = 21510
keywords = []
message_count = 6.0
messages = ['218592', '218604', '218606', '229311', '229313', '379684']
nosy_count = 6.0
nosy_names = ['rhettinger', 'mark.dickinson', 'pitrou', 'skrah', 'docs@python', 'jayanthkoushik']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue21510'
versions = ['Python 3.9', 'Python 3.10']

Linked PRs

• gh-65709: provide extra example in Decimal.fma() docs #150246

[jayanthkoushik]

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

[mdickinson]

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

[jayanthkoushik]

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

[skrah]

I have no strong opinion, except that the docs appear clear:

"Return self*other+third with no rounding of the intermediate product self*other."

[pitrou]

Just for the record, I think that an example also helps educate a non-expert reader (such as me ;-)) about the rounding problem.

[rhettinger]

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.