C++ API reference

The headers below define internal C++ interfaces and are not installed. See C++ interfaces for adapter requirements and components for behavior and tests.

backend.hpp

Quantum backend operations and the mock implementation. Open header.

profile.hpp

Full simulation profile, validation and configuration fingerprint. Open header.

control_links.hpp

Bounded mailboxes between CPU timing control and the TCU. Open header.

transport_config.hpp

Mailbox clocks, receiver-edge latencies and result capacity. Open header.

control_protocol.hpp

Timing-point requests, underflow policies and scheduled events. Open header.

cpu.hpp

Replaceable CPU interface with memory and control ports. Open header.

core.hpp

Per-controller CPU, memory, timing control, synchronization and measurement state. Open header.

sync.hpp

Countdowns and bounded fixed-delay connections for BISP, the booking-based synchronization protocol from Distributed-HISQ. Open header.

cpu/rv32.hpp

Three-stage RV32I CPU with scalar qsbit control instructions. Open header.

cpu/vliw.hpp

Three-stage CPU with scalar instructions and dual-codeword bundles. Open header.

cpu/trace.hpp

End-of-edge CPU pipeline snapshots. Open header.

cpu/pipeline.hpp

Shared in-order pipeline state and transitions. Open header.

defaults.hpp

Construction of the default timing and device profile. Open header.

decoder.hpp

Decoder MMIO registers, bounded transport and timed processing. Open header.

device.hpp

Physical intervals, resource reservations and device execution. Open header.

device/resources.hpp

Output-interval and resource-conflict checks. Open header.

error.hpp

Typed faults and their diagnostic names. Open header.

feedback.hpp

Per-qubit measurement result registers and execution flags. Open header.

image.hpp

ELF or raw loading, memory bytes and segment permissions. Open header.

isa.hpp

Decoded RV32I instructions and architectural effects. Open header.

mailbox.hpp

Bounded messages with explicit arrival ticks. Open header.

memory.hpp

Fetch and data ports with timed memory service. Open header.

timing_control.hpp

Quantum instruction adaptation, time point preparation, mailbox requests and replies, and feedback communication. Open header.

python_backend.hpp

Optional bridge to Python quantum adapters. Open header.

simulator.hpp

SystemC scheduling, CPU construction, reset and completion. Open header.

tcu.hpp

Timing queues, event queues and the TCU edge transition. Open header.

time.hpp

Tick arithmetic and clock-edge calculations. Open header.

trace.hpp

Trace records and JSONL serialization. Open header.

event.hpp

Device event specifications, codeword mappings and paired-gate definitions. Open header.

measurement.hpp

Measurement identities, completion bits and execution flags. Open header.

control_command.hpp

Named payloads for codeword, wait, measurement-read, halt and synchronization commands. Open header.

timing_config.hpp

Transport, timing-control and TCU configuration values. Open header.

device/gates.hpp

Indexed paired-gate definitions and gate-output resolution. Open header.

device/readouts.hpp

Acquisition pairing, readiness calculation and sampled-result lifetime. Open header.

decoder/mmio.hpp

Decoder register storage and typed MMIO commands. Open header.

runtime.hpp

Executable-relative installation discovery and paired runtime paths. Open header.

Namespace reference

namespace qsbit

Typedefs

using BackendOperation = std::variant<BackendEvolution, BackendGates, BackendMeasurement>

using DecoderCommand = std::variant<DecoderSubmit, DecoderReset, DecoderConsume, DecoderRead>

using Tick = std::uint64_t

using Id = std::uint64_t

using Epoch = std::uint64_t

Enums

enum class UnderflowPolicy

Values:

enumerator Inherit

enumerator Strict

enumerator PauseWhenEmpty

enum class ControlIssue

Values:

enumerator Scalar

enumerator DualCodeword

enum class DecoderReadKind

Values:

enumerator Count

enumerator Status

enumerator Low

enumerator High

enum class ErrorCode

Values:

enumerator InvalidProfile

enumerator TimeOverflow

enumerator IllegalInstruction

enumerator InstructionMisaligned

enumerator InstructionAccess

enumerator LoadMisaligned

enumerator StoreMisaligned

enumerator LoadAccess

enumerator StoreAccess

enumerator EnvironmentCall

enumerator Breakpoint

enumerator InvalidImage

enumerator UnsupportedSynchronization

enumerator InvalidPort

enumerator InvalidCodeword

enumerator InvalidOperand

enumerator Capacity

enumerator LateAdmission

enumerator ManifestMismatch

enumerator Protocol

enumerator ResourceConflict

enumerator GateInputMismatch

enumerator UnsupportedCapability

enumerator InvalidMeasurement

enumerator DuplicateResult

enumerator BackendFailure

enumerator Watchdog

enum class ActionKind

Values:

enumerator IdealGate

enumerator Pulse

enumerator Acquire

enumerator DiscriminatorArm

enumerator GateOutput

enum class ExecutionFlag

Values:

enumerator Always

enumerator LastOne

enumerator LastZero

enumerator Equal

enum class DecoderEventKind

Values:

enumerator RequestSubmitted

enumerator RequestSent

enumerator RequestArrived

enumerator Started

enumerator Completed

enumerator ResultReturned

enumerator Reset

enumerator ResultConsumed

Functions

ControlOperation adapt_quantum(const rv32::Decoded&, Id instruction, std::uint32_t lhs, std::uint32_t rhs)

std::vector<OperationEvent> decode_codeword(const TimingConfig &profile, std::uint32_t port, std::uint32_t codeword, Epoch epoch, Id instruction, Id first_event, std::span<const MeasurementReference> references = {})

void validate_timing_events(const TimingEvents &events, const TimingConfig &profile)

std::array<ControlOperation, 2> decode_cw_bundle(std::uint32_t word, Id instruction, const std::array<std::uint32_t, 32> &registers)

Profile default_profile()

DeviceProfile device_profile(const Profile &profile)

EventSpec gate_action(const DeviceProfile &profile, const std::string &name)

std::vector<EventSpec> resolve_gate_outputs(const DeviceProfile &profile, Tick now, const std::map<std::string, std::vector<const ScheduledEvent*>> &outputs)

const char *name(ErrorCode code) noexcept

void require(bool condition, ErrorCode code, const std::string &message)

DecoderSystemConfig python_decoders(const std::string &config)

RuntimeLayout runtime_layout()

std::string installation_info(const RuntimeLayout &layout)

inline Tick checked_add(Tick a, Tick b)

inline TcuCycle checked_add(TcuCycle a, TcuCycle b)

inline Tick checked_mul(Tick a, Tick b)

TimingConfig timing_config(const Profile &profile)

TcuConfig tcu_config(const Profile &profile)

TransportConfig transport_config(const Profile &profile)

Variables

constexpr unsigned PythonBackendApiVersion = 4

struct AcquireSpec

#include <event.hpp>

Public Functions

bool operator==(const AcquireSpec&) const = default

Public Members

std::string operation = "x"

QuantumOperands operands

Tick discriminator_delay = 20

bool separate_arm = false

struct BackendActivity

#include <backend.hpp>

Public Members

Id id

Tick start

Tick end

EventSpec action

std::optional<MeasurementReference> reference

struct BackendEvolution

#include <backend.hpp>

Public Members

Tick start

Tick tick

std::vector<BackendActivity> drives

std::vector<BackendActivity> acquisitions

class BackendExecution

#include <backend.hpp>

Public Functions

explicit BackendExecution(IQuantumBackend &backend, BackendExecutionConfig config = {})

inline void validate(const EventSpec &action) const

void reset(std::uint32_t qubits, std::uint32_t seed, Epoch epoch, Tick now = 0)

void evolve(Tick from, Tick to, std::span<const BackendActivity> active_drives, std::span<const BackendActivity> acquisitions = {})

void apply(Tick now, std::span<const EventSpec> gates)

std::vector<bool> measure(Tick now, std::span<const MeasurementReference> references)

void flush()

std::vector<std::complex<double>> state()

std::vector<std::vector<std::complex<double>>> density_matrix()

Private Functions

void commit(BackendOperation operation)

std::vector<bool> execute(std::size_t expected_results)

Private Members

IQuantumBackend &backend_

BackendExecutionConfig config_

std::vector<BackendOperation> pending_

Epoch epoch_ = 0

Tick committed_tick_ = 0

struct BackendExecutionConfig

#include <backend.hpp>

Public Members

std::uint32_t max_batch_operations = 1024

struct BackendGates

#include <backend.hpp>

Public Members

Tick tick

std::vector<EventSpec> gates

struct BackendMeasurement

#include <backend.hpp>

Public Members

Tick tick

std::vector<MeasurementReference> references

struct Clock

#include <time.hpp>

Public Functions

inline void validate() const

inline bool edge(Tick t) const

inline Tick after(Tick publication, std::uint32_t latency = 1) const

Public Members

Tick period = 1

Tick phase = 0

struct CodewordCommand

#include <control_command.hpp>

Public Functions

bool operator==(const CodewordCommand&) const = default

Public Members

std::uint32_t port

std::uint32_t codeword

struct Completion

#include <measurement.hpp>

Public Members

MeasurementReference reference

bool value = false

class ControlElectronics

#include <device.hpp>

Public Types

using Deliver = std::function<void(const Completion&)>

Public Functions

ControlElectronics(DeviceProfile profile, IQuantumBackend &backend, Trace &trace, BackendExecutionConfig execution = {})

inline BackendExecution &backend()

void validate(const EventSpec &action) const

void preflight(const TriggeredEvents &batch) const

void accept(const TriggeredEvents &batch)

void process(Tick now, Epoch epoch, const Deliver &deliver)

void finalize(Tick now)

void reset(Tick now, Epoch epoch)

std::optional<Tick> next_boundary() const

inline bool drained() const

inline const ResourceReservations &resources() const

Private Functions

PreparedEvents prepare(const TriggeredEvents &batch) const

std::vector<ScheduledEvent> resolve(const TriggeredEvents &batch) const

Private Members

const DeviceProfile profile_

BackendExecution backend_

Trace &trace_

ResourceReservations reservations_

std::map<Tick, Boundary> boundaries_

std::map<Id, ScheduledEvent> active_

Readouts readouts_

Tick last_tick_ = 0

std::optional<Tick> processed_tick_

struct Boundary

Public Members

std::vector<ScheduledEvent> starts

std::vector<Id> ends

std::vector<Id> ready

struct PreparedEvents

Public Members

std::vector<ScheduledEvent> actions

std::vector<qsbit::Readout> readouts

struct ControlLinks

#include <control_links.hpp>

Public Functions

inline explicit ControlLinks(TransportConfig p)

inline void reset()

Public Members

Mailbox<TimingEvents> timing_events

Mailbox<EnqueueReply> replies

Mailbox<EndOfStream> closure

Mailbox<Completion> cpu_results

Mailbox<Completion> fast_results

Mailbox<MeasurementReference> fast_credits

struct ControlOperation

#include <control_command.hpp>

Public Functions

template<typename T>
inline const T &get() const

template<typename T>
inline bool is() const

bool operator==(const ControlOperation&) const = default

Public Members

Id instruction = 0

std::variant<WaitCommand, CodewordCommand, FetchMeasurementCommand, HaltCommand, SynchronizeCommand> command = WaitCommand{0}

class Core

#include <core.hpp>

Public Types

using CpuFactory = std::function<std::unique_ptr<ICpuCycleModel>(Clock, std::uint32_t, Trace&)>

Public Functions

inline void attach_device(std::function<bool(std::uint32_t)> contains, MemoryModel::DeviceAccess access)

Core(std::uint32_t id, Profile profile, ProgramImage image, Trace &trace, SyncNetwork &network, TimingControl::ValidateAction validate, CpuFactory cpu_factory = {}, std::size_t sync_capacity = 8, bool identify = true)

void cpu_edge(Tick now, Epoch epoch)

void memory_edge(Tick now, Epoch epoch)

TcuOutput tcu_edge(Tick now, Epoch epoch, const TcuCycleModel::Preflight &preflight)

void deliver(Tick now, Epoch epoch, const Completion &result)

void reset(Tick now)

bool drained() const

inline const Profile &profile() const

inline const ICpuCycleModel &cpu() const

inline const ProgramImage &memory() const

inline const MeasurementRegisters &measurement_registers() const

inline std::uint32_t id() const

Private Members

std::uint32_t id_

const Profile profile_

Trace trace_

SyncUnit sync_

MeasurementRegisters registers_

TimingControl timing_control_

ControlLinks links_

MemoryPort fetch_port_

MemoryPort data_port_

MemoryModel memory_

std::unique_ptr<ICpuCycleModel> cpu_

TcuCycleModel tcu_

struct CoreConfig

#include <core.hpp>

Public Members

std::uint32_t id

Profile profile

ProgramImage image

Core::CpuFactory cpu_factory = {}

std::size_t sync_capacity = 8

class CpuCycleModel : public qsbit::ICpuCycleModel

#include <rv32.hpp>

Public Functions

inline CpuCycleModel(Clock clock, std::uint32_t entry, Trace &trace)

inline virtual void step(Tick now, Epoch epoch, CpuPorts &ports) override

inline virtual void reset(std::uint32_t entry) override

inline virtual const std::array<std::uint32_t, 32> &registers() const override

inline virtual std::uint32_t pc() const override

inline virtual bool halted() const override

Private Members

InOrderPipeline pipeline_

struct CpuPipelineInstruction

#include <trace.hpp>

Public Functions

bool operator==(const CpuPipelineInstruction&) const = default

Public Members

Id id = 0

std::uint32_t pc = 0

std::optional<std::uint32_t> word

bool discarded = false

struct CpuPipelineState

#include <trace.hpp>

Public Functions

bool operator==(const CpuPipelineState&) const = default

Public Members

std::array<std::optional<CpuPipelineInstruction>, 4> stages

bool halted = false

class CpuPipelineTrace

#include <trace.hpp>

Public Functions

inline explicit CpuPipelineTrace(Trace &trace)

inline void reset()

template<typename Fetch, typename Frame>
inline void sample(Tick now, Epoch epoch, Clock clock, const std::optional<Fetch> &fetch, const std::optional<Frame> &fetched, const std::optional<Frame> &decode, const std::optional<Frame> &execute, Id generation, bool halted)

Private Members

Trace &trace_

std::optional<CpuPipelineState> previous_

Epoch epoch_ = 0

struct CpuPorts

#include <cpu.hpp>

Public Members

MemoryPort &fetch

MemoryPort &data

std::function<std::optional<std::uint32_t>(const ControlOperation&)> control

struct DecoderConfig

#include <decoder.hpp>

Public Members

std::uint32_t id = 0

std::uint32_t measurements = 0

std::uint32_t outputs = 0

Tick latency = 1

Tick initiation_interval = 1

std::function<std::vector<bool>(std::span<const std::uint8_t>)> decode

struct DecoderConsume

#include <mmio.hpp>

Public Members

std::uint32_t decoder

struct DecoderEvent

#include <trace.hpp>

Public Members

DecoderEventKind kind

DecoderTrace state

class DecoderMmio

#include <mmio.hpp>

Public Functions

DecoderMmio(std::uint32_t base, std::set<std::uint32_t> decoders)

bool contains(std::uint32_t address) const

void validate_memory(const ProgramImage &image) const

std::optional<DecoderCommand> access(std::uint32_t core, const MemoryRequest &request)

inline void reset()

Private Members

std::uint32_t base_

std::set<std::uint32_t> decoders_

std::map<std::uint32_t, Registers> registers_

struct Registers

Public Members

std::uint32_t decoder = 0

std::uint32_t count = 0

std::uint32_t low = 0

std::uint32_t high = 0

std::uint32_t tag = 0

struct DecoderRead

#include <mmio.hpp>

Public Members

std::uint32_t decoder

DecoderReadKind kind

struct DecoderReset

#include <mmio.hpp>

Public Members

std::uint32_t decoder

std::uint32_t tag

struct DecoderSubmit

#include <mmio.hpp>

Public Members

std::uint32_t decoder

std::uint32_t count

std::uint32_t tag

std::uint64_t data

class DecoderSystem

#include <decoder.hpp>

Public Functions

DecoderSystem(DecoderSystemConfig config, Trace &trace)

inline bool contains(std::uint32_t address) const

inline void validate_memory(const ProgramImage &image) const

std::optional<std::uint32_t> access(std::uint32_t core, const MemoryRequest &request, Tick now, Epoch epoch)

void step(Tick now, Epoch epoch)

void reset()

bool idle() const

std::optional<Tick> next_boundary(Tick now) const

Private Functions

void advance_transmission(Tick now, Epoch epoch)

void advance_jobs(Tick now, Epoch epoch)

void admit_requests(Tick now, Epoch epoch)

void transmit_result(Tick now)

const DecoderConfig &decoder(std::uint32_t id) const

void event(Tick now, Epoch epoch, DecoderEventKind kind, Id id, std::uint32_t core, std::uint32_t decoder, std::uint32_t tag = 0)

Private Members

DecoderSystemConfig config_

Trace &trace_

DecoderMmio mmio_

std::map<std::pair<std::uint32_t, std::uint32_t>, Session> sessions_

std::map<std::uint32_t, Tick> available_

std::deque<Request> requests_

std::optional<Request> reset_request_

std::deque<Job> jobs_

Tick tx_available_ = 0

Tick rx_available_ = 0

Id next_ = 1

struct Job

Public Members

Id id

std::uint32_t core

std::uint32_t decoder

Tick start

Tick completion

std::uint64_t result

std::optional<Tick> arrival

bool started = false

bool completed = false

struct Request

Public Members

Id id

std::uint32_t core

std::uint32_t decoder

std::uint32_t count

std::uint32_t tag

std::uint64_t data

Tick sent

Tick arrival

bool transmitted = false

struct Session

Public Members

std::vector<std::uint8_t> measurements

std::optional<std::uint64_t> result

bool submitted = false

struct DecoderSystemConfig

#include <decoder.hpp>

Public Members

std::uint32_t base = 0x40000000

std::uint32_t request_capacity = 16

std::uint32_t result_capacity = 16

Tick link_latency = 1

std::uint32_t bytes_per_tick = 1

std::uint32_t packet_overhead = 16

std::vector<DecoderConfig> decoders

struct DecoderTrace

#include <trace.hpp>

Public Members

std::uint32_t id

std::uint32_t tag

std::size_t requests

std::size_t resets

std::size_t jobs

struct DeviceProfile

#include <gates.hpp>

Public Functions

const TwoQubitGate &gate(const std::string &name) const

Public Members

std::uint32_t qubits

std::uint32_t seed

std::map<std::string, TwoQubitGate> gates

struct DiscriminatorArmSpec

#include <event.hpp>

Public Functions

bool operator==(const DiscriminatorArmSpec&) const = default

Public Members

std::string operation = "x"

QuantumOperands operands

struct EndOfStream

#include <control_protocol.hpp>

Public Members

Id last_label = 0

struct EnqueueReply

#include <control_protocol.hpp>

Public Members

Id label = 0

struct EventSpec

#include <event.hpp>

Public Functions

template<typename T>
inline T &get()

template<typename T>
inline const T &get() const

ActionKind kind() const

const std::vector<std::uint32_t> &targets() const

const std::vector<ResourceUse> &resources() const

std::string operation() const

ExecutionFlag execution_flag() const

bool operator==(const EventSpec&) const = default

Public Members

std::uint32_t port = 0

Tick delay = 0

Tick duration = 20

std::variant<GateSpec, PulseSpec, AcquireSpec, DiscriminatorArmSpec, GateOutputSpec> spec = GateSpec{}

class ExecutionFlags

#include <feedback.hpp>

Public Functions

inline explicit ExecutionFlags(std::uint32_t qubits)

bool evaluate(std::uint32_t target, ExecutionFlag flag) const

void commit(const Completion &completion, Epoch epoch)

void reset()

Private Members

std::vector<Register> registers_

struct Register

Public Members

Id last_measurement = 0

bool last_one = false

bool last_zero = false

bool equal = false

class Fault : public std::runtime_error

#include <error.hpp>

Public Functions

inline Fault(ErrorCode code, const std::string &message)

inline ErrorCode code() const noexcept

Private Members

ErrorCode code_

struct FeedbackConfig

#include <feedback.hpp>

Public Members

std::uint32_t qubits

std::uint32_t result_capacity

bool fast_feedback

struct FetchMeasurementCommand

#include <control_command.hpp>

Public Functions

bool operator==(const FetchMeasurementCommand&) const = default

Public Members

std::uint32_t qubit

struct GateInput

#include <event.hpp>

Public Functions

bool operator==(const GateInput&) const = default

Public Members

std::uint32_t core = 0

std::uint32_t port = 0

std::uint32_t codeword = 0

struct GateOutputSpec

#include <event.hpp>

Public Functions

bool operator==(const GateOutputSpec&) const = default

Public Members

std::string gate

struct GateSpec

#include <event.hpp>

Public Functions

bool operator==(const GateSpec&) const = default

Public Members

std::string operation = "x"

QuantumOperands operands

double amplitude = 0.0

ExecutionFlag execution_flag = ExecutionFlag::Always

struct HaltCommand

#include <control_command.hpp>

Public Functions

bool operator==(const HaltCommand&) const = default

class ICpuCycleModel

#include <cpu.hpp>

Subclassed by qsbit::CpuCycleModel, qsbit::VliwCpuCycleModel

Public Functions

virtual ~ICpuCycleModel() = default

virtual void step(Tick now, Epoch epoch, CpuPorts &ports) = 0

virtual void reset(std::uint32_t entry) = 0

virtual const std::array<std::uint32_t, 32> &registers() const = 0

virtual std::uint32_t pc() const = 0

virtual bool halted() const = 0

class InOrderPipeline

#include <pipeline.hpp>

Public Functions

InOrderPipeline(Clock clock, std::uint32_t entry, Trace &trace, ControlIssue issue)

void step(Tick now, Epoch epoch, CpuPorts &ports)

void reset(std::uint32_t entry)

inline const std::array<std::uint32_t, 32> &registers() const

inline std::uint32_t pc() const

inline bool halted() const

Private Functions

void retire(const Frame &frame, std::uint32_t value, std::uint32_t next_pc, Tick now, Epoch epoch)

Private Members

ControlIssue issue_

Clock clock_

Trace &trace_

CpuPipelineTrace pipeline_trace_

std::array<std::uint32_t, 32> registers_ = {}

std::uint32_t pc_ = 0

std::uint32_t fetch_pc_ = 0

std::optional<Fetch> fetch_request_

std::optional<Frame> fetched_

std::optional<Frame> decode_

std::optional<Frame> execute_

Id next_fetch_ = 1

Id next_data_ = 1

Id generation_ = 0

bool halted_ = false

struct Fetch

Public Members

Id id

std::uint32_t pc

Id generation

struct Frame

Public Members

Id id = 0

std::uint32_t pc = 0

std::uint32_t word = 0

std::uint32_t lhs = 0

std::uint32_t rhs = 0

std::optional<ErrorCode> fault

std::optional<rv32::Decoded> decoded

std::optional<rv32::Effect> effect

Id memory_request = 0

bool bundle = false

std::array<ControlOperation, 2> operations = {}

std::size_t completed_lanes = 0

struct InstructionRetired

#include <trace.hpp>

Public Members

std::uint32_t pc

std::uint32_t word

std::uint32_t rd

std::uint32_t next_pc

std::uint32_t value

std::array<std::uint32_t, 32> registers

class IQuantumBackend

#include <backend.hpp>

Subclassed by qsbit::MockBackend, qsbit::PythonBackend

Public Functions

virtual ~IQuantumBackend() = default

virtual void validate(const EventSpec &action) const = 0

virtual void reset(std::uint32_t qubits, std::uint32_t seed) = 0

virtual std::vector<bool> execute(Epoch epoch, std::span<const BackendOperation> operations) = 0

inline virtual std::vector<std::complex<double>> state() const

inline virtual std::vector<std::vector<std::complex<double>>> density_matrix() const

template<typename T>
class Mailbox

#include <mailbox.hpp>

Public Functions

inline Mailbox(std::size_t capacity, Clock receiver, std::uint32_t latency = 1)

inline bool full() const

inline bool empty() const

inline std::size_t size() const

inline void publish(Tick now, Epoch epoch, T value)

inline const Envelope *peek(Tick now) const

inline std::optional<Envelope> take(Tick now)

inline void reset()

Private Members

std::size_t capacity_

Clock receiver_

std::uint32_t latency_

std::deque<Envelope> entries_

struct Envelope

#include <mailbox.hpp>

Public Members

Tick published

Tick eligible

Epoch epoch

T value

struct Mapping

#include <event.hpp>

Public Members

std::uint32_t port = 0

std::uint32_t codeword = 0

std::vector<EventSpec> actions

struct MeasurementReference

#include <measurement.hpp>

Public Functions

bool operator==(const MeasurementReference&) const = default

Public Members

Epoch epoch = 0

Id measurement = 0

std::uint32_t target = 0

class MeasurementRegisters

#include <feedback.hpp>

Public Functions

explicit MeasurementRegisters(FeedbackConfig config)

bool has_capacity(std::size_t count = 1) const

std::vector<MeasurementReference> prepare_reservation(Epoch epoch, std::span<const std::uint32_t> targets) const

void commit_reservation(std::span<const MeasurementReference> references)

MeasurementReference reserve(Epoch epoch, std::uint32_t target)

void deliver(const Completion &completion, Epoch epoch)

void acknowledge_fast(const MeasurementReference &reference, Epoch epoch)

std::optional<bool> read(std::uint32_t target) const

bool deliveries_pending() const

inline const std::vector<Register> &registers() const

void reset()

Private Members

const FeedbackConfig config_

std::vector<Register> registers_

std::map<Id, MeasurementReference> pending_

std::map<Id, MeasurementReference> fast_pending_

Id next_measurement_ = 1

struct Register

#include <feedback.hpp>

Public Members

std::uint32_t pending = 0

bool value = false

class MemoryModel

#include <memory.hpp>

Public Types

using DeviceAccess = std::function<std::optional<std::uint32_t>(const MemoryRequest&, Tick, Epoch)>

Public Functions

inline void attach_device(std::function<bool(std::uint32_t)> contains, DeviceAccess access)

MemoryModel(ProgramImage image, Clock clock, std::uint32_t latency)

void step(Tick now, Epoch epoch, MemoryPort &fetch, MemoryPort &data)

void reset()

inline const ProgramImage &image() const

inline bool idle() const

Private Functions

void step_port(Tick now, Epoch epoch, MemoryPort &port, std::size_t index)

Private Members

std::function<bool(std::uint32_t)> device_contains_

DeviceAccess device_access_

ProgramImage image_

Clock clock_

std::uint32_t latency_

std::array<std::optional<Pending>, 2> pending_

std::array<Id, 2> last_id_ = {}

struct Pending

Public Members

MemoryRequest request

Tick completion

Epoch epoch

struct MemoryPort

#include <memory.hpp>

Public Functions

inline explicit MemoryPort(Clock clock)

inline void reset()

Public Members

Mailbox<MemoryRequest> requests

Mailbox<MemoryResponse> responses

struct MemoryRequest

#include <memory.hpp>

Public Members

Id id = 0

std::uint32_t address = 0

std::uint32_t value = 0

std::uint8_t width = 4

bool write = false

bool instruction = false

struct MemoryResponse

#include <memory.hpp>

Public Members

Id id = 0

std::uint32_t value = 0

std::optional<ErrorCode> fault

class MockBackend : public qsbit::IQuantumBackend

#include <backend.hpp>

Public Functions

inline explicit MockBackend(std::map<Id, bool> outcomes = {})

virtual void validate(const EventSpec &action) const override

virtual void reset(std::uint32_t qubits, std::uint32_t seed) override

virtual std::vector<bool> execute(Epoch epoch, std::span<const BackendOperation> operations) override

inline virtual std::vector<std::complex<double>> state() const override

inline std::size_t calls() const

Private Members

std::map<Id, bool> outcomes_

std::uint32_t qubits_ = 0

std::size_t calls_ = 0

struct OperationEvent

#include <control_protocol.hpp>

Public Members

Epoch epoch = 0

Id id = 0

Id instruction = 0

Id label = 0

std::uint32_t source_port = 0

std::uint32_t codeword = 0

EventSpec action

std::optional<MeasurementReference> reference

std::optional<std::uint32_t> core = {}

struct Profile

#include <profile.hpp>

Public Functions

void validate() const

const Mapping &mapping(std::uint32_t port, std::uint32_t codeword) const

const TwoQubitGate &gate(const std::string &name) const

std::string fingerprint() const

Public Members

Clock cpu = {5, 0}

Clock tcu = {20, 0}

Tick start = 1000

Tick watchdog = 1000000

std::uint32_t memory_latency = 1

std::uint32_t command_latency = 1

std::uint32_t reply_latency = 1

std::uint32_t cpu_result_latency = 1

std::uint32_t fast_result_latency = 2

std::uint32_t timing_capacity = 32

std::uint32_t event_capacity = 32

std::uint32_t staging_capacity = 16

std::uint32_t result_capacity = 8

std::uint32_t ports = 8

std::uint32_t qubits = 2

std::uint32_t firing_width = 1

std::uint32_t seed = 1

bool fast_feedback = true

std::vector<Mapping> mappings

std::vector<TwoQubitGate> two_qubit_gates

class ProgramImage

#include <image.hpp>

Public Functions

ProgramImage(std::uint32_t base, std::uint32_t size)

inline std::uint32_t entry() const

inline std::uint32_t base() const

inline std::span<const std::uint8_t> bytes() const

inline const std::vector<Segment> &segments() const

std::uint32_t read(std::uint32_t address, std::uint8_t width, bool instruction = false) const

void write(std::uint32_t address, std::uint8_t width, std::uint32_t value)

Public Static Functions

static ProgramImage elf(std::span<const std::uint8_t> file, std::uint32_t base, std::uint32_t size)

static ProgramImage raw(std::span<const std::uint8_t> file, std::uint32_t address, std::uint32_t base, std::uint32_t size)

Private Functions

std::size_t offset(std::uint32_t address, std::uint8_t width, bool store, bool instruction) const

Private Members

std::uint32_t base_

std::uint32_t entry_ = 0

std::vector<std::uint8_t> bytes_

std::vector<Segment> segments_

struct PulseSpec

#include <event.hpp>

Public Functions

bool operator==(const PulseSpec&) const = default

Public Members

std::string operation = "x"

QuantumOperands operands

double amplitude = 0.0

std::string axis = "x"

ExecutionFlag execution_flag = ExecutionFlag::Always

class PythonBackend : public qsbit::IQuantumBackend

#include <python_backend.hpp>

Public Functions

explicit PythonBackend(const PythonBackendConfig &config)

std::string options() const

~PythonBackend() override

virtual void validate(const EventSpec &action) const override

virtual void reset(std::uint32_t qubits, std::uint32_t seed) override

virtual std::vector<bool> execute(Epoch epoch, std::span<const BackendOperation> operations) override

virtual std::vector<std::complex<double>> state() const override

virtual std::vector<std::vector<std::complex<double>>> density_matrix() const override

Public Static Functions

static std::string inspect(const std::string &name, const std::string &command)

static void run_simulation(const std::string &config, const std::string &executable, bool check_only = false)

Private Members

std::unique_ptr<Impl> impl_

struct PythonBackendConfig

#include <python_backend.hpp>

Public Members

std::string name

std::string options = "{}"

class PythonSession

#include <python_backend.hpp>

Public Functions

explicit PythonSession(const std::string &module_directory)

~PythonSession()

std::string backend_directory() const

PythonSession(const PythonSession&) = delete

PythonSession &operator=(const PythonSession&) = delete

Private Members

std::unique_ptr<Impl> impl_

struct QuantumOperands

#include <event.hpp>

Public Functions

bool operator==(const QuantumOperands&) const = default

Public Members

std::vector<std::uint32_t> targets

std::vector<ResourceUse> resources

struct Readout

#include <readouts.hpp>

Public Members

MeasurementReference reference

Tick end = 0

Tick arm = 0

Tick ready = 0

std::optional<bool> sample

std::optional<std::uint32_t> core = {}

class Readouts

#include <readouts.hpp>

Public Functions

std::vector<Readout> prepare(std::span<const ScheduledEvent> actions, Epoch epoch) const

void insert(std::span<const Readout> readouts)

void sample(Id measurement, bool value)

const Readout &at(Id measurement) const

Completion result(Id measurement) const

inline void erase(Id measurement)

inline void reset()

inline bool empty() const

Private Members

std::map<Id, Readout> pending_

class ResourceReservations

#include <resources.hpp>

Public Functions

void check(std::span<const ScheduledEvent> actions) const

void reserve(std::span<const ScheduledEvent> actions)

void discard_before(Tick now)

inline void reset()

inline const std::vector<ScheduledEvent> &reservations() const

Private Members

std::vector<ScheduledEvent> reservations_

Private Static Functions

static void pair(const ScheduledEvent &a, const ScheduledEvent &b)

struct ResourceUse

#include <event.hpp>

Public Functions

bool operator==(const ResourceUse&) const = default

Public Members

std::uint32_t id = 0

bool exclusive = true

struct RuntimeLayout

#include <runtime.hpp>

Public Members

bool installed = false

bool python_enabled = false

std::filesystem::path web_root

std::filesystem::path python

std::filesystem::path backend

std::string version

std::string revision

struct ScheduledEvent

#include <control_protocol.hpp>

Public Members

OperationEvent event

Tick start = 0

Tick end = 0

EventSpec resolved

struct Segment

#include <image.hpp>

Public Members

std::uint32_t address = 0

std::uint32_t size = 0

bool readable = false

bool writable = false

bool executable = false

class Simulator : public sc_core::sc_module

#include <simulator.hpp>

Public Types

using CpuFactory = Core::CpuFactory

Public Functions

Simulator(sc_core::sc_module_name name, Profile profile, ProgramImage image, std::unique_ptr<IQuantumBackend> backend, std::vector<Tick> resets = {}, bool reverse_registration = false, CpuFactory cpu_factory = {}, BackendExecutionConfig execution = {}, DecoderSystemConfig decoding = {})

Simulator(sc_core::sc_module_name name, std::vector<CoreConfig> cores, std::vector<SyncConnection> connections, std::unique_ptr<IQuantumBackend> backend, std::vector<Tick> resets = {}, bool reverse_registration = false, BackendExecutionConfig execution = {}, DecoderSystemConfig decoding = {})

inline const Trace &trace() const

inline void include_stalls(bool enabled)

inline const Core &core(std::size_t index) const

inline std::size_t core_count() const

inline const ICpuCycleModel &cpu() const

inline const ProgramImage &memory() const

inline const MeasurementRegisters &measurement_registers() const

inline BackendExecution &backend()

inline bool success() const

inline const std::optional<ErrorCode> &fault() const

inline const std::string &fault_message() const

inline const Profile &profile() const

Private Functions

void cpu_edge()

void memory_edge()

void tcu_edge()

void wakeup()

void barrier()

bool reset_at(Tick now)

void schedule_wakeup()

void fail(const Fault &fault)

TriggeredEvents device_events(const TriggeredEvents &batch, std::size_t index) const

Private Members

const Profile profile_

Trace trace_

DecoderSystem decoders_

std::unique_ptr<IQuantumBackend> backend_

SyncNetwork network_

std::vector<std::unique_ptr<Core>> cores_

std::vector<std::uint32_t> port_offsets_

ControlElectronics device_

std::vector<std::unique_ptr<sc_core::sc_clock>> cpu_clocks_

sc_core::sc_clock tcu_clock_

sc_core::sc_event wake_

sc_core::sc_event barrier_

std::optional<Tick> cpu_done_

std::optional<Tick> memory_done_

std::optional<Tick> tcu_done_

std::optional<Tick> last_reset_

std::vector<Tick> resets_

Epoch epoch_ = 1

bool reverse_ = false

bool stopped_ = false

bool success_ = false

std::optional<ErrorCode> fault_

std::string fault_message_

struct SyncConnection

#include <sync.hpp>

Public Members

std::uint32_t first = 0

std::uint32_t second = 0

Tick first_to_second = 1

Tick second_to_first = 1

std::size_t capacity = 8

struct SynchronizeCommand

#include <control_command.hpp>

Public Functions

bool operator==(const SynchronizeCommand&) const = default

Public Members

std::uint32_t target

class SyncNetwork

#include <sync.hpp>

Public Functions

SyncNetwork(Clock clock, std::span<const SyncConnection> connections)

Tick delay(std::uint32_t source, std::uint32_t target) const

void preflight(std::uint32_t source, std::uint32_t target, Tick now)

void send(std::uint32_t source, std::uint32_t target, Tick now)

std::optional<Tick> receive(std::uint32_t source, std::uint32_t target, Tick now)

bool empty() const

void reset()

Private Members

Clock clock_

std::map<std::pair<std::uint32_t, std::uint32_t>, Link> links_

struct Link

Public Members

Tick delay

std::size_t capacity

std::deque<Signal> signals

struct Signal

Public Members

Tick arrival

std::optional<Tick> consumed

class SyncUnit

#include <sync.hpp>

Public Functions

SyncUnit(std::uint32_t core, SyncNetwork &network, Trace &trace)

void validate(std::uint32_t target) const

void preflight(std::span<const std::uint32_t> targets, Tick now)

void book(std::span<const std::uint32_t> targets, Tick now, Epoch epoch)

bool step(Tick now, Epoch epoch)

inline bool drained() const

void reset()

Private Members

std::uint32_t core_

SyncNetwork &network_

Trace &trace_

std::optional<Booking> pending_

struct Booking

Public Members

std::uint32_t target

Tick deadline

bool received = false

struct TcuConfig

#include <timing_config.hpp>

Public Members

TimingConfig timing

Clock clock

Tick start

std::uint32_t timing_capacity

struct TcuCycle

#include <time.hpp>

Public Functions

auto operator<=>(const TcuCycle&) const = default

Public Members

std::uint64_t value = 0

class TcuCycleModel

#include <tcu.hpp>

Public Types

using Preflight = std::function<void(const TriggeredEvents&)>

using SyncPreflight = std::function<void(std::span<const std::uint32_t>)>

Public Functions

TcuCycleModel(TcuConfig profile, Trace &trace, std::size_t sync_capacity = 8)

TcuOutput step(Tick now, Epoch epoch, const TimingEvents *candidate, const std::vector<Completion> &results, const Preflight &preflight, bool synchronization_paused = false, const SyncPreflight &sync_preflight = {})

void close(const EndOfStream &end)

void reset(Tick epoch_origin = 0)

bool drained() const

inline std::size_t timing_size() const

inline std::size_t port_size(std::uint32_t port) const

inline Id last_label() const

inline TcuCycle last_due() const

inline const ExecutionFlags &execution_flags() const

Private Functions

TimingState current_timing_state(Tick now, bool synchronization_paused) const

bool meets_deadline(Tick now, Tick due_tick, const PauseState &pause) const

std::optional<Trigger> prepare_trigger(Tick now, Epoch epoch, const TimingState &state, const Preflight &preflight, const SyncPreflight &sync_preflight) const

std::optional<TcuCycle> prepare_admission(Tick now, Epoch epoch, const TimingEvents &candidate, const PauseState &pause) const

void commit_trigger(Tick now, Epoch epoch, TcuCycle cycle, const Trigger &trigger)

void commit_admission(Tick now, Epoch epoch, TcuCycle cycle, const TimingEvents &candidate, TcuCycle due)

void commit_fast_results(Tick now, Epoch epoch, TcuCycle cycle, const std::vector<Completion> &results, ExecutionFlags next_flags, TcuOutput &output)

void update_pause_state(Tick now, Epoch epoch, const TimingState &state, Tick paused_ticks)

Private Members

const TcuConfig profile_

Trace &trace_

std::deque<Point> timing_

std::vector<std::deque<OperationEvent>> events_

ExecutionFlags execution_flags_

TcuCycle last_due_

Tick start_ = 0

Tick paused_ticks_ = 0

std::size_t sync_capacity_ = 8

std::size_t sync_size_ = 0

Id last_label_ = 0

bool closed_ = false

UnderflowPolicy admitted_policy_ = UnderflowPolicy::Strict

UnderflowPolicy triggered_policy_ = UnderflowPolicy::Strict

PauseState pause_

Private Static Functions

static UnderflowPolicy policy_after(const TimingPoint &point, UnderflowPolicy previous)

struct PauseState

Public Functions

inline bool paused() const

Public Members

bool instruction_supply = false

bool synchronization = false

struct Point

Public Members

TimingPoint point

TcuCycle due

struct TimingState

Public Members

bool running

TcuCycle cycle

PauseState pause

struct Trigger

Public Members

TriggeredEvents batch

std::vector<OperationEvent> cancelled

std::vector<std::uint32_t> synchronizations

struct TcuOutput

#include <tcu.hpp>

Public Members

bool admitted = false

std::optional<TriggeredEvents> launch

std::vector<MeasurementReference> fast_delivered

std::vector<std::uint32_t> synchronizations

struct TimingConfig

#include <timing_config.hpp>

Public Functions

const Mapping &mapping(std::uint32_t port, std::uint32_t codeword) const

Public Members

std::uint32_t event_capacity

std::uint32_t staging_capacity

std::uint32_t ports

std::uint32_t qubits

std::uint32_t firing_width

bool fast_feedback

std::string configuration

std::map<std::pair<std::uint32_t, std::uint32_t>, Mapping> mappings

class TimingControl

#include <timing_control.hpp>

Public Types

using ValidateAction = std::function<void(const EventSpec&)>

using ValidateSync = std::function<void(std::uint32_t)>

Public Functions

TimingControl(TimingConfig profile, MeasurementRegisters &registers, Trace &trace, ValidateAction validate, ValidateSync validate_sync = {})

void receive(Tick now, Epoch epoch, ControlLinks &links)

std::optional<std::uint32_t> execute(const ControlOperation &operation, Tick now, Epoch epoch, ControlLinks &links)

void reset()

inline TcuCycle time_point() const

inline bool closed() const

inline bool pending() const

Private Functions

bool enqueue(Tick now, Epoch epoch, ControlLinks &links)

std::optional<std::uint32_t> execute_zero_wait(Tick now, Epoch epoch, ControlLinks &links)

std::optional<std::uint32_t> advance_time(TcuCycle interval, Tick now, Epoch epoch, ControlLinks &links)

std::optional<std::uint32_t> codeword(const ControlOperation &operation, Tick now, Epoch epoch)

Private Members

const TimingConfig profile_

MeasurementRegisters &measurement_registers_

Trace &trace_

ValidateAction validate_

ValidateSync validate_sync_

std::vector<OperationEvent> pending_events_

std::vector<std::uint32_t> pending_sync_

std::optional<TimingEvents> enqueue_request_

std::optional<ControlOperation> held_

TcuCycle time_point_

TcuCycle last_enqueued_time_

Id last_label_ = 0

Id next_event_ = 1

bool pending_point_ = false

bool enqueued_ = false

bool closed_ = false

bool pending_wait_for_next_ = false

bool allow_same_time_ = false

struct TimingEvents

#include <control_protocol.hpp>

Public Members

TimingPoint point

std::vector<OperationEvent> events

std::string configuration

struct TimingPoint

#include <control_protocol.hpp>

Public Members

Epoch epoch = 0

Id label = 0

TcuCycle interval

std::vector<Id> manifest

std::vector<std::uint32_t> synchronizations = {}

UnderflowPolicy underflow_policy = UnderflowPolicy::Inherit

class Trace

#include <trace.hpp>

Public Functions

Trace() = default

inline Trace(Trace &destination, std::optional<std::uint32_t> core)

void emit(TraceEvent event)

inline void include_stalls(bool enabled)

inline const std::vector<TraceEvent> &events() const

void write_jsonl(std::ostream &stream) const

Private Members

std::vector<TraceEvent> events_

bool include_stalls_ = true

Trace *destination_ = nullptr

std::optional<std::uint32_t> core_

struct TraceEvent

#include <trace.hpp>

Public Functions

inline TraceEvent(Tick at, Epoch session, std::string type, Id identity = 0, Id timing_label = 0, Tick local_cycle = 0)

inline TraceEvent(Tick at, Epoch session, Tick local_cycle, CpuPipelineState state)

inline TraceEvent(Tick at, Epoch session, Id instruction, Tick local_cycle, InstructionRetired state)

TraceEvent(Tick at, Epoch session, Id request, std::uint32_t core_id, DecoderEvent event)

template<typename T>
inline const T *get_if() const

Public Members

Tick tick = 0

Epoch epoch = 0

std::string kind

Id id = 0

Id label = 0

Tick cycle = 0

std::uint32_t port = 0

std::uint32_t codeword = 0

std::vector<std::uint32_t> targets

std::string operation

std::string detail

std::uint64_t value = 0

std::optional<std::uint32_t> core

Private Members

std::variant<std::monostate, CpuPipelineState, InstructionRetired, DecoderEvent> payload_

struct TransportConfig

#include <transport_config.hpp>

Public Members

Clock cpu

Clock tcu

std::uint32_t command_latency

std::uint32_t reply_latency

std::uint32_t cpu_result_latency

std::uint32_t fast_result_latency

std::uint32_t result_capacity

struct TriggeredEvents

#include <control_protocol.hpp>

Public Members

Epoch epoch = 0

Id label = 0

Tick fire_tick = 0

std::vector<OperationEvent> events

struct TwoQubitGate

#include <event.hpp>

Public Functions

bool operator==(const TwoQubitGate&) const = default

Public Members

std::string name

std::string operation

std::vector<std::uint32_t> targets

std::vector<GateInput> inputs

std::vector<ResourceUse> resources

Tick duration = 20

class VliwCpuCycleModel : public qsbit::ICpuCycleModel

#include <vliw.hpp>

Public Functions

inline VliwCpuCycleModel(Clock clock, std::uint32_t entry, Trace &trace)

inline virtual void step(Tick now, Epoch epoch, CpuPorts &ports) override

inline virtual void reset(std::uint32_t entry) override

inline virtual const std::array<std::uint32_t, 32> &registers() const override

inline virtual std::uint32_t pc() const override

inline virtual bool halted() const override

Private Members

InOrderPipeline pipeline_

struct WaitCommand

#include <control_command.hpp>

Public Functions

bool operator==(const WaitCommand&) const = default

Public Members

std::uint32_t cycles

namespace rv32

Enums

enum class Op

Values:

enumerator Lui

enumerator Auipc

enumerator Jal

enumerator Jalr

enumerator Beq

enumerator Bne

enumerator Blt

enumerator Bge

enumerator Bltu

enumerator Bgeu

enumerator Lb

enumerator Lh

enumerator Lw

enumerator Lbu

enumerator Lhu

enumerator Sb

enumerator Sh

enumerator Sw

enumerator Addi

enumerator Slti

enumerator Sltiu

enumerator Xori

enumerator Ori

enumerator Andi

enumerator Slli

enumerator Srli

enumerator Srai

enumerator Add

enumerator Sub

enumerator Sll

enumerator Slt

enumerator Sltu

enumerator Xor

enumerator Srl

enumerator Sra

enumerator Or

enumerator And

enumerator Fence

enumerator Ecall

enumerator Ebreak

enumerator Quantum

enum class MemoryKind

Values:

enumerator None

enumerator Load

enumerator Store

Functions

Decoded decode(std::uint32_t word)

Effect evaluate(const Decoded &instruction, std::uint32_t pc, std::uint32_t lhs, std::uint32_t rhs)

std::uint32_t sign_extend(std::uint32_t value, unsigned bits)

struct Decoded

#include <isa.hpp>

Public Members

Op op

std::uint32_t word

std::uint32_t immediate = 0

std::uint8_t rd = 0

std::uint8_t rs1 = 0

std::uint8_t rs2 = 0

bool reads_rs1 = false

bool reads_rs2 = false

bool writes_rd = false

struct Effect

#include <isa.hpp>

Public Members

std::uint32_t next_pc = 0

std::uint32_t value = 0

std::uint32_t address = 0

std::uint32_t store_value = 0

bool writes_rd = false

bool branch_taken = false

bool sign_extend_load = false

MemoryKind memory = MemoryKind::None

std::uint8_t width = 0