threshold-saturating-adder

4-bit unsigned saturating adder. Clamps to maximum value on overflow instead of wrapping around.

Circuit

A[3:0] ──┐
         ├──► Sat Add ──┬──► S[3:0]    (result)
B[3:0] ──┘              └──► saturated (overflow flag)

Behavior

A + B	Result	Saturated
≤ 15	A + B	0
> 15	15	1

Examples

 7 +  5 = 12, saturated=0
10 + 10 = 15, saturated=1 (true sum: 20)
15 + 15 = 15, saturated=1 (true sum: 30)
 8 +  7 = 15, saturated=0
 8 +  8 = 15, saturated=1 (true sum: 16)

Wrapping vs Saturating

Wrapping:   15 + 1 = 0  (modulo 16)
Saturating: 15 + 1 = 15 (clamped)

Architecture

Component	Count	Neurons
Full Adders	4	28
Saturation MUXes	4	12

Total: 40 neurons, 124 parameters, 4 layers

How It Works

1. Compute A + B with standard 4-bit adder
2. If carry out = 1:
   - Output 1111 (15)
   - Set saturated = 1
3. Else:
   - Output sum bits
   - Set saturated = 0

Applications

• Audio DSP: Prevents clipping distortion
• Image processing: Pixel value saturation
• Neural networks: Activation clamping
• Control systems: Prevents actuator overshoot
• Fixed-point arithmetic: Overflow protection

Usage

from safetensors.torch import load_file

w = load_file('model.safetensors')

# All 256 test cases verified
# Saturates 120 cases (where A+B > 15)

Files

threshold-saturating-adder/
├── model.safetensors
├── create_safetensors.py
├── config.json
└── README.md

License

MIT