> ## 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: run, monitor, and report backtests

> Start, stop, monitor, and report on Crucible backtesting jobs. Results are stored in DuckDB and exposed as L3 execution metrics through the native C++ API.

`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

```
quanuxctl crucible <command> [options]
```

## 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`.

```
quanuxctl crucible start <strategy> [--version VERSION]
```

<ParamField path="strategy" type="string" required>
  The strategy name. Must match a directory under `server/backtests/`.
</ParamField>

<ParamField path="--version" type="string">
  The version of the strategy to run (e.g., `1.0.0`). Defaults to the latest available version.
</ParamField>

**Example:**

```bash theme={null}
quanuxctl crucible start my_strategy --version 1.0.0
```

### `stop`

Sends a `SIGTERM` to the running engine PID. If the process has not exited after 5 seconds, Crucible escalates to `SIGKILL`.

```
quanuxctl crucible stop
```

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.

```
quanuxctl crucible status
```

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.

```
quanuxctl crucible report <strategy> [--version VERSION]
```

<ParamField path="strategy" type="string" required>
  The strategy name to pull metrics for.
</ParamField>

<ParamField path="--version" type="string">
  The version to report on. Defaults to the latest available version.
</ParamField>

**Example:**

```bash theme={null}
quanuxctl crucible report my_strategy --version 1.0.0
```

## 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:

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

<Note>
  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.
</Note>

## 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

<Steps>
  <Step title="Start the backtest">
    Launch the simulation in the background:

    ```bash theme={null}
    quanuxctl crucible start my_strategy --version 1.0.0
    ```

    The terminal returns immediately. The simulation runs as an isolated OS process.
  </Step>

  <Step title="Monitor resource usage">
    Check CPU and memory consumption while the simulation runs:

    ```bash theme={null}
    quanuxctl crucible status
    ```
  </Step>

  <Step title="Watch live telemetry (optional)">
    Subscribe to the NATS telemetry subject for real-time trade events:

    ```bash theme={null}
    nats sub "sys.crucible.report.my_strategy"
    ```
  </Step>

  <Step title="Pull the metrics report">
    When the simulation completes (or at any point during execution), extract the L3 metrics:

    ```bash theme={null}
    quanuxctl crucible report my_strategy --version 1.0.0
    ```

    The command returns a JSON payload with slippage, queue position, MAE, and MFE data.
  </Step>

  <Step title="Stop if needed">
    If you need to halt the simulation early:

    ```bash theme={null}
    quanuxctl crucible stop
    ```

    Crucible sends `SIGTERM` first, then `SIGKILL` after 5 seconds if the process has not exited.
  </Step>
</Steps>

## 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`.