Concepts and architecture

ParaQeet is organized as a stack of layers. Each layer interacts only with the layer above it in the hierarchy, which keeps the codebase modular: you can swap a pulse parametrization, a propagator, or an optimizer without touching the rest of the setup. The codebase follows the modular structure shown below:

The modules

Signal (paraqeet.signal)

Pulse parametrizations. Envelope shapes such as GaussEnvelope or DCRABEnvelope are combined by generators like the IQMixer (envelope mixed with a local oscillator) or the PWCGenerator (piecewise-constant bins for GRAPE) into the control signal seen by the system.

Hamiltonian (paraqeet.hamiltonian)

The physical system: Hamiltonians for qubits, transmons, and resonators, couplings and drives, composed with CompositeHamiltonian. Define your own Hamiltonian by following the Hamiltonian class structure.

Equation of motion (EOM) (paraqeet.eom)

The eom layer turns a Hamiltonian into an equation of motion — the SchroedingerEquation for closed systems or the Lindblad MasterEquation for open systems.

Propagation (paraqeet.propagation)

Solvers of the equation of motion, from piecewise matrix exponentials (Expm) to Euler, Runge-Kutta and Verner ODE integrators. Gradients come from wrapping any of them in GOAT, GRAPE or AutoDiffGradients, which add analytic or automatically differentiated gradients to the propagation they wrap.

Measurement (paraqeet.measurement)

Goal functions: state transfer and unitary fidelities, the Makhlin functional, pulse smoothness, and weighted sums of goals. A measurement reduces a propagated state to the scalar that the optimizer minimizes.

Optimizers (paraqeet.optimizers)

Gradient-based (ScipyOptimizerGradient) and gradient-free (CMA-ES, Bayesian) algorithms, including a gradient-based dCRAB optimizer.

Parameters: Quantity and OptimizationMap

Fundamental classes that connect the various modules across the package:

• A Quantity represents every tunable value — amplitude, frequency, coupling strength — together with its bounds and unit. Internally it is stored on a normalized scale, so optimizers always work on well-conditioned values regardless of physical magnitude. Quantities can be derived from other quantities via relations and update automatically.

• An Optimizable class that represents classes that contain parameters that can be optimized. In case an Optimizable class is also Differentiable it also provides gradients with repspect to its own parameters.

• An OptimizationMap collects which quantities from Optimizable classes that are optimized in a given run. This makes the choice of optimization variables explicit and independent of the model definition: the same setup can optimize two parameters or twenty.

Choosing an optimization method

Method	Pulse parametrization	Gradients	Example
GOAT	Analytic envelopes (Gaussian, flat-top, …)	Analytic, exact	Single spin Part 2: Gradient descent gate optimization
GRAPE	Piecewise-constant bins	Analytic, exact	GRAPE on a single spin
GOAToverGRAPE	Analytic envelopes, propagated piecewise	Chain rule of GOAT through GRAPE	Single qubit gate optimization using GOAT over GRAPE
Gradient-free	Any	None (CMA-ES, Bayesian)	Single spin: Bayesian optimization of a gate

As a rule of thumb: use GOAT when a few physical pulse parameters should stay interpretable, GRAPE when you want maximum pulse flexibility per time bin, and GOAToverGRAPE when you want smooth analytic pulses with the propagation efficiency of GRAPE. Gradient-free methods are a fallback for measures without gradients, e.g. when optimizing directly against an experiment.

Refer to the example gallery for examples on all of the above.