Interfacing to Python environment
The python interface eases the use of the C++ Quandary code, and adds additional functionality:
- Automatic estimation of the required time-step size based on eigenvalue decomposition of the system Hamiltonian
- Automatic computation of carrier frequencies based on system transition frequencies (Hamiltonian eigenvalue differences)
- Simulate and optimize with custom system and control Hamiltonian operators, other than the default model for superconducting quantum devices defined in User Guide.
All interface functions are defined in ./quandary.py, which defines the Quandary dataclass that gathers all configuration options and sets default values. Default values are overwritten by user input either through the constructor call through Quandary(<membervar>=<value>) directly, or by accessing the member variables after construction and calling update() afterwards. A good place to get started is to look at the example example_swap02.py, or jump start with the Jupyter Notebook Tutorial
Under the hood, the python interface dumps all configuration options to file and evokes (multiple) subprocesses that execute the C++ code on this configuration file. The C++ output files are loaded back into the python interpreter. It is therefore recommended to utilize the python interface only for smaller system sizes (fewer qubits), and switch to operate the C++ code directly when larger systems are considered (e.g. when parallel linear algebra is required.)
Custom Hamiltonian models
To enable custom Hamiltonians, pass the option standardmodel=False to the Quandary object and provide the complex-valued system Hamiltonian \(H_d\) with Hsys=<yourSystemHamiltonian> as well as the real and imaginary parts of the custom control Hamiltonians per oscillator with Hc_real=[<HcReal oscillator1, HcReal oscillator2, ...] (will be multiplied by controls \(p^k(t)\)) Hc_imag=[<HcImag oscillator1, HcImag oscillator2, ...] (will be multiplied by controls \(iq^k(t)\)).
- The units of the system Hamiltonian should be angular frequency (multiply \(2\pi\)), whereas the control Hamiltonian operators should be 'unit-free', since those units come in through the multiplied control pulses \(p\) and \(q\).
- The control Hamiltonian operators are optional, but the system Hamiltonian is always required if
standardmodel=False. - The matrix-free solver can not be used when custom Hamiltonians are provided. The code will therefore be slower.
Summary of all python interface options
Here is a list of all options available to the python interface, including their default values. Use help(Quandary) to get additional information on available interface functions, such as quandary.simulate(...), quandary.optimize(...).
This class collects configuration options to run quandary and sets all defaults. Each parameter can be overwritten within the constructor. The number of time-steps required to resolve the time-domain, as well as the resonant carrier wave frequencies are computed within the constructor. If you attempt to change options of the configuration *after* construction by accessing them directly (e.g. myconfig.fieldname = mynewsetting), it is therefore advised to call myconfig.update() afterwards to recompute the number of time-steps and carrier waves.
Environment Variables:
--------------------
QUANDARY_BASE_DATADIR : Base directory for output files. If set, all output will be written to this directory
instead of the current working directory. Relative paths provided to methods will be
considered relative to this base directory.
Parameters
----------
# Quantum system specifications
Ne # Number of essential energy levels per qubit. Default: [3]
Ng # Number of extra guard levels per qubit. Default: [0] (no guard levels)
freq01 # 01-transition frequencies [GHz] per qubit. Default: [4.10595]
selfkerr # Anharmonicities [GHz] per qubit. Default: [0.2198]
rotfreq # Frequency of rotations for computational frame [GHz] per qubit. Default: freq01
Jkl # Dipole-dipole coupling strength [GHz]. Formated list [J01, J02, ..., J12, J13, ...] Default: 0
crosskerr # ZZ coupling strength [GHz]. Formated list [g01, g02, ..., g12, g13, ...] Default: 0
T1 # Optional: T1-Decay time [ns] per qubit (invokes Lindblad solver). Default: 0
T2 # Optional: T2-Dephasing time [ns] per qubit (invokes Lindblad solver). Default: 0
# Optional: User-defined system and control Hamiltonian operators. Default: Superconducting Hamiltonian model
Hsys # Optional: User specified system Hamiltonian model. Array.
Hc_re # Optional: User specified control Hamiltonian operators for each qubit (real-parts). List of Arrays
Hc_im # Optional: User specified control Hamiltonian operators for each qubit (real-parts) List of Arrays
standardmodel # Internal: Bool to use standard Hamiltonian model for superconduction qubits. Default: True
# Time duration and discretization options
T # Pulse duration (simulation time). Default: 100ns
Pmin # Number of discretization points to resolve the shortest period of the dynamics (determines <nsteps>). Default: 150
nsteps # Number of time-discretization points (will be computed internally based on Pmin, or can be set here)
timestepper # Time-discretization scheme. Default: "IMR"
# Optimization targets and initial states options
targetgate # Complex target unitary in the essential level dimensions for gate optimization. Default: none
targetstate # Complex target state vector for state-to-state optimization. Default: none
initialcondition # Choose from provided initial states at time t=0.0: "basis" (all basis states, default), "pure, 0,0,1,..." (one pure initial state |001...>), or pass a vector as initial state. Default: "basis"
gate_rot_freq # Specify frequencies to rotate a target gate (one per oscillator). Default: no rotation (0.0 for each oscillator)
# Control pulse options
pcof0 # Optional: Pass an initial vector of control parameters. Default: none
pcof0_filename # Optional: Load initial control parameter vector from a file. Default: none
randomize_init_ctrl # Randomize the initial control parameters (will be ignored if pcof0 or pcof0_filename are given). Default: True
initctrl_MHz # Amplitude [MHz] of initial control parameters. Float or List[float]. Default: 10 MHz.
maxctrl_MHz # Amplitude bounds for the control pulses [MHz]. Float or List[float]. Default: none
control_enforce_BC # Bool to let control pulses start and end at zero. Default: False
spline_knot_spacing # Spacing of Bspline basis functions [ns]. The smaller this is, the larger the number of splines. Default: 3ns
nsplines # Number of Bspline basis functions. Default: T/spline_knot_spacing + 2
spline_order # Order of the B-spline basis (0 or 2). Default: 2
carrier_frequency # Carrier frequencies for each oscillator. List[List[float]]. Default will be computed based on Hsys.
cw_amp_thres # Threshold to ignore carrier wave frequencies whose growth rate is below this value. Default: 1e-7
cw_prox_thres # Threshold to distinguish different carrier wave frequencies from each other. Default: 1e-2
# Optimization options
maxiter # Maximum number of optimization iterations. Default 200
tol_infidelity # Optimization stopping criterion based on the infidelity. Default 1e-5
tol_costfunc # Optimization stopping criterion based on the objective function value. Default 1e-4
costfunction # Cost function measure: "Jtrace" or "Jfrobenius". Default: "Jtrace"
optim_target # Optional: Set other optimization target string, if not specified through the targetgate or targetstate.
gamma_tik0 # Parameter for Tikhonov regularization ||alpha||^2. Default 1e-4
gamma_tik0_interpolate # Switch to use ||alpha-alpha_0||^2 instead, where alpha_0 is the initial guess. Default: False
gamma_leakage # Parameter for leakage prevention. Default: 0.1
gamma_energy # Parameter for integral penality term on the control pulse energy. Default: 0.1
gamma_dpdm # Parameter for integral penality term on second state derivative. Default: 0.01
gamma_variation # Parameter for penality term on variations in the control parameters: Default: 0.01
# General options
rand_seed # Set a fixed random number generator seed. Default: None (non-reproducable)
print_frequency_iter # Output frequency for optimization iterations. (Print every <x> iterations). Default: 1
usematfree # Switch to use matrix-free (rather than sparse-matrix) solver. Default: True
verbose # Switch to turn on more screen output for debugging. Default: False
Internal variables.
-------------------
_ninit : int # number of initial conditions that are propagated
_lindblad_solver : bool # Flag to determine whether lindblad solver vs schroedinger solver
_hamiltonian_filename_Hsys : str
_hamiltonian_filename_Hc : str
_gatefilename : str
_initstatefilename : str
_initialstate : List[complex] = field(default_factory=list)
Output parameters, available after Quandary has been executed (simulate or optimze)
-----------------------------------------------------
popt # Optimized control palamters (Bspline coefficients). List[float]
time # Vector of discretized time points. List[float]
optim_hist # Optimization history: all fields as in Quandary's output file optim_history.dat. Dictionary.