fpbinary Objects¶

FpBinary¶

class fpbinary.FpBinary¶

Represents a real number using fixed point math and structure.

Parameters:

int_bits (int) – The number of bits to use to represent the integer part. This value may be negative - this simply removes that number of bits from the fractional bits. The frac_bits param still specifies the position of the least significant fractional bit but the total bits are int_bits + fract_bits. For example, a format of (-3, 6) would produce an instance with 3 fractional bits with a maximum value (assuming unsigned) of 2.0**-4 + 2.0**-5 + 2.0**-6.
frac_bits (int) – The number of bits to use to represent the fractional part. This value may be negative - this simply removes that number of bits from the int bits. The int_bits param still specifies the position of the most significant integer bit but the total bits are int_bits + fract_bits. For example, a format of (6, -3) would produce an instance with 3 integer bits with a maximum value (assuming unsigned) of 2.0**5 + 2.0**4 + 2.0**3. (Note that integer powers start at 0).
signed (bool) – Specifies whether the data represented is signed (True) or unsigned. This effects min/max values and wrapping/saturation behaviour.
value (float) – The value to initialise the fixed point object to. If int_bits and frac_bits do not provide enough precision to represent value fully, rounding will be done using RoundingEnum.near_pos_inf and overflow will be handled using OverflowEnum.sat.
bit_field (int) – If the precision of the desired initialise value is too great for the native float type, bit_field can be set to a 2’s complement representation of the desired value * 2**frac_bits. Note that bit_field overrides the value parameter.
format_inst (FpBinary) – If set, the int_bits and frac_bits values will be taken from the format of format_inst.

Notes

Add and Subtract: If op2 is not a fixed point type, an attempt will be made to convert it to a fixed point object using as few bits as necessary. Overflow is guaranteed to NOT happen. The resultant fixed point number has the following format:

int_bits  = max(op1.int_bits, op2.int_bits) + 1
frac_bits = max(op1.frac_bits, op2.frac_bits)

Multiply: If op2 is not a fixed point type, an attempt will be made to convert it to a fixed point object using as few bits as necessary. Overflow is guaranteed to NOT happen. The resultant fixed point number has the following format:

int_bits  = op1.int_bits + op2.int_bits
frac_bits = op1.frac_bits + op2.frac_bits

Divide: If op2 is not a fixed point type, an attempt will be made to convert it to a fixed point object using as few bits as necessary.

The divide operation is carried out on the fixed point representations. This is essentially an integer divide on the values scaled by 2**frac_bits. However, the numerator is scaled further so that the result has self.int_bits + value.frac bits fractional bits of precision. Once the divide is done, the result is direct rounded TOWARD ZERO. Enough int bits are in the result to ensure there is never an overflow. In short, the resultant fixed point number has the following format:

int_bits = op1.int_bits + op2.frac_bits + 1 if signed or
int_bits = op1.int_bits + op2.frac_bits     if unsigned
frac_bits = op1.frac_bits + op2.int_bits

If the user wants to implement a different type of rounding or increase the precision of the result, they need to resize the operands first, do the divide and then resize to the desired length with the desired rounding mode.

pow(): Only raising an FpBinary object to the power of 2 is supported.

Negate: Because a negate is a multiply by -1, the output has one extra integer bit than the input operand.

Absolute value: If the input operand is negative, the operation requires a negate, so the output will have one extra integer bit than the input operand. Otherwise, the format will remain the same.

bits_to_signed()¶

Interprets the bits of the fixed point binary object as a 2’s complement signed integer and returns an int. If self is an unsigned object, the MSB, as defined by the int_bits and frac_bits values, will be considered a sign bit.

Parameters:	None –
Returns:	The object bits interpreted as a 2’s complement signed integer.
Return type:	int

format¶

Read-only (int_bits, frac_bits) tuple representing the fixed point format.

Type:	tuple

is_signed¶

Read-only. True if the fixed point object is signed.

Type:	bool

resize()¶

Resizes the fixed point object IN PLACE to the format described by format.

Parameters:	format (length 2 tuple or instance of this object.) – If tuple, will be resized to format[0] int bits and format[1] frac bits. If instance of this type, the format will be taken from format. overflow_mode (fpbinary.OverflowEnum, optional) – Specifies how to deal with overflows when int bits are reduced. Default is wrap. round_mode (fpbinary.RoundingEnum, optional) – Specifies how to deal with rounding when frac bits are reduced. Default is direct_neg_inf.
Returns:	self
Return type:	FpBinary/FpBinaryComplex

str_ex()¶

Returns a str displaying the full precision value of the fixed point object. This is useful when the fixed point value has more bits than native floating point types can handle. Note that scientific notation is not used.

Parameters:	None –
Returns:	Non-scientific notation string representation of the instance value.
Return type:	str or unicode

FpBinaryComplex¶

class fpbinary.FpBinaryComplex¶

Represents a complex number using fixed point math and structure.

Parameters:

int_bits (int) – The number of bits to use to represent the integer part. This value may be negative - this simply removes that number of bits from the fractional bits. The frac_bits param still specifies the position of the least significant fractional bit but the total bits are int_bits + fract_bits. For example, a format of (-3, 6) would produce an instance with 3 fractional bits with a maximum value (assuming unsigned) of 2.0**-4 + 2.0**-5 + 2.0**-6.
frac_bits (int) – The number of bits to use to represent the fractional part. This value may be negative - this simply removes that number of bits from the int bits. The int_bits param still specifies the position of the most significant integer bit but the total bits are int_bits + fract_bits. For example, a format of (6, -3) would produce an instance with 3 integer bits with a maximum value (assuming unsigned) of 2.0**5 + 2.0**4 + 2.0**3. (Note that integer powers start at 0).
value (float/complex) – The value to initialise the fixed point object to. If int_bits and frac_bits do not provide enough precision to represent value fully, rounding will be done using RoundingEnum.near_pos_inf and overflow will be handled using OverflowEnum.sat.
real_fp_binary (FpBinary) – The real part of the FpBinaryComplex instance can be set to the value of an FpBinary instance. The format will also be used if it isn’t specified explicitly.
imag_fp_binary (FpBinary) – The imag part of the FpBinaryComplex instance can be set to the value of an FpBinary instance. The format will also be used if it isn’t specified explicitly.
real_bit_field (int) – If the precision of the desired initialise value is too great for the native float type, real_bit_field can be set to a 2’s complement representation of the desired real value * 2**frac_bits. Note that real_bit_field overrides the value parameter.
imag_bit_field (int) – If the precision of the desired initialise value is too great for the native float type, real_bit_field can be set to a 2’s complement representation of the desired imaginary value * 2**frac_bits. Note that imag_bit_field overrides the value parameter.
format_inst (FpBinary) – If set, the int_bits and frac_bits values will be taken from the format of format_inst.

Notes

Add and Subtract: If op2 is not a fixed point type, an attempt will be made to convert it to a fixed point object using as few bits as necessary. Overflow is guaranteed to NOT happen. The resultant real/imag fixed point numbers have the following format:

int_bits  = max(op1.int_bits, op2.int_bits) + 1
frac_bits = max(op1.frac_bits, op2.frac_bits)

Multiply: If op2 is not a fixed point type, an attempt will be made to convert it to a fixed point object using as few bits as necessary. Overflow is guaranteed to NOT happen. The resultant real/imag fixed point numbers have the following format:

int_bits  = op1.int_bits + op2.int_bits + 1
frac_bits = op1.frac_bits + op2.frac_bits

Divide: Complex divide is implemented by multiplying by the conjugate of the denominator and dividing by the denominator.real**2 + denominator.imag**2. pow(): Only raising an FpBinaryComplex object to the power of 2 is supported.

Negate: Because a negate is a multiply by -1, the output has one extra integer bit than the input operand.

Absolute value: Estimates the absolute value by calculating the energy, converting to float, squaring and converting back to FpBinaryComplex.

format¶

Read-only (int_bits, frac_bits) tuple representing the fixed point format.

Type:	tuple

resize()¶

Resizes the fixed point object IN PLACE to the format described by format.

Parameters:	format (length 2 tuple or instance of this object.) – If tuple, will be resized to format[0] int bits and format[1] frac bits. If instance of this type, the format will be taken from format. overflow_mode (fpbinary.OverflowEnum, optional) – Specifies how to deal with overflows when int bits are reduced. Default is wrap. round_mode (fpbinary.RoundingEnum, optional) – Specifies how to deal with rounding when frac bits are reduced. Default is direct_neg_inf.
Returns:	self
Return type:	FpBinary/FpBinaryComplex

str_ex()¶

Returns a str displaying the full precision value of the fixed point object. This is useful when the fixed point value has more bits than native floating point types can handle. Note that scientific notation is not used.

Parameters:	None –
Returns:	Non-scientific notation string representation of the instance value.
Return type:	str or unicode

FpBinarySwitchable¶

class fpbinary.FpBinarySwitchable¶

Represents a fixed point OR floating point value depending on the fp_mode constructor parameter. Also enables tracking of minimum and maximum values during the lifetime of the object via the value property. This class can be used in math and resize operations and act like an FpBinary instance when fp_mode is True and act sensibly (normally do nothing) when fp_mode is False.

Parameters:

fp_mode (bool) – If True, the underlying data/operations are fixed point. If False, a native double type will be used. If True, the fp_value parameter must be set to an FpBinary instance. This instance will define the fixed point data and initial value.
fp_value (FpBinary, optional if fp_mode is False.) – This instance will define the fixed point data and initial value.
float_value (float, optional) – Sets the initial value when fp_mode is False. Defaults to 0.0.

format¶

Read-only (int_bits, frac_bits) tuple representing the fixed point format. If fp_mode is False, (1, 0) is returned.

Type:	tuple

fp_mode¶

Read-only. True if the object is in fixed point mode.

Type:	bool

max_value¶

Will return the highest value the value property has been set to. This only applies when fp_mode is False. If fp_mode is True, this property will return 0.0 .

Type:	float

min_value¶

Will return the lowest value the value property has been set to. This only applies when fp_mode is False. If fp_mode is True, this property will return 0.0 .

Type:	float

resize()¶

If fp_mode is True, this method does what FpBinary.resize() does. If fp_mode is False, nothing is done.

Parameters:	FpBinary.resize() (See) –
Returns:	self
Return type:	FpBinarySwitchable

value¶

If fp_mode is True, may set to a FpBinary or FpBinarySwitchable type. If fp_mode is False may set any object that is castable to a float. This property can be used to set the underlying value of a monitoring variable for the purposes of profiling the min and max values at a given point in execution.

Type:	float-castable

OverflowEnum¶

class fpbinary.OverflowEnum¶

Provides static fields for overflow modes.

wrap¶

This is essentially the truncation of any int bits that are being removed (usually via a resize() call). For signed types, this mayresult in a positive number becoming negative and vice versa.

Type:	int

sat¶

If an overflow occurs, the value is railed to the min or max value of the new bit format.

Type:	int

excep¶

If an overflow occurs, an FpBinaryOverflowException is raised.

Type:	int

RoundingEnum¶

class fpbinary.RoundingEnum¶

Provides static fields for rounding modes. The enums will generally be of the ‘direct’ or ‘near’ types. ‘near’ implies that a rule is applied if the value is exactly halfway between the representable value. ‘direct’ implies that no consideration is given to these halfway situations.

near_pos_inf¶

The value is rounded towards the nearest value representable by the new format. Ties (i.e. X.5) are rounded towards positive infinity. The IEEE 754 standard does not have an equivalent, but this is common in general arithmetic that many call ‘rounding up’. Examples: 5.5 and 5.6 both go to 6.0 (assuming resizing to zero fract_bits). -5.25 goes to -5.0, -5.375 goes to -5.5 (assuming resizing to one fract_bit).

Type:	int

direct_neg_inf¶

The value is rounded in the negative direction to the nearest value representable by the new format. This is a clean truncate of bits without any other processing. It is often called ‘flooring’. This is the mode the VHDL fixed point library applies when using the ‘truncate’ mode. The IEEE 754 standard calls this ‘Round toward -infinity’. Examples: 5.5 and 5.6 both go to 5.0 (assuming resizing to zero fract_bits). -5.25 and -5.375 both go to -5.5 (assuming resizing to one fract_bit).

Type:	int

near_zero¶

The value is rounded towards the nearest value representable by the new format. Ties (i.e. X.5) are rounded towards zero. The IEEE 754 standard does not have an equivalent. Examples: 5.5 goes to 5.0, 5.6 goes to 6.0 (assuming resizing to zero fract_bits). -5.25 goes to -5.0, -5.375 goes to -5.5 (assuming resizing to one fract_bit).

Type:	int

direct_zero¶

The value is rounded in the direction towards zero to the nearest value representable by the new format. The IEEE 754 standard calls this ‘Round toward 0’ or ‘truncation’. Examples: 5.5 and 5.6 both go to 5.0 (assuming resizing to zero fract_bits). -5.25 and -5.375 both go to -5.0 (assuming resizing to one fract_bit).

Type:	int

near_even¶

The value is rounded towards the nearest value representable by the new format. Ties (i.e. X.5) are rounded towards the ‘even’ representation. This means that, after rounding a tie, the lsb is zero. The IEEE 754 standard calls this ‘Round to nearest, ties to even’. This is also the mode the Python 3 round() function applies. This is also the mode the VHDL fixed point library applies when using the ‘round’ mode. Examples: 5.5 and 6.5 both go to 6.0 (assuming resizing to zero fract_bits). -5.5 and -6.5 both go to -6.0 (assuming resizing to zero fract_bits). 5.75 goes to 6.0, 5.25 goes to 5.0 (assuming resizing to one fract_bit).

Type:	int

FpBinaryOverflowException¶

class fpbinary.FpBinaryOverflowException¶