README.md

---
license: mit
tags:
- pytorch
- safetensors
- threshold-logic
- neuromorphic
- arithmetic
- dsp
---

# 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

```python
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