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 ArithmeticIdentifier, (add, sub, mul, div)

Default precision context is set to TruncatureMode.NONE, PrecisionMode.MAX, and all ArithmeticIdentifier 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 :

Callable[[PreciseNumber, PreciseNumber], PreciseNumber]

For example, a multiplication algorithm which is essentialy equivalent to a * round(b,0):

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

Then you have to identify this algorithm with a unique string

>>> test_mul_identifier = (test_mul, "TEST_MUL")

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

>>> b * a
03 ; 40
>>> with set_precision(mul=test_mul_identifier):
...     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 easily accessed through 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_identifier):
...     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.ArithmeticIdentifier

Type

Tuple[Optional[Callable[[PreciseNumber, PreciseNumber], PreciseNumber]], str]

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