fixedpointmath 0.2.1

Fixed-point arithmetic and type that mirrors popular Solidity implementations

DELV FixedPoint Python repo

The FixedPoint arithmetic package provides a Python endpoint for simulationg FixedPoint arithmetic that follows standards established by the Ethereum Solidity community.

Install

We are on PyPI:

pip install fixedpointmath

Testing

Testing is achieved with py.test.

Contributions

Please refer to CONTRIBUTING.md.

Documentation

This numeric representation is a noiseless alternative to floating point arithmetic. Floating point rounding errors can be deteremental when precision matters, such as in the case of blockchain simulation. The FixedPoint conducts all operations using 18-decimal fixed-point precision integers and arithmetic.

Number format

This package supports 18-decimal fixed-point precision numbers for arithmetic. Briefly, this means our representation for unity, "one", is 1 * 10 ** 18, which would be 1.0 when cast to a float. Unlike typical floats, a FixedPoint numeric always supports 18 decimal digits of precision, regardless of the scale of the number.

If you want the integer scaled representation, which can be useful for communicating with Solidity contracts, you must ask for it explicitly, e.g. FixedPoint("8.52").scaled_value == 8520000000000000000. Conversely, if you want to initialize a FixedPoint variable using the scaled integer representation, then you need to instantiate the variable using the scaled_value argument, e.g. FixedPoint(scaled_value=8). In that example, the internal representation is 8, so casting it to a float would produce a small value: float(FixedPoint(scaled_value=8)) == 8e-18.

If you cast FixedPoint numbers to ints or floats you will get an "unscaled" representation, e.g. float(FixedPoint("8.0")) == 8.0 and int(FixedPoint("8.528")) == 8.

We have purposefully constrained support for mixed-type operations that include the FixedPoint type. Due to a lack of known precision, operations against Python floats are not allowed (e.g. float * FixedPoint will raise an error). However, operations against int are allowed. In this case, the int argument is assumed to be "unscaled", for example int(8) * FixedPoint(8) == FixedPoint(int(8)) * FixedPoint(8) == FixedPoint(64). The internal "scaled" representation would be FixedPoint(64).scaled_value == 64 * 10**18.

Warning! Using floating point as a constructor to FixedPoint can cause loss of precision. For example,

>>> FixedPoint(1e18)
FixedPoint("1000000000000000042.420637374017961984")

Allowing floating point in the constructor of FixedPoint will be removed in a future version of fixedpointmath.

Computing with FixedPoint

The FixedPoint class abstracts away an internal integer representation and provides a suite of operations that act upon the class. For example,

>>> from fixedpointmath import FixedPoint
>>> float(FixedPoint(8.0))
8.0
>>> int(FixedPoint(8.528))
8
>>> int(8) * FixedPoint(8)
FixedPoint("64.0")
>>> 8.0 * FixedPoint(8)
TypeError: unsupported operand type(s): <class 'float'>

The last example throws a TypeError due to the lack of known precision between Python float and FixedPoint.