QuanTAlib/lib/oscillators/bbs/Bbs.md

BBS: Bollinger Band Squeeze

"Volatility contraction precedes expansion. The squeeze tells you when to watch."

Bollinger Band Squeeze detects when Bollinger Bands contract inside Keltner Channels — a condition signaling low volatility consolidation that typically precedes explosive price moves.

Calculation

1. Compute Bollinger Bands using SMA and population standard deviation.
2. Compute Keltner Channels using SMA and EMA-smoothed ATR.
3. Detect squeeze: BB bands inside KC bands.
4. Output bandwidth as a percentage.

Formula:

BB_Middle = SMA(close, bbPeriod)
BB_StdDev = sqrt(E[x^2] - E[x]^2)
BB_Upper = BB_Middle + bbMult * BB_StdDev
BB_Lower = BB_Middle - bbMult * BB_StdDev

KC_Middle = SMA(close, kcPeriod)
ATR = EMA-smoothed True Range (with warmup compensation)
KC_Upper = KC_Middle + kcMult * ATR
KC_Lower = KC_Middle - kcMult * ATR

SqueezeOn = BB_Upper < KC_Upper AND BB_Lower > KC_Lower
Bandwidth = ((BB_Upper - BB_Lower) / BB_Middle) * 100

Interpretation

• Squeeze On (red dot) → low volatility, consolidation phase. Bands are tightening.
• Squeeze Off (green dot) → volatility expansion, potential breakout.
• Squeeze Fired → first bar after squeeze ends — the breakout moment.
• Bandwidth → measures BB width as a percentage of the middle band.

Parameters

Name	Type	Default	Range	Description
bbPeriod	int	20	>0	Bollinger Band lookback period.
bbMult	double	2.0	>0	BB standard deviation multiplier.
kcPeriod	int	20	>0	Keltner Channel lookback period.
kcMult	double	1.5	>0	KC ATR multiplier.

API

classDiagram
    class Bbs {
        +Name : string
        +WarmupPeriod : int
        +IsHot : bool
        +SqueezeOn : bool
        +SqueezeFired : bool
        +Last : TValue
        +Update(TBar input, bool isNew) TValue
        +Update(TBarSeries source) TSeries
        +Prime(TBarSeries source) void
        +Reset() void
        +Batch(TBarSeries source) TSeries
        +Batch(TBarSeries source, int bbPeriod, double bbMult, int kcPeriod, double kcMult) TSeries
        +Batch(ReadOnlySpan~double~ high, low, close, Span~double~ output, ...) void
        +Batch(ReadOnlySpan~double~ high, low, close, Span~double~ bandwidth, Span~bool~ squeezeOn, ...) void
        +Calculate(TBarSeries source, ...) (TSeries Results, Bbs Indicator)
    }

Usage Example

using QuanTAlib;

// Initialize
var bbs = new Bbs(bbPeriod: 20, bbMult: 2.0, kcPeriod: 20, kcMult: 1.5);

foreach (var bar in bars)
{
    bbs.Update(bar);

    if (bbs.IsHot)
    {
        string state = bbs.SqueezeOn ? "SQUEEZE" : "EXPANSION";
        Console.WriteLine($"{bar.Time}: Bandwidth={bbs.Last.Value:F2}% [{state}]");

        if (bbs.SqueezeFired)
        {
            Console.WriteLine("  *** BREAKOUT DETECTED ***");
        }
    }
}

Performance Profile

Metric	Score	Notes
Throughput	9	O(1) rolling sums for BB and KC.
Allocations	0	Zero allocations in hot path.
Complexity	O(1)	Constant time per update.
Accuracy	10	Matches Pine reference formula.
Timeliness	7	Period-length lag from SMA components.
Overshoot	N/A	Boolean squeeze output, bandwidth >= 0.
Smoothness	6	Moderate smoothing via SMA and ATR EMA.

Validation

Bandwidth component validated against Skender GetBollingerBands().Width. Internal consistency verified across streaming, batch, and span modes. Squeeze logic cross-validated against TtmSqueeze (which uses the same BB-inside-KC condition).

Sources

• John Bollinger, Bollinger on Bollinger Bands
• John Carter, Mastering the Trade — squeeze concept
• PineScript reference