All docs pages

Docs · Getting started

Reamer Research quickstart

Adapted from README.md in the 4.11.3 Reamer Research kit.

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

  1. 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 hardware
    

    It 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" in BENCHMARK.md for how to read the shape.

  2. DEPLOYMENT.md, Step 1. Verify the download, then read Step 2 about licensing — see the next section first, because you need a key.

  3. include/reamer_research_abi.h. Twenty minutes here answers most integration questions. It is the contract, and it is written to be read.

  4. Run something. The fastest path to a backtest result, from this directory. In Python:

    pip install python/reamer_research-*.whl
    python3 python/examples/quickstart.py
    

    Or 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.csv
    

    Each 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.

  5. 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

  1. Convert each ticker's CSV to a .bin file:

    bin/reamer-csv-build AAPL.csv AAPL.bin
    

    The 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-first keeps the first bar of each second.

    A .bin file 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.bin
    
  2. Pass the .bin paths to reamer_run_backtest_files(). The files are memory-mapped, so a dataset larger than RAM runs. start_ts and end_ts select 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.

Buy a licenceKey and kit by email on payment.