Documentation Index
Fetch the complete documentation index at: https://docs.quanux.org/llms.txt
Use this file to discover all available pages before exploring further.
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.
The strategy name. Must match a directory under
server/backtests/.The version of the strategy to run (e.g.,
1.0.0). Defaults to the latest available version.stop
Sends a SIGTERM to the running engine PID. If the process has not exited after 5 seconds, Crucible escalates to SIGKILL.
/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.
- 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.
The strategy name to pull metrics for.
The version to report on. Defaults to the latest available version.
L3 execution metrics
Unlike conventional backtesters, Crucible enforces institutional-grade L3 (Market By Order) metric collection. Thereport command returns the following metrics in its JSON payload:
| Metric | Description |
|---|---|
| Latency Slippage (bps) | Slippage measured in basis points based on execution delay relative to signal time |
| Queue Position at Entry | Simulated position in the order queue, tracked via volume-ahead in the FifoMatcher |
| MAE | Maximum Adverse Excursion — the worst unrealized loss reached during the trade |
| MFE | Maximum Favorable Excursion — the best unrealized gain reached during the trade |
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
| Path | Description |
|---|---|
/tmp/quanux_crucible.pid | OS process ID of the currently running simulation |
server/backtests/<strategy>_v<version>/crucible.duckdb | DuckDB state file written natively by the C++ engine |
Example workflow
Start the backtest
Launch the simulation in the background:The terminal returns immediately. The simulation runs as an isolated OS process.
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.
Architecture note
Crucible uses the nativeduckdb::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.