# DECAY: Linear Decay

> *A ratchet that only moves down slowly: price can push it up instantly, but gravity pulls it back at a steady, linear pace.*

| Property         | Value                            |
| ---------------- | -------------------------------- |
| **Category**     | Numerics                         |
| **Inputs**       | Source (close)                   |
| **Parameters**   | `period` (default 5)             |
| **Outputs**      | Single series (Decay)            |
| **Output range** | Same as input (overlay)          |
| **Warmup**       | `1` bar                          |
| **PineScript**   | [decay.pine](decay.pine)                       |

- DECAY (Linear Decay) tracks the maximum of the current input and the previous output minus a fixed absolute step of `1/period`.
- **Similar:** [EDecay](../edecay/Edecay.md) | **Trading note:** Linear decay function; models signal fading over time. Used for recency-weighted calculations.
- Validated against Tulip Indicators `ti_decay` reference algorithm.

DECAY implements the Tulip Indicators `ti_decay` function. When price is above the decayed level, output snaps to price. When price falls below, the output decays linearly at a rate of `1/period` per bar, creating a ceiling that gradually descends. This produces a one-sided envelope that hugs price from above.

## Historical Context

The linear decay indicator originates from the Tulip Indicators library, a high-performance C library of technical indicators. It provides a simple peak-tracking mechanism where the tracked level decays at a constant absolute rate. The indicator is useful for:

- **Trailing stops**: The decaying level acts as a simple trailing stop that descends at a fixed rate.
- **Peak detection**: Identifies when price last reached a new high relative to the decay rate.
- **Signal filtering**: Removes noise by requiring price to exceed the decayed level to register as significant.

## Architecture & Physics

### 1. Pure IIR (No Buffer)

The indicator requires no history buffer — only the previous output value is needed:

$$
\text{state} = \{y_{t-1}\}
$$

This makes it O(1) in both time and space.

### 2. Linear Decay Calculation

$$
y_t = \max(x_t, \; y_{t-1} - \frac{1}{p})
$$

where:
- $x_t$ = current input value
- $y_{t-1}$ = previous output value
- $p$ = period parameter
- $\frac{1}{p}$ = fixed decay step per bar

### 3. First Bar Initialization

$$
y_0 = x_0
$$

The first bar simply passes through the input value.

### 4. State Management

The indicator uses state rollback for bar correction:

```
if isNew:
    save current state as previous
else:
    restore previous state
```

## Mathematical Foundation

### Core Formula

$$
y_t = \max(x_t, \; y_{t-1} - s)
$$

where $s = \frac{1}{p}$ is the fixed linear decay rate.

### Decay Behavior

After a peak at value $v$, with no new inputs exceeding the decayed level, the output follows:

$$
y_{t+k} = v - k \cdot s
$$

reaching zero after $k = v \cdot p$ bars (assuming $v > 0$).

### Properties

| Property | Value |
|----------|-------|
| Lookback | 0 |
| Output ≥ Input | Always (by construction) |
| Decay rate | Constant absolute $\frac{1}{p}$ |
| Monotonic when decaying | Yes (strictly decreasing) |

## Performance Profile

### Operation Count (Streaming Mode)

| Operation | Count | Notes |
| :--- | :---: | :--- |
| SUB | 1 | prev_output - scale |
| MAX/CMP | 1 | max(input, decayed) |
| State copy | 1 | rollback support |
| **Total** | **~3 ops** | Extremely lightweight |

### Batch Mode (Span-based)

| Operation | Complexity | Notes |
| :--- | :---: | :--- |
| Per-element | O(1) | Sub + compare |
| Total | O(n) | Linear scan |
| Memory | O(1) | No additional allocation |

### Quality Metrics

| Metric | Score | Notes |
| :--- | :---: | :--- |
| **Accuracy** | 10/10 | Exact arithmetic, no approximation |
| **Timeliness** | 10/10 | Zero lag on upward moves |
| **Smoothness** | 2/10 | No smoothing — linear staircase |
| **Simplicity** | 10/10 | Single subtraction + compare |

## Validation

| Library | Status | Notes |
| :--- | :---: | :--- |
| **Tulip** | ✅ | Manual ti_decay algorithm matches exactly |

## Common Pitfalls

1. **Not a moving average**: Decay is a peak-tracking/envelope indicator, not a smoothing filter. It only descends when price is below the decayed level.

2. **Absolute decay rate**: The decay step is `1/period` in absolute terms, regardless of price level. For a stock at $100 with period=5, the decay is $0.20/bar; for a stock at $10, it's the same $0.20/bar. Consider normalizing if comparing across instruments.

3. **Period interpretation**: Period=5 means the output decays by 1.0 over 5 bars (0.2 per bar), not that it looks back 5 bars.

4. **First bar**: The first bar always equals the input — there is no warmup period in the traditional sense.

5. **Asymmetric behavior**: Upward moves are instant (output = input), but downward moves are rate-limited to `1/period` per bar.

## References

- Tulip Indicators Library: https://tulipindicators.org/decay
- Kegel, L. "Tulip Indicators" — Open-source C library of technical indicators.