Skip to content

v0.5.0

Choose a tag to compare

View all tags
@rcarback rcarback released this 30 Oct 23:16
· 26 commits to main since this release
v0.5.0
a99f7d2

v0.5.0 removes the Python reference VM, moves xqsa, xqcp and xquad onto the typed xqffi model API, and replaces the per-hardware solvers with one Solver base. Code written against 0.4 needs changes: read Breaking changes or the migration guide first. This release carries part of its planned scope, and the rest moves to v0.6.0. Install v0.5.1 rather than this release: it fixes the two known issues below and changes no API.

Breaking changes

One VM

  • The Python reference VM is gone, and xqvm_py has no 0.5 release: from xqvm_py ... → from xqffi.vm ... or xquad.types.
  • VM(backend=VMBackend.RUST) → VM(). VMBackend, the backend argument and the runners' --interpreter flag are removed.

Model types

  • xquad.types.XQMX, XQMXDomain, XQMXMode, Vec and VecElem → XqmxModel, XqmxSample and Domain: XQMX.binary_model(size=4) → XqmxModel.binary(4), and compute_energy(model, sample) → model.energy(sample).
  • Exceptions change around the model types. An oversized model or an impossible grid raises InvalidAllocation or InvalidGridDimensions, where 0.4 raised ValueError. An index outside 0..size raises IndexOutOfBounds, where 0.4 raised IndexError. All three are XqvmError subclasses and so RuntimeError.
  • define_model() takes an xqcp.Domain only, and each Domain value is now the domain's name as a string.

Solvers

  • SolverDWaveCPU → SolverCPU, SolverCudaGPU → SolverGPU(engine="cuda"), SolverMetalGPU → SolverGPU(engine="metal"), SolverDWaveQPU → SolverDWave.
  • strategy= → algorithm=, fixed when the solver is built. solve() no longer accepts it, and an unknown keyword to solve() raises TypeError. Constructors take keyword arguments only.
  • xqsa.registry → xqsa or xqsa.solvers. Registry keys become cpu, cuda, metal and dwave; quip is unchanged.
  • result.metadata holds exactly seed, reads and params.
  • A Solver subclass needs its own __init__, because Solver.__init__ now takes the implementation it runs.

Verifier and metering

  • The verifier checks stack underflow by pop count, including across a later SCLR. In the xqvm crate, StackEffect::Delta → StackEffect::Fixed { pops, pushes }.
  • A step charge that would carry the counter past 2^64 - 1 raises StepLimitExceeded, whatever the step limit.

Highlights

  • XQCP decoder outputs can be filled in any order, written and read by index, and appended to conditionally.
  • XqmxSample.default(domain, size) starts a sample at its domain default, ready to be written.
  • XqvmError.offset gives the byte offset of the faulting instruction.
  • xqffi ships type stubs for asm, vm and verifier.

Deprecations

The names 0.4 deprecated still work and warn in 0.5.x, and each is removed in v0.6.0. The book's Deprecated APIs table names the replacement where one exists.

Known issues

Both are fixed in v0.5.1.

  • Some deprecation warnings say the name was removed in v0.5.0. The name still works, and its removal is in v0.6.0.
  • The book published with this release has no migration guide and still describes the Python VM on some pages.

Packages

Registry Packages
crates.io xqvm · xqasm
PyPI xquad · xqsa · xqcp · xqffi 
pip install xquad==0.5.0

Documentation: developers.quip.network/docs/xquad

Full changelog (50 changes)

Added

  • xqcp: Support conditional append in a decoder output block
  • xqcp: Make random-access output write and read work
  • xqcp: Let decoder outputs be filled in any order
  • xqsa: Run solver-core binaries through --solve
  • xqsa: Add a dimod-free BINARY to Ising conversion
  • xqffi: Let a sample start at its domain default and be written
  • xqffi: Carry the faulting byte offset on every XqvmError
  • xqffi: Ship type stubs for asm, vm and verifier
  • xqffi: Type the model API, energy, faults and limits [BREAKING]

Changed

  • xqsa: Fold the solver registry into xqsa.solvers [BREAKING]
  • xqsa: Move in-process implementations into xqsa.inprocess [BREAKING]
  • xqsa: Carry the GPU budget in the registry and drop ABC
  • xqsa: Merge per-call keywords over defaults in the template [BREAKING]
  • xqsa: Replace the per-hardware solvers with one Solver base [BREAKING]
  • Remove the Python reference VM [BREAKING]
  • examples: Run the examples on the Rust VM only [BREAKING]
  • xqcp: Key domains on xqcp.Domain, not XQMXDomain [BREAKING]
  • xquad: Re-export the xqffi types and drop the Python backend [BREAKING]
  • xqsa: Move onto the xqffi model types [BREAKING]
  • xqvm: Expose the IDXTRIU index as triu_index

Documentation

  • Cover any-order, indexed and conditional decoder outputs
  • xqsa: Specify the solver-binary implementation
  • Use the new solver names in READMEs, examples and the book
  • xqsa: Specify the Solver base and the metadata shape [BREAKING]
  • xqvm: Keep the model register out of the pre-charge validation
  • xqvm: Validate what a charge is sized from before charging
  • xqvm: State that a zero coefficient write removes the entry
  • xqvm: Drop the Python VM from test and source comments
  • xqvm: Describe one implementation in the specification
  • book: Make the spec the authority the VM is checked against
  • book: Teach one VM from first run to the cookbook
  • xqvm: State that SLACK never doubles past its capacity
  • xqvm: Correct the sample and step claims in the ONEHOT rule
  • xqvm: Charge a register-derived extent only on a model
  • Describe xqsa and the book in terms of the xqffi types
  • Drop the removed --interpreter flag and VMBackend from README
  • xqvm: Describe the opcode-table check as pops and pushes
  • xqvm: Point the verifier check order at the underflow rule
  • xqvm: Drop dead links and stale paths after the vector move
  • xqvm: Stop crediting the step budget with the expansion refusal

Fixed

  • xqcp: Refuse iterating an output and align decoder wording
  • xqcp: Refuse output() inside a loop or a branch arm
  • xqffi: Refuse a model or sample no program could build [BREAKING]
  • xqcp: Reject a define_model domain that is not an xqcp.Domain
  • xqffi: Bound XqmxSample.default by MAX_ALLOCATION_SIZE
  • xqvm: Keep a static underflow across a later SCLR in the verifier [BREAKING]
  • xqvm: Check stack underflow by pop count in the verifier [BREAKING]
  • xqffi: Bound model coefficient indices at the host boundary
  • xqffi: Report decode errors by their Display text
  • xqvm: Refuse a step charge that overflows the counter [BREAKING]

Full diff: v0.4.5...v0.5.0

Assets 2
Loading