Download the PHP package opencck/amphp-kalman without Composer

opencck/amphp-kalman

Русская версия: README.ru.md.

High-performance n-dimensional discrete Kalman filter for PHP 8.2+, with a catalogue of market-data models and an asynchronous streaming layer on AMPHP v3 / Revolt.

• Numerically stable forms — sequential scalar correction (default), Joseph, UD (Bierman–Thornton), square-root (Potter + Householder); no matrix inversion anywhere in production code; exact symmetry by construction.
• Time from the data — dt is derived from exchange timestamps, F(dt) and Q(dt) come from exact continuous-time discretisation (closed forms or Van Loan).
• Diagnostics built in — χ² / σ / Huber gating, NIS/NEES consistency, innovation whiteness, observability, model-break detection.
• Everything around the step is async — WebSocket ingest with back-pressure, reorder buffer, single-owner filter session, bar clock, snapshots to WebSocket/HTTP/files/Redis, worker processes, parallel calibration, file-based backtests.
• Pure, offloadable kernels — FilterBatch::run, InnovationLikelihood, RTS smoothing, EM steps and more are public static, deterministic, and take only serialisable arrays, so they run unchanged in a worker, behind a queue consumer or an HTTP compute service (@offloadable, ADR-005).
• Zero allocations in the hot loop, unrolled kernels for n = 2/4, optional OpenBLAS backend through FFI, stepRaw() object-free path in every filter.

Installation

Requirements: PHP ≥ 8.2 (8.4+ recommended), ext-json; ext-opcache with the JIT for production speed; optional ext-ffi + OpenBLAS for n > 32 (on Windows php tools/fetch-openblas.php downloads the DLL, then set KALMAN_BLAS_LIB); the amphp/* packages are pulled in by Composer. No compiled extension is needed.

Enable the JIT (2–4× on the filter step)

The filter core is written to be JIT-safe: PHP 8.2 and 8.3 miscompile two common floating-point statement shapes (both JIT modes), and the library avoids them and checks its own kernels at start-up (Diagnostics\JitSanity; see ADR-007). Raise the tracing JIT's budget for processes hosting many models or many code paths — when it is exhausted the rest of the code silently runs interpreted (3–8× slower, no warning):

On Windows, CLI processes started with the same binary and ini attach to one OPcache shared-memory segment — compiled scripts, JIT buffer and tracing-JIT state included. Traces specialised by one process make hot loops in another exit to the interpreter (we measured 3–8× on small kernels). Give each process family its own segment with opcache.cache_id; WorkerPools::likeParent() does this for worker pools and bench/run.php for every benchmark child.

Quick start

1. Local linear trend on one price stream

stepRaw(int $tsNs, array $values) does the same without creating objects; results are read back with lastInnovation($channel) and friends.

2. ETF basket: fair value of the fund and of every constituent

The state is [p₁, v₁, …, p_k, v_k, premium] (n = 2k + 1); prediction is sparse and O(k·n).

3. Pairs trading: time-varying hedge ratio

Every catalogue model is serialisable (toArray() / ModelRegistry), so the same filter can be rebuilt from a config array in another process: FilterFactory::fromConfig($modelConfig, $filterConfig, $snapshot).

More models: multi-venue fair value, time-varying beta, stochastic volatility (QML and UKF with leverage), order-book microprice, Nelson–Siegel yield curve, bid-ask bounce, log-price ETF basket (EKF), regime switching (IMM). See docs/models.

Streaming with AMPHP

The step itself is synchronous and atomic; asynchrony lives around it. Details, worker processes, parallel calibration and shutdown order: docs/async.md.

Runnable examples: examples/etf-live.php --mock, examples/calibrate-pair.php --synthetic, examples/backtest-trend.php --synthetic --em. The full index of every quantity the library can measure, with an example per row, is in по-русски).

Calibration, smoothing, backtests

ParallelCalibrator evaluates every simplex batch on an amphp/parallel worker pool; give it new MultiStartNelderMead(starts: 4) to run four simplexes in lockstep (16 candidate points per round — enough for 8 workers, and robust to local optima). ExpectationMaximization::fit() estimates full Q, R with RTS smoothing; App\Backtest\Engine replays a history file into a filter and reports NIS, rejection rate and smoothed trajectories.

Metrics, indicators and order-book measures

Filtering is only half the job: what gets filtered is usually an indicator, and an indicator computed from raw ticks is itself a noisy series. Domain\Metric supplies 32 measurements — technical indicators, order-book metrics, volatility estimators and microstructure measures — each as a streaming object that costs O(1) per observation and as a pure @deterministic @offloadable kernel that a worker process can run on a whole history.

That last call is the point of the layer. Fourteen of the fifty indicators in the reference catalogue this library was built against are finite differences of a noisy series, which is the worst possible estimator of a derivative. Filtered\Derivative replaces all of them with one constant-velocity filter that returns the rate and its standard error, so a trend can be tested for significance instead of eyeballed.

The full catalogue — every measurement with its symbol, category, offloadable kernels, an algotrading-oriented description and a runnable example — is in по-русски), generated from the code so it cannot drift. Where a metric departs from the reference formula it replaces, ROADMAP.md says exactly how and why: the reference RSI uses a 30-minute lag and a flat average instead of Wilder's smoothing, its MACD uses simple averages over 8 and 17 samples instead of EMAs of 12 and 26, its stochastic oscillator has no signal line, and its liquidity density reads the best bid out of an unsorted map.