What this is
Reamer Research is a deterministic backtesting engine for Python and C++,
with a visual trade diagnostics tool and live trading through its relay.
pip install python/*.whl and import reamer_research, or
#include <reamer_research.hpp>. A whole backtest is then a strategy
function and one backtest() call, and open_viewer=True opens the visual
trade diagnostics tool on the run.
It is a library you call, not a program you run: there is no
reamer-research binary in this kit. Underneath the Python package and the
C++ header is a stable C ABI and a shared library. From any other
language, you write a program that builds a strategy vtable, hands the
engine your bars and config, and calls reamer_run_backtest(); the live
relay is in the same interface.
reamer_run_backtest() takes per-ticker execution config
(per-instrument commission, slippage and spread in one run), mandatory
instrument names (so results carry your own symbols rather than a
positional placeholder), and exogenous data sidecars (any non-OHLCV
series, resolved point-in-time and delivered to on_bar). Read the results
with reamer_get_summary() — 31 metrics including Sharpe and Sortino at the annualisation you choose, Calmar,
drawdown and holding-time statistics — or dump the whole run with
reamer_write_result_json().
Determinism is the property to check first. A run with a fixed rng_seed
is byte-identical across repeats, including the stochastic slippage and
spread path. Run any backtest twice and compare. Determinism holds in
timing as well as output: on a 64-core EPYC 9575F the native engine ran
2000 independent backtests with per-run throughput CV 0.66% (1.05× min→max
spread) on release 4.6.0 — the single-threaded engine has no scheduler in
its path to introduce run-to-run drift. See the replication of the
whitepaper.
Scope. Mid-frequency strategies on bars of any type (time, tick, volume,
dollar, imbalance or your own custom rule), intraday to multi-day. Focusing
on bars keeps the engine small, fast and byte-identical; order-book (L2/L3)
and options work belong to specialist tools. Equity input should already be
split- and dividend-adjusted, as Alpaca's bars arrive. EXECUTION_SPEC.md states the boundaries
precisely.
Backtests run over historical bars, and live trading runs on your own feed and broker.
Your loop takes each closed bar from the broker or vendor you choose and
calls your strategy. reamer_relay_* (rr.Relay
in Python, rr::Relay in C++) sends the orders it returns over a Unix socket
to a receiver you run, which places them with your broker and sends the fills
back. Live trading with Reamer Research has the steps, the receiver's wire format, and a working paper
receiver and live loop in the kit's python/live/ and cpp/live/.
New in 4.11.3
Evaluation Mode explains itself. The library and ABI 8 are unchanged in
shape; only messages, the sample bars and status changed.
| Change | What it means |
|---|---|
| Limit messages | A run past a limit says which limit it hit and that a Reamer Research licence removes every limit, with https://reamerlabs.com/pricing. The relay's refusal says Evaluation Mode covers backtests. |
EvaluationLimit |
Python raises rr.EvaluationLimit and C++ throws rr::EvaluationLimit with that message alone. Both derive from ReamerError and rr::Error, and code_name is still LICENSE_MISSING, so existing handlers keep working. |
reamer-license status |
Without a Research seat it states that backtests run in Evaluation Mode, with the limits and how to activate. |
| Sample bars | python/sample_data/AAPL.csv is 100 synthetic hourly bars over three weeks, inside Evaluation Mode, so rr.backtest(on_bar, 'AAPL.csv') runs before activation. |
In 4.11.2
The ABI and the library are unchanged from 4.11.1; this release is about the examples.
| Change | What it means |
|---|---|
| Every example runs | Each Python example and template runs as python3 examples/<name>.py from python/, and single-ticker ones run in Evaluation Mode. Release CI runs every one from the packaged kit. |
| C++ examples | cpp/examples/ builds and runs on the sample bars, in all three strategy forms (a lambda, a function, an object with on_bar), with new data_csv.cpp and data_bin.cpp. |
| Live in the kit | python/live/ has the relay receiver and paper broker, and cpp/live/live_paper.cpp runs the same paper trade from C++. |
In 4.11.1
ABI 8 only adds: code built against 4.5.0 or later runs as it is.
| Change | What it means |
|---|---|
| Relay actions | Relay.send() sends modify_order, modify_position, close_all and cancel_all, as a backtest applies them. Before, the relay refused them. |
| Relay order IDs | Python Relay.send() returns the IDs the relay took; before, they drifted after a cancel. C++ Relay::send() returns them too. |
| Relay positions | take_profit and stop_loss report the position's live exits. |
Live trading with Reamer Research covers going live, with a working receiver and paper broker.
In 4.11.0
ABI 7 is unchanged: code built against 4.5.0 or later runs as it is.
| Change | What it means |
|---|---|
| Evaluation Mode | Without an active licence, a backtest runs one ticker over at most 30 days of bar time or 50,000 bars, whichever comes first. Past a limit the run fails with REAMER_RESEARCH_ERROR_LICENSE_MISSING naming the limit. Monte Carlo and the visual trade diagnostics tool work within it; the relay needs a licence. Activating removes every limit. |
python/sample_data/SAMPLE_5min.csv |
Synthetic five-minute bars that fit inside Evaluation Mode, for a first run before activation. |
LICENSE.txt 1.6 |
Section 2B grants Evaluation Mode use without a key. |
In 4.10.0
ABI 7 is unchanged: code built against 4.5.0 or later runs as it is.
| Change | What it means |
|---|---|
python/, cpp/ |
The wrappers' directories, formerly reference-python/ and reference-cpp/. pip install ./python replaces pip install ./reference-python; the wheel, include/reamer_research.hpp and the package API are unchanged. |
| Supported wrappers | The Python package and the C++ wrapper are now part of the licensed product, supported like the library (LICENSE.txt version 1.5, Section 4). |
In 4.9.0
| Addition | What it does |
|---|---|
python/reamer_research-*.whl |
The Python package, with the library and the visual trade diagnostics tool inside it. pip install it, or pip install ./python, and rr.backtest(on_bar, "AAPL.csv") runs from any directory. CSV, pandas, numpy and .bin input; per-ticker costs, exogenous sidecars, Relay. See the Python package page. |
include/reamer_research.hpp |
The C++ wrapper, one header: rr::backtest(on_bar, "AAPL.csv") with a lambda or an object strategy, CSV and .bin loading, fluent orders, Relay. Found by find_package(ReamerResearch) and pkg-config through lib/cmake/ and lib/pkgconfig/. See the C++ wrapper page. |
viewer/reamer-viewer.html |
The visual trade diagnostics tool. open_viewer=True (Python) or .open_viewer = true (C++) opens a run in it as soon as it finishes. |
The Python and C++ quickstarts are python/examples/quickstart.py
and cpp/examples/quickstart.cpp: an ATR band reversion with a
bracket on every entry, in about a dozen lines each.
In 4.5.0 — ABI 7
ABI 7 breaks ABI 6: on_bar and the strategy vtable change. Rebuild
against the shipped header. CHANGELOG.md lists every change.
| Addition | What it does |
|---|---|
on_bar position_states, open_orders |
Full position state per ticker (ReamerPositionState) and every resting order (ReamerOpenOrder), sorted by order_id. |
on_bar out_actions |
MODIFY_ORDER, MODIFY_POSITION, CLOSE_ALL, CANCEL_ALL (ReamerOrderAction). EXECUTION_SPEC.md §6b has the timing. |
on_progress vtable slot |
Progress calls between bars. Return nonzero to stop the run with REAMER_RESEARCH_ERROR_CANCELLED (11). |
reamer_relay_* |
Sends ReamerOrderRequests, brackets included, to your own receiver or a running Reamer Server, and reads fills back as ReamerPositionState. REAMER_RESEARCH_ERROR_RELAY (12). Linux and macOS. |
In 4.4.0 — ABI 6
ABI 6 breaks ABI 5. Rebuild against the shipped header. CHANGELOG.md
lists every removal and rename.
| Addition | What it does |
|---|---|
reamer_run_backtest_files() |
Runs over memory-mapped .bin files, one per ticker, with an inclusive start_ts/end_ts range. Datasets larger than RAM run. |
reamer_write_bin() |
Writes validated, sorted bars to a .bin file. Needs no license. |
bin/reamer-csv-build |
Converts an OHLCV CSV into a .bin file and prints a parse report. Needs no license. |
reamer_run_monte_carlo() |
Resamples a run's per-trade returns. Reports final-equity, loss, ruin and max-drawdown percentiles. Seeded and reproducible. |
reamer_get_summary(handle, periods_per_year, out) |
Sets the Sharpe and Sortino annualisation. <= 0 infers it. |
Result JSON equity_curve, equity_curve_ts |
Realised equity after each closed trade, with timestamps. |
REAMER_RESEARCH_ERROR_BAR_FILE (10) |
A .bin file is missing, unreadable, truncated or unsorted. |
What ships
| Path | What it is |
|---|---|
include/reamer_research_abi.h |
The entire integration contract. Every struct, vtable, and entry point, with lifetime rules stated inline. Read this first. |
include/reamer_research.hpp |
The C++ wrapper over that contract, one header. See cpp/README.md. |
lib/libreamer_research.so |
The engine you link against (.dylib on macOS). |
lib/cmake/ReamerResearch/, lib/pkgconfig/ |
find_package(ReamerResearch) and pkg-config reamer-research files for the library and the C++ header. |
python/reamer_research-*.whl |
The Python package, library and visual trade diagnostics tool included. pip install it. See python/README.md. |
bin/reamer-license |
Activates this machine's license (activate / status / deactivate). |
bin/release-sign |
Verifies the detached Ed25519 signature over this archive's .sha256. See DEPLOYMENT.md Step 1. |
bin/reamer-exo-build |
Converts a two-column CSV into the .exo.bin sidecar reamer_run_backtest() reads. Offline converter — needs no license. See EXOGENOUS_FORMAT.md. |
bin/reamer-csv-build |
Converts an OHLCV CSV into the .bin bar file reamer_run_backtest_files() memory-maps. Offline converter — needs no license. See "Your own data" below. |
bin/research-bench |
Runs the pure-ABI backtest throughput benchmark on your own hardware after activation, reproducing BENCHMARK.md's bars/sec figure. See "Measuring on your own hardware" there. |
cpp/ |
The C++ wrapper (supported, in source) and five runnable examples, quickstart.cpp first. |
python/ |
The Python package (supported, in source: pip install ./python installs it), strategy templates, Alpaca and Databento bar fetchers, and runnable examples, examples/quickstart.py first. |
viewer/reamer-viewer.html |
A visual trade diagnostics tool: one HTML file you open in a browser. Add a run's result JSON, its bar files and, optionally, its console log, and it charts each closed trade on its bars beside the indicator values and other output your strategy printed. Nothing is uploaded. See viewer/README.md. |
python/sample_data/ |
Synthetic bars inside Evaluation Mode: AAPL.csv (100 hourly bars) and SAMPLE_5min.csv (1,638 five-minute bars), so the quickstart runs without you sourcing data first. |
VENDOR_QUESTIONNAIRE_PACK.md |
The standing answer to an infra/risk/procurement team's security questionnaire, support model, vulnerability disclosure policy, data-handling statement, and business-continuity/escrow note — hand it to your own security review. Published as the vendor questionnaire pack. |
SECURITY_HARDENING.md |
The internal adversarial security pass already performed against the ABI/IPC and license boundaries: the defect classes found and closed, and the sanitizer + regression-test verification each fix carries. |
LICENSE.txt |
The licence terms governing this kit. bin/reamer-license activate reads this file from the kit root and will not activate until you accept it, so do not move bin/ out of the extracted tree. |
SHA256SUMS |
Manifest covering every file above, for post-extraction verification. |
sbom.cdx.json, THIRD_PARTY_NOTICES |
CycloneDX SBOM and license text for every third-party component in the shipped library. |
Every binary answers --version, so you can confirm which build you have:
./bin/reamer-license --version # reamer-license 4.11.3
./bin/release-sign --version # release-sign 4.11.3
./bin/reamer-exo-build --version # reamer-exo-build 4.11.3
./bin/reamer-csv-build --version # reamer-csv-build 4.11.3
Docs: EXECUTION_SPEC.md (authoritative on fills, slippage, spread,
commission, margin, and roll), RESULT_JSON_SCHEMA.md (field-by-field
schema for the result document, including how returns[] is defined — read
it before recomputing any risk metric yourself), EXOGENOUS_FORMAT.md
(attaching non-OHLCV data to a run), DEPLOYMENT.md (quickstart and licensing),
LICENSING.md (seat policy, activation failure modes),
SUPPORTED_PLATFORMS.md (OS, arch, and glibc floor), BENCHMARK.md
(relative cost of each integration path), MONITORING.md (running backtests
unattended: what the library logs, what to alert on, what to send to
support), RESEARCH_TO_SERVER.md (for
firms that also run Reamer Server), and
VENDOR_QUESTIONNAIRE_PACK.md/SECURITY_HARDENING.md (procurement and
the security-hardening record).
Where to start
See a number in about a minute —
bin/research-bench. The cheapest thing to try, and the one to do first. It is a prebuilt binary: no compiler, no toolchain, no environment setup. Activate a key (next section), then, from this directory:bin/reamer-license activate <license-key> # once per machine bin/research-bench # a real number on your hardwareIt prints a bars/sec throughput and latency table for this box, directly comparable to
BENCHMARK.md. That is the whole ask to get a first result — everything below is there when you want to go deeper. See "Measuring on your own hardware" inBENCHMARK.mdfor how to read the shape.DEPLOYMENT.md, Step 1. Verify the download, then read Step 2 about licensing — see the next section first, because you need a key.include/reamer_research_abi.h. Twenty minutes here answers most integration questions. It is the contract, and it is written to be read.Run something. The fastest path to a backtest result, from this directory. In Python:
pip install python/reamer_research-*.whl python3 python/examples/quickstart.pyOr in C++:
c++ -std=c++20 -O2 cpp/examples/quickstart.cpp -Iinclude \ -Llib -lreamer_research -Wl,-rpath,"$PWD/lib" -o quickstart ./quickstart python/sample_data/SAMPLE_5min.csvEach runs an ATR band reversion over the sample data, prints the summary and opens the run in the visual trade diagnostics tool. Both require an activated license. Run either twice — the output is byte-identical.
EXECUTION_SPEC.md. Before you size a position against any backtest result, read §1 (bid/ask and the slippage model), §2 (fill prices), and §10 (margin). Slippage is not floored at zero — negative slippage, meaning price improvement, occurs by design, and aggregate slippage cost can be negative. Model costs accordingly.
Your own data
Convert each ticker's CSV to a
.binfile:bin/reamer-csv-build AAPL.csv AAPL.binThe tool detects the delimiter, the column names and the timestamp format. It prints what it detected, the rows it skipped, and the first and last timestamp written. Check the report before you run.
Timestamps are whole seconds, so each instrument can have one bar per second. If two rows share a timestamp, the tool stops and writes nothing unless
--keep-firstkeeps the first bar of each second.A
.binfile holds one instrument. If the CSV has a symbol column with more than one symbol, the tool stops and writes nothing. Select each symbol with--symbol:bin/reamer-csv-build --symbol AAPL market.csv AAPL.binPass the
.binpaths toreamer_run_backtest_files(). The files are memory-mapped, so a dataset larger than RAM runs.start_tsandend_tsselect a date range without rewriting the files.
Your license key
This archive contains no license key, deliberately. Your key arrives by email on payment, with this kit's download link. It carries the month you paid for, and each monthly renewal extends it. Nothing in this archive will activate on its own.
Without an active license the engine runs in Evaluation Mode: one ticker
per backtest, over at most 30 days of bar time or 50,000 bars, whichever
comes first, and no live relay. Both files in python/sample_data/ fit
inside it. Activating your key removes every limit. If your key did not
arrive, write to:
support@reamerlabs.com — missing or failed keys.
Activation is per-machine and keyed to a host fingerprint, so a
containerized deployment needs a word of setup — LICENSING.md's "Self-Service Activation Failure
Modes" covers this, and is worth reading before you activate.
Activation is per machine and per product: this kit's reamer-license
activates Reamer Research keys only, and a machine running Reamer Server
too activates each product with its own key. See LICENSING.md for the
seat and machine-migration policy.
reamer-license activate presents LICENSE.txt and requires you to type
accept before it contacts the licence server. Declining consumes no seat.
The acceptance is recorded next to the activation record and is not
re-prompted for the same terms. For unattended provisioning, set
REAMER_ACCEPT_LICENSE=accept in the environment — activation without a
terminal and without that variable fails rather than defaulting to
acceptance. Amended terms carry a different hash and prompt again.
| For | Address |
|---|---|
| Purchases, invoices, commercial terms | hello@reamerlabs.com |
| Licensing and technical support | support@reamerlabs.com |
| Security correspondence | team@reamerlabs.com |
What is not in this kit
Stated plainly, so you can scope the work rather than discover it:
- No data. Beyond the synthetic samples that make the quickstart run, sourcing, cleaning, and adjusting market data is yours. The engine validates bar structure, not data quality, and feeding it unadjusted equity data produces wrong results with no warning.
- No source. Reamer Research is closed-source. The ABI header is the contract; nothing here asks you to compile the product, and no document in this archive should tell you to. If one does, that is a defect — report it to support@reamerlabs.com.
- No test suite. The reference trees ship without tests. Validate any adaptation against your own.
- No live market data. The relay sends orders out; it does not feed bars to
on_bar. Your loop does, as in Live trading with Reamer Research.
Platform
Linux x86-64 and macOS arm64, and Windows through WSL2 using the Linux kit.
There is no native Windows build. See
SUPPORTED_PLATFORMS.md for exact OS versions and the glibc floor —
and note that if you are deploying Reamer Server on the same image, the
server's floor is higher and governs the combined image.