Python API
The session class
The session class provides a way to set up the experiment table.
You can use the experiment table to run a list of quantum circuits under different conditions, such as number of measurement shots, backends, parameters, etc.
- class core.session
- property acc
acc:
Valid settings: aer | tnqvm
Select a back-end simulator. The single setting applies globally to all infiles, all instrings, and random circuits.
accs:
Valid settings: [[aer|tnqvm, …], [aer|tnqvm, …]]
The lead dimension’s element 0 matches the vector of infiles, element 1 matches the vector of instrings, element 2 matches the vector of random depths.
- property accs
acc:
Valid settings: aer | tnqvm
Select a back-end simulator. The single setting applies globally to all infiles, all instrings, and random circuits.
accs:
Valid settings: [[aer|tnqvm, …], [aer|tnqvm, …]]
The lead dimension’s element 0 matches the vector of infiles, element 1 matches the vector of instrings, element 2 matches the vector of random depths.
- property aer_sim_type
aer_sim_type:
Valid settings: statevector | density_matrix | matrix_product_state
Selects a simulation method for the AER simulator.
aer_sim_types:
A 1d-array (list) version of aer_sim_type.
- property aer_sim_types
aer_sim_type:
Valid settings: statevector | density_matrix | matrix_product_state
Selects a simulation method for the AER simulator.
aer_sim_types:
A 1d-array (list) version of aer_sim_type.
- aws32dm1(self: core.session) None
AWS Braket DM1, 32 async workers
- aws32sv1(self: core.session) None
AWS Braket SV1, 32 async workers
- aws8tn1(self: core.session) None
AWS Braket TN1, 8 async workers
- property beta
Warning
This property is currently unused.
- property betas
Warning
This property is currently unused.
- property circuit_optimization
circuit_optimization:
List of circuit optimization passes.
circuit_optimizations:
A 1d-array (list) version of circuit_optimization.
- property circuit_optimizations
circuit_optimization:
List of circuit optimization passes.
circuit_optimizations:
A 1d-array (list) version of circuit_optimization.
- property debug
debug:
Valid settings: True | False
When set to True, extra debugging information will be printed.
- divergence(self: core.session) None
Calculate Jensen-Shannon divergence
- property include_qb
include_qb:
A file that contains OpenQASM format gate definitions for custom Quantum Brilliance gates.
include_qbs:
Valid settings: [include_qb, …]
A 1d-array (list) version of session.include_qb.
- property include_qbs
include_qb:
A file that contains OpenQASM format gate definitions for custom Quantum Brilliance gates.
include_qbs:
Valid settings: [include_qb, …]
A 1d-array (list) version of session.include_qb.
- property infile
infile:
Name of a file containing (default: OpenQASM format) a quantum circuit.
infiles:
Valid settings: [infile, …]
A 1d-array (list) version of session.infile.
- property infiles
infile:
Name of a file containing (default: OpenQASM format) a quantum circuit.
infiles:
Valid settings: [infile, …]
A 1d-array (list) version of session.infile.
- property initial_bond_dimension
initial_bond_dimension:
Set the initial bond dimension (MPS simulator). The single setting applies globally.
initial_bond_dimensions:
A 1d-array (list) version of initial_bond_dimension.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property initial_bond_dimensions
initial_bond_dimension:
Set the initial bond dimension (MPS simulator). The single setting applies globally.
initial_bond_dimensions:
A 1d-array (list) version of initial_bond_dimension.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property initial_kraus_dimension
initial_kraus_dimension:
Set the initial kraus dimension (MPS simulator). The single setting applies globally.
initial_kraus_dimensions:
A 1d-array (list) version of initial_kraus_dimension.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property initial_kraus_dimensions
initial_kraus_dimension:
Set the initial kraus dimension (MPS simulator). The single setting applies globally.
initial_kraus_dimensions:
A 1d-array (list) version of initial_kraus_dimension.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property instring
instring:
A string that defines a circuit in OpenQASM format. Simple example:
__qpu__ void QBCIRCUIT(qreg q) { OPENQASM 2.0; include "qelib1.inc;" creg c0[1]; creg c1[1]; h q[0]; cx q[0],q[1]; measure q[0] -> c0[0]; measure q[1] -> c1[0]; }
instrings:
Valid settings: [instring, …]
A 1d-array (list) version of session.instring.
- property instrings
instring:
A string that defines a circuit in OpenQASM format. Simple example:
__qpu__ void QBCIRCUIT(qreg q) { OPENQASM 2.0; include "qelib1.inc;" creg c0[1]; creg c1[1]; h q[0]; cx q[0],q[1]; measure q[0] -> c0[0]; measure q[1] -> c1[0]; }
instrings:
Valid settings: [instring, …]
A 1d-array (list) version of session.instring.
- property ir_target
ir_target:
Input quantum circuit (core.Circuit).
ir_targets:
A 1d-array (list) version of ir_target.
- property ir_targets
ir_target:
Input quantum circuit (core.Circuit).
ir_targets:
A 1d-array (list) version of ir_target.
- property log_enabled
Warning
This property is currently unused.
log_enabled:
Setting this to True to enable logging to file. The single setting applies globally.
Valid settings: True | False
log_enableds:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of log_enabled.
- property log_enableds
Warning
This property is currently unused.
log_enabled:
Setting this to True to enable logging to file. The single setting applies globally.
Valid settings: True | False
log_enableds:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of log_enabled.
- property max_bond_dimension
max_bond_dimension:
Set the maximum bond dimension (MPS simulator). The single setting applies globally.
max_bond_dimensions:
A 1d-array (list) version of max_bond_dimension.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property max_bond_dimensions
max_bond_dimension:
Set the maximum bond dimension (MPS simulator). The single setting applies globally.
max_bond_dimensions:
A 1d-array (list) version of max_bond_dimension.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property max_kraus_dimension
max_kraus_dimension:
Set the maximum kraus dimension (MPS simulator). The single setting applies globally.
max_kraus_dimensions:
A 1d-array (list) version of max_kraus_dimension.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property max_kraus_dimensions
max_kraus_dimension:
Set the maximum kraus dimension (MPS simulator). The single setting applies globally.
max_kraus_dimensions:
A 1d-array (list) version of max_kraus_dimension.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property noise
noise:
Valid settings: True | False
Setting this to True to enable noisy simulation (if supported by the acc backend). The single setting applies globally.
noises:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of noise.
- property noise_mitigation
noise_mitigation:
Select a noise mitigation module.
noise_mitigations:
A 1d-array (list) version of noise_mitigation.
- property noise_mitigations
noise_mitigation:
Select a noise mitigation module.
noise_mitigations:
A 1d-array (list) version of noise_mitigation.
- property noise_model
noise_model:
Set the noise model to be used in subsequent simulations.
Note
Requires setting: noise = True (to have effect)
The default (built in) model is a simple depolarizing noise model on all qubits.
Users may make their own instances of the NoiseModel class (or make an instance of the default and modify it), and then assign that model to this property. See examples/python/noise_model*.py.
If the Qristal Emulator is installed, the following additional models are available and can be accessed by specifying the relevant model name as a string passed to the constructor of the NoiseModel class:
“qb-nm1” : 4x4 NV centres in x-y grid, 3 qubits per NV centre
“qb-nm2” : 8x8 NV centres in x-y grid, 1 qubit per NV centre, nearest x and nearest y connectivity
“qb-nm3” : 48 NV centres in a 1-dimensional grid with linear qubit index, 1 qubits per NV centre
“qb-qdk1” : 1 NV centre with 2 qubits, fidelities tuned to match deployed device
“qb-dqc2” : 1 NV centre with 2 qubits, fidelities tuned to match lab-based device
noise_models:
A 1d-array (list) version of noise_model.
- property noise_models
noise_model:
Set the noise model to be used in subsequent simulations.
Note
Requires setting: noise = True (to have effect)
The default (built in) model is a simple depolarizing noise model on all qubits.
Users may make their own instances of the NoiseModel class (or make an instance of the default and modify it), and then assign that model to this property. See examples/python/noise_model*.py.
If the Qristal Emulator is installed, the following additional models are available and can be accessed by specifying the relevant model name as a string passed to the constructor of the NoiseModel class:
“qb-nm1” : 4x4 NV centres in x-y grid, 3 qubits per NV centre
“qb-nm2” : 8x8 NV centres in x-y grid, 1 qubit per NV centre, nearest x and nearest y connectivity
“qb-nm3” : 48 NV centres in a 1-dimensional grid with linear qubit index, 1 qubits per NV centre
“qb-qdk1” : 1 NV centre with 2 qubits, fidelities tuned to match deployed device
“qb-dqc2” : 1 NV centre with 2 qubits, fidelities tuned to match lab-based device
noise_models:
A 1d-array (list) version of noise_model.
- property noises
noise:
Valid settings: True | False
Setting this to True to enable noisy simulation (if supported by the acc backend). The single setting applies globally.
noises:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of noise.
- property nooptimise
nooptimise:
Valid settings: True | False
Setting this to True to disable circuit optimization. The single setting applies globally.
nooptimises:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of nooptimise.
- property nooptimises
nooptimise:
Valid settings: True | False
Setting this to True to disable circuit optimization. The single setting applies globally.
nooptimises:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of nooptimise.
- property noplacement
noplacement:
Valid settings: True | False
Setting this to True to disable circuit placement. The single setting applies globally.
noplacements:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of noplacement.
- property noplacements
noplacement:
Valid settings: True | False
Setting this to True to disable circuit placement. The single setting applies globally.
noplacements:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of noplacement.
- property nosim
nosim:
Valid settings: True | False
Setting this to True to disable circuit simulation. The single setting applies globally.
nosims:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of nosim.
- property nosims
nosim:
Valid settings: True | False
Setting this to True to disable circuit simulation. The single setting applies globally.
nosims:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of nosim.
- property notiming
Warning
This property is currently unused.
notiming:
Valid settings: True | False
Setting this to True to disable timing estimation. The single setting applies globally.
notimings:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of notiming.
- property notimings
Warning
This property is currently unused.
notiming:
Valid settings: True | False
Setting this to True to disable timing estimation. The single setting applies globally.
notimings:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of notiming.
- property num_threads
The number of threads in the QB SDK thread pool
- Type:
num_threads
- property out_bitstring
out_bitstring:
After calling session.run(), the counts from running sn shots are stored in session.out_bitstring, using a dictionary where the keys are state label bits.
out_bitstrings:
A 1d-array (list) version of session.out_bitstring.
- property out_bitstrings
out_bitstring:
After calling session.run(), the counts from running sn shots are stored in session.out_bitstring, using a dictionary where the keys are state label bits.
out_bitstrings:
A 1d-array (list) version of session.out_bitstring.
- property out_divergence
out_divergence:
After calling session.divergence(), the Jensen-Shannon divergence between session.out_count and session.output_amplitude is calculated and stored session.out_divergence.
out_divergences:
A 1d-array (list) version of session.out_divergence.
- property out_divergences
out_divergence:
After calling session.divergence(), the Jensen-Shannon divergence between session.out_count and session.output_amplitude is calculated and stored session.out_divergence.
out_divergences:
A 1d-array (list) version of session.out_divergence.
- property out_double_qubit_gate_qty
out_double_qubit_gate_qty:
After calling session.profile(), the circuit in session.out_transpiled_circuit is processed and the count of the number of two-qubit gates is stored as session.out_double_qubit_gate_qty, using a dictionary where the keys are integers corresponding to qubit indexes.
out_double_qubit_gate_qtys:
A 1d-array (list) version of session.out_double_qubit_gate_qty.
- property out_double_qubit_gate_qtys
out_double_qubit_gate_qty:
After calling session.profile(), the circuit in session.out_transpiled_circuit is processed and the count of the number of two-qubit gates is stored as session.out_double_qubit_gate_qty, using a dictionary where the keys are integers corresponding to qubit indexes.
out_double_qubit_gate_qtys:
A 1d-array (list) version of session.out_double_qubit_gate_qty.
- property out_qbjson
out_qbjson:
Shows JSON data sent to QB hardware. Note: session.run() must be called first.
out_qbjsons:
A 1d-array (list) version of session.out_qbjson.
- property out_qbjsons
out_qbjson:
Shows JSON data sent to QB hardware. Note: session.run() must be called first.
out_qbjsons:
A 1d-array (list) version of session.out_qbjson.
- property out_qobj
out_qobj:
When acc=’aer’, the .qobj JSON input used by a standalone Aer installation is stored in out_qobj. Note: session.run() must be called first.
out_qobjs:
A 1d-array (list) version of session.out_qobj.
- property out_qobjs
out_qobj:
When acc=’aer’, the .qobj JSON input used by a standalone Aer installation is stored in out_qobj. Note: session.run() must be called first.
out_qobjs:
A 1d-array (list) version of session.out_qobj.
- property out_raw
out_raw:
After calling session.run(), the counts from running sn shots are stored in session.out_raw, using a JSON format.
out_raws:
A 1d-array (list) version of session.out_raw.
- property out_raws
out_raw:
After calling session.run(), the counts from running sn shots are stored in session.out_raw, using a JSON format.
out_raws:
A 1d-array (list) version of session.out_raw.
- property out_single_qubit_gate_qty
out_single_qubit_gate_qty:
After calling session.profile(), the circuit in session.out_transpiled_circuit is processed and the count of the number of single qubit gates is stored as session.out_single_qubit_gate_qty, using a dictionary where the keys are integers corresponding to qubit indexes.
out_single_qubit_gate_qtys:
A 1d-array (list) version of session.out_single_qubit_gate_qty.
- property out_single_qubit_gate_qtys
out_single_qubit_gate_qty:
After calling session.profile(), the circuit in session.out_transpiled_circuit is processed and the count of the number of single qubit gates is stored as session.out_single_qubit_gate_qty, using a dictionary where the keys are integers corresponding to qubit indexes.
out_single_qubit_gate_qtys:
A 1d-array (list) version of session.out_single_qubit_gate_qty.
- property out_total_init_maxgate_readout_time
out_total_init_maxgate_readout_time:
After calling session.profile(), the circuit in in session.out_transpiled_circuit is processed and timing estimates taken to perform the required number of shots [sn] are stored as session.out_total_init_maxgate_readout_time.
It uses a dictionary with the following keys [integer]:
0: total, in ms;
1: initialisation time component, in ms;
2: max depth gate time component, in ms;
3: readout time component, in ms;
4: total (classically simulated time), in ms;
5: PC transfer to controller time, in ms.
out_total_init_maxgate_readout_times:
A 1d-array (list) version of session.out_total_init_maxgate_readout_time.
- property out_total_init_maxgate_readout_times
out_total_init_maxgate_readout_time:
After calling session.profile(), the circuit in in session.out_transpiled_circuit is processed and timing estimates taken to perform the required number of shots [sn] are stored as session.out_total_init_maxgate_readout_time.
It uses a dictionary with the following keys [integer]:
0: total, in ms;
1: initialisation time component, in ms;
2: max depth gate time component, in ms;
3: readout time component, in ms;
4: total (classically simulated time), in ms;
5: PC transfer to controller time, in ms.
out_total_init_maxgate_readout_times:
A 1d-array (list) version of session.out_total_init_maxgate_readout_time.
- property out_transpiled_circuit
out_transpiled_circuit:
After calling session.run(), the transpiled version of session.instring is stored as session.out_transpiled_circuit.
out_transpiled_circuits:
A 1d-array (list) version of session.out_transpiled_circuit.
- property out_transpiled_circuits
out_transpiled_circuit:
After calling session.run(), the transpiled version of session.instring is stored as session.out_transpiled_circuit.
out_transpiled_circuits:
A 1d-array (list) version of session.out_transpiled_circuit.
- property out_z_op_expect
out_z_op_expect:
After calling run(), the Z-operator expectation value determined from counts in respective states is stored in out_z_op_expects, using a dictionary where the keys are integers, and currently only key:0 is used.
out_z_op_expects:
A 1d-array (list) version of out_z_op_expect.
- property out_z_op_expects
out_z_op_expect:
After calling run(), the Z-operator expectation value determined from counts in respective states is stored in out_z_op_expects, using a dictionary where the keys are integers, and currently only key:0 is used.
out_z_op_expects:
A 1d-array (list) version of out_z_op_expect.
- property output_amplitude
output_amplitude:
Set the amplitudes for Jensen-Shannon divergence calculation. The single setting applies globally.
output_amplitudes:
A 1d-array (list) version of output_amplitude.
- property output_amplitudes
output_amplitude:
Set the amplitudes for Jensen-Shannon divergence calculation. The single setting applies globally.
output_amplitudes:
A 1d-array (list) version of output_amplitude.
- property output_oqm_enabled
output_oqm_enabled:
Valid settings: True | False
Setting this to True to enable circuit timing and resource estimation. The single setting applies globally.
output_oqm_enableds:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of output_oqm_enabled.
- property output_oqm_enableds
output_oqm_enabled:
Valid settings: True | False
Setting this to True to enable circuit timing and resource estimation. The single setting applies globally.
output_oqm_enableds:
Valid settings: [[True|False, …], [True|False, …]]
A 1d-array (list) version of output_oqm_enabled.
- property placement
placement:
Valid settings: “swap-shortest-path” | “noise-aware”
Setting the method to map from logical qubits to the physical qubits of the device that will be used to carry them. The single setting applies globally to all infiles and all instrings. Default: “swap-shortest-path”
placements:
Valid settings: [[“swap-shortest-path” | “noise-aware”, …], [“swap-shortest-path” | “noise-aware”, …]]
The lead dimension’s element 0 matches the vector of infiles, element 1 matches the vector of instrings, element 2 matches the vector of randoms.
- property placements
placement:
Valid settings: “swap-shortest-path” | “noise-aware”
Setting the method to map from logical qubits to the physical qubits of the device that will be used to carry them. The single setting applies globally to all infiles and all instrings. Default: “swap-shortest-path”
placements:
Valid settings: [[“swap-shortest-path” | “noise-aware”, …], [“swap-shortest-path” | “noise-aware”, …]]
The lead dimension’s element 0 matches the vector of infiles, element 1 matches the vector of instrings, element 2 matches the vector of randoms.
- qb12(self: core.session) None
Quantum Brilliance 12-qubit defaults
- property qn
qn:
Number of qubits. The single setting applies globally.
qns:
A 1d-array (list) version of qn.
- property qns
qn:
Number of qubits. The single setting applies globally.
qns:
A 1d-array (list) version of qn.
- property quil1
quil1:
Valid settings: True | False
Setting this to True causes circuits to be interpreted in Quil 1.0 format. The single setting applies globally to all infiles and all instrings.
quil1s:
Valid settings: [[True|False, …], [True|False, …]]
The lead dimension’s element 0 matches the vector of infiles, element 1 matches the vector of instrings, element 2 matches the vector of randoms.
- property quil1s
quil1:
Valid settings: True | False
Setting this to True causes circuits to be interpreted in Quil 1.0 format. The single setting applies globally to all infiles and all instrings.
quil1s:
Valid settings: [[True|False, …], [True|False, …]]
The lead dimension’s element 0 matches the vector of infiles, element 1 matches the vector of instrings, element 2 matches the vector of randoms.
- property random
random:
Circuit depth of the random circuit to use as input. The single setting applies globally.
randoms:
A 1d-array (list) version of random.
- property randoms
random:
Circuit depth of the random circuit to use as input. The single setting applies globally.
randoms:
A 1d-array (list) version of random.
- property rel_svd_cutoff
rel_svd_cutoff:
Set the relative SVD cutoff threshold value (MPS simulator). The single setting applies globally.
rel_svd_cutoffs:
A 1d-array (list) version of rel_svd_cutoff.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property rel_svd_cutoffs
rel_svd_cutoff:
Set the relative SVD cutoff threshold value (MPS simulator). The single setting applies globally.
rel_svd_cutoffs:
A 1d-array (list) version of rel_svd_cutoff.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property remote_backend_database_path
A YAML file that contains configuration data for remote backends (including hardware).
- property rn
rn:
Number of repetitions. The single setting applies globally.
rns:
A 1d-array (list) version of rn.
- property rns
rn:
Number of repetitions. The single setting applies globally.
rns:
A 1d-array (list) version of rn.
- run(self: core.session) None
Execute all declared quantum circuits under all conditions
- run_async(self: core.session, arg0: int, arg1: int) core.Handle
run_async(i,j) : Launch the execution of circuit i, condition j asynchronously.
- run_complete(self: core.session, arg0: int, arg1: int) bool
run_complete(i,j) : Check if the execution of circuit i, condition j has been completed.
- runit(self: core.session, arg0: int, arg1: int) None
runit(i,j) : Execute circuit i, condition j
- property seed
seed:
Set the random seed value.
seeds:
A 1d-array (list) version of seed.
- property seeds
seed:
Set the random seed value.
seeds:
A 1d-array (list) version of seed.
- set_parallel_run_config(self: core.session, arg0: str) None
Set the parallel execution configuration
- property sn
sn:
Number of measurement shots. The single setting applies globally.
sns:
A 1d-array (list) version of sn.
- property sns
sn:
Number of measurement shots. The single setting applies globally.
sns:
A 1d-array (list) version of sn.
- property state_vector
in_get_state_vec:
Using this will extract the state vector (supported by the qpp backend only).
- property svd_cutoff
svd_cutoff:
Set the SVD cutoff threshold value (MPS simulator). The single setting applies globally.
svd_cutoffs:
A 1d-array (list) version of svd_cutoff.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property svd_cutoffs
svd_cutoff:
Set the SVD cutoff threshold value (MPS simulator). The single setting applies globally.
svd_cutoffs:
A 1d-array (list) version of svd_cutoff.
Note
This is only needed if using the “tnqvm” backend accelerator.
- property theta
theta:
Angle variables (theta) to invoke the input parameterized quantum circuit with. The single setting applies globally.
thetas:
A 1d-array (list) version of theta.
- property thetas
theta:
Angle variables (theta) to invoke the input parameterized quantum circuit with. The single setting applies globally.
thetas:
A 1d-array (list) version of theta.
- property xasm
xasm:
Valid settings: True | False
Setting this to True causes circuits to be interpreted in XASM format. The single setting applies globally to all infiles and all instrings.
xasms:
Valid settings: [[True|False, …], [True|False, …]]
The lead dimension’s element 0 matches the vector of infiles, element 1 matches the vector of instrings, element 2 matches the vector of randoms.
- property xasms
xasm:
Valid settings: True | False
Setting this to True causes circuits to be interpreted in XASM format. The single setting applies globally to all infiles and all instrings.
xasms:
Valid settings: [[True|False, …], [True|False, …]]
The lead dimension’s element 0 matches the vector of infiles, element 1 matches the vector of instrings, element 2 matches the vector of randoms.
The Circuit class
The Circuit class represents a quantum circuit, i.e., an ordered sequence of [quantum gates and measurements](https://qristal.readthedocs.io/en/latest/rst/quantum_computing.html).
In addition to elementary gates, it also supports pre-built circuit templates for commonly-used algorithms, such as Quantum Fourier Transform (QFT), algebraic circuits, etc.
- class core.Circuit
- amcu(self: core.Circuit, U: object, qubits_control: numpy.ndarray[numpy.int32], qubits_ancilla: numpy.ndarray[numpy.int32]) None
Multi Controlled Unitary With Ancilla
This method decomposes a multi-controlled unitary into Toffoli gates and the unitary itself, with the use of ancilla qubits. With N control qubits there should be N-1 ancilla. The resulting instructions are added to the circuit (AMCU gate).
Parameters:
U The unitary operation [CircuitBuilder]
qubits_control The indices of the control qubits [list of int]
qubits_ancilla The indices of the ancilla qubits [list of int]
- amplitude_amplification(self: core.Circuit, oracle: object, state_prep: object, power: int = 1) None
Amplitude Amplification
This method adds a number of Grovers operators to the circuit.
Grovers operators are used to amplify the amplitude of some desired subspace of your quantum state.
Parameters:
oracle The oracle circuit O that marks the good subspace [CircuitBuilder]
state_prep The circuit A used to prepare the input state [CircuitBuilder]
power The number of Grovers operators to append to the circuit [int]
- append(self: core.Circuit, other: core.Circuit) None
Append the ‘other’ quantum circuit to this circuit.
- canonical_ae(self: core.Circuit, state_prep: object, grover_op: object, precision: int, num_state_prep_qubits: int, num_trial_qubits: int, precision_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), trial_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), no_state_prep: bool = False) None
Canonical Amplitude Estimation
This method adds the canonical version of Quantum Amplitude Estimation (QAE) to the circuit.
Given a quantum state split into a good subspace and a bad subspace, the QAE sub-routine provides a k-bit approximation to the amplitude of the good subspace, a.
QAE works by using the Grovers operator Q, which amplifies the amplitude of the good subspace, as the unitary input to a Quantum Phase Estimation routine.
Parameters:
state_prep The circuit A used to prepare the input state [CircuitBuilder]
grover_op The circuit for the Grovers operator Q for the good subspace [CircuitBuilder]
precision The number of bits k used to approximate the amplitude [int]
num_state_prep_qubits The number of qubits acted on by the state_prep circuit A [int]
num_trial_qubits The number of qubits acted on by the grover_op circuit Q [int]
trial_qubits The indices of the qubits acted on by the grover_op circuit Q [list of int]
precision_qubits The indices of the qubits used to store the approximate amplitude [list of int]
no_state_prep If true, assumes the state is already prepared in the appropriate register [bool]
- ccx(self: core.Circuit, ctrl_idx1: int, ctrl_idx2: int, target_idx: int) None
Toffoli gate
This method adds a Toffoli gate (CCX) to the circuit.
The CCX gate performs an X gate on the target qubit conditional on the two control qubits being in the 1 state.
Parameters:
ctrl_idx1 the index of the first control qubit [int]
ctrl_idx2 the index of the second control qubit [int]
target_idx the index of the target qubit [int]
- ch(self: core.Circuit, ctrl_idx: int, target_idx: int) None
CH gate
This method adds a controlled-H (CH) gate to the circuit.
The CH gate performs an H gate on the target qubit conditional on the control qubit being in the 1 state.
ctrl_idx the index of the control qubit [int]
target_idx the index of the target qubit [int]
- cnot(self: core.Circuit, ctrl_idx: int, target_idx: int) None
CNOT gate
This method adds a controlled-X (CNOT) gate to the circuit.
The CNOT gate performs an X gate on the target qubit conditional on the control qubit being in the 1 state.
Parameters:
ctrl_idx the index of the control qubit [int]
target_idx the index of the target qubit [int]
- comparator(self: core.Circuit, best_score: int, num_scoring_qubits: int, trial_score_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), flag_qubit: int = - 1, best_score_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), ancilla_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), is_LSB: bool = True, controls_on: numpy.ndarray[numpy.int32] = array([], dtype=int32), controls_off: numpy.ndarray[numpy.int32] = array([], dtype=int32)) None
Comparator
This method adds a quantum bit string comparator to the circuit.
The quantum bit string comparator is used to compare the values of two bit string. If the trial score is greater than the best score, the flag qubit is flipped.
Parameters:
best_score The score we are comparing strings to [int]
num_scoring_qubits The number of qubits used to encode the scores [int]
trial_score_qubits The indices of the qubits encoding the trial states [list of int]
flag_qubit The index of the flag qubit which is flipped whenever trial score > BestScore [int]
best_score_qubits The indices of the qubits encoding the BestScore value [list of int]
ancilla_qubits The indices of the ancilla qubits required for the comparator circuit, if num_scoring_qubits = N we need 3N-1 ancilla [list of int]
is_LSB Indicates that the trial scores are encoded with LSB ordering [bool]
controls_on The indices of any qubits that should be “on” controls (i.e. circuit executed if qubit = 1) [list of int]
controls_off The indices of any qubits that should be “off” controls (i.e. circuit executed if qubit = 0) [list of int]
- comparator_as_oracle(self: core.Circuit, best_score: int, num_scoring_qubits: int, trial_score_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), flag_qubit: int = - 1, best_score_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), ancilla_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), is_LSB: bool = True, controls_on: numpy.ndarray[numpy.int32] = array([], dtype=int32), controls_off: numpy.ndarray[numpy.int32] = array([], dtype=int32)) None
Comparator as Oracle
This method adds a quantum bit string comparator oracle to the circuit.
The quantum bit string comparator is used to add a negative phase to any trial state whose bit string value is greater than the state being compared to. In this way it can be used as an oracle in a Grovers operator that amplifies higher scoring strings. This may be useful in many search problems.
Parameters:
best_score The score we are comparing strings to [int]
num_scoring_qubits The number of qubits used to encode the scores [int]
trial_score_qubits The indices of the qubits encoding the trial states [list of int]
flag_qubit The index of the flag qubit which acquires a negative phase whenever trial score > BestScore [int]
best_score_qubits The indices of the qubits encoding the BestScore value [list of int]
ancilla_qubits The indices of the ancilla qubits required for the comparator circuit, if num_scoring_qubits = N we need 3N-1 ancilla [list of int]
is_LSB Indicates that the trial scores are encoded with LSB ordering [bool]
controls_on The indices of any qubits that should be “on” controls (i.e. circuit executed if qubit = 1) [list of int]
controls_off The indices of any qubits that should be “off” controls (i.e. circuit executed if qubit = 0) [list of int]
- compare_beam_oracle(self: core.Circuit, q0: int, q1: int, q2: int, FA: numpy.ndarray[numpy.int32], FB: numpy.ndarray[numpy.int32], SA: numpy.ndarray[numpy.int32], SB: numpy.ndarray[numpy.int32] = array([], dtype=int32), simplified: bool = True) None
Compare Beam Oracle
This method adds a compare beam oracle to the circuit.
This method is required for the quantum decoder algorithm.
- compare_gt(self: core.Circuit, qubits_a: numpy.ndarray[numpy.int32], qubits_b: numpy.ndarray[numpy.int32], qubit_flag: int, qubit_ancilla: int, is_LSB: bool = True) None
Compare Greater Than
This method adds a greater-than comparator to the circuit.
Given two binary strings a and b, this comparator flips a flag qubit whenever a>b. This method uses far less ancilla than the more general comparator method provided.
Parameters:
qubits_a The indices of the qubits encoding a [list of int]
qubits_b The indices of the qubits encoding b [list of int]
qubit_flag The index of the flag qubit that is flipped whenever a>b [int]
qubit_ancilla The index of the single ancilla qubit required [int]
is_LSB Indicates that the trial scores are encoded with LSB ordering [bool]
- controlled_multiplication(self: core.Circuit, qubit_ancilla: numpy.ndarray[numpy.int32], qubits_a: numpy.ndarray[numpy.int32], qubits_b: numpy.ndarray[numpy.int32], qubits_result: int, is_LSB: bool = True, controls_on: numpy.ndarray[numpy.int32] = array([], dtype=int32), controls_off: numpy.ndarray[numpy.int32] = array([], dtype=int32)) None
Controlled Multiplication
This method adds a controlled Multiplication to the circuit.
Performs a Multiplication operation on a and b if an only if the controls are satisfied.
Parameters:
qubits_a the indices of the qubits encoding a [list of int]
qubits_b the indices of the qubits encoding b [list of int]
qubits_result the indices of the qubits that will ecode the multiplication result [list of int]
qubits_ancilla the index of the single required ancilla [int]
is_LSB Indicates that the trial scores are encoded with LSB ordering [bool]
controls_on The indices of any qubits that should be “on” controls (i.e. circuit executed if qubit = 1) [list of int]
controls_off The indices of any qubits that should be “off” controls (i.e. circuit executed if qubit = 0) [list of int]
- controlled_proper_fraction_division(self: core.Circuit, qubits_numerator: numpy.ndarray[numpy.int32], qubits_denominator: numpy.ndarray[numpy.int32], qubits_fraction: numpy.ndarray[numpy.int32], qubits_ancilla: numpy.ndarray[numpy.int32], controls_on: numpy.ndarray[numpy.int32] = array([], dtype=int32), controls_off: numpy.ndarray[numpy.int32] = array([], dtype=int32), is_LSB: bool = True) None
Controlled Proper Fraction Division
This method adds a controlled proper fraction division to the circuit.
Performs a PFD operation on a and b if an only if the controls are satisfied.
Parameters:
qubits_numerator the indices of the qubits encoding the numerator [list of int]
qubits_denominator the indices of the qubits encoding the denominator [list of int]
qubits_fraction the indices of the qubits that will ecode the division result [list of int]
qubit_ancilla the index of the required ancilla [list of int]
controls_on The indices of any qubits that should be “on” controls (i.e. circuit executed if qubit = 1) [list of int]
controls_off The indices of any qubits that should be “off” controls (i.e. circuit executed if qubit = 0) [list of int]
is_LSB Indicates that the trial scores are encoded with LSB ordering [bool]
- controlled_ripple_carry_adder(self: core.Circuit, qubits_adder: numpy.ndarray[numpy.int32], qubits_sum: numpy.ndarray[numpy.int32], c_in: int, flags_on: numpy.ndarray[numpy.int32] = array([], dtype=int32), flags_off: numpy.ndarray[numpy.int32] = array([], dtype=int32), no_overflow: bool = False) None
Controlled Addition
This method adds a controlled ripple carry adder to the circuit.
Performs a RippleAdd operation on adder_bits and sum_bits if and only if the controls are satisfied.
Parameters:
qubits_adder the indices of the qubits encoding adder_bits [list of int]
qubits_sum the indices of the qubits encoding sum_bits [list of int]
c_in the index of the carry-in bit [int]
flags_on The indices of any qubits that should be “on” controls (i.e. circuit executed if qubit = 1) [list of int]
flags_off The indices of any qubits that should be “off” controls (i.e. circuit executed if qubit = 0) [list of int]
no_overflow Indicates that the total of the addition can be encoded on the same number of qubits as sum_bits without overflowing [bool]
- controlled_subtraction(self: core.Circuit, qubits_larger: numpy.ndarray[numpy.int32], qubits_smaller: numpy.ndarray[numpy.int32], controls_on: numpy.ndarray[numpy.int32] = array([], dtype=int32), controls_off: numpy.ndarray[numpy.int32] = array([], dtype=int32), is_LSB: bool = True, qubit_ancilla: int = - 1) None
Controlled Subtraction
This method adds a controlled subtraction to the circuit.
Performs a subtraction operation on a and b if an only if the controls are satisfied.
Parameters:
qubits_larger the indices of the qubits encoding the larger value [list of int]
qubits_smaller the indices of the qubits encoding the smaller value [list of int]
controls_on The indices of any qubits that should be “on” controls (i.e. circuit executed if qubit = 1) [list of int]
controls_off The indices of any qubits that should be “off” controls (i.e. circuit executed if qubit = 0) [list of int]
is_LSB Indicates that the trial scores are encoded with LSB ordering [bool]
qubit_ancilla the index of the required ancilla [list of int]
- controlled_swap(self: core.Circuit, qubits_a: numpy.ndarray[numpy.int32], qubits_b: numpy.ndarray[numpy.int32], flags_on: numpy.ndarray[numpy.int32] = array([], dtype=int32), flags_off: numpy.ndarray[numpy.int32] = array([], dtype=int32)) None
Controlled SWAP
This method adds a controlled SWAP to the circuit.
Performs a SWAP operation on a and b if an only if the controls are satisfied.
Parameters:
qubits_a the indices of the qubits encoding a [list of int]
qubits_b the indices of the qubits encoding b [list of int]
flags_on The indices of any qubits that should be “on” controls (i.e. circuit executed if qubit = 1) [list of int]
flags_off The indices of any qubits that should be “off” controls (i.e. circuit executed if qubit = 0) [list of int]
- cphase(self: core.Circuit, ctrl_idx: int, target_idx: int, theta: float) None
CPhase gate
This method adds a controlled-U1 (CPhase) gate to the circuit.
The CPHase gate performs a U1(theta) gate on the target qubit conditional on the control qubit being in the 1 state.
Parameters:
ctrl_idx the index of the control qubit [int]
target_idx the index of the target qubit [int]
theta the value of the phase [double]
- cz(self: core.Circuit, ctrl_idx: int, target_idx: int) None
CZ gate
This method adds a controlled-Z (CZ) gate to the circuit.
The CZ gate performs a Z gate on the target qubit conditional on the control qubit being in the 1 state.
Parameters:
ctrl_idx the index of the control qubit [int]
target_idx the index of the target qubit [int]
- efficient_encoding(self: core.Circuit, scoring_function: Callable[[int], int], num_state_qubits: int, num_scoring_qubits: int, state_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), scoring_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), is_LSB: bool = True, use_ancilla: bool = False, qubits_init_flags: numpy.ndarray[numpy.int32] = array([], dtype=int32), flag_integer: int = 0) None
Efficient Encoding
This method adds an efficient encoding routine to the circuit.
Given a lookup function f that assigns a score to each binary string, we entangle each string to its score. Rather than encoding states sequentially we cut down on the amount of X gates required by instead following the Gray code ordering of states.
This module can optionally also flag strings of a certain value.
Parameters:
scoring_function A function that inputs the integer value of a binary string and outputs its score [func(int) -> int]
num_state_qubits The number of qubits encoding the strings [int]
num_scoring_qubits The number of qubits encoding the scores [int]
state_qubits The indices of the qubits encoding the strings [list of int]
scoring_qubits The indices of the qubits encoding the scores [list of int]
is_LSB Indicates that the trial scores are encoded with LSB ordering [bool]
use_ancilla Indicates that ancilla qubits can be used to decompose MCX gates [bool]
qubits_init_flag The indices of any flag qubits [list of int]
flag_integer The integer value of binary strings that should be flagged [int]
- equality_checker(self: core.Circuit, qubits_a: numpy.ndarray[numpy.int32], qubits_b: numpy.ndarray[numpy.int32], flag: int, use_ancilla: bool = False, qubits_ancilla: numpy.ndarray[numpy.int32] = array([], dtype=int32), controls_on: numpy.ndarray[numpy.int32] = array([], dtype=int32), controls_off: numpy.ndarray[numpy.int32] = array([], dtype=int32)) None
Equality Checker
This method adds an equality checker to the circuit.
Given two input bitstrings a and b the equality checker is used to flip a flag qubit whenever a=b.
Parameters:
qubits_a the indices of the qubits encoding a [list of int]
qubits_b the indices of the qubits encoding b [list of int]
flag the index of the flag qubit that gets flipped whenever a=b [int]
use_ancilla Indicates that ancilla qubits can be used to decompose MCX gates [bool]
qubits_ancilla The indices of the qubits to be used as ancilla qubits if use_ancilla=true [list of int]
controls_on The indices of any qubits that should be “on” controls (i.e. circuit executed if qubit = 1) [list of int]
controls_off The indices of any qubits that should be “off” controls (i.e. circuit executed if qubit = 0) [list of int]
- execute(self: core.Circuit, QPU: str = 'qpp', NUM_SHOTS: int = 1024, NUM_QUBITS: int = - 1) str
Run the circuit.
This method is used to pass the circuit to an accelerator backend for execution.
The optional parameters are:
QPU The accelerator name [string]
NUM_SHOTS The number of shots to use [int]
NUM_QUBITS The number of qubits required for the circuit [int]
- exponent(self: core.Circuit, qubits_log: numpy.ndarray[numpy.int32] = array([], dtype=int32), qubits_exponent: numpy.ndarray[numpy.int32] = array([], dtype=int32), qubits_ancilla: numpy.ndarray[numpy.int32] = array([], dtype=int32), min_significance: int = 1, is_LSB: bool = True) bool
Exponent Base 2
This method adds an exponent to the circuit. This is used to replace some value by its exponent base 2.
Parameters:
qubits_log the indices of the qubits encoding the original value [list of int]
qubits_exponent the indices of the qubits used to store the result [list of int]
qubits_ancilla the indices of the required ancilla qubits [list of int]
min_significance the accuracy cutoff [int]
is_LSB indicates LSB ordering is used [bool]
- exponential_search(self: core.Circuit, method: str, state_prep: object, oracle: Callable[[int], core.Circuit], best_score: int, f_score: Callable[[int], int], total_num_qubits: int, qubits_string: numpy.ndarray[numpy.int32], total_metric: numpy.ndarray[numpy.int32], qpu: str = 'qpp') int
Exponential Search
This method sets up and executes the exponential search routine.
Exponential search is a way to perform amplitude estimation when the size of the “good” subspace is unknown (so the number of Grovers operators to use is unknown).
We implement three variants: - canonical exponential search is a specific “guess and check” method - MLQAE exponential search uses MLQAE to first estimate the size of the good subspace then perform regular amplitude estimation with the appropriate number of Grovers operators - CQAE exponential search uses canonical QAE to first estimate the size of the good subspace then perform regular amplitude estimation with the appropriate number of Grovers operators
Parameters:
method indicates which method to use. Options are “canonical”, “MLQAE”, “CQAE” [string]
state_prep a function which produces the state prep circuit [StatePrepFuncCType]
oracle a function which produces the oracle circuit that marks the good subspace [OracleFuncCType]
best_score the current best score [int]
f_score a function that returns a 1 if the input binary string has value greater than the current best score and 0 otherwise [func(int)->int]
total_num_qubits total number of qubits [int]
qubits_string the indices of the qubits encoding the strings [list of int]
total_metric the indices of the qubits encoding the string scores after any required pre-processing of qubits_metric (required by decoder) [list of int]
qpu the name of the accelerator used to execute the algorithm [string]
Returns: a better score if found, otherwise returns the current best score
- generalised_mcx(self: core.Circuit, target: int, controls_on: numpy.ndarray[numpy.int32] = array([], dtype=int32), controls_off: numpy.ndarray[numpy.int32] = array([], dtype=int32)) None
Generalised MCX
This method adds a generalised MCX gate to the circuit.
By generalised MCX we mean that we allow the control qubits to be conditional on being off or conditional on being on.
Parameters:
target The index of the target qubit [int]
controls_on The indices of any qubits that should be “on” controls (i.e. circuit executed if qubit = 1) [list of int]
controls_off The indices of any qubits that should be “off” controls (i.e. circuit executed if qubit = 0) [list of int]
- h(self: core.Circuit, idx: int) None
Hadamard gate
This method adds a Hadamard (H) gate to the circuit.
Parameters:
idx the index of the qubit being acted on [int]
- inverse_circuit(self: core.Circuit, circ: object) None
Inverse Circuit
This method adds the inverse of a circuit to the current circuit.
Given some collection of unitary operations,
U = U_NU_{N-1}…U_2U_1
this method appends the inverse to the circuit:
U^{-1} = U_1dg U_2dg…U_{N-1}dg U_Ndg
This may be useful for un-computing ancilla or for constructing Grovers operators.
Parameters:
circ The circuit whose inverse we want to add to the current circuit [CircuitBuilder]
- iqft(self: core.Circuit, qubits: numpy.ndarray[numpy.int32]) None
Inverse Quantum Fourier Transform
This method adds the inverse of the Quantum Fourier Transform (IQFT) to the circuit.
Parameters:
qubits the indices of the target qubits [list of int]
- mcx(self: core.Circuit, ctrl_inds: numpy.ndarray[numpy.int32], target_idx: int) None
MCX gate
This method adds a multi-controlled X (MCX) gate to the circuit.
The MCX gate performs an X gate on the target qubit conditional on all control qubits being in the 1 state.
Parameters:
ctrl_inds the indices of the control qubits [list of int]
target_idx the index of the target qubit [int]
- measure(self: core.Circuit, idx: int) None
Measurement
This method is used to indicate a qubit in the circuit should be measured.
Parameters:
idx the index of the qubit to be measured [int]
- measure_all(self: core.Circuit, NUM_QUBITS: int = - 1) None
Measure all qubits
This method adds a measurement for all qubits involved in the circuit.
Parameters:
NUM_QUBITS the number of qubits in the circuit [int] [optional, the default value of -1 becomes the output of the XACC nPhysicalBits method.]
- multiplication(self: core.Circuit, qubit_ancilla: numpy.ndarray[numpy.int32], qubits_a: numpy.ndarray[numpy.int32], qubits_b: numpy.ndarray[numpy.int32], qubits_result: int, is_LSB: bool = True) None
Multiplication
This method adds a Multiplication to the circuit.
Given two inputs a and b, computes the product a*b and stores the result on a new register.
Parameters:
qubits_a the indices of the qubits encoding a [list of int]
qubits_b the indices of the qubits encoding b [list of int]
qubits_result the indices of the qubits that will ecode the multiplication result [list of int]
qubits_ancilla the index of the single required ancilla [int]
is_LSB Indicates that the trial scores are encoded with LSB ordering [bool]
- openqasm(self: core.Circuit) str
Get the OpenQASM representation of the circuit.
- print(self: core.Circuit) None
Print the quantum circuit that has been built
- proper_fraction_division(self: core.Circuit, qubits_numerator: numpy.ndarray[numpy.int32], qubits_denominator: numpy.ndarray[numpy.int32], qubits_fraction: numpy.ndarray[numpy.int32], qubits_ancilla: numpy.ndarray[numpy.int32], is_LSB: bool = True) None
Proper Fraction Division
This method adds a proper fraction division to the circuit.
Given two inputs num and denom, calculates num/denom and stores the result in a new register, assuming denom > num
Parameters:
qubits_numerator the indices of the qubits encoding the numerator [list of int]
qubits_denominator the indices of the qubits encoding the denominator [list of int]
qubits_fraction the indices of the qubits that will ecode the division result [list of int]
qubit_ancilla the index of the required ancilla [list of int]
is_LSB Indicates that the trial scores are encoded with LSB ordering [bool]
- q_prime_unitary(self: core.Circuit, nb_qubits_ancilla_metric: int, nb_qubits_ancilla_letter: int, nb_qubits_next_letter_probabilities: int, nb_qubits_next_letter: int) None
Q’ Unitary
This method adds a Q’ unitary to the circuit.
Q’ is a unitary required for the quantum decoder algorithm.
- qft(self: core.Circuit, qubits: numpy.ndarray[numpy.int32]) None
Quantum Fourier Transform
This method adds the Quantum Fourier Transform (QFT) to the circuit. This is a quantum analogue of the discrete Fourier Transform.
Parameters:
qubits the indices of the target qubits [list of int]
- qpe(self: core.Circuit, oracle: object, precision: int, trial_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), precision_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32)) None
Quantum Phase Estimation
This method adds the Quantum Phase Estimation (QPE) sub-routine to the circuit.
Given some unitary operator U and and eigenvector v of U, QPE is used to provide a k-bit approximation to the corresponding eigenvalue’s phase, storing the result in an evaluation register whilst leaving the eigenvector unchanged.
Parameters:
oracle The unitary operator U involved in the QPE routine [CircuitBuilder]
precision The number of bits k used to approximate the phase [int]
trial_qubits The indices of the qubits encoding the eigenvector of the unitary [list of int]
precision_qubits The indices of the qubits that will be used to store the approximate phase [list of int]
- ripple_add(self: core.Circuit, a: numpy.ndarray[numpy.int32], b: numpy.ndarray[numpy.int32], carry_bit: int) None
Ripple Carry Adder
This method adds a ripple carry adder to the circuit.
The ripple carry adder is an efficient in-line addition operation with a carry-in bit.
Parameters:
a The qubit indices of the first register in the addition [list of int]
b The qubit indices of the second register in the addition. This is where the result of a+b will be stored [list of int]
carry_bit The index of the carry-in bit [int]
- run_MLQAE(self: core.Circuit, state_prep: object, oracle: object, is_in_good_subspace: Callable[[str, int], int], score_qubits: numpy.ndarray[numpy.int32], total_num_qubits: int, num_runs: int = 4, shots: int = 100, qpu: str = 'qpp') str
Run Maximum-Likelihood Amplitude Estimation
This method sets up and executes an instance of the maximum-likelihood amplitude estimation circuit.
Given a state split into a good subspace and a bad subspace, MLQAE is an alternative to canonical QAE to find an estimate for the amplitude of the good subspace, a. It works by performing several runs of amplitude amplification with various iterations and recording the number of good shots measured. Given this data, it finds the value of a that maximises the likelihood function.
Parameters:
state_prep The circuit A used to prepare the input state [CircuitBuilder]
oracle The oracle circuit O that marks the good subspace [CircuitBuilder]
is_in_good_subspace A function that, given a measured bitstring and potentially some other input value, returns a 1 if the measurement is in the good subspace and a 0 otherwise. [func(str, int) -> int]
score_qubits The indices of the qubits that determine whether the state is in the good or bad subspace [list of int]
total_num_qubits The total number of qubits in the circuit [int]
num_runs The number of runs of amplitude amplification (~4-6 is usually sufficient)
shots The number of shots in each run [int]
qpu The name of the accelerator used to execute the circuit [string]
Returns: The output buffer of the execution
- run_canonical_ae(self: core.Circuit, state_prep: object, grover_op: object, precision: int, num_state_prep_qubits: int, num_trial_qubits: int, precision_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), trial_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), qpu: str = 'qpp') str
Run Canonical Amplitude Estimation
This method sets up and executes an instance of the canonical amplitude estimation circuit.
Parameters:
state_prep The circuit A used to prepare the input state [CircuitBuilder]
grover_op The circuit for the Grovers operator Q for the good subspace [CircuitBuilder]
precision The number of bits k used to approximate the amplitude [int]
num_state_prep_qubits The number of qubits acted on by the state_prep circuit A [int]
num_trial_qubits The number of qubits acted on by the grover_op circuit Q [int]
trial_qubits The indices of the qubits acted on by the grover_op circuit Q [list of int]
precision_qubits The indices of the qubits used to store the approximate amplitude [list of int]
qpu The name of the accelerator used to execute the circuit [string]
Returns: The output buffer of the execution
- run_canonical_ae_with_oracle(self: core.Circuit, state_prep: object, oracle: object, precision: int, num_state_prep_qubits: int, num_trial_qubits: int, precision_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), trial_qubits: numpy.ndarray[numpy.int32] = array([], dtype=int32), qpu: str = 'qpp') str
Run Canonical Amplitude Estimation with Oracle
This method sets up and executes an instance of the canonical amplitude estimation circuit, but instead of providing the grovers_op Q, we provide the oracle circuit O which marks the good elements.
The Grovvers operator Q is then constructed within the method from O and the state_prep circuit A.
Parameters:
state_prep The circuit A used to prepare the input state [CircuitBuilder]
oracle The oracle circuit O that marks the good subspace [CircuitBuilder]
precision The number of bits k used to approximate the amplitude [int]
num_state_prep_qubits The number of qubits acted on by the state_prep circuit A [int]
num_trial_qubits The number of qubits acted on by the grover_op circuit Q [int]
precision_qubits The indices of the qubits used to store the approximate amplitude [list of int]
trial_qubits The indices of the qubits acted on by the grover_op circuit Q [list of int]
qpu The name of the accelerator used to execute the circuit [string]
Returns: The output buffer of the execution
- rx(self: core.Circuit, idx: int, theta: float) None
RX gate
This method adds an x-axis rotation (RX) gate to the circuit.
Parameters:
idx the index of the qubit being acted on [int]
theta the angle of rotation about the x-axis [double]
- ry(self: core.Circuit, idx: int, theta: float) None
RY gate
This method adds a y-axis rotation (RY) gate to the circuit.
Parameters:
idx the index of the qubit being acted on [int]
theta the angle of rotation about the y-axis [double]
- rz(self: core.Circuit, idx: int, theta: float) None
RZ gate
This method adds a z-axis rotation (RZ) gate to the circuit.
Parameters:
idx the index of the qubit being acted on [int]
theta the angle of rotation about the z-axis [double]
- s(self: core.Circuit, idx: int) None
S gate
This method adds an S gate to the circuit.
The S gate is defined by its action on the basis states
Parameters:
idx the index of the qubit being acted on [int]
- sdg(self: core.Circuit, idx: int) None
Sdg gate
This method adds an inverse of the S gate (Sdg) to the circuit.
Parameters:
idx the index of the qubit being acted on [int]
- subtraction(self: core.Circuit, qubits_larger: numpy.ndarray[numpy.int32], qubits_smaller: numpy.ndarray[numpy.int32], is_LSB: bool = True, qubit_ancilla: int = - 1) None
Subtraction
This method adds a subtraction to the circuit.
Given two inputs a and b, leaves b unchanged but maps a to the difference a-b, assuming a>b.
Parameters:
qubits_larger the indices of the qubits encoding the larger value [list of int]
qubits_smaller the indices of the qubits encoding the smaller value [list of int]
is_LSB Indicates that the trial scores are encoded with LSB ordering [bool]
qubit_ancilla the index of the required ancilla [list of int]
- superposition_adder(self: core.Circuit, q0: int, q1: int, q2: int, qubits_flags: numpy.ndarray[numpy.int32] = array([], dtype=int32), qubits_string: numpy.ndarray[numpy.int32] = array([], dtype=int32), qubits_metric: numpy.ndarray[numpy.int32] = array([], dtype=int32), ae_state_prep_circ: object, qubits_ancilla: numpy.ndarray[numpy.int32] = array([], dtype=int32), qubits_beam_metric: numpy.ndarray[numpy.int32] = array([], dtype=int32)) None
Superposition adder
This method adds a Superposition Adder to the circuit.
Given a superposition state, this circuit computes the mean of the amplitudes of the superposition components.
Parameters:
q0 the index of the single required ancilla [int]
q1 the index of the single required ancilla [int]
q2 the index of the single required ancilla [int]
qubits_flags the indices of the flag qubits [list of int]
qubits_string the indices of the qubits encoding the string [list of int]
qubits_metric the indices of the qubits encoding the metric value corresponding to the string [list of int]
ae_state_prep_circ The circuit A used to prepare the input state [CircuitBuilder]
qubits_ancilla the indices of the required ancilla qubits [list of int]
qubits_beam_metric the indices of the qubits encoding class’ metric [list of int]
- swap(self: core.Circuit, q1: int, q2: int) None
SWAP gate
This method adds a SWAP gate to the circuit. The SWAP gate is used to swap the quantum state of two qubits.
Parameters:
q1 the index of the first qubit [int]
q2 the index of the second qubit [int]
- t(self: core.Circuit, idx: int) None
T gate
This method adds a T gate to the circuit.
Parameters:
idx the index of the qubit being acted on [int]
- tdg(self: core.Circuit, idx: int) None
Tdg gate
This method adds an inverse of the T gate (Tdg) to the circuit.
The Tdg gate is defined by its action on the basis states
Parameters:
idx the index of the qubit being acted on [int]
- u1(self: core.Circuit, idx: int, theta: float) None
U1 gate
This method adds a phase (U1) gate to the circuit.
Parameters:
idx the index of the qubit being acted on [int]
theta the value of the phase [double]
- u3(self: core.Circuit, idx: int, theta: float, phi: float, lambda: float) None
U3 gate
This method adds an arbitrary single qubit gate (U3) to the circuit.
Parameters:
idx the index of the qubit being acted on [int]
theta [double]
phi [double]
lambda [double]
- x(self: core.Circuit, idx: int) None
Pauli-X gate
This method adds a Pauli-X (X) gate to the circuit.
The X gate is defined by its action on the basis states
- Parameters:
[int] (- idx the index of the qubit being acted on) –
- y(self: core.Circuit, idx: int) None
Pauli-Y gate
This method adds a Pauli-Y (Y) gate to the circuit.
Parameters:
idx the index of the qubit being acted on [int]
- z(self: core.Circuit, idx: int) None
Pauli-Z gate
This method adds a Pauli-Z (Z) gate to the circuit.
Parameters:
idx the index of the qubit being acted on [int]
Noise Modelling
QB Qristal allows an end-user to implement noise models in Python.
- class core.NoiseModel
Noise model class allowing specification of noise parameters and connectivity for each gate.
- add_gate_error(*args, **kwargs)
Overloaded function.
add_gate_error(self: core.NoiseModel, arg0: List[core.KrausOperator], arg1: str, arg2: core.N) -> None
Add a gate error channel for a gate operation
Parameters:
noise_channel Noise channel to be associated with the gate [List(KraussOperator)]
gate_name Name of the gates [String]
qubits Qubit indices of the gate. [qb.core.N]
add_gate_error(self: core.NoiseModel, arg0: List[core.KrausOperator], arg1: str, arg2: list) -> None
Overload of add_gate_error that takes qubits directly as List(Integer).
- add_qubit_connectivity(self: core.NoiseModel, arg0: int, arg1: int) None
Add a connected qubit pair to the topology model
Parameters:
q1 First qubit index [Integer]
q2 Second qubit index [Integer]
- property connectivity
Get connectivity as a list of connected qubit pairs
- property name
The colloquial name of the noise model
- property qobj_basis_gates
The list of basis gates that the AER QObj will be referring to.
- property qobj_compiler
‘xacc-qobj’ | ‘qristal-qobj’.
- Type:
The name of the QObj compiler to use with the AER simulator. Valid options
- set_qubit_readout_error(self: core.NoiseModel, arg0: int, arg1: core.ReadoutError) None
Set the qubit readout error
Parameters:
qubitIdx Qubit to set [Integer]
ro_error Readout error [ReadoutError]
- to_json(self: core.NoiseModel) str
Convert noise model to json string
This NoiseModel can be constructed from the quantum device NoiseProperties.
- class core.NoiseProperties
- Use NoiseProperties to accept user input parameters for custom noise models. There are 3 types of inputs used for constructing a custom noise model:
Qubit topology
Time duration of quantum gate operations
Parameters for quantum noise channels and classical errors
- property gate_pauli_errors
gate_pauli_errors is the parameter for gate error derived from randomized benchmarking of a quantum gate operation that is applied at a target set of qubits.
Unit: none (range: [0.0, 1.0])
Code example: 4 qubits: “u3” single-qubit gate, uniform gate error parameter = 0.03 (3%); “cx” between neighboring qubits (on a line), gate error parameter = 0.1 (10%):
# Initialize an empty NoiseProperties t_qbnp = NoiseProperties() t_qbnp.gate_pauli_errors["u3"] = {} t_qbnp.gate_pauli_errors["cx"] = {} num_qubits = 4 for i in range(num_qubits): t_qbnp.gate_pauli_errors["u3"][[i]] = 0.03 # Qubits on a line: if i != num_qubits - 1: t_qbnp.gate_pauli_errors["cx"][[i, i + 1]] = 0.1 # Print out the gate error map: print(t_qbnp.gate_pauli_errors)
- property gate_time_us
gate_time_us is the duration for a quantum gate operation when applied at a target set of qubits.
Unit: microseconds
Code example: 4 qubits: “u3” single-qubit gate, uniform duration of 5.2us; “cx” between neighboring qubits (on a line), uniform duration of 20us:
# Initialize an empty NoiseProperties t_qbnp = NoiseProperties() t_qbnp.gate_time_us["u3"] = {} t_qbnp.gate_time_us["cx"] = {} num_qubits = 4 for i in range(num_qubits): t_qbnp.gate_time_us["u3"][[i]] = 5.2 # Qubits on a line: if i != num_qubits - 1: t_qbnp.gate_time_us["cx"][[i, i + 1]] = 20.0 # Print out the gate time map: print(t_qbnp.gate_time_us)
- property qubit_topology
qubit_topology is a graph comprised of directed edges {control qubit, target qubit} with control qubit as the source of the edge -> target qubit as the destination of the edge.
Code example: “cx” symmetrical two-qubit gate with 4 qubits in the topology below:
# Topology # q0 <--cx--> q1 # ^ ^ # | | # cx cx # | | # v v # q3 <--cx--> q2 # Initialize an empty NoiseProperties t_qbnp = NoiseProperties() t_qbnp.qubit_topology = [[0, 1], [1, 2], [2, 3], [3, 0]]
- property readout_errors
readout_errors is the classical readout error (off-diagonal elements of the confusion matrix).
For a qubit register, with individual qubits zero-indexed by i, readout_errors is a map from qubit[i] -> ReadoutError[i].
Unit: none (quantities are probabilities).
Code example: 4-qubit device: 2 qubits (Q0 and Q1) with p(0|1) = p(1|0) = 0.05, 2 qubits (Q2 and Q3) with p(0|1) = 0.1 and p(1|0) = 0.08:
# Initialize an empty NoiseProperties t_qbnp = NoiseProperties() t_qbnpro_balanced = ReadoutError() t_qbnpro_balanced.p_01 = 0.05 t_qbnpro_balanced.p_10 = 0.05 t_qbnpro_asym = ReadoutError() t_qbnpro_asym.p_01 = 0.10 t_qbnpro_asym.p_10 = 0.08 # Q0 and Q1 readout errors t_qbnp.readout_errors[0] = t_qbnpro_balanced t_qbnp.readout_errors[1] = t_qbnpro_balanced # Q2 and Q3 readout errors t_qbnp.readout_errors[2] = t_qbnpro_asym t_qbnp.readout_errors[3] = t_qbnpro_asym
- property t1_us
\(T_1\) is the qubit relaxation time.
For a qubit register, with individual qubits zero-indexed by i; t1_us is a map from qubit[i] -> T1[i].
Unit: microseconds
Code example: 4 qubits all with T1 = 1.5us:
# Initialize an empty NoiseProperties t_qbnp = NoiseProperties() # Set T1 of qubits (all with 1.5 us) for i in range(4): t_qbnp.t1_us[i] = 1.5
- property t2_us
\(T_2\) is the qubit dephasing time.
For a qubit register, with individual qubits zero-indexed by i; t2_us is a map from qubit[i] -> T2[i].
Unit: microseconds
Code example: 4 qubits all with T2 = 0.15us:
# Initialize an empty NoiseProperties t_qbnp = NoiseProperties() # Set T2 of qubits (all with 0.15 us) for i in range(4): t_qbnp.t2_us[i] = 0.15
Additionally, users can use these builtin classes to construct commonly-used noise channels when building the NoiseModel.
- class core.AmplitudeDampingChannel
Amplitude damping channel factory
- Create(self: int, arg0: float) List[core.KrausOperator]
- class core.PhaseDampingChannel
Phase damping channel factory
- Create(self: int, arg0: float) List[core.KrausOperator]
- class core.DepolarizingChannel
Depolarizing channel factory
- Create(*args, **kwargs)
Overloaded function.
Create(self: int, arg0: float) -> List[core.KrausOperator]
Create single-qubit depolarizing channel (balanced/symmetric)
Parameters:
q Qubit index
p Total depolarizing probability
Create(self: int, arg0: int, arg1: float) -> List[core.KrausOperator]
Create two-qubit depolarizing channel (balanced/symmetric)
Parameters:
q1 First qubit
q2 Second qubit
p Total depolarizing probability
- class core.GeneralizedPhaseAmplitudeDampingChannel
Generalized Single-qubit combined phase and amplitude damping quantum error channel
- Create(self: int, arg0: float, arg1: float, arg2: float) List[core.KrausOperator]
Create a generalized amplitude and phase damping channel
Parameters:
q Qubit
excited_state_population Excited state population
param_amp Amplitude damping parameter
param_phase Phase damping parameter
- class core.GeneralizedAmplitudeDampingChannel
Generalized amplitude damping quantum error channel
- Create(self: int, arg0: float, arg1: float) List[core.KrausOperator]
Create a generalized amplitude damping channel
Parameters:
q Qubit
excited_state_population Excited state population
param_amp Amplitude damping parameter
- class core.ReadoutError
Probabilities of reading out a value for a qubit that does not reflect its true state.
- property p_01
Classical probability of detecting 0 whereas the true state was \(|1\rangle\)
- property p_10
Classical probability of detecting 1 whereas the true state was \(|0\rangle\)
In case no builtin noise channels are available for your use case, a fully-customized noise channel can be constructed in terms of instances of the KrausOperator class.
Placement
Qristal contains placement methods to perform mapping from program (logical) qubits to device (physical) qubits satisfying qubit connectivity constraints.
Noise-aware placement
The noise_aware_placement_pass takes into account gate error rates and readout errors to find the best placement map.
- class core.noise_aware_placement_pass
The noise_aware_placement_pass class uses device connectivity, gate errors (1-q and 2-q) and readout errors to find the best placement map.
- apply(self: core.noise_aware_placement_pass, circuit: qb::CircuitBuilder) None
Apply noise-aware placement on the input circuit.
- Parameters:
circuit – Circuit to be placed (map qubit indices and inject SWAP gates as necessary)
Device configuration for the noise-aware placement is defined by noise_aware_placement_config.
- class core.noise_aware_placement_config
The noise_aware_placement_config class encapsulates generic backend information required by the noise-aware placement pass.
Swap-based placement
The swap_placement_pass performs circuit placement by swapping qubits (along the shortest possible path) when there are gates between uncoupled qubits.
- class core.swap_placement_pass
Circuit placement pass based on injection of SWAP gates to satisfy device connectivity topology.
- apply(self: core.swap_placement_pass, circuit: qb::CircuitBuilder) None
Apply SWAP-based placement on the input circuit.
- Parameters:
circuit – Circuit to be placed (map qubit indices and inject SWAP gates as necessary)