v1.0.0 to v1.1.0

+ version: "1.1.0"

+ ## When NOT to Use

+

+ - **As a substitute for measurement.** This is a first-order sizing model for a *procurement* decision. It does not model queueing delay distributions, NUMA effects, cache behaviour, GC pauses or kernel bypass. Before committing to a design, replay real captures at target rate.

+ - **When per-symbol rates are wildly skewed and you need a tight answer.** The model multiplies one peak rate by the symbol count. Real message rates follow a heavy-tailed distribution — a handful of names dominate — so a uniform peak applied across a 3,000-symbol universe overestimates aggregate load, while a uniform *average* underestimates the hot symbols that actually break your feed handler. See Common Pitfalls.

+ - **For latency budgeting.** Capacity and latency are different questions; use `strategy-latency-budget-decomposition` and `tick-to-trade-latency-measurement`.

+

+ - Base knowledge of average and peak tick rates (messages per second) for the target asset class, measured over the **burst window you actually care about** (see `peak_rate_per_sec_from_burst`).

+ - Specifications of the hardware: NIC bandwidth, cores you can genuinely dedicate to feed processing, RAM, and measured messages/second/core for your parser.

+ - Knowledge of your feed's transport: whether messages are batched into packets, and whether you take one feed line or a redundant A/B pair.

+ ## Units

+

+ Mixed by design, matching how each domain is quoted commercially:

+ - **Network is decimal** — 1 Mbps = 10⁶ bits/sec, so a "10 GbE" NIC is `nic_bandwidth_mbps=10000`.

+ - **Memory is binary** — 1 GB = 1024 MB (GiB/MiB), matching how RAM is sold and reported.

+

+ 1. **Parameter Initialization**: Define `HardwareSpec` — NIC bandwidth, measured `cpu_msgs_per_sec_per_core`, RAM, and `available_cpu_cores`. Set `available_cpu_cores` to cores you can *dedicate*, not the machine's total; the OS and your strategy threads need their own.

+ 2. **Universe Definition**: Define `UniverseSpec`. Decide how you are charging wire overhead, and be consistent:

+ - *Unbatched:* fold payload + framing into `bytes_per_msg`, leave `msgs_per_packet=1`, `packet_overhead_bytes=0`.

+ - *Batched (correct for ITCH over MoldUDP64 and similar):* put only the payload in `bytes_per_msg`, set `packet_overhead_bytes=UDP_IPV4_ETHERNET_OVERHEAD_BYTES` (66) and `msgs_per_packet` to your observed batching factor.

+ 3. **Account for Feed Reality**: Set `redundant_feeds=2` if you consume both sides of an A/B multicast pair — it genuinely doubles the bill. Set `retransmission_overhead_fraction` for gap-fill traffic; OPRA's own guidance is +10%.

+ 4. **Choose a Margin Deliberately**: `safety_margin` defaults to `1.0` (no inflation) so the model reports exactly what you specified. Raise it to cover forecast uncertainty, but do not silently double-count against `max_network_utilization`, which already reserves headroom on the supply side.

+ 5. **Capacity Calculation**: `CapacityPlanner.evaluate(universe)` returns bandwidth, RAM, core count, each bottleneck flag, and the utilisation ceiling it applied.

+ 6. **Validation — read all the flags, not just `is_viable`**: If `single_symbol_exceeds_core` is set, the design is infeasible *at any core count* under symbol partitioning; adding hardware will not fix it, and you must either split that symbol's processing by message type or move to a faster parser. If only `network_bottleneck` is set, a bigger NIC or a filtered subscription may suffice.

+ - **Designing for Average Load**: Architecting for the *average* daily tick rate instead of the *peak* microburst. OPRA publishes its capacity projections in messages per 100ms and per 10ms intervals precisely because the 10ms window "reflects system utilization during bursts of traffic" — a one-second average can hide a burst an order of magnitude larger. Use `peak_rate_per_sec_from_burst(messages, window_ms)` to convert a burst observation into the rate to plan against.

+ - **Charging Per-Packet Framing to Every Message**: The 66 bytes of UDP/IPv4/Ethernet framing is paid **per packet**, not per message. MoldUDP64 batches many ITCH messages into a single datagram (max 1472 bytes), so billing every message for full framing can overstate required bandwidth several-fold and send you shopping for a link you do not need.

+ - **Forgetting the B Feed**: Redundant A/B multicast lines double bandwidth. OPRA states its projections are "for one stream only" and that subscribers taking both streams need double the bandwidth. A model that silently assumes one line under-provisions by 100%.

+ - **Assuming Cores Are Fungible**: A single symbol's stream cannot be split across cores when you partition by symbol. If the hottest symbol exceeds one core's throughput, a 64-core machine does not help — this is what `single_symbol_exceeds_core` catches, and a raw "required cores" figure hides it entirely.

+ - **Uniform Per-Symbol Rates**: Multiplying one peak rate by 3,000 symbols assumes every symbol is as hot as your benchmark. Message rates are heavy-tailed; model your universe in liquidity tiers and sum them rather than trusting a single uniform figure.

+ - Reproducible worked example, pinned by the test suite: a 5,000-symbol universe at 1,000 msgs/sec/symbol and 125 bytes/msg needs 5,000 Mbps — 5 Gbps — which a 1 Gbps link cannot carry (`network_bottleneck=True`, `is_viable=False`).

+ - Confirm the batching correction: the same 1M msgs/sec at 50-byte payloads costs 928 Mbps charged per message versus 426.4 Mbps when batched 20 messages per packet.

+ - Confirm a 20-core requirement is flagged on a 16-core `HardwareSpec` — earlier versions compared against a hard-coded 64.

+ - Run `python -m unittest discover -s skills/capacity-planning-for-symbol-universe-growth/scripts`.

+ - `tick-buffering-burst-handling`

+ - `load-testing-before-scaling-to-new-instrument-universe`