KMPCharts/docs/PERFORMANCE.md

Performance — chart-realtime

Measured numbers for 0.5.0-SNAPSHOT on iosSimulatorArm64 and Android. Benchmark module (vs Vico / KoalaPlot / MPAndroidChart) lands in 1.0.0.

Test surface

• 207 tests on iosSimulatorArm64Test, all green
• ABI baseline locked via Binary Compatibility Validator
  • chart-realtime.api: 428 LOC
  • chart-realtime.klib.api: 501 LOC

LoD algorithm performance

Measured on iosSimulatorArm64 (Apple Silicon iOS simulator). Input: 100_000 samples, output: 512 points. Median of 5 runs.

Algorithm	Time	vs pure LTTB
LttbLodStrategy (pure LTTB)	5071 µs	1.00×
MinMaxLodStrategy	2400 µs (approx)	2.1×
MinMaxLttbLodStrategy	2814 µs	1.80×

Paper claim (arXiv 2305.00332) is 10× under Rust + SIMD. Gap to reference attributed to Kotlin/Native scalar code generation (no SIMD primitives exposed to Kotlin; LLVM autovectorization less aggressive than Rust's). Algorithm-level win matches paper; implementation-level gap stays open.

Visual fidelity (MinMaxLTTB vs MinMax baseline)

Input: 100_000 samples of sin(t / 100) + noise(0.1), output: 512 points.

Min/max envelope drift: < 5% of pure-MinMax range. Single tall spike preserved across all three strategies (preselection step guarantees boundary preservation).

Buffer / snapshot performance

TieredBuffer.snapshotWindow (T1, v0.5.0) uses bisect instead of linear scan.

Operation	Tier0 (5min @ 200Hz)	Tier1 (10min @ 10Hz)	Tier2 (45min @ 1Hz)
snapshot() full	60_000 copies	24_000 copies	10_800 copies
snapshotWindow(10s) linear	60_000 scans, 2_000 writes	24_000 scans, 100 writes	10_800 scans, 10 writes
snapshotWindow(10s) bisect (T1)	2_000 writes	100 writes	10 writes

30× fewer per-frame copies for the common case (10s window inside a 5min Tier0 ring).

CircularBuffer.bisectStart is O(log n), zero-alloc, overflow-safe midpoint (ushr 1).

Render hot path — allocation budget

Steady state, 4 signals, 200Hz push, 30fps render. Per-frame allocations:

Site	Pre-v0.4.0	Post-v0.4.0	Post-v0.5.0
Pair<Float,Float> from resolveYRange	1	1	0 (FloatArray out-param)
Map.entries iterator	3	3	0 (cached signalsArray)
Map.Entry boxing	12	12	0
Stroke(width) per signal	4	4	0 (cached in LineSignalRenderer)
TextStyle per tick	~12	~12	0 (cached, 16-entry cap)
TextLayoutResult per tick	~12	~12	depends on TextMeasurer LRU
buffer.snapshot Long+Float arrays	4×2 (8)	4×1 (4)	4×1 (4)¹

¹ buffer.snapshot writes into pre-allocated SignalEntry.scratchTs / scratchV (T11). No allocation; only the per-signal scratch (sized at addSignal time) is touched.

Total per-frame steady-state alloc: < 1 KB / s (driven by Compose-internal drawText / TextMeasurer machinery; everything inside chart-realtime is 0).

Memory budget

Per signal, full 1h capacity:

TIER0_CAPACITY  = 5min × 200Hz × 1 sample      = 60_000 records
TIER1_CAPACITY  = 10min × 10Hz × 4 M4 records  = 24_000 records
TIER2_CAPACITY  = 45min × 1Hz  × 4 M4 records  = 10_800 records
TOTAL_CAPACITY  = 94_800 records per signal

Per record: 8 bytes (Long ts) + 4 bytes (Float value) = 12 bytes.

Buffer memory:  94_800 × 12 B = 1_137_600 B ≈ 1.11 MB
Scratch memory: 94_800 × 12 B ≈ 1.11 MB (per-signal pre-allocated)
LoD scratch:    ~2048 pixels × strategies (shared) ≈ 64 KB (one-shot)

≈ 2.22 MB per signal at full 1h capacity

10 signals × 1h: ~22 MB. Plain Compose+Kotlin overhead aside.

Compose stability report

All public types verified stable class by the Compose compiler (T6):

Class	Verdict
RealtimeChartState	stable (@Stable)
ChartConfig, DataConfig, AxisConfig, RenderConfig	stable (@Immutable)
SignalConfig, ChartTheme	stable (@Immutable)
T0, T0.FirstSample, T0.Fixed	stable (@Immutable sealed)
YRange, YRange.Auto, YRange.Fixed	stable (@Immutable sealed)
FrameRate, FrameRate.Display, FrameRate.Fixed	stable (@Immutable sealed)
LodMode, AxisLabelMode	stable (enum, Compose-inferred)
SignalRenderer (interface)	stable (@Stable)
LineSignalRenderer (object)	stable (singleton)
AxisFormatter (interface + 4 impls)	stable (@Immutable)
ChartInteractionState	stable (@Stable)
ViewportMode, CrosshairState, InteractionConfig	stable (@Immutable)

Recomposition driven by dataVersion: mutableLongStateOf only. Idle = 0 recompositions verified by snapshot lambda equality check.

Threading

• Producer (any thread) — push(name, ts, value) routes through Snapshot.withMutableSnapshot with SnapshotApplyConflictException retry helper. Tested under 100 interleaved push+clear cycles
• Renderer (UI thread) — reads state.signalsArray + per-signal entry.scratch*. Visibility via @Volatile on _signals / resolvedT0Ms / SignalEntry.lastPushedTs
• Pointer-input lambdas read from LongArray cache slots populated inside the draw lambda. 1-frame stale tolerance is acceptable for gesture handling

What is not measured yet

The following land in 1.0.0 with a dedicated benchmark module:

• Sustained frame time @ 200Hz × N signals on real hardware (Pixel 6, iPhone 13)
• Battery impact over 1h sessions
• Comparison vs Vico / KoalaPlot / MPAndroidChart (push throughput, frame time, memory steady-state)
• Android macrobench (Jetpack Macrobenchmark) for cold/warm startup + render frame-time distribution
• iOS Instruments allocation tracker capture

If the library loses any specific comparison, the result is documented honestly. The bet is: chart-realtime wins on sustained high-frequency streaming; loses on static dataset rendering convenience (Vico has more polish there).