Optimization Parameters

Ctrl-freeq employs a JSON-based configuration schema that is shared between the programmatic API and the graphical user interface. This section provides a complete reference for all configurable parameters, organized by category.

Configuration Schema

The top-level structure of a configuration is as follows:

{
  "qubits": ["q1", "q2"],
  "hamiltonian_type": "spin_chain",
  "compute_resource": "cpu",
  "parameters": { ... },
  "initial_states": [["Z", "Z"]],
  "target_states": { ... },
  "optimization": { ... }
}

Field	Description
`qubits`	List of qubit identifiers for display and indexing
`hamiltonian_type`	Selects the physical platform via the model registry (see Hamiltonian Models)
`compute_resource`	`"cpu"` or `"gpu"` (see Compute)

Backward Compatibility

The hamiltonian_type field is optional. When omitted, the legacy spin-chain code path is used, ensuring backward compatibility with existing configuration files. Built-in values are "spin_chain" and "superconducting". Custom models registered with @register_hamiltonian("name") can also be referenced here.

System Parameters

The system parameters define the physical properties of the quantum system under consideration. All values are specified as per-qubit arrays, with one entry for each qubit in the configuration. The interpretation and GUI labelling of these parameters depends on the selected Hamiltonian type.

Spin Chain

Key	GUI Label	Description	Default	Units
`Delta`	Δ (Hz)	Detuning frequency (chemical shift)	10 MHz	Hz
`sigma_Delta`	σΔ (Hz)	Detuning uncertainty (for robustness)	0	Hz
`Omega_R_max`	Ω_R Max (Hz)	Maximum Rabi frequency	40 MHz	Hz
`sigma_Omega_R_max`	σΩ_R Max (Hz)	Rabi frequency uncertainty	0	Hz

Superconducting

Key	GUI Label	Description	Default	Units
`Delta`	ω (Hz)	Qubit transition frequency	10 MHz	Hz
`sigma_Delta`	σω (Hz)	Frequency uncertainty (for robustness)	0	Hz
`Omega_R_max`	Ω_d Max (Hz)	Maximum drive amplitude	40 MHz	Hz
`sigma_Omega_R_max`	σΩ_d Max (Hz)	Drive amplitude uncertainty	0	Hz

Shared Configuration Keys

Both platforms use the same JSON keys (Delta, sigma_Delta, Omega_R_max, sigma_Omega_R_max) for cross-platform compatibility. The GUI relabels these fields to match the physical conventions of the selected platform (Δ vs ω, Ω_R vs Ω_d).

Pulse Parameters

The pulse parameters control the temporal characteristics of the control waveform, including its duration, discretization, and frequency properties. As with the system parameters, all values are per-qubit arrays.

Key	GUI Label	Description	Default	Units
`pulse_duration`	Pulse Duration (sec)	Total pulse length	200 ns	seconds
`point_in_pulse`	Point in Pulse	Time discretization points	100	—
`sw`	Sweep Rate (Hz)	Frequency sweep rate	5 MHz	Hz
`pulse_offset`	Pulse Offset (Hz)	Frequency offset	0	Hz
`pulse_bandwidth`	Pulse Bandwidth (Hz)	Selective band width — FWHM of the target rotation-angle profile	500 kHz	Hz

Waveform Settings

The waveform settings determine the basis functions and envelope used to parameterize the control pulse. The choice of basis and mode has a significant influence on the smoothness, bandwidth, and convergence properties of the optimized waveform. All values are per-qubit arrays.

Key	GUI Label	Options	Default	Description
`wf_type`	Waveform Type	See below	`cheb`	Basis function type
`wf_mode`	Waveform Mode	`cart`, `polar`, `polar_phase`	`cart`	Cartesian or polar representation
`amplitude_envelope`	Amplitude Envelope	`gn`, `hs`, `quad`	`gn`	Pulse envelope shape (super-Gaussian, hyperbolic secant, quadratic)
`amplitude_order`	Amplitude Order	Integer	1	Envelope order parameter
`coverage`	Coverage	`single`, `broadband`, `selective`, `band_selective`	`single`	Frequency coverage mode
`profile_order`	Profile Order	Integer	2	Supergaussian order for selectivity profile (1 = Gaussian, higher values → more rectangular)
`n_para`	Number of Parameters	Integer	16	Optimization parameters per qubit

Waveform Types

Several families of orthogonal basis functions are available for the parameterization of the control waveform:

cheb — Chebyshev polynomial basis (recommended for most applications due to favourable convergence properties)
fou — Fourier series basis
poly — Standard polynomial basis
leg — Legendre polynomial basis
hermite — Hermite polynomial basis
gegen — Gegenbauer polynomial basis
chirp — Chirp basis

Waveform Modes

The waveform representation may be specified in one of three modes:

cart — Cartesian mode, in which the in-phase (I) and quadrature (Q) components are optimized independently
polar — Polar mode, in which the amplitude and phase are optimized directly
polar_phase — Polar phase mode, in which only the phase is optimized while the amplitude profile remains fixed

Coverage Modes

single — one nominal offset per qubit, optionally with Gaussian uncertainty
broadband — offsets drawn uniformly across the sweep width sw
selective — a hard in-band / out-of-band split. Qubits inside their band are driven to the target; qubits outside it must be left where they started. Each qubit's samples are drawn independently, so the ensemble contains mixed in-band/out-of-band combinations.
band_selective — a smooth target rotation-angle profile,

[ p(\Delta) = \exp!\left[-\ln 2 \left(\frac{2\,|\Delta - \Delta_0|}{\text{bw}}\right)^{2p}\right] ]

where bw is pulse_bandwidth and \(p\) is profile_order.

pulse_bandwidth is the FWHM of this target profile: it equals 1 at the band centre and exactly 1/2 at \(\Delta_0 \pm \text{bw}/2\), for every order. It is not a guarantee that the achieved excitation curve of the optimised pulse has that width.

band_selective requires a rotation-angle target

band_selective coverage is rejected with Axis or Gate targets: a smooth profile has no all-or-nothing interpretation for a discrete target, and nearly every drawn offset would silently be handed the identity. Use selective coverage for hard in-band/out-of-band targets, or a Phi/Beta target, which scales smoothly with the profile. See Objectives and Fidelity.

Dissipation Parameters

For the simulation of open quantum systems, ctrl-freeq supports dissipative dynamics via the Lindblad master equation. When dissipation is enabled, the evolution includes amplitude damping (characterised by the longitudinal relaxation time T1) and pure dephasing (characterised by the transverse relaxation time T2) for each qubit. All values are per-qubit arrays, with one entry for each qubit in the configuration.

Key	GUI Label	Description	Default	Units
`T1`	T1 (s)	Amplitude damping time constant (energy relaxation)	—	seconds
`T2`	T2 (s)	Pure dephasing time constant (phase decoherence)	—	seconds

The Lindblad collapse operators constructed from these parameters are:

Amplitude damping: \(L_1 = \sqrt{1/T_1}\;\sigma^-\) — models energy relaxation to the ground state
Pure dephasing: \(L_2 = \sqrt{1/T_2 - 1/(2T_1)}\;\sigma_z/2\) — models loss of phase coherence without energy exchange

For multi-qubit systems, the collapse operators are extended to the full Hilbert space via tensor products with identity operators on the remaining qubits.

Physical Constraint

The physical constraint \(T_2 \leq 2\,T_1\) is enforced automatically. Configurations that violate this bound will raise a validation error, as such values are unphysical (the pure dephasing rate cannot be negative).

Liouville Space Requirement

Dissipative simulations require the optimization space to be set to liouville (density matrix mode). When dissipation_mode is set to "dissipative", the space is automatically forced to liouville in the GUI.

Example:

{
  "parameters": {
    // ... other parameters ...
    "T1": [0.001],       // 1 ms amplitude damping
    "T2": [0.0005]       // 500 μs pure dephasing (T2 ≤ 2·T1)
  },
  "optimization": {
    "space": "liouville",
    "dissipation_mode": "dissipative",
    // ...
  }
}

Multi-Qubit Coupling

For systems comprising two or more qubits, the inter-qubit coupling parameters must be specified. These fields are used when len(qubits) > 1. The available coupling types depend on the selected Hamiltonian type.

Spin Chain Coupling

Key	GUI Label	Description	Default
`J`	J_ij	J-coupling matrix (N×N), symmetric	~16.7 MHz
`coupling_type`	Coupling Type	`Z`, `XY`, or `XYZ`	`XY`
`sigma_J`	σ J	Coupling strength uncertainty	0

Spin Chain Coupling Types

Three coupling models are supported for spin-chain systems:

Z — Ising-type ZZ coupling only
XY — XX + YY exchange coupling (default)
XYZ — Full Heisenberg coupling (XX + YY + ZZ)

Superconducting Coupling

Key	GUI Label	Description	Default
`J`	g_ij	Capacitive coupling matrix (N×N), symmetric	~16.7 MHz
`coupling_type`	Coupling Type	`XY`, `ZZ`, or `XY+ZZ`	`XY`
`sigma_J`	σ g	Coupling strength uncertainty	0
`anharmonicities`	Anharmonicity (Hz)	Per-qubit anharmonicity α_i, used for ZZ computation	—
`zz_crosstalk`	—	Calibrated static ZZ coupling matrix (Hz). Overrides perturbative formula	—
`stark_shift_coeffs`	—	Per-qubit AC Stark shift coefficients \(s_i\) (dimensionless). Adds drive-dependent Z term	—

Superconducting Coupling Types

Three coupling models are supported for superconducting qubit systems:

XY — Exchange coupling from capacitive interaction (XX + YY, default)
ZZ — Static ZZ coupling from anharmonicity-mediated frequency shifts
XY+ZZ — Both exchange and static ZZ terms

When the coupling type includes ZZ, the static ZZ interaction is determined by the first available source (highest priority first):

Runtime zz_instances kwarg (per-snapshot)
Calibrated zz_crosstalk matrix (fixed, from constructor / config)
Perturbative formula (see below)
Zero matrix

The perturbative estimate is evaluated with each snapshot's detunings and couplings:

\[ \zeta_{ij} = \frac{2\,g_{ij}^2\,(\alpha_i + \alpha_j)}{(\Delta + \alpha_i)(\Delta - \alpha_j)}, \qquad \Delta = \delta_i - \delta_j \]

It comes from second-order perturbation theory in the \(|11\rangle \leftrightarrow |20\rangle\) and \(|11\rangle \leftrightarrow |02\rangle\) couplings, so it is only meaningful away from those avoided crossings. The estimate is refused when the mixing \(\sqrt{2}\,|g| / \min(|\Delta + \alpha_i|, |\Delta - \alpha_j|)\) exceeds 0.1; supply a calibrated zz_crosstalk matrix or use the 3-level duffing_transmon model instead.

0.1 is a small-mixing heuristic, not a uniform error bound. At equal detunings with \(\alpha/2\pi = -300\) MHz and \(g/2\pi = 21\) MHz the mixing is just under the limit while the estimate is still ~1.9% off the exact value.

AC Stark Shift

When stark_shift_coeffs is provided, an additional Z control channel per qubit is added, modelling the drive-dependent frequency shift (light shift):

\[ H_{\text{Stark}}(t) = -\sum_i s_i\,(I_i^2 + Q_i^2)\,\Omega_{d,i}^2\;Z_i, \qquad Z_i = \tfrac{1}{2}\sigma_z^{(i)} \]

\(s_i\) is defined as a shift of the qubit frequency, so it enters the drift with the same minus sign as the detuning (see the two-level drift convention below).

This increases n_controls from \(2N\) to \(3N\) qubits. The stark_shift_coeffs are specified as-is in the configuration (no Hz-to-rad/s conversion). They are nominally dimensionless but multiply \(\Omega_d^2\), so their effective units are inverse frequency and useful values are far below 1.

Two-Level Drift Convention

With \(X, Y, Z = \tfrac{1}{2}\sigma_{x,y,z}\), the two-level superconducting drift is

\[ H_{\text{drift}} = -\sum_i \delta_i\,Z_i + \sum_{i<j} 2 g_{ij}\bigl(X_iX_j + Y_iY_j\bigr) + \sum_{i<j} \zeta_{ij}\,Z_iZ_j \]

The detuning sign and the exchange factor of 2 are fixed by requiring this to equal the projection of the Duffing drift onto the computational subspace, up to a scalar identity: projecting \(\delta_i \hat{n}_i\) gives \(\delta_i(I/2 - Z_i)\), and projecting \(g(a_i^\dagger a_j + \text{h.c.})\) gives \(2g(X_iX_j + Y_iY_j)\).

This is not the spin-chain / NMR convention, which is unchanged and documented under Spin Chain Coupling.

Shared JSON Keys

Both platforms use the J and sigma_J keys in the JSON configuration for cross-platform compatibility. The GUI relabels these as g_ij / σg for superconducting qubits.

Duffing Transmon (3-Level)

When using hamiltonian_type: "duffing_transmon", each transmon is modelled as a 3-level system (\(|0\rangle, |1\rangle, |2\rangle\)) to capture leakage outside the computational subspace. The Hilbert space dimension is \(3^{n_\text{qubits}}\).

Key	Description	Default	Units
`anharmonicities`	Per-qubit anharmonicities α_i (required)	−330 MHz	Hz
`coupling_type`	Currently `"XY"` only	`XY`	—

The drift Hamiltonian includes the number operator and anharmonicity:

\[ H_{\text{drift}} = \sum_i \bigl[\delta_i\,\hat{n}_i + \tfrac{\alpha_i}{2}\,\hat{n}_i(\hat{n}_i - I)\bigr] + \sum_{i<j} g_{ij}(a_i^\dagger a_j + a_i a_j^\dagger) \]

Anharmonicities Required

The anharmonicities parameter is mandatory for the Duffing transmon model. The 3-level structure is meaningless without it. Configurations that omit this field will raise a ValueError.

Initial States

The initial state of each qubit is specified as a list of Bloch sphere axis labels. For multi-qubit systems, each entry in the outer list corresponds to a distinct initial configuration of the entire register.

// Single qubit
{ "initial_states": [["Z"]] }

// Two qubits
{ "initial_states": [["Z", "Z"]] }

Target States

The desired final state or gate may be specified using one of three methods, each suited to different use cases.

Axis Targets

The target state is specified as a Bloch sphere axis direction.

{ "target_states": { "Axis": [["-Z"]] } }

Value	Description
`Z`	Ground state (\|0⟩)
`-Z`	Excited state (\|1⟩)
`X`, `-X`	Superposition along ±X
`Y`, `-Y`	Superposition along ±Y

Gate Targets

The target is specified as a quantum gate, which implicitly defines the required unitary transformation. In the GUI, gates are selected from a dropdown menu with platform-aware defaults.

{ "target_states": { "Gate": ["X", "H", "CNOT"] } }

Single-qubit: X, Y, Z, H, S, T

Two-qubit: CNOT, CZ, SWAP, iSWAP, √iSWAP, ECR

Three-qubit: Toff (Toffoli)

Platform-Specific Gate Ordering

In the GUI dropdown, gates are ordered by relevance to the selected Hamiltonian type:

Spin Chain: CNOT (default), CZ, SWAP, iSWAP, √iSWAP, ECR
Superconducting: iSWAP (default), √iSWAP, ECR, CZ, CNOT, SWAP

The √iSWAP gate is the square root of the iSWAP gate, satisfying (√iSWAP)² = iSWAP. The ECR (echoed cross-resonance) gate is a native entangling gate on many superconducting platforms.

Phi/Beta Targets

The target rotation is specified in terms of the rotation axis and angle.

{ "target_states": { "Phi": ["x"], "Beta": ["180"] } }

Parameter	Description	Range
Phi (φ)	Rotation axis in XY plane	`x`, `y`, or angle in degrees
Beta (β)	Rotation angle	0° – 360°

Multi-State Optimization

Ctrl-freeq supports the simultaneous optimization of pulses for multiple initial/target state pairs. This capability is essential for the design of universal rotation pulses (in the single-qubit case) and conditional gates such as CNOT or SWAP (in the multi-qubit case). The optimizer seeks a single pulse that achieves all specified state transformations concurrently.

Single-Qubit Example: Universal Rotation

To design a pulse that performs a universal rotation, multiple initial-to-target state mappings are specified:

{
  "initial_states": [["X"], ["Y"], ["Z"]],
  "target_states": {
    "Axis": [["X"], ["Z"], ["-Y"]]
  }
}

The optimization then seeks a single pulse that simultaneously achieves the following transformations:

Initial	Target	Transformation
X	X	X axis preserved
Y	Z	Y → Z rotation
Z	-Y	Z → -Y rotation

Multi-Qubit Example: Conditional Gates

For two-qubit systems, multiple state pairs may be specified to design conditional gates:

{
  "initial_states": [["Z", "-Z"], ["X", "Y"]],
  "target_states": {
    "Gate": ["CNOT", "SWAP"]
  }
}

State Pair Matching

It should be noted that the number of initial states must equal the number of target states. Each initial state at index i is mapped to the target state at the corresponding index.

GUI Usage

In the graphical interface, multiple states are entered as comma-separated values:

Initial States: X, Y, Z
Target Axis: X, Z, -Y

For two-qubit systems, semicolons are used to separate qubits within each state pair.

API Usage

from ctrl_freeq.api import load_single_qubit_multiple_config

# Load pre-configured multi-state example
api = load_single_qubit_multiple_config()
solution = api.run_optimization()

Available multi-state configurations:

Function	Description
`load_single_qubit_multiple_config()`	Single qubit with X,Y,Z → X,Z,-Y
`load_two_qubit_multiple_config()`	Two qubits with multiple gate targets

Optimization Settings

The following fields control the behaviour of the optimization procedure:

Key	GUI Label	Description	Default
`space`	Space	`hilbert` (pure states) or `liouville` (density matrices)	`hilbert`
`dissipation_mode`	Dissipation	`non-dissipative` or `dissipative` (Lindblad master equation)	`non-dissipative`
`H0_snapshots`	\(H_0\) Snapshots	Time steps for drift Hamiltonian	100
`Omega_R_snapshots`	Ω_R Snapshots	Time steps for control Hamiltonian	1
`algorithm`	Algorithm	Optimization algorithm (see Algorithms)	varies by config
`max_iter`	Max Iterations	Maximum optimization iterations	1000
`targ_fid`	Target Fidelity	Stop when the penalized score (fidelity − penalty) reaches this value	0.999

Next Steps

Algorithms — Algorithm selection guide
Compute (CPU/GPU) — Hardware acceleration options
GUI Guide — Interactive configuration