### Install fxpmath from source

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/install.md

Clone the repository and install fxpmath locally. Navigate to the cloned directory before running the installation command.

```bash
git clone https://github.com/francof2a/fxpmath.git
```

```bash
cd fxpmath
pip install .
```

--------------------------------

### Install fxpmath using pip

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/install.md

Use this command to install the fxpmath library via pip.

```bash
pip install fxpmath
```

--------------------------------

### Zero Fractional Bits Example

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/generalized_sizing.md

Demonstrates the case with zero fractional bits (`n_frac = 0`), representing pure integer scaling in fixed-point form.

```python
from fxpmath import Fxp

w = Fxp(7, signed=True, n_word=8, n_frac=0)
print(w.dtype, w.n_int, w())
# fxp-s8/0 7 7.0
```

--------------------------------

### Fxp Scaling Example

Source: https://github.com/francof2a/fxpmath/blob/develop/README.md

Demonstrates using scaling and bias to represent numbers within a specific range and precision. The `info(3)` method provides detailed information about the Fxp object's configuration and limits.

```python
x = Fxp(10128.5, signed=False, n_word=12, scale=1, bias=10000)

x.info(3)
```

--------------------------------

### Install fxpmath using conda

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/install.md

Use this command to install the fxpmath library via conda, specifying the francof2a channel.

```bash
conda install -c francof2a fxpmath
```

--------------------------------

### Negative Fractional Bits Example

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/generalized_sizing.md

Demonstrates the use of negative fractional bits (`n_frac < 0`), which results in coarser resolution and a larger step size. This is common for scaled accumulators and intermediate pipeline nodes.

```python
from fxpmath import Fxp

x = Fxp(16, signed=True, n_word=8, n_frac=-2)
print(x.dtype, x.n_int, x())
# fxp-s8/-2 9 16.0
```

--------------------------------

### Negative Integer Bits Example

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/generalized_sizing.md

Shows an example of negative integer bits (`n_int < 0`), which is a geometric interpretation of the binary point being outside the stored word, similar to case (2).

```python
from fxpmath import Fxp

z = Fxp(1, signed=False, n_word=4, n_frac=5)
print(z.dtype, z.n_int, z.raw(), z())
# fxp-u4/5 -1 15 0.46875
```

--------------------------------

### Zero Integer Bits Example

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/generalized_sizing.md

Illustrates the case with zero integer bits (`n_int = 0`), which provides a pure fractional-style range, often used for normalized signals and coefficients.

```python
from fxpmath import Fxp

u = Fxp(0.75, signed=True, n_word=8, n_frac=7)
print(u.dtype, u.n_int, u())
# fxp-s8/7 0 0.75
```

--------------------------------

### Get Detailed Fxp Information

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Use the info method with increased verbosity to display detailed information about the Fxp object, including bit allocations, value range, and overflow/rounding modes.

```python
x.info(verbose=3)
```

--------------------------------

### Get Upper and Lower Limits of Fxp

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Access the predefined upper and lower representable limits of a fixed-point number by checking the 'upper' and 'lower' attributes.

```python
print(x.upper)
print(x.lower)
```

--------------------------------

### Get Model Layer Names

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Iterates through the model's layers to print each layer's name. Useful for identifying layers before weight extraction.

```python
for layer in model.layers:
    print(layer.name)
```

--------------------------------

### Get Value in Different Bases

Source: https://github.com/francof2a/fxpmath/blob/develop/README.md

Display the fixed-point number in binary or hexadecimal format. Use base_repr for representations that include the sign symbol instead of two's complement.

```python
x.bin()
x.bin(frac_dot=True)

x.base_repr(2)

x.hex()
x.base_repr(16)

```

--------------------------------

### Getting and Setting Fxp Values from Operations

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Retrieve the numerical value of an Fxp object resulting from an operation using `get_val()` and assign it to another Fxp variable using `set_val()`. Alternatively, use the `()` operator for a more concise syntax.

```python
y.set_val( (x1*x3 - 3*x2).get_val() )   # equivalent to y.equal(x1*x3 - 3*x2), but less elegant
y( (x1*x3 - 3*x2)() )                   # just a little more elegant
```

--------------------------------

### Initialize and Print Fxp Configuration

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Demonstrates initializing an Fxp object and accessing its configuration parameters for printing. This is useful for inspecting the default or current settings of an Fxp instance.

```python
x = Fxp(None, True, 16, 4)
x.config.print()
```

--------------------------------

### Demonstrate 'ceil' Rounding with Offset

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/rounding_methods.ipynb

Illustrates the 'ceil' rounding method by applying a small offset to the input values before conversion. This helps to show how values just below a fixed-point boundary are rounded up.

```python
rounding = 'ceil'
fxp_var = Fxp(x-2**(-2*n_frac), rounding=rounding, like=fxp_ref)

plt.figure(figsize=(8,8))
plt.plot(x, x, marker='.', label='float')
plt.plot(x, fxp_var, marker='*', label=f'fxp {rounding}')
plt.grid()
plt.title(f'{rounding} rounding')
plt.legend()
plt.show()
```

--------------------------------

### Get Fxp Precision

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Retrieve the current precision setting of an Fxp object. This indicates the total number of bits used for representation.

```python
print(x.precision)
```

--------------------------------

### Demonstrate 'floor' Rounding with Offset

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/rounding_methods.ipynb

Visualizes the 'floor' rounding method by applying a small positive offset to the input values. This shows how values are rounded down to the nearest representable fixed-point number.

```python
rounding = 'floor'
fxp_var = Fxp(x+2**(-2*n_frac), rounding=rounding, like=fxp_ref)

plt.figure(figsize=(8,8))
plt.plot(x, x, marker='.', label='float')
plt.plot(x, fxp_var, marker='*', label=f'fxp {rounding}')
plt.grid()
plt.title(f'{rounding} rounding')
plt.legend()
plt.show()
```

--------------------------------

### Initialize Fxp with Various Data Types

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Demonstrates initializing Fxp variables with diverse input types including integers, floats, complex numbers, lists, NumPy arrays, and string representations of numbers (binary, hex, decimal).

```python
x(2)
```

```python
x(-1.75)
```

```python
x(-2.5 + 1j*0.25)
```

```python
x([1.0, 1.5, 2.0])
```

```python
x(np.random.uniform(size=(2,4)))
```

```python
x('3.5')
```

```python
x('0b11001010')
```

```python
x('0xA4')
```

--------------------------------

### Test Different op_sizing Strategies

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Iterates through all available 'op_sizing' strategies ('optimal', 'same', 'fit', 'largest', 'smallest') and applies them to an addition operation between two Fxp objects. The output shows how each strategy affects the resulting Fxp's data type.

```python
x = Fxp(3.5, True, 16, 4)
y = Fxp(-1.25, True, 24, 8)

for s in x.config._op_sizing_list:
    x.config.op_sizing = s
    print('{}:'.format(x.config.op_sizing))
    (x + y).info()
```

--------------------------------

### Get Value Representations

Source: https://github.com/francof2a/fxpmath/blob/develop/README.md

Retrieve the value stored in an fxp object in its original data type or as a NumPy array. The callable form is equivalent to get_val() or astype(self.vdtype).

```python
x
```

```python
x.get_val()

x()

```

--------------------------------

### Order of Operations for Copy and Assignment

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Demonstrates the correct order for copying Fxp properties and assigning new values to avoid unintended modifications. Applying `like` before assigning the new value is recommended.

```python
# be careful with:
y = y(-1.25).like(x)    # value -1.25 could be modify by overflow or rounding before considerating `x` properties.
```

```python
y = y.like(x)(-1.25)    # better!
```

--------------------------------

### Initialize Fxp Variables from Templates

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Initializes Fxp variables using the `like` method to inherit properties from predefined Fxp templates. This ensures consistency in fixed-point representation across different variables.

```python
# init
x1 = Fxp(-3.2).like(DATA)
x2 = Fxp(25.5).like(DATA)
c  = Fxp(2.65).like(CONSTANTS)
m  = Fxp().like(MULTIPLIERS)
y  = Fxp().like(ADDERS)
```

--------------------------------

### Get Fxp Value as Numpy Array

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Retrieve the value stored in the Fxp object as a NumPy array, maintaining its original data type representation. The call operator `()` is a shortcut for this.

```python
x.get_val()
```

```python
x()
```

--------------------------------

### Initialize Fxp with Saturation Overflow

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/rounding_methods.ipynb

Initializes a fixed-point number object with specific integer and fractional bits, and sets the overflow behavior to saturation. This configuration is used as a reference for subsequent operations.

```python
import numpy as np
import matplotlib.pyplot as plt

from fxpmath import Fxp
```

```python
n_frac = 2
n_int = 0
n_word = n_int + n_frac
overflow = 'saturate'

fxp_ref = Fxp(None, signed=True, n_int=n_int, n_frac=n_frac, overflow=overflow)

fxp_ref.info(3)
```

--------------------------------

### Initialize Fxp with Scaling and Bias

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Initializes an Fxp object with scaling and bias parameters to represent a specific range of numbers with a desired precision using fewer bits.

```python
x = Fxp(10128.5, signed=False, n_word=12, scale=1, bias=10000)
```

--------------------------------

### Initialize Fixed-Point Precision Object

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Creates a fixed-point number object with a specified format (signed 16-bit word, 15 fractional bits). This object serves as a reference for converting other numbers.

```python
from fxpmath import Fxp

fxp_ref = Fxp(None, dtype='fxp-s16/15')
```

--------------------------------

### Perform Arithmetic Operations with Fxp

Source: https://github.com/francof2a/fxpmath/blob/develop/README.md

Demonstrates basic arithmetic operations (+, -, *) between Fxp objects and constants. The result is a new Fxp object.

```python
x1 = Fxp(-7.25, signed=True, n_word=16, n_frac=8)
x2 = Fxp(1.5, signed=True, n_word=16, n_frac=8)
x3 = Fxp(-0.5, signed=True, n_word=8, n_frac=7)

y = 2*x1 + x2 - 0.5     # y is a new Fxp object

y = x1*x3 - 3*x2        # y is a new Fxp object, again
```

--------------------------------

### Initialize Fxp Templates

Source: https://github.com/francof2a/fxpmath/blob/develop/README.md

Define Fxp objects as templates (e.g., DATA, ADDERS) to ensure consistent properties when initializing other Fxp instances using the `like()` method.

```python
# Fxp like templates
DATA        = Fxp(None, True, 24, 15)
ADDERS      = Fxp(None, True, 40, 16)
MULTIPLIERS = Fxp(None, True, 24, 8)
CONSTANTS   = Fxp(None, True, 8, 4)
```

```python
# init
x1 = Fxp(-3.2).like(DATA)
x2 = Fxp(25.5).like(DATA)
c  = Fxp(2.65).like(CONSTANTS)
m  = Fxp().like(MULTIPLIERS)
y  = Fxp().like(ADDERS)
```

```python
# do the calc!
m.equal(c*x2)
y.equal(x1 + m)
```

--------------------------------

### Create Fxp Variable with Automatic Sizing

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Create an Fxp variable with a given value. The library automatically calculates the necessary bit sizes for word and fraction based on the value.

```python
from fxpmath import Fxp

x = Fxp(-7.25)      # create fxp variable with value 7.25
x.info()
```

--------------------------------

### Perform Addition with Raw Operation Method

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Illustrates addition of two Fxp objects using the 'raw' operation method, which uses internal integer representation for accuracy. This method is recommended for extended precision operations.

```python
a = Fxp([-1.0, 0.0, 1.0], True, 128, 96)
b = Fxp([2**-64, -2**48, 2**32], True, 128, 96)

c = a + b
print(c)
print(c-a) # equal to b
```

--------------------------------

### Generating a Sine Wave with Fxp and NumPy

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Create a sine wave using NumPy for calculations and store the result in an Fxp object. This demonstrates combining Fxp with external libraries for signal processing.

```python
import numpy as np

f = 5.0         # signal frequency
fs = 400.0      # sampling frequency
N = 1000        # number of samples

n = Fxp( list(range(N)) )                       # sample indices
y( 0.5 * np.sin(2 * np.pi * f * n() / fs) )     # a sin wave with 5.0 Hz of frequecy sampled at 400 samples per second
```

--------------------------------

### Assign Output to a Specific Fxp Object

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Demonstrates using the 'op_out' configuration to direct the result of an operation to a pre-existing Fxp object. Both the original Fxp and the output Fxp will hold the result.

```python
x = Fxp(2.0, True, 16, 2)
z = Fxp(0.0, True, 16, 4)

x.config.op_out = z

(x + 1).info()
z.info()
```

--------------------------------

### Demonstrate 'trunc' Rounding with Small Positive Offset

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/rounding_methods.ipynb

Shows the 'trunc' rounding method with a small positive offset added to the input values. This demonstrates how positive numbers are truncated towards zero.

```python
rounding = 'trunc'
fxp_var = Fxp(x + np.sign(x)*2**(-2*n_frac), rounding=rounding, like=fxp_ref)

plt.figure(figsize=(8,8))
plt.plot(x, x, marker='.', label='float')
plt.plot(x, fxp_var, marker='*', label=f'fxp {rounding}')
plt.grid()
plt.title(f'{rounding} rounding')
plt.legend()
plt.show()
```

--------------------------------

### Basic Arithmetic Operations with Constants

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Perform addition, subtraction, multiplication, division, floor division, modulo, and power operations with Fxp objects and constants. The precision of the result depends on the Fxp object's configuration.

```python
0.75 + x    # add a constant
x - 0.125   # substract a constant
3 * x       # multiply by a constant
x / 1.5     # division by a constant
x // 1.5    # floor division by a constant
x % 2       # modulo
x ** 3      # power
```

```python
y = 3.25 * (x - 0.5)    # y is a new Fxp object
```

--------------------------------

### Set Array Output Type

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Demonstrates switching between 'fxp' and 'array' output types for numpy operations, showing the difference in the returned object type.

```python
x = Fxp([1.0, 2.5, 3.0, 4.5], dtype='fxp-s16/4')
x.config.array_output_type = 'fxp'

z = np.sum(x)
z.info()

x.config.array_output_type = 'array'
z = np.sum(x)
print(z, type(z))
```

--------------------------------

### Configure Fxp Overflow Behavior

Source: https://github.com/francof2a/fxpmath/blob/develop/README.md

Explains how to configure the overflow behavior for Fxp objects at instantiation or after creation, with options for 'saturate' (default) and 'wrap'.

```python
# at instantiation
x = Fxp(3.25, True, 16, 8, overflow='saturate')

# afer ...
x.overflow = 'saturate'
# or
x.overflow = 'wrap'
```

--------------------------------

### Compile and Train Model

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Compiles the model with the SGD optimizer and categorical crossentropy loss, then trains it on the provided data. Uses a validation split to monitor performance during training.

```python
N_epochs = 50
model.compile(optimizer="sgd", loss='categorical_crossentropy', metrics=['accuracy'])

history = model.fit(x_train, y_train, batch_size=128, epochs=N_epochs, verbose=True, validation_split=.1)
```

--------------------------------

### Initialize Fxp with Various Data Types

Source: https://github.com/francof2a/fxpmath/blob/develop/README.md

Create or update an fxp object using various input types including integers, floats, complex numbers, lists, NumPy arrays, and string representations of numbers.

```python
x(2)

x(-1.75)

x(-2.5 + 1j*0.25)

x([1.0, 1.5, 2.0])

x(np.random.uniform(size=(2,4)))

x('3.5')

x('0b11001010')

x('0xA4')

```

--------------------------------

### Demonstrate 'trunc' Rounding with Larger Positive Offset

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/rounding_methods.ipynb

Illustrates the 'trunc' rounding method with a larger positive offset added to the input values. This further clarifies the truncation behavior, especially for values further from zero.

```python
rounding = 'trunc'
fxp_var = Fxp(x + 2*np.sign(x)*2**(-2*n_frac), rounding=rounding, like=fxp_ref)

plt.figure(figsize=(8,8))
plt.plot(x, x, marker='.', label='float')
plt.plot(x, fxp_var, marker='*', label=f'fxp {rounding}')
plt.grid()
plt.title(f'{rounding} rounding')
plt.legend()
plt.show()
```

--------------------------------

### Configure Array Operation Output Like

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Specifies an Fxp object to determine the output type and configuration for numpy operations, ensuring results match the 'like' object's properties.

```python
w = Fxp([1.0, -2.5, 3.0, -4.5], dtype='fxp-s16/4')
w.config.array_op_out_like = Fxp(0.0, True, 32, 8)

y = np.sum(w)
y.info()

y = np.cumsum(w)
y.info()
```

--------------------------------

### Initialize Fxp Templates

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Defines Fxp objects as templates with specific properties (signed, word bits, fractional bits) to be used for initializing other Fxp variables with the same characteristics.

```python
# Fxp like templates
DATA        = Fxp(None, True, 24, 15)
ADDERS      = Fxp(None, True, 40, 16)
MULTIPLIERS = Fxp(None, True, 24, 8)
CONSTANTS   = Fxp(None, True, 8, 4)
```

--------------------------------

### Perform Addition with Repr Operation Method

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Shows addition of two Fxp objects using the 'repr' operation method, which uses the original data types for operations. This can lead to precision loss, as demonstrated when adding a small fraction to a float.

```python
a.config.op_method = 'repr'
b.config.op_method = 'repr'

c = a + b
print(c)
print(c-a) # should be equal to b, but it doesn't
```

--------------------------------

### Read and Analyze Layer Weights and Biases

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Extracts weights and biases for each layer and prints their mean and standard deviation. This helps in understanding the distribution of values before fixed-point conversion.

```python
w_dict = {}
for layer in model.layers:
    w_dict[layer.name] = model.get_layer(layer.name).get_weights() # [layer_x_weights, layer_x_bias] 

    # print mean and standard deviation from weights and bias
    print('{} (weights):\tmean = {}\tstd = {}'.format(layer.name, np.mean(w_dict[layer.name][0]), np.std(w_dict[layer.name][0])))
    print('{} (bias):\t\tmean = {}\tstd = {}\n'.format(layer.name, np.mean(w_dict[layer.name][1]), np.std(w_dict[layer.name][1])))
```

--------------------------------

### Evaluate Model Performance with Varying Fixed-Point Precision

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Iterates through different fractional bit sizes to evaluate model performance. Converts floating-point weights to fixed-point representation using the Fxp class and evaluates the model on test data.

```python
n_frac_vals = np.arange(1, 16)
n_int = 1

fxp_loss_vals = []
fxp_acc_vals = []

for n_frac in n_frac_vals:
    fxp_ref = Fxp(None, signed=True, n_int=n_int, n_frac=n_frac)

    # convert floating point weights and bias to Fxp
    for layer, values in w_dict.items():
        
        model.get_layer(layer).set_weights([
            Fxp(values[0], like=fxp_ref), 
            Fxp(values[1], like=fxp_ref),
            ])
    
    loss, accuracy  = model.evaluate(x_test, y_test, verbose=False)
    print('{}:\tloss = {:.3}\tacc = {:.3}'.format(fxp_ref.dtype, loss, accuracy))

    fxp_loss_vals.append(loss)
    fxp_acc_vals.append(accuracy)
```

--------------------------------

### Configure Constant Operation Sizing

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Iterates through different constant operation sizing modes to observe their effect on the output Fxp object's data type and value.

```python
x = Fxp(3.5, True, 16, 4)

for s in x.config._const_op_sizing_list:
    x.config.const_op_sizing = s
    print('{}:'.format(x.config.const_op_sizing))
    (x + 2).info()
```

--------------------------------

### Quantization with Different Rounding Methods

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/ADC_sampling_quantization.ipynb

Applies quantization with 8 bits and 2 fractional bits using various rounding methods (ceil, floor, around, fix, trunc) and plots the results.

```python
signed = True
n_word = 8
n_frac = 2

roundings = ['ceil', 'floor', 'around', 'fix', 'trunc']

plt.figure(figsize=(12,6))
plt.plot(n, sig)
for r in roundings:
    sig_fxp = Fxp(sig, signed=signed, n_word=n_word, n_frac=n_frac, rounding=r)
    plt.plot(n, sig_fxp, label=r)
plt.legend()
plt.show()
```

--------------------------------

### Apply 'floor' Rounding

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/rounding_methods.ipynb

Applies the 'floor' rounding method to the input float array using the fxpmath library and visualizes the result against the original float values.

```python
rounding = 'floor'
fxp_var = Fxp(x, rounding=rounding, like=fxp_ref)

plt.figure(figsize=(8,8))
plt.plot(x, x, marker='.', label='float')
plt.plot(x, fxp_var, marker='*', label=f'fxp {rounding}')
plt.grid()
plt.title(f'{rounding} rounding')
plt.legend()
plt.show()
```

--------------------------------

### Configure Overflow Behavior on Instantiation

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Set the overflow behavior ('saturate' or 'wrap') when creating a new Fxp instance. The default is 'saturate'.

```python
x = Fxp(3.25, True, 16, 8, overflow='saturate')
```

--------------------------------

### Create Fxp Variable with Explicit Sizing

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Create an Fxp variable by explicitly defining its signedness, total word bits, and fractional bits. This provides precise control over the fixed-point representation.

```python
x = Fxp(-7.25, signed=True, n_word=16, n_frac=8)
```

```python
x = Fxp(-7.25, True, 16, 8)
```

--------------------------------

### Create Fxp Variable using dtype String

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Specify the fixed-point format using a string, either in the 'fxp-s<n_word>/<n_frac>' format or the 'Qm.n'/'Sm.n' notation.

```python
x = Fxp(-7.25, dtype='fxp-s16/8')
```

```python
x = Fxp(-7.25, dtype='S8.8')
```

--------------------------------

### Display Fixed-Point Weights

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Shows the fixed-point representation of the weights for a specific layer (layer_0 in this case). Useful for inspecting the conversion results.

```python
# show weights of layer_0 converted to fixed point
w_fxp_dict['layer_0'][0]
```

--------------------------------

### Copy Fxp and Set New Value

Source: https://github.com/francof2a/fxpmath/blob/develop/README.md

Copy an Fxp object and immediately set a new value. The `like(x)` method is useful for creating Fxp objects as templates for consistent properties.

```python
y = x.copy()(-1.25)
```

```python
y = Fxp(-1.25).like(x)
```

```python
y = Fxp(-1.25, like=x)
```

```python
y = y.like(x)(-1.25)
```

--------------------------------

### Convert Weights to Fixed-Point

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Converts all extracted weights and biases to the defined fixed-point precision using the 'like' parameter of the Fxp constructor.

```python
w_fxp_dict = {}

for layer in w_dict.keys():
    w_fxp_dict[layer] = [
        Fxp(w_dict[layer][0], like=fxp_ref), 
        Fxp(w_dict[layer][1], like=fxp_ref),
        ]

```

--------------------------------

### Display Fxp Scaling Information

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Displays detailed information about an Fxp object, including its value, scaling parameters, bit allocation, and operational limits.

```python
x.info(3)
```

--------------------------------

### Quantization with 8 bits, 7 fractional bits

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/ADC_sampling_quantization.ipynb

Quantizes the signal using 8-bit signed fixed-point representation with 7 fractional bits.

```python
signed = True
n_word = 8
n_frac = 7

sig_fxp = Fxp(sig, signed=signed, n_word=n_word, n_frac=n_frac)
```

--------------------------------

### Import Libraries

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/ADC_sampling_quantization.ipynb

Imports necessary libraries for numerical operations and plotting.

```python
import numpy as np
import matplotlib.pyplot as plt

from fxpmath import Fxp
```

--------------------------------

### Quantization with 8 bits, 2 fractional bits

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/ADC_sampling_quantization.ipynb

Quantizes the signal using 8-bit signed fixed-point representation with 2 fractional bits.

```python
signed = True
n_word = 8
n_frac = 2

sig_fxp = Fxp(sig, signed=signed, n_word=n_word, n_frac=n_frac)
```

--------------------------------

### Set Output Fxp Type Using op_out_like

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Configures the output Fxp object's type using 'op_out_like'. The result of the operation will be stored in an Fxp object matching the type specified by 'op_out_like'.

```python
x = Fxp(2.0, True, 16, 2)
x.config.op_out = Fxp(None, True, 24, 4)

z = x * 3.5 

z.info()
```

--------------------------------

### Instantiate Fxp with Rounding

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Set the rounding mode during the instantiation of an Fxp object. This mode will be used for all subsequent operations involving this object.

```python
x = Fxp(3.25, True, 16, 8, rounding='floor')
```

--------------------------------

### Apply 'around' Rounding

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/rounding_methods.ipynb

Applies the 'around' rounding method to the input float array using the fxpmath library and visualizes the result against the original float values.

```python
rounding = 'around'
fxp_var = Fxp(x, rounding=rounding, like=fxp_ref)

plt.figure(figsize=(8,8))
plt.plot(x, x, marker='.', label='float')
plt.plot(x, fxp_var, marker='*', label=f'fxp {rounding}')
plt.grid()
plt.title(f'{rounding} rounding')
plt.legend()
plt.show()
```

--------------------------------

### Quantization with 8 bits, 4 fractional bits

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/ADC_sampling_quantization.ipynb

Quantizes the signal using 8-bit signed fixed-point representation with 4 fractional bits.

```python
signed = True
n_word = 8
n_frac = 4

sig_fxp = Fxp(sig, signed=signed, n_word=n_word, n_frac=n_frac)
```

--------------------------------

### Load and Preprocess MNIST Dataset

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Loads the MNIST dataset, reshapes images into flat vectors, and converts labels to one-hot encoded format for neural network training.

```python
# Setup train and test splits
(x_train, y_train), (x_test, y_test) = mnist.load_data()
print("Training data shape: ", x_train.shape) 
print("Test data shape", x_test.shape)

# Flatten the images
image_size = 784 # 28*28
x_train = x_train.reshape(x_train.shape[0], image_size)
x_test = x_test.reshape(x_test.shape[0], image_size)

# Convert to "one-hot" vectors using the to_categorical function
num_classes = 10
y_train = keras.utils.to_categorical(y_train, num_classes)
y_test = keras.utils.to_categorical(y_test, num_classes)
```

--------------------------------

### Signedness and Overflow Orthogonality

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/generalized_sizing.md

Highlights that sizing defines range and precision, while runtime overflow behavior depends on configuration like signedness and overflow mode ('wrap' vs 'saturate').

```python
from fxpmath import Fxp

a = Fxp(20.0, signed=False, n_word=4, n_frac=0, overflow='wrap')
b = Fxp(20.0, signed=False, n_word=4, n_frac=0, overflow='saturate')

print(a())  # wrapped modulo range
print(b())  # clipped to max
```

--------------------------------

### Plot Signal Quantized with 8 bits, 7 fractional bits

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/ADC_sampling_quantization.ipynb

Plots the original signal alongside the signal quantized with 8 bits and 7 fractional bits.

```python
plt.figure(figsize=(12,6))
plt.plot(n, sig)
plt.plot(n, sig_fxp)
plt.show()
```

--------------------------------

### Apply 'ceil' Rounding

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/rounding_methods.ipynb

Applies the 'ceil' rounding method to the input float array using the fxpmath library and visualizes the result against the original float values.

```python
rounding = 'ceil'
fxp_var = Fxp(x, rounding=rounding, like=fxp_ref)

plt.figure(figsize=(8,8))
plt.plot(x, x, marker='.', label='float')
plt.plot(x, fxp_var, marker='*', label=f'fxp {rounding}')
plt.grid()
plt.title(f'{rounding} rounding')
plt.legend()
plt.show()
```

--------------------------------

### Copy Fxp Object

Source: https://github.com/francof2a/fxpmath/blob/develop/README.md

Create a copy of an Fxp object, including its value. `deepcopy` can also be used. `like(x)` copies properties without the value.

```python
y = x.copy()
```

```python
y = x.deepcopy()
```

```python
y = y.like(x)
```

--------------------------------

### Configure Array Operation Output

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Sets a specific Fxp object as the output for numpy operations, ensuring the result conforms to the specified Fxp object's configuration.

```python
w = Fxp([1.0, -2.5, 3.0, -4.5], dtype='fxp-s16/4')
z = Fxp(0.0, True, 16, 4)
w.config.array_op_out = z

y = np.sum(w)
y.info()
z.info()
print(y is z)
```

--------------------------------

### Copy Fxp Object

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Creates a copy of an Fxp object, optionally preserving existing values in the target variable. The `like` method is useful for copying properties to an existing Fxp object.

```python
y = x.copy()        # copy also the value stored
```

```python
# or
y = x.deepcopy()
```

```python
# if you want to preserve a value previously stored in `y` and only copy the properties from `x`:
y = y.like(x)
```

--------------------------------

### Basic Arithmetic Operations with Constants

Source: https://github.com/francof2a/fxpmath/blob/develop/README.md

Perform standard arithmetic operations (addition, subtraction, multiplication, division, modulo, power) between an fxp object and a constant. The constant is converted to an fxp object before the operation.

```python
0.75 + x

x - 0.125

3 * x

x / 1.5

x // 1.5

x % 2

x ** 3

```

--------------------------------

### Comparison Operators with Fxp

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Compare Fxp objects with constants or other Fxp variables using standard comparison operators like greater than and equal to.

```python
x > 5
x == y
# ... and other comparison availables
```

--------------------------------

### Copy and Assign New Value to Fxp

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Copies an Fxp object and immediately assigns a new value to the copied object. This can be done in a single line using chaining.

```python
y = x.copy()(-1.25)     # where -1.25 y the new value for `y` after copying `x`. It isn't necessary the `y` exists previously.
```

```python
# or
y = Fxp(-1.25).like(x)
```

```python
# or
y = Fxp(-1.25, like=x)
```

--------------------------------

### Perform Calculations with Fxp Variables

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Performs arithmetic operations between Fxp variables, ensuring that the results adhere to the fixed-point properties defined by their templates.

```python
# do the calc!
m.equal(c*x2)
y.equal(x1 + m)
```

--------------------------------

### Logical (Bitwise) Operations with Fxp

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Perform bitwise AND, OR, XOR, and NOT operations on Fxp objects with constants or other Fxp variables. Supports bit shifting to the left and right.

```python
x & 0b1100110011110000          # Fxp var AND constant
x & Fxp('0b11001100.11110000')  # Fxp var AND other Fxp with same constant
x & y                           # x AND y, both previoulsy defined

~x      # bits inversion
x | y   # x OR y
x ^ y   # x XOR y

x << 5  # x shifted 5 bits to the left
x >> 3  # x shifted 3 bits to the right (filled with sign bit)
```

--------------------------------

### Plot Model Accuracy vs. Fractional Bits

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Visualizes the model's accuracy as a function of the number of fractional bits used in the fixed-point representation. Compares the fixed-point accuracy with the original floating-point accuracy.

```python
fig, ax = plt.subplots(1, 1, figsize=(16,8))
plt.plot(fxp_acc_vals, marker='*', label='Fxp')
ax.axhline(float_accuracy, color='k', linestyle='--', label='float')
plt.title('model accuracy vs precision')
plt.ylabel('accuracy')
plt.xlabel('fractional bits')
plt.legend()
plt.ylim([0, 1])
plt.show()
```

--------------------------------

### Evaluate Fixed-Point Model Performance

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Evaluates the performance of the model with updated fixed-point weights on the test dataset, reporting the loss and accuracy.

```python
fxp_loss, fxp_accuracy  = model.evaluate(x_test, y_test, verbose=False)
print(f'Test loss: {fxp_loss:.3}')
print(f'Test accuracy: {fxp_accuracy:.3}')
```

--------------------------------

### NumPy Version Metadata

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/compatibility_notes.md

This metadata declares the compatible NumPy version range for the fxpmath package.

```text
numpy>=1.26.4,<3
```

--------------------------------

### Configure Array Operation Method

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Switches between 'repr' and 'raw' modes for numpy array conversion, affecting whether the array contains representation values or raw bit values.

```python
w = Fxp([1.0, -2.5, 3.0, -4.5], dtype='fxp-s8/2')
w.config.array_op_method = 'repr'

w_array = np.asarray(w)
print(w_array, type(w_array))

w.config.array_op_method = 'raw'
w_array = np.asarray(w)
print(w_array, type(w_array))
```

--------------------------------

### Set Input Size to 'same' for Multiplication

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Configures the Fxp object's input size to 'same' for operations involving non-Fxp types. When multiplying by a float, the float is converted to an Fxp with the same bit width, potentially losing precision.

```python
x = Fxp(2.0, True, 16, 2)
x.config.op_input_size = 'same'

z = x * 2.125

z.info()
```

--------------------------------

### Set Input Size to 'best' for Multiplication

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/config.md

Sets the Fxp object's input size to 'best' for operations with non-Fxp types. This allows the non-Fxp value to be converted to an Fxp with the most suitable resolution, preserving accuracy.

```python
x = Fxp(2.0, True, 16, 2)
x.config.op_input_size = 'best'

z = x * 2.125

z.info()
```

--------------------------------

### Import Libraries for MNIST NN

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Imports necessary libraries for building and training a neural network with TensorFlow and Keras, including data loading and visualization tools.

```python
import tensorflow as tf
import tensorflow.keras as keras

from tensorflow.keras.datasets import mnist
from tensorflow.keras.layers import Dense
from tensorflow.keras.models import Sequential

import matplotlib.pyplot as plt

import numpy as np
```

--------------------------------

### Plot Original Signal

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/ADC_sampling_quantization.ipynb

Plots the generated sinusoidal signal.

```python
plt.figure(figsize=(12,6))
plt.plot(n, sig)
plt.show()
```

--------------------------------

### Check Fxp Precision

Source: https://github.com/francof2a/fxpmath/blob/develop/README.md

Print the precision of an Fxp object, which is determined by the number of fractional bits.

```python
print(Fxp(n_frac=7).precision)
```

--------------------------------

### Print Fxp Precision

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Prints the precision of an Fxp object, which is determined by the number of fractional bits.

```python
print(Fxp(n_frac=7).precision)  # print the precision of a fxp with 7 bits for fractional part.
```

--------------------------------

### Apply 'fix' Rounding

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/rounding_methods.ipynb

Applies the 'fix' rounding method to the input float array using the fxpmath library and visualizes the result against the original float values.

```python
rounding = 'fix'
fxp_var = Fxp(x, rounding=rounding, like=fxp_ref)

plt.figure(figsize=(8,8))
plt.plot(x, x, marker='.', label='float')
plt.plot(x, fxp_var, marker='*', label=f'fxp {rounding}')
plt.grid()
plt.title(f'{rounding} rounding')
plt.legend()
plt.show()
```

--------------------------------

### Represent Fxp Value in Binary and Hexadecimal

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Convert the Fxp value to its binary or hexadecimal string representation. Options are available to include a fractional dot or display with a sign symbol.

```python
x.bin()
```

```python
x.bin(frac_dot=True)
```

```python
x.base_repr(2)
```

```python
x.hex()
```

```python
x.base_repr(16)
```

--------------------------------

### Generate Float Array for Rounding Tests

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/rounding_methods.ipynb

Creates a NumPy array of floating-point numbers based on the precision and range of the reference fixed-point object. This array serves as input for testing different rounding methods.

```python
ratio = 4
float_precision = fxp_ref.precision / ratio
x = np.arange(fxp_ref.lower - (ratio*float_precision), fxp_ref.upper + ratio*float_precision, step=float_precision)
print(x)
```

--------------------------------

### Assigning Operation Results to a Specific Fxp Variable

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Store the result of an arithmetic operation into a pre-defined Fxp variable with a specific format. Use the `equal` method for direct assignment.

```python
# variable to store a result
y = Fxp(None, signed=True, n_word=32, n_frac=16)

y.equal(x1*x3 - 3*x2)
```

--------------------------------

### Plot Training Accuracy vs. Epochs

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Visualizes the training and validation accuracy over epochs. This helps in understanding model convergence and identifying overfitting. The y-axis is limited to a range of 0.4 to 1 for better visualization.

```python
plt.figure(figsize=(16,8))
plt.plot(history.history['accuracy'], label='train')
plt.plot(history.history['val_accuracy'], label='test')
plt.title('model accuracy')
plt.ylabel('accuracy')
plt.xlabel('epoch')
plt.legend()
plt.ylim([0.4, 1])
plt.show()
```

--------------------------------

### Apply 'trunc' Rounding

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/rounding_methods.ipynb

Applies the 'trunc' (truncate) rounding method to the input float array using the fxpmath library and visualizes the result against the original float values.

```python
rounding = 'trunc'
fxp_var = Fxp(x, rounding=rounding, like=fxp_ref)

plt.figure(figsize=(8,8))
plt.plot(x, x, marker='.', label='float')
plt.plot(x, fxp_var, marker='*', label=f'fxp {rounding}')
plt.grid()
plt.title(f'{rounding} rounding')
plt.legend()
plt.show()
```

--------------------------------

### Update Model Weights with Fixed-Point Values

Source: https://github.com/francof2a/fxpmath/blob/develop/examples/Fixed_Point_Precision_Neural_Network_for_MNIST_dataset.ipynb

Sets the weights and biases of the model's layers to their newly converted fixed-point representations.

```python
for layer, values in w_fxp_dict.items():
    model.get_layer(layer).set_weights(values)
```

--------------------------------

### Arithmetic Operations with Two Fxp Operands

Source: https://github.com/francof2a/fxpmath/blob/develop/docs/quick_start.md

Perform arithmetic operations between two Fxp objects. The size of the returned Fxp object is determined by the sizes of the operands and the `config.op_sizing` parameter.

```python
# Fxp as operands
x1 = Fxp(-7.25, signed=True, n_word=16, n_frac=8)
x2 = Fxp(1.5, signed=True, n_word=16, n_frac=8)
x3 = Fxp(-0.5, signed=True, n_word=8, n_frac=7)

y = 2*x1 + x2 - 0.5     # y is a new Fxp object

y = x1*x3 - 3*x2        # y is a new Fxp object, again
```