QuEra Computing · Rust · v0.1

vihaco

A virtual ISA and machine framework for orchestrating hybrid analog/digital quantum control. Define instruction sets, components, effects, and parsers as ordinary Rust — then compose them into a machine.

Quick Start Tutorials API Reference

Source: QuEraComputing/vihaco

counter.rs

use eyre::Result;
use vihaco::{component, dispatch, Effects, Message};

// Bytecode-visible operations. Each variant becomes an opcode; tuple fields
// become the payload bytes that follow it.
component! {
    #[derive(Debug, Default)]
    pub component Counter {
        value: i64,
    }

    instruction {
        Add(i64),
        Print,
    }
}

use counter::runtime::Instruction as CounterInst;

/// Resolved execution input — supplied by the runtime, not encoded in
/// the instruction stream.
#[derive(Debug, Clone, Message)]
pub struct Prefix(pub String);

/// A value the component returns for the runtime or observers to consume.
#[derive(Debug, Clone, PartialEq)]
pub struct Line(pub String);

// One `execute` per component: (instruction, message) in, effects out.
#[dispatch(instruction = counter::runtime::Instruction, message = Prefix, effect = Line)]
impl counter::Counter {
    fn execute(&mut self, inst: &CounterInst, msg: Prefix) -> Result<Effects<Line>> {
        match inst {
            CounterInst::Add(v) => {
                self.value += v;
                Ok(Effects::none())
            }
            CounterInst::Print => Ok(Effects::one(Line(format!("{}{}", msg.0, self.value)))),
        }
    }
}

A component takes a typed instruction and resolved message, then returns typed effects. The derives handle opcodes and runtime glue.

use eyre::Result;
use vihaco::{Effects, observe};

#[derive(Debug, Clone)]
pub struct Line(pub String);

/// A standalone observer: it reacts to delivered effects and owns no
/// instructions or messages of its own.
#[derive(Debug, Default)]
pub struct Collector {
    lines: Vec<String>,
}

// `#[observe(T)]` generates `Observe<T>`; the handler is named
// `observe_<snake_case_effect>` and may return follow-up effects.
#[observe(Line)]
impl Collector {
    fn observe_line(&mut self, effect: &Line) -> Result<Effects<()>> {
        self.lines.push(effect.0.clone());
        Ok(Effects::none())
    }
}

Execution and effect delivery are separate. An observer reacts to an effect type and can produce follow-up effects.

§ 1 Explore

What vihaco is for

i. Instruction setsBytecode as Rust enums

#[derive(Instruction)] turns an enum into an opcode set with inferred or fixed encoding width. Nest enums to compose several component instruction families under one machine type.

ii. Components & effectsExecute, then observe

Components consume a resolved Message and return typed Effects. Observers react to those effects with #[observe], keeping execution and delivery separate.

iii. Pattern-derived syntaxFrom source text to module

#[derive(Parse)] generates a parser for instruction syntax from declarative, compile-time-checked patterns. Module parsing produces typed function bodies for the resolver.

§ 2 Install

Add vihaco

[dependencies]
vihaco        = { git = "https://github.com/QuEraComputing/vihaco" }
vihaco-cpu    = { git = "https://github.com/QuEraComputing/vihaco" }
vihaco-parser = { git = "https://github.com/QuEraComputing/vihaco" }

Vihaco is a Cargo workspace of focused crates with no published release or umbrella crate yet. Add the ones you need from the git repository; Rust edition 2024 is required.

Quick Start, Tutorials or API Reference