What it does for you
Before a model interprets noisy telemetry or scientific data, something has to measure it reliably. signal-kernels is a header-only C++23 library of well-known, published measures: entropy, divergences, causal tests, change-point detection, forecasting and graph curvature. It depends only on the standard library, so you add a folder of headers and link one target.
- Header-onlyInclude the headers you need; the only dependency is the C++ standard library.
- Published methodsShannon and Renyi entropy, KL and Jensen-Shannon divergence, Granger, PELT, SARIMA, VAR, Forman and Ollivier-Ricci.
- Unit tested99 doctest cases with 245 assertions cover every header.
- One demo program
examples/demo_pipeline.cppcalls each module on fixed inputs.
Source: README.md at 386aeb9 (source at 386aeb9)
Watch
No concept film fits this tool closely yet. The walkthrough below covers it in text, with real commands and output.
Video walkthrough: coming with the next release.
How it works, one step at a time
Scroll, or use the step buttons. Each step shows one module on the inputs written in examples/demo_pipeline.cpp and the values it printed, built with MSVC from commit 386aeb9.
- 01
Entropy: how much surprise
A uniform distribution over 8 outcomes carries 3 bits under Shannon, Renyi of order 2 and min-entropy alike. The 256 byte values 0 to 255, each once, carry 8 bits. Permutation entropy of order 3 reads the ordering patterns in a short wiggly series: 1.842 bits.
Source: include/algorithms/entropy.hpp
- 02
Divergences: how far apart two distributions are
Compare a fair coin, p = (0.5, 0.5), with a biased one, q = (0.9, 0.1). KL divergence is 0.737 bits and is not symmetric; Jensen-Shannon is 0.147 bits and is. Shifting the samples 1, 2, 3, 4 up by one gives a Wasserstein distance of exactly 1. A variable's mutual information with itself equals its entropy: 1.585 bits for three equally likely values.
- 03
Granger: does x help predict y?
The demo builds 200 points where y at each step is 0.8 times x one step earlier plus a little noise. The Granger test asks whether past x improves the prediction of y beyond y's own past. It does, overwhelmingly, and picks a lag of 1, which is how y was built.
Source: include/algorithms/causal.hpp
- 04
PELT: where the series changes
A step series sits at 0 for 25 points and at 10 for the next 25. PELT, with an L2 cost and a BIC penalty, finds exactly one change point, at index 25.
- 05
Forecasting: SARIMA and VAR
An AR(1) model is fitted to a 200-point series and forecasts five steps, which settle toward 0.066. A VAR(1) is fitted to two series together and forecasts three steps for both, a 3 by 2 result.
Source: include/algorithms/forecast.hpp
- 06
Graph curvature
On the path graph 0, 1, 2, the edge from 0 to 1 has Forman-Ricci curvature -1 and Ollivier-Ricci curvature 0.5 at a laziness of 0.5. The shortest path from 0 to 2 is 2.
Source: include/algorithms/curvature.hpp
Walkthrough
Install it, run it once, then use the main feature. Each command below is real, and so is its output.
Get it and build
Clone and build with CMake and MSVC; the bundled CMake file targets Windows x64.
$ git clone https://github.com/HarperZ9/signal-kernels && cd signal-kernels $ cmake -S . -B build -DSIGNAL_KERNELS_BUILD_TESTS=ON $ cmake --build build --config DebugRun the tests
The test binary covers every header.
$ ctest --test-dir build -C Debug --output-on-failureEntropy
The demo program
examples/demo_pipeline.cpp, built in Release, printed these entropy values.shannon(uniform-8) = 3.000000 bits renyi(uniform-8, a=2) = 3.000000 bits min_entropy(uniform-8) = 3.000000 bits shannon_from_bytes(0..255) = 8.000000 bits permutation_entropy(o=3) = 1.842371 bitsChange points
On a step series, PELT finds one change point at index 25.
input: step = 25 x 0.0, then 25 x 10.0 pelt(L2) detected 1 change point(s): index=25 segment_cost=0.000000
Values above came from examples/demo_pipeline.cpp built with MSVC 19.50 in Release from commit 386aeb9. The test binary reported 99 cases and 245 assertions passing.
What it does not do
- The bundled CMakeLists.txt targets Windows x64 with MSVC and stops on other platforms. The headers are standard C++ and can be used elsewhere with your own build.
- These are published methods. The library offers no new statistics and makes no claim beyond each method's assumptions.
- A Granger result says past x helps predict y. It does not show that x causes y.
- The package is intended for defensive and research analytics.
Source: README.md at 386aeb9, "Platform" and "Overview"; PUBLIC-DISCLAIMER.md
Check what stuck
Answer each one in your head before you open it.
Why are Shannon, Renyi and min-entropy all 3 bits for a uniform 8-outcome distribution?
On a uniform distribution every entropy of this family takes the same value, log2 of 8.
The demo's y is built from x one step earlier. What lag does the Granger test choose?
1.
Where does PELT put the change in a series of 25 zeros then 25 tens?
At index 25.