troy 0.1.3

Superfast primitives and data structures for high frequency trading
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

# Release Notes

This page is the source of truth for troy release notes. Each section below
maps to a tagged release on
[GitHub](https://github.com/quantmind/troy/releases). When a new tag is
pushed, the matching section is extracted by
`.github/workflows/release.yml` and published as the GitHub Release body.

Keep entries compact: grouped bullets under `Fixed`, `Added`, `Changed` and
`Removed`, one bullet per change, one or two lines each. Say what changed and
what a caller does about it. Reasoning belongs in the code, beside the thing it
explains.

## v0.1.3

Square roots, and a rounding strategy on the operations that round.

Added

- `Dec::sqrt`, `Dec::checked_sqrt` and `Dec::sqrt_approx`. `sqrt` rounds half
  away from zero at `Dec::SCALE` and is the one operation here that cannot
  overflow: the largest root the range holds is about `1.3e10`, so a negative
  value and NaN are its only failures, which is what `checked_sqrt` reports as
  `None`. `sqrt_approx` goes through `f64` for about three times the speed,
  accurate to the double's sixteen significant digits rather than to the last
  place; take it where a root feeds a comparison, not where two of them are
  tested equal.
- `RoundingStrategy`, taken by `Dec::round_dp_with` and
  `Dec::round_to_step_with`: `MidpointAwayFromZero`, `MidpointNearestEven`,
  `ToZero`, `AwayFromZero`, `ToNegativeInfinity` and `ToPositiveInfinity`. Pass
  one where the direction is the exchange's rather than yours: `ToZero` for a
  quantity filter, the infinity pair for a bid or ask pinned to a tick,
  `MidpointNearestEven` where many rounded values are summed. It derives
  `Default` as `MidpointAwayFromZero` and serialises under the `serde` feature,
  so a per-instrument policy stores and restores with the instrument.

Changed

- `round_dp` and `round_to_step` are unchanged, and are now defined as the
  `MidpointAwayFromZero` case of their `_with` counterparts. `floor`, `ceil`
  and `trunc` are the `dp` 0 cases of the three directed strategies, and say so
  in their docs.
- The `arithmetic` benchmark is now `dec` and carries the roots alongside the
  arithmetic, so `cargo bench --bench arithmetic` is `cargo bench --bench dec`.
  `make bench` is unchanged. `docs/bench-data.json` is re-measured, and the
  site's front page hands off to a `Dec` page for the per-operation numbers.
- The readme says who writes this crate: every line generated by an AI agent
  under the review of high frequency trading practitioners, and what a
  contribution has to clear before it lands.

## v0.1.2

Added

- The market types serialise under the `serde` feature: `PriceAmount`,
  `OrderBookSide`, `OrderBook`, `OrderBookTop` and `OrderBookDiff`. A book
  snapshot now round trips whole, where before only `Dec` did.
- `OrderBook::is_consistent` — every level valid, each side ordered the way its
  slot requires, no price held twice, and a spread above zero. A book built
  through `set` holds this by construction, so check it on one that arrived
  another way: deserialised from a snapshot, or assembled by hand.
- `Display` honours the format spec. A precision rounds to exactly that many
  places, halves away from zero, padded with zeros past `Dec::SCALE`; width,
  fill, alignment, `0` and `+` behave as they do on the built-in numeric types.
  Bare `{}` is unchanged, and still compiles to what it did before. The
  rounding runs on the digits rather than through a `Dec`, so a carry out of
  the range still renders: `format!("{:.0}", Dec::MAX)` is
  `170141183460469231732`, a number `Dec` cannot hold and `round_dp` answers
  with `Dec::NAN`.
- A benchmark and docs site at <https://troy.quantmind.com>, carrying the full
  benchmark set, the order book numbers, the digit and depth sweeps and the
  design docs. `make site` builds it, `make site-dev` serves it locally.

Removed

- `make bench-page`, which rendered a single page from the snapshot. `make
  site` builds the whole site instead.

## v0.1.1

Fixed

- Parser reported `Overflow` for text carrying more significant digits than a
  `u128` holds, even for values well inside the range: `1.0` written with 43
  decimal places, or a float printed as its exact expansion. Surplus digits now
  round the last one kept instead of failing the parse.

Added

- `OrderBook::imbalance` — `(bid - ask) / (bid + ask)` at the touch, in `[-1, 1]`.
- `OrderBook::range_imbalance(from, to)` — the same over a half open band of
  levels. An empty or inverted band reads `None`, not zero.
- `tests/fuzz.rs` — proptest properties over `Dec`; `make rs-fuzz` sweeps wider.
- `tests/fuzz_book.rs` — capped-book invariants at 10, 50, 100 and 200 levels.
- `benches/orderbook.rs` — book operations by depth; `make bench` runs it.

Changed

- `OrderBookSide` drops its running `total_amount`. `amount_mean` and
  `amount_std_dev` sum on demand, `trim` becomes a `truncate`, and a non-finite
  amount can no longer poison a side for good.

## v0.1.0

First release: `Dec`, a fixed-scale decimal backed by an `i128` with
`Dec::SCALE` decimal places, with parsing, formatting, arithmetic, rounding,
and optional `serde` and `rust_decimal` support.

Arithmetic is exact over a symmetric finite range of roughly +/-1.7e20.
Anything leaving it becomes `Dec::NAN`, which propagates through every later
operation so the fault reaches the boundary where `Dec::is_finite` is checked,
rather than being clamped to a plausible number or raised as a panic on a hot
path. The ordering stays total, so `Dec` remains usable as a map key and in a
sorted book. See the `design` module for the reasoning.