backend

Documentation

Overview

Package backend defines the interface for quantum execution backends.

Package backend defines the Backend interface for quantum execution targets and the associated request/response types.

A Backend can submit circuits, poll job status, retrieve results, and cancel pending jobs. Result carries both measurement counts and probabilities, with conversion methods Result.ToCounts and Result.ToProbabilities.

Implementations: local simulator (backend/local), IonQ REST client (backend/ionq), IBM Quantum Runtime (backend/ibm), Amazon Braket (backend/braket), and configurable mock (backend/mock).

Index

• type Backend
• type Job
• type JobState
  • func (s JobState) String() string
  • func (s JobState) Terminal() bool
• type JobStatus
• type Result
  • func (r *Result) ToCounts() map[string]int
  • func (r *Result) ToProbabilities() map[string]float64
• type SubmitRequest

Types

type Backend

type Backend interface {
	// Name returns the backend identifier (e.g., "ionq.aria-1").
	Name() string

	// Target returns hardware constraints for transpilation.
	Target() target.Target

	// Submit sends a circuit for execution.
	Submit(ctx context.Context, req *SubmitRequest) (*Job, error)

	// Status checks the current state of a job.
	Status(ctx context.Context, jobID string) (*JobStatus, error)

	// Result retrieves completed job results.
	Result(ctx context.Context, jobID string) (*Result, error)

	// Cancel attempts to cancel a pending/running job.
	Cancel(ctx context.Context, jobID string) error
}

Backend represents a quantum execution target.

type Job

type Job struct {
	ID      string
	Backend string
	State   JobState
}

Job represents a submitted quantum job.

type JobState

type JobState int

JobState represents the lifecycle state of a quantum job.

const (
	StateSubmitted JobState = iota
	StateReady
	StateRunning
	StateCompleted
	StateFailed
	StateCancelled
)

func (JobState) String

func (s JobState) String() string

String returns the human-readable state name.

func (JobState) Terminal

func (s JobState) Terminal() bool

Terminal reports whether this state is final (no further transitions).

type JobStatus

type JobStatus struct {
	ID        string
	State     JobState
	Progress  float64 // 0.0–1.0, or -1 if unknown
	QueuePos  int     // position in queue, or -1 if unknown
	CreatedAt time.Time
	UpdatedAt time.Time
	Error     string // populated when State == StateFailed
}

JobStatus contains detailed information about a job's current state.

type Result

type Result struct {
	Counts        map[string]int     // bitstring → shot count
	Probabilities map[string]float64 // bitstring → probability
	Shots         int
	Metadata      map[string]string
}

Result contains the output of a completed quantum job.

func (*Result) ToCounts

func (r *Result) ToCounts() map[string]int

ToCounts returns measurement counts. If only probabilities are available, they are converted to counts using the largest-remainder method.

func (*Result) ToProbabilities

func (r *Result) ToProbabilities() map[string]float64

ToProbabilities returns measurement probabilities. If only counts are available, they are normalized by the total number of shots.

type SubmitRequest

type SubmitRequest struct {
	Circuit      *ir.Circuit    // gate-level circuit (nil if PulseProgram set)
	PulseProgram *pulse.Program // OpenPulse program (nil if Circuit set)
	Shots        int
	Name         string
	Metadata     map[string]string
	Options      map[string]any // backend-specific options (e.g., ionq.PulseShapes)
}

SubmitRequest contains the parameters for submitting a quantum job. Exactly one of Circuit or PulseProgram must be non-nil.