VWAP (Volume Weighted Average Price) calculates the cumulative average price weighted by trading volume, typically reset at session boundaries. It represents the true average price at which a security has traded throughout the period, giving more weight to prices where higher volume occurred. This implementation supports flexible period-based resets rather than traditional session-based anchoring.
## Historical Context
VWAP emerged in the 1980s as institutional traders sought benchmarks for execution quality. Before electronic trading, large orders moved markets significantly, and traders needed a way to measure whether their executions were favorable relative to the day's overall trading activity.
The concept gained prominence with the rise of algorithmic trading in the 1990s. Portfolio managers began using VWAP as a benchmark for their brokers—if you bought shares at a price below VWAP, you outperformed the average buyer that day. This created an entire industry of "VWAP execution algorithms" designed to spread large orders across time to minimize market impact.
Traditional implementations anchor VWAP to market session boundaries (daily, weekly, monthly). This QuanTAlib implementation extends the concept with configurable period-based resets, enabling intraday applications and backtesting scenarios where session boundaries aren't meaningful.
## Architecture & Physics
VWAP operates as a cumulative weighted average with optional periodic resets.
### 1. Typical Price Calculation
The typical price (HLC3) represents the central tendency of each bar:
$$
TP_t = \frac{High_t + Low_t + Close_t}{3}
$$
HLC3 is preferred over close-only pricing because it captures intrabar price discovery, particularly important for high-volume bars where significant trading occurred across the price range.
### 2. Cumulative Sums
VWAP maintains two running totals:
$$
\sum PV_t = \sum_{i=start}^{t} (TP_i \times V_i)
$$
$$
\sum V_t = \sum_{i=start}^{t} V_i
$$
where $start$ is either the beginning of the series or the last reset point.
### 3. VWAP Calculation
$$
VWAP_t = \frac{\sum PV_t}{\sum V_t}
$$
When $\sum V_t = 0$ (no volume), VWAP returns the current typical price as a fallback.
| **Stability** | 9/10 | Smooth; resets can cause jumps |
| **Interpretability** | 10/10 | Clear economic meaning |
## Validation
| Library | Status | Notes |
| :--- | :---: | :--- |
| **TA-Lib** | N/A | Not implemented |
| **Skender** | ⚠️ | Session-anchored, different reset model |
| **Tulip** | N/A | Not implemented |
| **Ooples** | ⚠️ | Implementation may differ |
| **Self-consistency** | ✅ | Streaming/Batch/Span modes match |
VWAP implementations vary primarily in reset behavior. This implementation uses period-based resets for maximum flexibility, while most others use calendar-based session anchoring.
## Common Pitfalls
1.**Session vs Period Confusion**: Traditional VWAP resets at market open. This implementation uses bar-count periods. For session VWAP, set period to match your session length in bars (e.g., 390 for US equities on 1-minute data).
2.**Cumulative Error Accumulation**: While mathematically exact, floating-point arithmetic accumulates error over thousands of bars. Difference of ~1e-10 per 5000 bars is typical and acceptable.
3.**Zero Volume Bars**: Bars with zero volume don't affect VWAP. This is correct behavior—no trades means no price discovery contribution.
4.**Intraday Interpretation**: VWAP is most meaningful when reset at consistent intervals. Comparing VWAP values across different reset periods is not meaningful.
5.**Reset Timing**: Reset occurs BEFORE processing the bar that triggers it. Bar at index `period` starts fresh accumulation.
6.**TValue API Limitation**: When using `Update(TValue)`, a synthetic bar is created with the value as all OHLC prices and volume=1. This works for simple averaging but loses volume weighting benefits.
## References
- Berkowitz, S., Logue, D., & Noser, E. (1988). "The Total Cost of Transactions on the NYSE." *Journal of Finance*.
- Madhavan, A. (2002). "VWAP Strategies." *Trading*, Spring 2002.
