scikit_quri.circuit package

Submodules

scikit_quri.circuit.circuit module

class scikit_quri.circuit.circuit.LearningCircuit(n_qubits)

Bases: object

Parametric quantum circuit for quantum machine learning.

Manages three types of circuit parameters:

• Fixed gates: Non-parametric gates (X, Y, Z, H, CNOT, etc.).

• Input gates (add_input_R*): Rotation angle is computed from input data x via a user-supplied function at inference time.

• Learnable gates (add_parametric_R*): Rotation angle is a trainable parameter updated during optimization. Multiple gates can share a single parameter via share_with / share_with_coef.

• Parametric-input gates (add_parametric_input_R*): Angle depends on both a learnable parameter and input data (e.g. f(theta, x)).

Parameters:

n_qubits (int) – Number of qubits in the circuit.

Example

>>> circuit = LearningCircuit(n_qubits=4)
>>> circuit.add_input_RY_gate(0, lambda x: np.arcsin(x[0]))
>>> param_id = circuit.add_parametric_RX_gate(1)
>>> bound = circuit.bind_input_and_parameters(x, theta)

n_qubits: int

circuit: ParametricQuantumCircuit

add_gate(gate)

Add arbitrary gate.

Parameters:

gate (QuantumGate) –

Return type:

None

add_X_gate(index)

Parameters:

index (int) –

Return type:

None

add_Y_gate(index)

Parameters:

index (int) –

Return type:

None

add_Z_gate(index)

Parameters:

index (int) –

Return type:

None

add_RX_gate(index, angle)

Parameters:

• index (int) –

• angle (float) –

Return type:

None

add_RY_gate(index, angle)

Parameters:

• index (int) –

• angle (float) –

Return type:

None

add_RZ_gate(index, angle)

Parameters:

• index (int) –

• angle (float) –

Return type:

None

add_CNOT_gate(control_index, target_index)

Parameters:

• control_index (int) –

• target_index (int) –

Return type:

None

add_H_gate(index)

Parameters:

index (int) –

Return type:

None

add_input_RX_gate(qubit, input_function)

Add an RX gate whose angle is determined by input data at inference time.

Parameters:

• qubit (int) –

• input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

add_input_RY_gate(qubit, input_function)

Add an RY gate whose angle is determined by input data at inference time.

Parameters:

• qubit (int) –

• input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

add_input_RZ_gate(qubit, input_function)

Add an RZ gate whose angle is determined by input data at inference time.

Parameters:

• qubit (int) –

• input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

add_parametric_RX_gate(qubit, share_with=None, share_with_coef=None)

Add a trainable RX gate and return its parameter ID.

Parameters:

• qubit (int) – Index of the target qubit.

• share_with (Optional[int]) – If given, share the learnable parameter with the gate whose parameter_id equals share_with.

• share_with_coef (Optional[float]) – Coefficient applied to the shared parameter value (angle = shared_value * coef). Used only when share_with is set.

Returns:

Index of the learnable parameter assigned to this gate.

Return type:

parameter_id

add_parametric_RY_gate(qubit, share_with=None, share_with_coef=None)

Add a trainable RY gate and return its parameter ID.

Parameters:

• qubit (int) –

• share_with (Optional[int]) –

• share_with_coef (Optional[float]) –

Return type:

int

add_parametric_RZ_gate(qubit, share_with=None, share_with_coef=None)

Add a trainable RZ gate and return its parameter ID.

Parameters:

• qubit (int) –

• share_with (Optional[int]) –

• share_with_coef (Optional[float]) –

Return type:

int

add_parametric_multi_Pauli_rotation_gate(targets, pauli_ids)

Add a trainable multi-qubit Pauli rotation gate.

Note: this gate is not integrated with the share_with mechanism.

Parameters:

• targets (List[int]) –

• pauli_ids (List[int]) –

Return type:

Parameter

add_parametric_input_RX_gate(index, input_func=<function LearningCircuit.<lambda>>)

Add an RX gate whose angle depends on both a learnable parameter and input data.

Parameters:

• index (int) –

• input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

add_parametric_input_RY_gate(index, input_func=<function LearningCircuit.<lambda>>)

Add an RY gate whose angle depends on both a learnable parameter and input data.

Parameters:

• index (int) –

• input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

add_parametric_input_RZ_gate(index, input_func=<function LearningCircuit.<lambda>>)

Add an RZ gate whose angle depends on both a learnable parameter and input data.

Parameters:

• index (int) –

• input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

property parameter_count: int

Total number of parametric slots in the underlying circuit (input + learnable).

property input_params_count: int

Number of input-data-driven parameters.

property learning_params_count: int

Number of unique learnable parameters (i.e. the length of the theta vector).

get_learning_params_indexes()

Circuit-level indices of all learnable parameter slots.

Positions belonging to the same parameter via share_with appear separately.

Return type:

List[int]

get_minimum_learning_param_indexes()

One representative circuit-level index per unique learnable parameter.

Return type:

List[int]

get_input_params_indexes()

Circuit-level indices of all input-data-driven parameter slots.

Return type:

List[int]

get_learning_param_grad_aggregators()

For each learning parameter, list (gate_pos, coef) tuples that must be summed to compose the per-learning-param gradient from per-gate gradients. share_with produces multiple entries per learning param.

Return type:

List[List[Tuple[int, float]]]

bind_input_and_parameters(x, parameters)

Bind input data and learnable parameters to produce a concrete circuit.

Parameters:

• x (ndarray[tuple[int, ...], dtype[float64]]) –

• parameters (ndarray[tuple[int, ...], dtype[float64]]) –

Return type:

ImmutableBoundParametricQuantumCircuit

generate_bound_params(x, parameters)

Compute the full gate-level parameter list from input data and learnable parameters.

Parameters:

• x (ndarray[tuple[int, ...], dtype[float64]]) –

• parameters (ndarray[tuple[int, ...], dtype[float64]]) –

Return type:

Sequence[float]

to_batched(data, parameters)

Build a batched parameter array for use with scaluq (quri-parts-scaluq).

Returns:

Tuple of (circuit, batched_params) where batched_params has shape (n_data, parameter_count).

Parameters:

• data (ndarray[tuple[int, ...], dtype[float64]]) –

• parameters (ndarray[tuple[int, ...], dtype[float64]]) –

Return type:

Tuple[ParametricQuantumCircuit, ndarray[tuple[int, …], dtype[float64]]]

to_batched_for_gradient(data, parameters, delta=1e-05)

Build shifted parameter arrays for numerical gradient estimation.

For each sample and each learning parameter, creates two rows with the parameter shifted by +delta/2 and -delta/2.

Row layout: for sample i and learning param j,

plus row = i * 2 * learning_params_count + 2 * j minus row = i * 2 * learning_params_count + 2 * j + 1

Parameters:

• data (ndarray[tuple[int, ...], dtype[float64]]) –

• parameters (ndarray[tuple[int, ...], dtype[float64]]) –

• delta (float) –

Return type:

Tuple[ParametricQuantumCircuit, ndarray[tuple[int, …], dtype[float64]]]

backprop_inner_product(x, theta, state)

Compute gradients of learnable parameters via qulacs backpropagation using inner product.

Thin delegator to scikit_quri.circuit.gradient.backprop_inner_product().

Parameters:

• x (NDArray[np.float64]) –

• theta (NDArray[np.float64]) –

• state (QulacsQuantumState) –

Return type:

NDArray[np.float64]

backprop_innner_product(x, theta, state)

Compute gradients of learnable parameters via qulacs backpropagation using inner product.

Thin delegator to scikit_quri.circuit.gradient.backprop_inner_product().

Parameters:

• x (NDArray[np.float64]) –

• theta (NDArray[np.float64]) –

• state (QulacsQuantumState) –

Return type:

NDArray[np.float64]

hadamard_gradient(x, theta, operator, estimator)

Compute gradients of learnable parameters via the Hadamard test.

Thin delegator to scikit_quri.circuit.gradient.hadamard_gradient().

Parameters:

• x (NDArray[np.float64]) –

• theta (NDArray[np.float64]) –

• operator (Operator) –

• estimator (ConcurrentQuantumEstimator) –

Return type:

NDArray[np.float64]

scikit_quri.circuit.pre_defined module

scikit_quri.circuit.pre_defined.CNOT()

scikit_quri.circuit.pre_defined.CZ()

scikit_quri.circuit.pre_defined.create_qcl_ansatz(n_qubit, c_depth, time_step=0.5, seed=0)

Create a circuit used in this page: https://dojo.qulacs.org/ja/latest/notebooks/5.2_Quantum_Circuit_Learning.html

Parameters:

• n_qubit (int) – number of qubits

• c_depth (int) – circuit depth

• time_step (float) – the evolution time used for the hamiltonian dynamics

• seed (Optional[int]) – seed for random numbers. used for determining the interaction strength of the hamiltonian simulation

Return type:

LearningCircuit

Examples

>>> n_qubit = 4
>>> circuit = create_qcl_ansatz(n_qubit, 3, 0.5)
>>> qnn = QNNRegressor(circuit)
>>> qnn.fit(x_train, y_train)

scikit_quri.circuit.pre_defined.create_farhi_neven_ansatz(n_qubit, c_depth, seed=0)

Parameters:

• n_qubit (int) –

• c_depth (int) –

• seed (Optional[int]) –

Return type:

LearningCircuit

scikit_quri.circuit.pre_defined.create_ibm_embedding_circuit(n_qubit)

Create circuit proposed in https://arxiv.org/abs/1802.06002.

Parameters:

• n_qubits – number of qubits

• n_qubit (int) –

Return type:

LearningCircuit

scikit_quri.circuit.pre_defined.create_dqn_cl(n_qubit, c_depth, s_qubit)

Parameters:

• n_qubit (int) –

• c_depth (int) –

• s_qubit (int) –

Return type:

LearningCircuit

scikit_quri.circuit.pre_defined.create_dqn_cl_no_cz(n_qubit, c_depth)

Parameters:

• n_qubit (int) –

• c_depth (int) –

Return type:

LearningCircuit

scikit_quri.circuit.pre_defined.create_qcnn_ansatz(n_qubit, seed=0)

Creates circuit used in https://www.tensorflow.org/quantum/tutorials/qcnn?hl=en, Section 1.

Parameters:

• n_qubit (int) – number of qubits. must be even.

• seed (Optional[int]) – seed for random numbers. used for determining the interaction strength of the hamiltonian simulation

Return type:

LearningCircuit

Module contents

class scikit_quri.circuit.LearningCircuit(n_qubits)

Bases: object

Parametric quantum circuit for quantum machine learning.

Manages three types of circuit parameters:

• Fixed gates: Non-parametric gates (X, Y, Z, H, CNOT, etc.).

• Input gates (add_input_R*): Rotation angle is computed from input data x via a user-supplied function at inference time.

• Learnable gates (add_parametric_R*): Rotation angle is a trainable parameter updated during optimization. Multiple gates can share a single parameter via share_with / share_with_coef.

• Parametric-input gates (add_parametric_input_R*): Angle depends on both a learnable parameter and input data (e.g. f(theta, x)).

Parameters:

n_qubits (int) – Number of qubits in the circuit.

Example

>>> circuit = LearningCircuit(n_qubits=4)
>>> circuit.add_input_RY_gate(0, lambda x: np.arcsin(x[0]))
>>> param_id = circuit.add_parametric_RX_gate(1)
>>> bound = circuit.bind_input_and_parameters(x, theta)

n_qubits: int

circuit: ParametricQuantumCircuit

add_gate(gate)

Add arbitrary gate.

Parameters:

gate (QuantumGate) –

Return type:

None

add_X_gate(index)

Parameters:

index (int) –

Return type:

None

add_Y_gate(index)

Parameters:

index (int) –

Return type:

None

add_Z_gate(index)

Parameters:

index (int) –

Return type:

None

add_RX_gate(index, angle)

Parameters:

• index (int) –

• angle (float) –

Return type:

None

add_RY_gate(index, angle)

Parameters:

• index (int) –

• angle (float) –

Return type:

None

add_RZ_gate(index, angle)

Parameters:

• index (int) –

• angle (float) –

Return type:

None

add_CNOT_gate(control_index, target_index)

Parameters:

• control_index (int) –

• target_index (int) –

Return type:

None

add_H_gate(index)

Parameters:

index (int) –

Return type:

None

add_input_RX_gate(qubit, input_function)

Add an RX gate whose angle is determined by input data at inference time.

Parameters:

• qubit (int) –

• input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

add_input_RY_gate(qubit, input_function)

Add an RY gate whose angle is determined by input data at inference time.

Parameters:

• qubit (int) –

• input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

add_input_RZ_gate(qubit, input_function)

Add an RZ gate whose angle is determined by input data at inference time.

Parameters:

• qubit (int) –

• input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

add_parametric_RX_gate(qubit, share_with=None, share_with_coef=None)

Add a trainable RX gate and return its parameter ID.

Parameters:

• qubit (int) – Index of the target qubit.

• share_with (Optional[int]) – If given, share the learnable parameter with the gate whose parameter_id equals share_with.

• share_with_coef (Optional[float]) – Coefficient applied to the shared parameter value (angle = shared_value * coef). Used only when share_with is set.

Returns:

Index of the learnable parameter assigned to this gate.

Return type:

parameter_id

add_parametric_RY_gate(qubit, share_with=None, share_with_coef=None)

Add a trainable RY gate and return its parameter ID.

Parameters:

• qubit (int) –

• share_with (Optional[int]) –

• share_with_coef (Optional[float]) –

Return type:

int

add_parametric_RZ_gate(qubit, share_with=None, share_with_coef=None)

Add a trainable RZ gate and return its parameter ID.

Parameters:

• qubit (int) –

• share_with (Optional[int]) –

• share_with_coef (Optional[float]) –

Return type:

int

add_parametric_multi_Pauli_rotation_gate(targets, pauli_ids)

Add a trainable multi-qubit Pauli rotation gate.

Note: this gate is not integrated with the share_with mechanism.

Parameters:

• targets (List[int]) –

• pauli_ids (List[int]) –

Return type:

Parameter

add_parametric_input_RX_gate(index, input_func=<function LearningCircuit.<lambda>>)

Add an RX gate whose angle depends on both a learnable parameter and input data.

Parameters:

• index (int) –

• input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

add_parametric_input_RY_gate(index, input_func=<function LearningCircuit.<lambda>>)

Add an RY gate whose angle depends on both a learnable parameter and input data.

Parameters:

• index (int) –

• input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

add_parametric_input_RZ_gate(index, input_func=<function LearningCircuit.<lambda>>)

Add an RZ gate whose angle depends on both a learnable parameter and input data.

Parameters:

• index (int) –

• input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) –

Return type:

None

property parameter_count: int

Total number of parametric slots in the underlying circuit (input + learnable).

property input_params_count: int

Number of input-data-driven parameters.

property learning_params_count: int

Number of unique learnable parameters (i.e. the length of the theta vector).

get_learning_params_indexes()

Circuit-level indices of all learnable parameter slots.

Positions belonging to the same parameter via share_with appear separately.

Return type:

List[int]

get_minimum_learning_param_indexes()

One representative circuit-level index per unique learnable parameter.

Return type:

List[int]

get_input_params_indexes()

Circuit-level indices of all input-data-driven parameter slots.

Return type:

List[int]

get_learning_param_grad_aggregators()

For each learning parameter, list (gate_pos, coef) tuples that must be summed to compose the per-learning-param gradient from per-gate gradients. share_with produces multiple entries per learning param.

Return type:

List[List[Tuple[int, float]]]

bind_input_and_parameters(x, parameters)

Bind input data and learnable parameters to produce a concrete circuit.

Parameters:

• x (ndarray[tuple[int, ...], dtype[float64]]) –

• parameters (ndarray[tuple[int, ...], dtype[float64]]) –

Return type:

ImmutableBoundParametricQuantumCircuit

generate_bound_params(x, parameters)

Compute the full gate-level parameter list from input data and learnable parameters.

Parameters:

• x (ndarray[tuple[int, ...], dtype[float64]]) –

• parameters (ndarray[tuple[int, ...], dtype[float64]]) –

Return type:

Sequence[float]

to_batched(data, parameters)

Build a batched parameter array for use with scaluq (quri-parts-scaluq).

Returns:

Tuple of (circuit, batched_params) where batched_params has shape (n_data, parameter_count).

Parameters:

• data (ndarray[tuple[int, ...], dtype[float64]]) –

• parameters (ndarray[tuple[int, ...], dtype[float64]]) –

Return type:

Tuple[ParametricQuantumCircuit, ndarray[tuple[int, …], dtype[float64]]]

to_batched_for_gradient(data, parameters, delta=1e-05)

Build shifted parameter arrays for numerical gradient estimation.

For each sample and each learning parameter, creates two rows with the parameter shifted by +delta/2 and -delta/2.

Row layout: for sample i and learning param j,

plus row = i * 2 * learning_params_count + 2 * j minus row = i * 2 * learning_params_count + 2 * j + 1

Parameters:

• data (ndarray[tuple[int, ...], dtype[float64]]) –

• parameters (ndarray[tuple[int, ...], dtype[float64]]) –

• delta (float) –

Return type:

Tuple[ParametricQuantumCircuit, ndarray[tuple[int, …], dtype[float64]]]

backprop_inner_product(x, theta, state)

Compute gradients of learnable parameters via qulacs backpropagation using inner product.

Thin delegator to scikit_quri.circuit.gradient.backprop_inner_product().

Parameters:

• x (NDArray[np.float64]) –

• theta (NDArray[np.float64]) –

• state (QulacsQuantumState) –

Return type:

NDArray[np.float64]

backprop_innner_product(x, theta, state)

Compute gradients of learnable parameters via qulacs backpropagation using inner product.

Thin delegator to scikit_quri.circuit.gradient.backprop_inner_product().

Parameters:

• x (NDArray[np.float64]) –

• theta (NDArray[np.float64]) –

• state (QulacsQuantumState) –

Return type:

NDArray[np.float64]

hadamard_gradient(x, theta, operator, estimator)

Compute gradients of learnable parameters via the Hadamard test.

Thin delegator to scikit_quri.circuit.gradient.hadamard_gradient().

Parameters:

• x (NDArray[np.float64]) –

• theta (NDArray[np.float64]) –

• operator (Operator) –

• estimator (ConcurrentQuantumEstimator) –

Return type:

NDArray[np.float64]

scikit_quri.circuit.create_qcl_ansatz(n_qubit, c_depth, time_step=0.5, seed=0)

Create a circuit used in this page: https://dojo.qulacs.org/ja/latest/notebooks/5.2_Quantum_Circuit_Learning.html

Parameters:

• n_qubit (int) – number of qubits

• c_depth (int) – circuit depth

• time_step (float) – the evolution time used for the hamiltonian dynamics

• seed (Optional[int]) – seed for random numbers. used for determining the interaction strength of the hamiltonian simulation

Return type:

LearningCircuit

Examples

>>> n_qubit = 4
>>> circuit = create_qcl_ansatz(n_qubit, 3, 0.5)
>>> qnn = QNNRegressor(circuit)
>>> qnn.fit(x_train, y_train)

scikit_quri.circuit.create_farhi_neven_ansatz(n_qubit, c_depth, seed=0)

Parameters:

• n_qubit (int) –

• c_depth (int) –

• seed (Optional[int]) –

Return type:

LearningCircuit

scikit_quri.circuit.create_ibm_embedding_circuit(n_qubit)

Create circuit proposed in https://arxiv.org/abs/1802.06002.

Parameters:

• n_qubits – number of qubits

• n_qubit (int) –

Return type:

LearningCircuit