Skip to content

Installation and Quick Start

Requirements

  • Python 3.10 or newer
  • No runtime Python dependencies
  • pytest 8 or newer only when running tests

Install in editable mode

From the Cnuas repository root:

python3 -m pip install -e timing
cnuas-timing --help

Without installing, place the package on PYTHONPATH:

PYTHONPATH=timing/src python3 -m cnuas_timing.cli --help

The remaining examples assume:

cd timing

Predict one component

Estimate CnuasNIC service for four packets carrying 4 KiB:

cnuas-timing predict profiles/cnuas-analytic-v0.json cnuasnic \
  --bytes 4096 --packets 4

The result is JSON:

{
  "component": "cnuasnic",
  "duration_ns": 427.68,
  "evidence": "analytic",
  "target": null,
  "uncertainty_pct": null
}

The analytic evidence label and null target are important. This is the result of the selected profile, not measured NIC latency.

Simulate an end-to-end pipeline

cnuas-timing simulate profiles/cnuas-analytic-v0.json \
  examples/rdma-gpu-pipeline.json --jobs 100

The result includes:

  • profile name and version;
  • evidence classes used by the pipeline;
  • job count and elapsed model time;
  • mean and nearest-rank p95 latency;
  • completed jobs per model second.

Add the full event trace:

cnuas-timing simulate profiles/cnuas-analytic-v0.json \
  examples/rdma-gpu-pipeline.json --jobs 4 --trace > run.json

Each event identifies its job, stage, component, lane, stage arrival, service start, and completion in picoseconds.

Model arrival rate and queueing

Submit a job every 500 ns:

cnuas-timing simulate profiles/cnuas-analytic-v0.json \
  examples/rdma-gpu-pipeline.json \
  --jobs 1000 --arrival-interval-ns 500 --trace > queued.json

Compare each event's submitted_ps and start_ps. Their difference is the queue time at that stage. A growing difference identifies a resource that cannot keep up with the configured arrival rate.

Generate QEMU virtual-time arguments

cnuas-timing qemu-args --shift 0

Output:

-accel tcg,thread=single -icount shift=0,align=off,sleep=off -rtc clock=vm

This is a separate TCG experiment mode. Do not append it to the standard KVM launch command. The command prints a deterministic guest-clock configuration; it does not start QEMU or capture counts.

Run the checks

PYTHONPATH=src python3 -m pytest tests -q

The suite contains 46 checks covering arithmetic, invalid inputs, queueing, parallel lanes, replay, profile I/O, QEMU mapping, fitting, validation, and CLI workflows.

Next steps