1use derive_more::Deref;
8use itertools::Itertools as _;
9use serde::{Deserialize, Deserializer, Serialize};
10use thiserror::Error;
11
12const FILL_TOLERANCE: f64 = 4.0 * f64::EPSILON;
19
20#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
23pub struct PriceLevel {
24 pub price: f64,
26 pub quantity: f64,
28}
29
30impl PriceLevel {
31 fn fillable(self) -> Result<Option<Self>, InvalidLevel> {
37 if !self.quantity.is_finite() || self.quantity < 0.0 {
38 return Err(InvalidLevel::Quantity(self.quantity));
39 }
40 if self.quantity == 0.0 {
41 return Ok(None);
42 }
43 if !self.price.is_finite() || self.price <= 0.0 {
44 return Err(InvalidLevel::Price(self.price));
45 }
46 Ok(Some(self))
47 }
48}
49
50#[derive(Clone, Copy, Debug, PartialEq, Error)]
52pub enum InvalidLevel {
53 #[error("price level quantity must be a non-negative finite number, got {0}")]
54 Quantity(f64),
55 #[error("price level price must be a positive finite number, got {0}")]
56 Price(f64),
57}
58
59#[derive(Clone, Debug, Default, Deref, PartialEq, Serialize)]
65#[serde(transparent)]
66#[deref(forward)]
67pub struct Levels(Vec<PriceLevel>);
68
69impl Levels {
70 pub fn new(levels: Vec<PriceLevel>) -> Result<Self, InvalidLevel> {
74 let mut levels: Vec<_> = levels
77 .into_iter()
78 .filter_map(|level| level.fillable().transpose())
79 .try_collect()?;
80 levels.shrink_to_fit();
81 Ok(Levels(levels))
82 }
83
84 pub fn fill(&self, amount_in: f64) -> Fill {
89 if amount_in.is_nan() || amount_in <= 0.0 {
93 return Fill { amount_out: 0.0, remaining_in: amount_in };
94 }
95
96 let mut consumed = 0.0;
100 let mut amount_out = 0.0;
101 for level in &self.0 {
102 let taken = (amount_in - consumed).min(level.quantity);
103 amount_out += taken * level.price;
104 consumed += taken;
105 if consumed >= amount_in {
106 break;
107 }
108 }
109
110 let remaining_in = amount_in - consumed;
111 let remaining_in = if remaining_in.is_finite() && remaining_in <= amount_in * FILL_TOLERANCE
115 {
116 0.0
117 } else {
118 remaining_in
119 };
120
121 Fill { amount_out, remaining_in }
122 }
123
124 pub fn invert(&self) -> Levels {
129 Levels(
130 self.0
131 .iter()
132 .filter_map(|level| {
133 PriceLevel { price: 1.0 / level.price, quantity: level.quantity * level.price }
134 .fillable()
135 .ok()
136 .flatten()
137 })
138 .collect(),
139 )
140 }
141
142 pub fn notional(&self) -> f64 {
144 self.totals().1
145 }
146
147 pub fn totals(&self) -> (f64, f64) {
149 self.0
150 .iter()
151 .fold((0.0, 0.0), |(quantity, notional), level| {
152 (quantity + level.quantity, notional + level.price * level.quantity)
153 })
154 }
155
156 pub fn average_price(&self, amount_in: f64) -> Option<f64> {
160 let fill = self.fill(amount_in);
161 let consumed = amount_in - fill.remaining_in;
162 (consumed > 0.0).then(|| fill.amount_out / consumed)
163 }
164}
165
166impl<'de> Deserialize<'de> for Levels {
167 fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
168 Levels::new(Vec::deserialize(deserializer)?).map_err(serde::de::Error::custom)
169 }
170}
171
172#[derive(Clone, Copy, Debug, PartialEq)]
174pub struct Fill {
175 pub amount_out: f64,
177 pub remaining_in: f64,
179}
180
181impl Fill {
182 pub fn is_complete(&self) -> bool {
183 self.remaining_in <= 0.0
184 }
185}
186
187#[cfg(test)]
188mod tests {
189 use rstest::rstest;
190
191 use super::*;
192
193 fn ladder() -> Levels {
194 Levels::new(vec![
195 PriceLevel { price: 3000.0, quantity: 1.0 },
196 PriceLevel { price: 2999.0, quantity: 2.0 },
197 ])
198 .unwrap()
199 }
200
201 #[test]
202 fn new_drops_zero_quantity_placeholders() {
203 let levels = Levels::new(vec![
204 PriceLevel { price: 0.0, quantity: 0.0 },
205 PriceLevel { price: 3000.0, quantity: 1.0 },
206 PriceLevel { price: -1.0, quantity: 0.0 },
207 ])
208 .unwrap();
209
210 assert_eq!(&*levels, &[PriceLevel { price: 3000.0, quantity: 1.0 }]);
211 }
212
213 #[test]
214 fn new_rejects_invalid_levels() {
215 assert_eq!(
216 Levels::new(vec![PriceLevel { price: 1.0, quantity: -1.0 }]),
217 Err(InvalidLevel::Quantity(-1.0))
218 );
219 assert!(matches!(
220 Levels::new(vec![PriceLevel { price: 1.0, quantity: f64::NAN }]),
221 Err(InvalidLevel::Quantity(_))
222 ));
223 assert_eq!(
224 Levels::new(vec![PriceLevel { price: 0.0, quantity: 1.0 }]),
225 Err(InvalidLevel::Price(0.0))
226 );
227 assert_eq!(
228 Levels::new(vec![PriceLevel { price: f64::INFINITY, quantity: 1.0 }]),
229 Err(InvalidLevel::Price(f64::INFINITY))
230 );
231 }
232
233 #[test]
234 fn deserialize_validates_and_serialize_is_transparent() {
235 let levels: Levels = serde_json::from_str(
236 r#"[{"price":3000.0,"quantity":1.0},{"price":1.0,"quantity":0.0}]"#,
237 )
238 .unwrap();
239 assert_eq!(levels.len(), 1);
240 assert_eq!(serde_json::to_string(&levels).unwrap(), r#"[{"price":3000.0,"quantity":1.0}]"#);
241
242 assert!(serde_json::from_str::<Levels>(r#"[{"price":0.0,"quantity":1.0}]"#).is_err());
243 }
244
245 #[test]
246 fn fill_walks_levels_in_order_and_reports_the_unfilled_rest() {
247 let ladder = ladder();
248
249 assert_eq!(ladder.fill(1.0), Fill { amount_out: 3000.0, remaining_in: 0.0 });
250 assert_eq!(ladder.fill(2.0), Fill { amount_out: 5999.0, remaining_in: 0.0 });
251 let partial = ladder.fill(5.0);
252 assert_eq!(partial, Fill { amount_out: 8998.0, remaining_in: 2.0 });
253 assert!(!partial.is_complete());
254 }
255
256 #[rstest]
257 #[case::nothing(0.0)]
258 #[case::less_than_nothing(-1.0)]
259 #[case::not_a_number(f64::NAN)]
260 fn fill_of_an_amount_that_is_not_positive_takes_nothing(#[case] amount_in: f64) {
261 let fill = ladder().fill(amount_in);
265
266 assert_eq!(fill.amount_out, 0.0);
267 assert!(
268 fill.remaining_in.to_bits() == amount_in.to_bits(),
269 "the amount comes back untouched"
270 );
271 }
272
273 #[test]
274 fn fill_of_an_infinite_amount_takes_the_whole_ladder() {
275 let fill = ladder().fill(f64::INFINITY);
278
279 assert_eq!(fill.amount_out, 8998.0);
280 assert_eq!(fill.remaining_in, f64::INFINITY);
281 assert!(!fill.is_complete());
282 }
283
284 #[test]
288 fn filling_the_whole_ladder_leaves_nothing() {
289 let quantities = [1.1, 2.2, 3.3, 4.4, 5.5, 6.6, 7.7, 8.8, 9.9, 48.508172];
290 let ladder = Levels::new(
291 quantities
292 .iter()
293 .map(|&quantity| PriceLevel { price: 2.0, quantity })
294 .collect(),
295 )
296 .unwrap();
297 let (depth, _) = ladder.totals();
298
299 let fill = ladder.fill(depth);
300
301 assert_eq!(fill.remaining_in, 0.0);
302 assert!(fill.is_complete());
303 }
304
305 #[test]
308 fn filling_past_the_ladder_still_reports_the_shortfall() {
309 let ladder = ladder();
310 let (depth, _) = ladder.totals();
311
312 let fill = ladder.fill(depth + 0.001);
313
314 assert!((fill.remaining_in - 0.001).abs() < 1e-12, "got {}", fill.remaining_in);
315 assert!(!fill.is_complete());
316 }
317
318 #[test]
319 fn invert_swaps_units_and_drops_overflowing_levels() {
320 let inverted = Levels::new(vec![
322 PriceLevel { price: 0.11, quantity: 3000.0 },
323 PriceLevel { price: 0.12, quantity: 3000.0 },
324 PriceLevel { price: 1e308, quantity: 1e308 },
325 ])
326 .unwrap()
327 .invert();
328
329 assert_eq!(inverted.len(), 2);
330 assert!((inverted[0].price - 9.090909090909092).abs() < 1e-9);
331 assert!((inverted[0].quantity - 330.0).abs() < 1e-9);
332 assert!((inverted[1].price - 8.333333333333334).abs() < 1e-9);
333 assert!((inverted[1].quantity - 360.0).abs() < 1e-9);
334 }
335
336 #[test]
337 fn notional_and_totals_sum_the_ladder() {
338 let ladder = ladder();
339
340 assert_eq!(ladder.notional(), 8998.0);
341 assert_eq!(ladder.totals(), (3.0, 8998.0));
342 }
343
344 #[test]
345 fn average_price_is_per_consumed_unit() {
346 let ladder = ladder();
347
348 assert_eq!(ladder.average_price(1.0), Some(3000.0));
349 assert_eq!(ladder.average_price(2.0), Some(2999.5));
350 assert_eq!(ladder.average_price(5.0), Some(8998.0 / 3.0));
352 assert_eq!(ladder.average_price(0.0), None);
353 assert_eq!(Levels::default().average_price(1.0), None);
354 }
355}