precision — Manage precision and algorithms on arithmetical operations

kanon.units.precision Module

The precision module is used when wanting to adjust BasedReal arithmetical operations behavior. All operations are made within a PrecisionContext rules, which indicate :

• A TruncatureMode

• A PrecisionMode

• 4 CustomArithmeticAlgorithm, (add, sub, mul, div)

Default precision context is set to TruncatureMode.NONE, PrecisionMode.MAX, and all CustomArithmeticAlgorithm as default.

To set new precision rules you should use the set_precision context manager. In the example below, I set the precision so that the result significant number is 0 and that it should be truncated.

>>> from kanon.units import Sexagesimal
>>> a = Sexagesimal("1;50")
>>> b = Sexagesimal("2;0")
>>> a + b
03 ; 50
>>> with set_precision(tmode=TruncatureMode.TRUNC, pmode=0):
...     a + b
...
03 ;

If you want to use a specific algorithm for one of the arithmetical operations, you first need to define the algorithm with this signature with the identify_func decorator specifying a unique ID :

Callable[[PreciseNumber, PreciseNumber], PreciseNumber]

For example, a multiplication algorithm which is essentialy equivalent to a * round(b,0) with TEST_MUL as its ID:

>>> @identify_func("TEST_MUL")
... def test_mul(a: PreciseNumber, b: PreciseNumber) -> PreciseNumber:
...     res = 0
...     for i in range(int(round(b,0))):
...         res += a
...     return res

You can now use this function to make multiplications use this algorithm

>>> b * a
03 ; 40
>>> with set_precision(mul=test_mul):
...     b * a
04 ; 00

All operations and their associated context are stored inside the ContextPrecision when the recording flag is set to True. You can either set it to True inside of a set_precision context manager, or globally turn it on with set_recording(True). Records are displayed with get_records, and can be cleared with clear_records.

Let’s try to record our operations.

>>> set_recording(True)
>>> get_records()
[]
>>> a + b
03 ; 50
>>> with set_precision(tmode=TruncatureMode.ROUND, pmode=1):
...     a + Sexagesimal("2;5,30")
03 ; 56
>>> with set_precision(mul=test_mul):
...     b * a
04 ; 00
>>> get_records()
[{'args': (01 ; 50, 02 ; 00, '+', 03 ; 50), 'tmode': 'NONE', 'pmode': 'MAX', 'add': 'DEFAULT', 'sub': 'DEFAULT', 'mul': 'DEFAULT', 'div': 'DEFAULT'}, {'args': (01 ; 50, 02 ; 05,30, '+', 03 ; 56), 'tmode': 'ROUND', 'pmode': 1, 'add': 'DEFAULT', 'sub': 'DEFAULT', 'mul': 'DEFAULT', 'div': 'DEFAULT'}, {'args': (02 ; 00, 01 ; 50, '*', 04 ; 00), 'tmode': 'NONE', 'pmode': 'MAX', 'add': 'DEFAULT', 'sub': 'DEFAULT', 'mul': 'TEST_MUL', 'div': 'DEFAULT'}]
>>> clear_records()
>>> set_recording(False)
>>> a + b
03 ; 50
>>> get_records()
[]

Types

kanon.units.precision.CustomArithmeticAlgorithm

Type:

Optional[Callable[[PreciseNumber, PreciseNumber], PreciseNumber]

Functions

set_precision([pmode, tmode, recording, ...])	Mutates the current PrecisionContext with the specified rules.
get_context()	Returns current context
set_context(context)	Replace current PrecisionContext.
set_recording(flag)	Set current PrecisionContext recording mode to flag.
get_records()	Get current PrecisionContext records.
clear_records()	Clear current PrecisionContext records.

Classes

PrecisionMode(value)	Enumeration of standard precision modes available.
TruncatureMode(value)	Enumeration of standard truncature modes available.
PrecisionContext([pmode, tmode, add, sub, ...])	Context containing PreciseNumber arithmetic rules.
PreciseNumber()	Abstract class of numbers with PrecisionContext compatibility
Truncable()

Class Inheritance Diagram