pulse

package
v1.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 19, 2026 License: MIT Imports: 1 Imported by: 0

Documentation

Overview

Package pulse provides types for pulse-level quantum control.

Pulse programming operates at a lower level than gate-based circuits, directly controlling the analog signals sent to quantum hardware. This package implements the OpenPulse model used by AWS Braket and compatible with the OpenQASM 3.0 pulse grammar.

The three core types are Port (hardware I/O endpoint), Frame (software reference clock), and Waveform (signal envelope interface). Eight instruction types (Play, Delay, SetPhase, ShiftPhase, SetFrequency, ShiftFrequency, Barrier, Capture) compose into an immutable Program via a fluent Builder.

Timing uses float64 seconds (not time.Duration) for sub-nanosecond precision required by quantum hardware. Frames are stateless value types - phase and frequency changes are expressed as instructions.

Standard waveform shapes are provided in the [waveform] sub-package. IonQ custom pulse envelopes use a separate model; see the [ionq.PulseShapes] type in the backend/ionq package.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Barrier 

type Barrier struct {
	Frames []Frame
}

Barrier synchronizes one or more frames.

type Builder 

type Builder struct {
	// contains filtered or unexported fields
}

Builder constructs a Program using a fluent API with eager validation and error short-circuiting.

Example 
package main

import (
	"fmt"

	"github.com/splch/goqu/pulse"
	"github.com/splch/goqu/pulse/waveform"
)

func main() {
	port := pulse.MustPort("d0", 1e-9)
	frame := pulse.MustFrame("q0_drive", port, 5e9, 0)
	gauss := waveform.MustGaussian(1.0, 160e-9, 40e-9)

	prog, err := pulse.NewBuilder("x90").
		AddPort(port).
		AddFrame(frame).
		ShiftPhase(frame, 0).
		Play(frame, gauss).
		Capture(frame, 1e-6).
		Build()
	if err != nil {
		panic(err)
	}

	stats := prog.Stats()
	fmt.Printf("name=%s ports=%d frames=%d instructions=%d\n",
		prog.Name(), stats.NumPorts, stats.NumFrames, stats.NumInstructions)
}

Output:

name=x90 ports=1 frames=1 instructions=3

func NewBuilder 

func NewBuilder(name string) *Builder

NewBuilder creates a Builder for a pulse program with the given name.

func (*Builder) AddFrame 

func (b *Builder) AddFrame(f Frame) *Builder

AddFrame registers a software frame. The frame's port must have been added via [AddPort] first.

func (*Builder) AddPort 

func (b *Builder) AddPort(p Port) *Builder

AddPort registers a hardware port.

func (*Builder) Barrier 

func (b *Builder) Barrier(frames ...Frame) *Builder

Barrier appends a Barrier instruction that synchronizes the given frames.

func (*Builder) Build 

func (b *Builder) Build() (*Program, error)

Build constructs the immutable Program. Returns an error if any builder method failed or if the program has no instructions.

func (*Builder) Capture 

func (b *Builder) Capture(f Frame, duration float64) *Builder

Capture appends a Capture instruction.

func (*Builder) Delay 

func (b *Builder) Delay(f Frame, duration float64) *Builder

Delay appends a Delay instruction.

func (*Builder) Play 

func (b *Builder) Play(f Frame, wf Waveform) *Builder

Play appends a Play instruction.

func (*Builder) SetFrequency 

func (b *Builder) SetFrequency(f Frame, frequency float64) *Builder

SetFrequency appends a SetFrequency instruction.

func (*Builder) SetPhase 

func (b *Builder) SetPhase(f Frame, phase float64) *Builder

SetPhase appends a SetPhase instruction.

func (*Builder) ShiftFrequency 

func (b *Builder) ShiftFrequency(f Frame, delta float64) *Builder

ShiftFrequency appends a ShiftFrequency instruction.

func (*Builder) ShiftPhase 

func (b *Builder) ShiftPhase(f Frame, delta float64) *Builder

ShiftPhase appends a ShiftPhase instruction.

func (*Builder) WithMetadata 

func (b *Builder) WithMetadata(key, value string) *Builder

WithMetadata adds a key-value pair to the program metadata.

type Capture 

type Capture struct {
	Frame    Frame
	Duration float64 // seconds
}

Capture records the signal on a frame for the given duration.

type Delay 

type Delay struct {
	Frame    Frame
	Duration float64 // seconds
}

Delay inserts a wait on a frame.

type Frame 

type Frame struct {
	// contains filtered or unexported fields
}

Frame represents a software reference clock attached to a port. Frames are stateless value types - phase and frequency changes are expressed as SetPhase, ShiftPhase, SetFrequency, and ShiftFrequency instructions.

func MustFrame 

func MustFrame(name string, port Port, frequency, phase float64) Frame

MustFrame is like NewFrame but panics on error.

func NewFrame 

func NewFrame(name string, port Port, frequency, phase float64) (Frame, error)

NewFrame creates a Frame with the given name, port, initial frequency (Hz), and initial phase (radians).

func (Frame) Frequency 

func (f Frame) Frequency() float64

Frequency returns the initial frequency in Hz.

func (Frame) Name 

func (f Frame) Name() string

Name returns the frame identifier.

func (Frame) Phase 

func (f Frame) Phase() float64

Phase returns the initial phase in radians.

func (Frame) Port 

func (f Frame) Port() Port

Port returns the hardware port this frame is attached to.

type Instruction 

type Instruction interface {
	// contains filtered or unexported methods
}

Instruction is a sealed interface for pulse program instructions. Only the eight types defined in this package implement it.

type Play 

type Play struct {
	Frame    Frame
	Waveform Waveform
}

Play outputs a waveform on a frame.

type Port 

type Port struct {
	// contains filtered or unexported fields
}

Port represents a hardware I/O endpoint on the quantum device. dt is the minimum time resolution in seconds.

func MustPort 

func MustPort(name string, dt float64) Port

MustPort is like NewPort but panics on error.

func NewPort 

func NewPort(name string, dt float64) (Port, error)

NewPort creates a Port with the given name and time resolution.

func (Port) Dt 

func (p Port) Dt() float64

Dt returns the minimum time resolution in seconds.

func (Port) Name 

func (p Port) Name() string

Name returns the port identifier.

type Program 

type Program struct {
	// contains filtered or unexported fields
}

Program is an immutable pulse schedule consisting of ports, frames, and a sequence of instructions. Construct programs using Builder.

func NewProgram 

func NewProgram(name string, ports []Port, frames []Frame, instrs []Instruction, metadata map[string]string) *Program

NewProgram creates an immutable Program. All slices and maps are defensively copied. Prefer the Builder for validated construction.

func (*Program) Frames 

func (p *Program) Frames() []Frame

Frames returns a copy of the registered frames.

func (*Program) Instructions 

func (p *Program) Instructions() []Instruction

Instructions returns a copy of the instruction sequence.

func (*Program) Metadata 

func (p *Program) Metadata() map[string]string

Metadata returns a copy of the key-value metadata.

func (*Program) Name 

func (p *Program) Name() string

Name returns the program identifier.

func (*Program) Ports 

func (p *Program) Ports() []Port

Ports returns a copy of the registered ports.

func (*Program) Stats 

func (p *Program) Stats() ProgramStats

Stats returns summary statistics for the program.

func (*Program) String 

func (p *Program) String() string

String returns a summary of the program.

type ProgramStats 

type ProgramStats struct {
	NumPorts        int
	NumFrames       int
	NumInstructions int
	TotalDuration   float64 // seconds (sum of play/delay/capture durations)
}

ProgramStats holds summary statistics for a pulse program.

type SetFrequency 

type SetFrequency struct {
	Frame     Frame
	Frequency float64
}

SetFrequency sets the absolute frequency of a frame (Hz).

type SetPhase 

type SetPhase struct {
	Frame Frame
	Phase float64
}

SetPhase sets the absolute phase of a frame (radians).

type ShiftFrequency 

type ShiftFrequency struct {
	Frame Frame
	Delta float64
}

ShiftFrequency adds a relative frequency offset to a frame (Hz).

type ShiftPhase 

type ShiftPhase struct {
	Frame Frame
	Delta float64
}

ShiftPhase adds a relative phase offset to a frame (radians).

type Waveform 

type Waveform interface {
	// Name returns the waveform identifier (e.g., "gaussian(0.5, 1e-8, 2.5e-9)").
	Name() string

	// Duration returns the total waveform duration in seconds.
	Duration() float64

	// Sample returns the waveform envelope sampled at the given time
	// resolution dt (seconds). The returned slice length is ceil(Duration/dt).
	Sample(dt float64) []complex128
}

Waveform defines a signal envelope that can be played on a frame. Standard waveforms are provided in the waveform sub-package.

Source Files

View all Source files

Directories

Path Synopsis
Package defcal maps gate-level circuits to pulse programs via calibration tables.
 Package defcal maps gate-level circuits to pulse programs via calibration tables.
Package qasmparse parses OpenQASM 3.0 with OpenPulse cal {} blocks into pulse.Program objects.
 Package qasmparse parses OpenQASM 3.0 with OpenPulse cal {} blocks into pulse.Program objects.
Package waveform provides standard pulse envelope shapes for the pulse package.
 Package waveform provides standard pulse envelope shapes for the pulse package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.