Python Reference¶

pyserq compiles, simulates and draws serQ programs in Python. It uses the same interpreter as the CLI and returns objects for inspecting a run.

Install¶

pip install pyserq

Requires Python 3.9 or newer. To include development releases, use pip install --pre pyserq.

Run a program¶

import pyserq

source = """
fn main() {
  pool reqs { cap 2; }
  stage svc : fifo;
  workload {
    arrive batch(4);
    session { turn; end; }
  }
  server {
    hold reqs (cost(reqs, 1)) { run svc (cost(svc, 2)); }
  }
  gauge occupied = used(reqs);
}
"""
report = pyserq.run(pyserq.compile(source=source, horizon=10))
response = report.client["response"]   # what each turn's client saw
print(response.mean)

API¶

Compilation and execution¶

Function or class	Description
`pyserq.compile`	Compile a file or source text with parameter and run overrides.
`pyserq.Program`	A compiled program; serialize or load its IR.
`pyserq.run`	Simulate a compiled program and return a report.

Results¶

Class	Description
`pyserq.Report`	Run metadata, named lookups and JSON output.
`pyserq.Observe`	Sample statistics and per-session records.
`pyserq.Gauge`	Time-weighted statistics and change points.
`pyserq.Claim`	What the run found of a claim.
`pyserq.Stage`	Queue, service, iteration and inter-token statistics.
`pyserq.Pool`	Allocation, cache, admission and preemption statistics.

Visualization and inputs¶

Function or class	Description
`pyserq.draw`	Render a deployment as TikZ or SVG.
`pyserq.read_trace`	Read a replay CSV into sessions and turns.
`pyserq.Rng`	Draw from the interpreter's random-number generator.

Version constants¶

Name	Type	Meaning
`pyserq.__version__`	`str`	Version of the installed serQ implementation.
`pyserq.IR_VERSION`	`int`	IR version accepted by this build. See IR stability.
`pyserq.REPORT_VERSION`	`int`	Schema version of `Report.json()`.

Errors and types¶

Compilation, validation, trace-loading and simulation errors raise ValueError with serQ's diagnostic. Wrong Python argument types raise TypeError; integers outside the accepted unsigned range raise OverflowError. Individual entries describe additional conditions.

Signatures below use Python type notation to describe accepted values and returns. A * marks keyword-only arguments. None for a compile override keeps the program's setting; it does not select a new default.

For language syntax, see the language API. For command-line options and report definitions, see the CLI reference.