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.core.nautilus_pyo3.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 SECONDS_PER_DAY: f64 = 86_400.0;
86        let epoch_day = (timestamp / SECONDS_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::{average::vwap::VolumeWeightedAveragePrice, indicator::Indicator, stubs::*};
121
122    const SECONDS_PER_DAY: f64 = 86_400.0;
123    const DAY0: f64 = 10.0;
124    const DAY1: f64 = SECONDS_PER_DAY;
125
126    #[rstest]
127    fn test_vwap_initialized(indicator_vwap: VolumeWeightedAveragePrice) {
128        let display_st = format!("{indicator_vwap}");
129        assert_eq!(display_st, "VolumeWeightedAveragePrice");
130        assert!(!indicator_vwap.initialized());
131        assert!(!indicator_vwap.has_inputs());
132    }
133
134    #[rstest]
135    fn test_value_with_one_input(mut indicator_vwap: VolumeWeightedAveragePrice) {
136        indicator_vwap.update_raw(10.0, 10.0, DAY0);
137        assert_eq!(indicator_vwap.value, 10.0);
138    }
139
140    #[rstest]
141    fn test_value_with_three_inputs_on_the_same_day(
142        mut indicator_vwap: VolumeWeightedAveragePrice,
143    ) {
144        indicator_vwap.update_raw(10.0, 10.0, DAY0);
145        indicator_vwap.update_raw(20.0, 20.0, DAY0 + 1.0);
146        indicator_vwap.update_raw(30.0, 30.0, DAY0 + 2.0);
147        assert!((indicator_vwap.value - 23.333_333_333_333_332).abs() < 1e-12);
148    }
149
150    #[rstest]
151    fn test_value_with_three_inputs_on_different_days(
152        mut indicator_vwap: VolumeWeightedAveragePrice,
153    ) {
154        indicator_vwap.update_raw(10.0, 10.0, DAY0);
155        indicator_vwap.update_raw(20.0, 20.0, DAY1);
156        indicator_vwap.update_raw(30.0, 30.0, DAY0);
157        assert_eq!(indicator_vwap.value, 30.0);
158    }
159
160    #[rstest]
161    fn test_value_with_ten_inputs(mut indicator_vwap: VolumeWeightedAveragePrice) {
162        for i in 0..10 {
163            let price = 0.00010f64.mul_add(f64::from(i), 1.00000);
164            let volume = 1.0 + f64::from(i % 3);
165            indicator_vwap.update_raw(price, volume, DAY0);
166        }
167        indicator_vwap.update_raw(1.00000, 2.00000, DAY0);
168        assert!((indicator_vwap.value - 1.000_414_285_714_286).abs() < 1e-12);
169    }
170
171    #[rstest]
172    fn test_handle_bar(
173        mut indicator_vwap: VolumeWeightedAveragePrice,
174        bar_ethusdt_binance_minute_bid: Bar,
175    ) {
176        indicator_vwap.handle_bar(&bar_ethusdt_binance_minute_bid);
177        assert_eq!(indicator_vwap.value, 1522.333333333333);
178        assert!(indicator_vwap.initialized);
179    }
180
181    #[rstest]
182    fn test_reset(mut indicator_vwap: VolumeWeightedAveragePrice) {
183        indicator_vwap.update_raw(10.0, 10.0, DAY0);
184        indicator_vwap.reset();
185        assert_eq!(indicator_vwap.value, 0.0);
186        assert!(!indicator_vwap.has_inputs);
187        assert!(!indicator_vwap.initialized);
188    }
189
190    #[rstest]
191    fn test_reset_on_exact_day_boundary() {
192        let mut vwap = VolumeWeightedAveragePrice::new();
193
194        vwap.update_raw(100.0, 5.0, DAY0);
195        let old = vwap.value;
196
197        vwap.update_raw(200.0, 5.0, DAY1);
198        assert_eq!(vwap.value, 200.0);
199        assert_ne!(vwap.value, old);
200    }
201
202    #[rstest]
203    fn test_no_reset_within_same_day() {
204        let mut vwap = VolumeWeightedAveragePrice::new();
205        vwap.update_raw(100.0, 5.0, DAY0);
206
207        vwap.update_raw(200.0, 5.0, DAY0 + 1.0);
208        assert!(vwap.value > 100.0 && vwap.value < 200.0);
209    }
210
211    #[rstest]
212    fn test_zero_volume_does_not_change_value() {
213        let mut vwap = VolumeWeightedAveragePrice::new();
214        vwap.update_raw(100.0, 10.0, DAY0);
215        let before = vwap.value;
216
217        vwap.update_raw(9999.0, 0.0, DAY0);
218        assert_eq!(vwap.value, before);
219    }
220
221    #[rstest]
222    fn test_epoch_day_floor_rounding() {
223        let mut vwap = VolumeWeightedAveragePrice::new();
224
225        vwap.update_raw(50.0, 5.0, DAY1 - 0.000_001);
226        let before = vwap.value;
227
228        vwap.update_raw(150.0, 5.0, DAY1);
229        assert_eq!(vwap.value, 150.0);
230        assert_ne!(vwap.value, before);
231    }
232
233    #[rstest]
234    fn test_reset_when_timestamp_goes_backwards() {
235        let mut vwap = VolumeWeightedAveragePrice::new();
236        vwap.update_raw(10.0, 10.0, DAY0);
237        vwap.update_raw(20.0, 10.0, DAY1);
238        vwap.update_raw(30.0, 10.0, DAY0);
239        assert_eq!(vwap.value, 30.0);
240    }
241
242    #[rstest]
243    #[case(10.0, 11.0)]
244    #[case(43_200.123, 86_399.999)]
245    fn test_no_reset_for_same_epoch_day(#[case] t1: f64, #[case] t2: f64) {
246        let mut vwap = VolumeWeightedAveragePrice::new();
247
248        vwap.update_raw(100.0, 10.0, t1);
249        let before = vwap.value;
250
251        vwap.update_raw(200.0, 10.0, t2);
252
253        assert!(vwap.value > before && vwap.value < 200.0);
254    }
255
256    #[rstest]
257    #[case(86_399.999, 86_400.0)]
258    #[case(86_400.0, 172_800.0)]
259    fn test_reset_when_epoch_day_changes(#[case] t1: f64, #[case] t2: f64) {
260        let mut vwap = VolumeWeightedAveragePrice::new();
261
262        vwap.update_raw(100.0, 10.0, t1);
263
264        vwap.update_raw(200.0, 10.0, t2);
265
266        assert_eq!(vwap.value, 200.0);
267    }
268
269    #[rstest]
270    fn test_first_input_zero_volume_does_not_divide_by_zero() {
271        let mut vwap = VolumeWeightedAveragePrice::new();
272
273        vwap.update_raw(100.0, 0.0, DAY0);
274        assert_eq!(vwap.value, 100.0);
275        assert!(vwap.initialized());
276
277        vwap.update_raw(200.0, 10.0, DAY0 + 1.0);
278        assert_eq!(vwap.value, 200.0);
279    }
280
281    #[rstest]
282    fn test_zero_volume_day_rollover_resets_and_seeds() {
283        let mut vwap = VolumeWeightedAveragePrice::new();
284        vwap.update_raw(100.0, 10.0, DAY0);
285
286        vwap.update_raw(9999.0, 0.0, DAY1);
287        assert_eq!(vwap.value, 9999.0);
288    }
289
290    #[rstest]
291    fn test_handle_bar_matches_update_raw(
292        mut indicator_vwap: VolumeWeightedAveragePrice,
293        bar_ethusdt_binance_minute_bid: Bar,
294    ) {
295        indicator_vwap.handle_bar(&bar_ethusdt_binance_minute_bid);
296
297        let tp = (bar_ethusdt_binance_minute_bid.close.as_f64()
298            + bar_ethusdt_binance_minute_bid.high.as_f64()
299            + bar_ethusdt_binance_minute_bid.low.as_f64())
300            / 3.0;
301
302        let mut vwap_raw = VolumeWeightedAveragePrice::new();
303        vwap_raw.update_raw(
304            tp,
305            (&bar_ethusdt_binance_minute_bid.volume).into(),
306            bar_ethusdt_binance_minute_bid.ts_init.as_f64(),
307        );
308
309        assert!((indicator_vwap.value - vwap_raw.value).abs() < 1e-12);
310    }
311
312    #[rstest]
313    #[case(1.0e-9, 1.0e-9)]
314    #[case(1.0e9, 1.0e6)]
315    #[case(42.4242, std::f64::consts::PI)]
316    fn test_extreme_prices_and_volumes_do_not_overflow(#[case] price: f64, #[case] volume: f64) {
317        let mut vwap = VolumeWeightedAveragePrice::new();
318        vwap.update_raw(price, volume, DAY0);
319        assert_eq!(vwap.value, price);
320    }
321
322    #[rstest]
323    fn negative_timestamp() {
324        let mut vwap = VolumeWeightedAveragePrice::new();
325        vwap.update_raw(42.0, 1.0, -1.0);
326        assert_eq!(vwap.value, 42.0);
327        vwap.update_raw(43.0, 1.0, -1.0);
328        assert!(vwap.value > 42.0 && vwap.value < 43.0);
329    }
330
331    #[rstest]
332    fn huge_future_timestamp_saturates() {
333        let ts = 1.0e20;
334        let mut vwap = VolumeWeightedAveragePrice::new();
335        vwap.update_raw(1.0, 1.0, ts);
336        vwap.update_raw(2.0, 1.0, ts + 1.0);
337        assert!(vwap.value > 1.0 && vwap.value < 2.0);
338    }
339
340    #[rstest]
341    fn negative_volume_changes_sign() {
342        let mut vwap = VolumeWeightedAveragePrice::new();
343        vwap.update_raw(100.0, 10.0, 0.0);
344        vwap.update_raw(200.0, -10.0, 0.0);
345        assert_eq!(vwap.volume_total, 0.0);
346    }
347
348    #[rstest]
349    fn nan_volume_propagates() {
350        let mut vwap = VolumeWeightedAveragePrice::new();
351        vwap.update_raw(100.0, 1.0, 0.0);
352        vwap.update_raw(200.0, f64::NAN, 0.0);
353        assert!(vwap.value.is_nan());
354    }
355
356    #[rstest]
357    fn zero_and_negative_price() {
358        let mut vwap = VolumeWeightedAveragePrice::new();
359        vwap.update_raw(0.0, 5.0, 0.0);
360        assert_eq!(vwap.value, 0.0);
361        vwap.update_raw(-10.0, 5.0, 0.0);
362        assert!(vwap.value < 0.0);
363    }
364
365    #[rstest]
366    fn nan_price_propagates() {
367        let mut vwap = VolumeWeightedAveragePrice::new();
368        vwap.update_raw(f64::NAN, 1.0, 0.0);
369        assert!(vwap.value.is_nan());
370    }
371}
nautilus_indicators/average/vwap.rs

nautilus_indicators/average/
vwap.rs
