xquad -- Primary user-facing package for the XQuad toolchain

xquad is the Python distribution most users should install. It provides the interactive Program / Session / RunResult API, a VM wrapper over the Rust interpreter, and re-exports the lower-level peer packages (xqffi, xqcp, xqsa) under a single namespace.

Install

pip install xquad

Pulls xqffi, xqcp, and xqsa as runtime dependencies. Peer installs stay valid (pip install xqffi xqcp xqsa) if you only need a subset.

Interactive usage

Load a program once, run it with different calldata, inspect outputs by slot:

from xquad.program import Program

program = Program.from_source("""
PUSH 0
INPUT r0
PUSH 1
INPUT r1
LOAD r0
LOAD r1
ADD
STOW r2
PUSH 0
OUTPUT r2
HALT
""")

session = program.session(output_slots=1)
session.set_calldata([40, 2])
result = session.run()
assert dict(result.outputs) == {0: 42}

Program.load(bytes) takes wire-format bytecode; Session.run() returns a RunResult with dict-keyed outputs (unset slots present as None), residual stack, and step count.

Full pipeline

Compile a problem via the DSL, execute, sample:

from xquad import cp, sa
from xquad.vm import VM

problem = cp.Problem("MyProblem")
# ... define inputs, model, objective, decoder ...
programs = problem.compile()

vm = VM()
vm.set_output_slots(1)
vm.run(programs.encoder)
model = vm.outputs()[0]

sample = sa.SolverCPU().solve(model).sample

Re-exports of peer packages are identity, not copies:

import xquad, xqcp
assert xquad.cp.Problem is xqcp.Problem   # always True

So isinstance works whether the caller imported directly from the peer or via the umbrella.

Subnamespaces

The raw FFI surface stays available as xqffi.vm.Vm.

Also see

• xqffi -- PyO3 FFI bindings (low-level / conformance).
• xqcp -- constraint-programming DSL.
• xqsa -- solver adapters.
• Running Programs -- end-to-end tour including the Program/Session, xqffi.vm, and xquad.vm surfaces.

License

AGPL-3.0-or-later.