nautilus_indicators/average/
vwap.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16use std::fmt::Display;
17
18use nautilus_model::data::Bar;
19
20use crate::indicator::Indicator;
21
22#[repr(C)]
23#[derive(Debug, Default)]
24#[cfg_attr(
25    feature = "python",
26    pyo3::pyclass(module = "nautilus_trader.indicators")
27)]
28#[cfg_attr(
29    feature = "python",
30    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.indicators")
31)]
32pub struct VolumeWeightedAveragePrice {
33    pub value: f64,
34    pub initialized: bool,
35    has_inputs: bool,
36    price_volume: f64,
37    volume_total: f64,
38    day: i64,
39}
40
41impl Indicator for VolumeWeightedAveragePrice {
42    fn name(&self) -> String {
43        stringify!(VolumeWeightedAveragePrice).to_string()
44    }
45
46    fn has_inputs(&self) -> bool {
47        self.has_inputs
48    }
49
50    fn initialized(&self) -> bool {
51        self.initialized
52    }
53
54    fn handle_bar(&mut self, bar: &Bar) {
55        let typical_price = (bar.close.as_f64() + bar.high.as_f64() + bar.low.as_f64()) / 3.0;
56
57        self.update_raw(typical_price, (&bar.volume).into(), bar.ts_init.as_f64());
58    }
59
60    fn reset(&mut self) {
61        self.value = 0.0;
62        self.has_inputs = false;
63        self.initialized = false;
64        self.day = -1;
65        self.price_volume = 0.0;
66        self.volume_total = 0.0;
67    }
68}
69
70impl VolumeWeightedAveragePrice {
71    /// Creates a new [`VolumeWeightedAveragePrice`] instance.
72    #[must_use]
73    pub const fn new() -> Self {
74        Self {
75            value: 0.0,
76            initialized: false,
77            has_inputs: false,
78            price_volume: 0.0,
79            volume_total: 0.0,
80            day: -1,
81        }
82    }
83
84    pub fn update_raw(&mut self, price: f64, volume: f64, timestamp: f64) {
85        const NANOSECONDS_PER_DAY: f64 = 86_400.0 * 1_000_000_000.0;
86        let epoch_day = (timestamp / NANOSECONDS_PER_DAY).floor() as i64;
87
88        if epoch_day != self.day {
89            self.reset();
90            self.day = epoch_day;
91            self.value = price;
92        }
93
94        if !self.initialized {
95            self.has_inputs = true;
96            self.initialized = true;
97        }
98
99        if volume == 0.0 {
100            return;
101        }
102
103        self.price_volume += price * volume;
104        self.volume_total += volume;
105        self.value = self.price_volume / self.volume_total;
106    }
107}
108
109impl Display for VolumeWeightedAveragePrice {
110    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
111        write!(f, "{}", self.name())
112    }
113}
114
115#[cfg(test)]
116mod tests {
117    use nautilus_model::data::Bar;
118    use rstest::rstest;
119
120    use crate::{
121        average::vwap::VolumeWeightedAveragePrice, indicator::Indicator, stubs::*,
122        testing::assert_approx_equal,
123    };
124
125    const NANOSECONDS_PER_DAY: f64 = 86_400.0 * 1_000_000_000.0;
126    const DAY0: f64 = 10.0 * 1_000_000_000.0;
127    const DAY1: f64 = NANOSECONDS_PER_DAY;
128
129    #[rstest]
130    fn test_vwap_initialized(indicator_vwap: VolumeWeightedAveragePrice) {
131        let display_st = format!("{indicator_vwap}");
132        assert_eq!(display_st, "VolumeWeightedAveragePrice");
133        assert!(!indicator_vwap.initialized());
134        assert!(!indicator_vwap.has_inputs());
135    }
136
137    #[rstest]
138    fn test_value_with_one_input(mut indicator_vwap: VolumeWeightedAveragePrice) {
139        indicator_vwap.update_raw(10.0, 10.0, DAY0);
140        assert_eq!(indicator_vwap.value, 10.0);
141    }
142
143    #[rstest]
144    fn test_value_with_three_inputs_on_the_same_day(
145        mut indicator_vwap: VolumeWeightedAveragePrice,
146    ) {
147        indicator_vwap.update_raw(10.0, 10.0, DAY0);
148        indicator_vwap.update_raw(20.0, 20.0, DAY0 + 1.0);
149        indicator_vwap.update_raw(30.0, 30.0, DAY0 + 2.0);
150        assert!((indicator_vwap.value - 23.333_333_333_333_332).abs() < 1e-12);
151    }
152
153    #[rstest]
154    fn test_value_with_three_inputs_on_different_days(
155        mut indicator_vwap: VolumeWeightedAveragePrice,
156    ) {
157        indicator_vwap.update_raw(10.0, 10.0, DAY0);
158        indicator_vwap.update_raw(20.0, 20.0, DAY1);
159        indicator_vwap.update_raw(30.0, 30.0, DAY0);
160        assert_eq!(indicator_vwap.value, 30.0);
161    }
162
163    #[rstest]
164    fn test_value_with_ten_inputs(mut indicator_vwap: VolumeWeightedAveragePrice) {
165        for i in 0..10 {
166            let price = 0.00010f64.mul_add(f64::from(i), 1.00000);
167            let volume = 1.0 + f64::from(i % 3);
168            indicator_vwap.update_raw(price, volume, DAY0);
169        }
170        indicator_vwap.update_raw(1.00000, 2.00000, DAY0);
171        assert!((indicator_vwap.value - 1.000_414_285_714_286).abs() < 1e-12);
172    }
173
174    #[rstest]
175    fn test_handle_bar(
176        mut indicator_vwap: VolumeWeightedAveragePrice,
177        bar_ethusdt_binance_minute_bid: Bar,
178    ) {
179        indicator_vwap.handle_bar(&bar_ethusdt_binance_minute_bid);
180        assert_approx_equal(indicator_vwap.value, 1522.33333333);
181        assert!(indicator_vwap.initialized);
182    }
183
184    #[rstest]
185    fn test_reset(mut indicator_vwap: VolumeWeightedAveragePrice) {
186        indicator_vwap.update_raw(10.0, 10.0, DAY0);
187        indicator_vwap.reset();
188        assert_eq!(indicator_vwap.value, 0.0);
189        assert!(!indicator_vwap.has_inputs);
190        assert!(!indicator_vwap.initialized);
191    }
192
193    #[rstest]
194    fn test_reset_on_exact_day_boundary() {
195        let mut vwap = VolumeWeightedAveragePrice::new();
196
197        vwap.update_raw(100.0, 5.0, DAY0);
198        let old = vwap.value;
199
200        vwap.update_raw(200.0, 5.0, DAY1);
201        assert_eq!(vwap.value, 200.0);
202        assert_ne!(vwap.value, old);
203    }
204
205    #[rstest]
206    fn test_no_reset_within_same_day() {
207        let mut vwap = VolumeWeightedAveragePrice::new();
208        vwap.update_raw(100.0, 5.0, DAY0);
209
210        vwap.update_raw(200.0, 5.0, DAY0 + 1.0);
211        assert!(vwap.value > 100.0 && vwap.value < 200.0);
212    }
213
214    #[rstest]
215    fn test_zero_volume_does_not_change_value() {
216        let mut vwap = VolumeWeightedAveragePrice::new();
217        vwap.update_raw(100.0, 10.0, DAY0);
218        let before = vwap.value;
219
220        vwap.update_raw(9999.0, 0.0, DAY0);
221        assert_eq!(vwap.value, before);
222    }
223
224    #[rstest]
225    fn test_epoch_day_floor_rounding() {
226        let mut vwap = VolumeWeightedAveragePrice::new();
227
228        vwap.update_raw(50.0, 5.0, DAY1 - 1.0); // 1 nanosecound before midnight
229        let before = vwap.value;
230
231        vwap.update_raw(150.0, 5.0, DAY1);
232        assert_eq!(vwap.value, 150.0);
233        assert_ne!(vwap.value, before);
234    }
235
236    #[rstest]
237    fn test_reset_when_timestamp_goes_backwards() {
238        let mut vwap = VolumeWeightedAveragePrice::new();
239        vwap.update_raw(10.0, 10.0, DAY0);
240        vwap.update_raw(20.0, 10.0, DAY1);
241        vwap.update_raw(30.0, 10.0, DAY0);
242        assert_eq!(vwap.value, 30.0);
243    }
244
245    #[rstest]
246    #[case(10.0e9, 11.0e9)]
247    #[case(43_200.123e9, 86_399.999e9)]
248    fn test_no_reset_for_same_epoch_day(#[case] t1: f64, #[case] t2: f64) {
249        let mut vwap = VolumeWeightedAveragePrice::new();
250
251        vwap.update_raw(100.0, 10.0, t1);
252        let before = vwap.value;
253
254        vwap.update_raw(200.0, 10.0, t2);
255
256        assert!(vwap.value > before && vwap.value < 200.0);
257    }
258
259    #[rstest]
260    #[case(86_399.999e9, 86_400.0e9)]
261    #[case(86_400.0e9, 172_800.0e9)]
262    fn test_reset_when_epoch_day_changes(#[case] t1: f64, #[case] t2: f64) {
263        let mut vwap = VolumeWeightedAveragePrice::new();
264
265        vwap.update_raw(100.0, 10.0, t1);
266
267        vwap.update_raw(200.0, 10.0, t2);
268
269        assert_eq!(vwap.value, 200.0);
270    }
271
272    #[rstest]
273    fn test_first_input_zero_volume_does_not_divide_by_zero() {
274        let mut vwap = VolumeWeightedAveragePrice::new();
275
276        vwap.update_raw(100.0, 0.0, DAY0);
277        assert_eq!(vwap.value, 100.0);
278        assert!(vwap.initialized());
279
280        vwap.update_raw(200.0, 10.0, DAY0 + 1.0);
281        assert_eq!(vwap.value, 200.0);
282    }
283
284    #[rstest]
285    fn test_zero_volume_day_rollover_resets_and_seeds() {
286        let mut vwap = VolumeWeightedAveragePrice::new();
287        vwap.update_raw(100.0, 10.0, DAY0);
288
289        vwap.update_raw(9999.0, 0.0, DAY1);
290        assert_eq!(vwap.value, 9999.0);
291    }
292
293    #[rstest]
294    fn test_handle_bar_matches_update_raw(
295        mut indicator_vwap: VolumeWeightedAveragePrice,
296        bar_ethusdt_binance_minute_bid: Bar,
297    ) {
298        indicator_vwap.handle_bar(&bar_ethusdt_binance_minute_bid);
299
300        let tp = (bar_ethusdt_binance_minute_bid.close.as_f64()
301            + bar_ethusdt_binance_minute_bid.high.as_f64()
302            + bar_ethusdt_binance_minute_bid.low.as_f64())
303            / 3.0;
304
305        let mut vwap_raw = VolumeWeightedAveragePrice::new();
306        vwap_raw.update_raw(
307            tp,
308            (&bar_ethusdt_binance_minute_bid.volume).into(),
309            bar_ethusdt_binance_minute_bid.ts_init.as_f64(),
310        );
311
312        assert!((indicator_vwap.value - vwap_raw.value).abs() < 1e-12);
313    }
314
315    #[rstest]
316    #[case(1.0e-9, 1.0e-9)]
317    #[case(1.0e9, 1.0e6)]
318    #[case(42.4242, std::f64::consts::PI)]
319    fn test_extreme_prices_and_volumes_do_not_overflow(#[case] price: f64, #[case] volume: f64) {
320        let mut vwap = VolumeWeightedAveragePrice::new();
321        vwap.update_raw(price, volume, DAY0);
322        assert_eq!(vwap.value, price);
323    }
324
325    #[rstest]
326    fn negative_timestamp() {
327        let mut vwap = VolumeWeightedAveragePrice::new();
328        vwap.update_raw(42.0, 1.0, -1.0);
329        assert_eq!(vwap.value, 42.0);
330        vwap.update_raw(43.0, 1.0, -1.0);
331        assert!(vwap.value > 42.0 && vwap.value < 43.0);
332    }
333
334    #[rstest]
335    fn huge_future_timestamp_saturates() {
336        let ts = 1.0e20;
337        let mut vwap = VolumeWeightedAveragePrice::new();
338        vwap.update_raw(1.0, 1.0, ts);
339        vwap.update_raw(2.0, 1.0, ts + 1.0);
340        assert!(vwap.value > 1.0 && vwap.value < 2.0);
341    }
342
343    #[rstest]
344    fn negative_volume_changes_sign() {
345        let mut vwap = VolumeWeightedAveragePrice::new();
346        vwap.update_raw(100.0, 10.0, 0.0);
347        vwap.update_raw(200.0, -10.0, 0.0);
348        assert_eq!(vwap.volume_total, 0.0);
349    }
350
351    #[rstest]
352    fn nan_volume_propagates() {
353        let mut vwap = VolumeWeightedAveragePrice::new();
354        vwap.update_raw(100.0, 1.0, 0.0);
355        vwap.update_raw(200.0, f64::NAN, 0.0);
356        assert!(vwap.value.is_nan());
357    }
358
359    #[rstest]
360    fn zero_and_negative_price() {
361        let mut vwap = VolumeWeightedAveragePrice::new();
362        vwap.update_raw(0.0, 5.0, 0.0);
363        assert_eq!(vwap.value, 0.0);
364        vwap.update_raw(-10.0, 5.0, 0.0);
365        assert!(vwap.value < 0.0);
366    }
367    /// Regression test for <https://github.com/nautechsystems/nautilus_trader/issues/4428>
368    ///
369    /// Before the fix, `update_raw` compared a nanosecond `ts_init` value against
370    /// `SECONDS_PER_DAY = 86_400.0`, causing a spurious day-rollover every ~86 µs.
371    #[rstest]
372    fn test_no_spurious_reset_with_real_nanosecond_timestamps() {
373        let mut vwap = VolumeWeightedAveragePrice::new();
374
375        // 2024-01-15 10:00:00 UTC → 1_705_312_800_000_000_000 ns
376        // 2024-01-15 10:05:00 UTC → 1_705_313_100_000_000_000 ns
377        let ts1 = 1_705_312_800_000_000_000_f64;
378        let ts2 = 1_705_313_100_000_000_000_f64;
379
380        vwap.update_raw(100.0, 10.0, ts1);
381        assert_eq!(vwap.value, 100.0);
382
383        vwap.update_raw(200.0, 10.0, ts2);
384
385        // Before the fix this would reset to 200.0 instead of accumulating
386        assert!((vwap.value - 150.0).abs() < 1e-9);
387    }
388
389    #[rstest]
390    fn nan_price_propagates() {
391        let mut vwap = VolumeWeightedAveragePrice::new();
392        vwap.update_raw(f64::NAN, 1.0, 0.0);
393        assert!(vwap.value.is_nan());
394    }
395}
nautilus_indicators/average/vwap.rs

nautilus_indicators/average/
vwap.rs
