Skip to main content
quanuxctl crucible is the primary interface for managing the QuanuX Crucible backtesting engine — a C++20 simulation engine that executes strategies at speeds up to 100x faster than pandas-based backends. Crucible enforces process isolation by moving execution off the terminal shell via os.setsid(), meaning your backtest runs in the background and survives terminal disconnection. All metrics are stored natively in a DuckDB state file and are accessible instantly via the C++ API without going through Python.

​
Synopsis

​
Commands

​
start

Starts a backtesting simulation for the named strategy. Crucible looks for a test harness generated by the Foundry at server/backtests/<strategy>_v<version>/. If found, it forks the process and writes the OS process ID to /tmp/quanux_crucible.pid.
​
string
required
The strategy name. Must match a directory under server/backtests/.
​
string
The version of the strategy to run (e.g., 1.0.0). Defaults to the latest available version.
Example:

​
stop

Sends a SIGTERM to the running engine PID. If the process has not exited after 5 seconds, Crucible escalates to SIGKILL.
Crucible reads the PID from /tmp/quanux_crucible.pid. If no PID file exists, the command exits cleanly.

​
status

Reads the tracked PID and returns real-time CPU and memory usage for the running simulation.
The output shows:
  • CPU usage (%) against the C++ execution loop
  • RAM consumption inside the 128-byte aligned memory pools

​
report

Extracts the complete metrics payload from the DuckDB state file at C++ speed. This command bypasses the Python pandas pipeline entirely — it loads the compiled Cython extension and calls DuckDBFeeder::get_metrics_json() directly via the C++ DuckDB API.
​
string
required
The strategy name to pull metrics for.
​
string
The version to report on. Defaults to the latest available version.
Example:

​
L3 execution metrics

Unlike conventional backtesters, Crucible enforces institutional-grade L3 (Market By Order) metric collection. The report command returns the following metrics in its JSON payload:
The CrucibleTrade struct is explicitly aligned to 128 bytes to maintain CPU L1/L2 cache locality. If you modify this struct in C++, you must propagate the change to quanux_crucible.pxd Cython headers. Failing to do so will produce a segmentation fault at runtime.

​
Files

​
Example workflow

1

Start the backtest

Launch the simulation in the background:
The terminal returns immediately. The simulation runs as an isolated OS process.
2

Monitor resource usage

Check CPU and memory consumption while the simulation runs:
3

Watch live telemetry (optional)

Subscribe to the NATS telemetry subject for real-time trade events:
4

Pull the metrics report

When the simulation completes (or at any point during execution), extract the L3 metrics:
The command returns a JSON payload with slippage, queue position, MAE, and MFE data.
5

Stop if needed

If you need to halt the simulation early:
Crucible sends SIGTERM first, then SIGKILL after 5 seconds if the process has not exited.

​
Architecture note

Crucible uses the native duckdb::Appender API to inject vectorized blocks of CrucibleTrade structures directly into DuckDB’s in-memory columnar engine. No SQL parsing occurs during execution. The Cython bridge (QuanuX-Backtesting-Engine/python) provides Python developers with transparent C++ throughput by statically linking libbacktest_engine.a into quanux_crucible.so.