scikit_quri.circuit package

Contents

scikit_quri.circuit package#

Submodules#

scikit_quri.circuit.circuit module#

scikit_quri.circuit.circuit.need_learning_parameter_guard(func, companion_parameter_id)[source]#
Parameters:
Return type:

TypeGuard[Callable[[ndarray[tuple[int, …], dtype[float64]]], float]]

scikit_quri.circuit.circuit.not_needed_learning_parameter_guard(func, companion_parameter_id)[source]#
Parameters:
Return type:

TypeGuard[Callable[[float, ndarray[tuple[int, …], dtype[float64]]], float]]

class scikit_quri.circuit.circuit.LearningCircuit(n_qubits)[source]#

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#
input_functions: dict[int, Callable[[numpy.ndarray[tuple[int, ...], numpy.dtype[numpy.float64]]], float]]#
add_gate(gate)[source]#

Add arbitrary gate.

Parameters:

gate (QuantumGate) – Gate to add.

Return type:

None

add_X_gate(index)[source]#
Parameters:

index (int) – Index of qubit to add X gate.

Return type:

None

add_Y_gate(index)[source]#
Parameters:

index (int) – Index of qubit to add Y gate.

Return type:

None

add_Z_gate(index)[source]#
Parameters:

index (int) – Index of qubit to add Z gate.

Return type:

None

add_RX_gate(index, angle)[source]#
Parameters:

  • index (int) – Index of qubit to add RX gate.

  • angle (float) – Rotation angle.

Return type:

None

add_RY_gate(index, parameter)[source]#
Parameters:

  • index (int) – Index of qubit to add RY gate.

  • angle – Rotation angle.

  • parameter (float) –

Return type:

None

add_RZ_gate(index, parameter)[source]#
Parameters:

  • index (int) – Index of qubit to add RZ gate.

  • angle – Rotation angle.

  • parameter (float) –

Return type:

None

add_CNOT_gate(control_index, target_index)[source]#
Parameters:

  • control_index (int) – Index of control qubit.

  • target_index (int) – Index of target qubit.

Return type:

None

add_H_gate(index)[source]#
Parameters:

index (int) – Index of qubit to put H gate.

Return type:

None

add_input_RX_gate(qubit, input_function)[source]#

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

Parameters:

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

  • input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(x) -> float that maps input data to the rotation angle.

Return type:

None

add_input_RY_gate(qubit, input_function)[source]#

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

Parameters:

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

  • input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(x) -> float that maps input data to the rotation angle.

Return type:

None

add_input_RZ_gate(qubit, input_function)[source]#

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

Parameters:

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

  • input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(x) -> float that maps input data to the rotation angle.

Return type:

None

add_parametric_RX_gate(qubit, share_with=None, share_with_coef=None)[source]#

Add a trainable RX gate and return its parameter ID.

Parameters:

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

  • share_with (Optional[int]) – If given, this gate shares 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). Only used 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)[source]#

Add a trainable RY gate and return its parameter ID.

Parameters:

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

  • share_with (Optional[int]) – If given, this gate shares 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). Only used when share_with is set.

Returns:

Index of the learnable parameter assigned to this gate.

Return type:

parameter_id

add_parametric_RZ_gate(qubit, share_with=None, share_with_coef=None)[source]#

Add a trainable RZ gate and return its parameter ID.

Parameters:

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

  • share_with (Optional[int]) – If given, this gate shares 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). Only used when share_with is set.

Returns:

Index of the learnable parameter assigned to this gate.

Return type:

parameter_id

add_parametric_multi_Pauli_rotation_gate(targets, pauli_ids)[source]#

Add a trainable multi-qubit Pauli rotation gate.

Parameters:

  • targets (List[int]) – List of target qubit indices.

  • pauli_ids (List[int]) – List of Pauli operator IDs for each target qubit (1=X, 2=Y, 3=Z).

Returns:

The Parameter object associated with this gate.

Return type:

Parameter

add_parametric_input_RX_gate(index, input_func=<function LearningCircuit.<lambda>>)[source]#

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

Parameters:

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

  • input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(theta, x) -> float that computes the rotation angle from the current learnable parameter value and input data. Defaults to lambda theta, x: x[0].

Return type:

None

add_parametric_input_RY_gate(index, input_func=<function LearningCircuit.<lambda>>)[source]#

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

Parameters:

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

  • input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(theta, x) -> float that computes the rotation angle from the current learnable parameter value and input data. Defaults to lambda theta, x: x[0].

Return type:

None

add_parametric_input_RZ_gate(index, input_func=<function LearningCircuit.<lambda>>)[source]#

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

Parameters:

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

  • input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(theta, x) -> float that computes the rotation angle from the current learnable parameter value and input data. Defaults to lambda theta, x: x[0].

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()[source]#

Return circuit-level indices of all learnable parameter slots. A single learnable parameter may occupy multiple slots when share_with is used.

Returns:

List of gate-position indices for every learnable slot in the circuit.

Return type:

List[int]

get_minimum_learning_param_indexes()[source]#

Return the minimal set of circuit-level indices needed to represent all learnable parameters. Returns only the first slot for each learnable parameter, ignoring shared duplicates.

Returns:

List of gate-position indices, one per unique learnable parameter.

Return type:

List[int]

get_input_params_indexes()[source]#

Return circuit-level indices of all input-data-driven parameter slots.

Returns:

List of gate-position indices for every input parameter slot in the circuit.

Return type:

List[int]

bind_input_and_parameters(x, parameters)[source]#

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

Parameters:
Returns:

A fully bound (non-parametric) quantum circuit.

Return type:

ImmutableBoundParametricQuantumCircuit

generate_bound_params(x, parameters)[source]#

Compute the full parameter list to bind to the circuit from input data and learnable parameters.

Parameters:
Returns:

Sequence of float values with length parameter_count, ready to pass to circuit.bind_parameters().

Return type:

Sequence[float]

backprop_innner_product(x, theta, state)[source]#

Compute gradients of learnable parameters via qulacs backpropagation using inner product. Converts the circuit to qulacs format and calls backprop_inner_product.

Parameters:

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

  • theta (ndarray[tuple[int, ...], dtype[float64]]) – Learnable parameter vector of length learning_params_count.

  • state (QuantumState) – Target qulacs quantum state used in the inner product.

Returns:

Gradient array of shape (learning_params_count,).

Return type:

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

hadamard_gradient(x, theta, operator, estimator)[source]#

Compute gradients of learnable parameters via the Hadamard test.

For each learnable parameter θ_j, estimates ∂⟨O⟩/∂θ_j = ⟨O ⊗ Y⟩ on the Hadamard-test circuit, where the ancilla qubit is index n_qubits.

Parameters:
Returns:

Gradient array of shape (learning_params_count,).

Return type:

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

to_batched(data, parameters)[source]#

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

Parameters:

  • data (ndarray[tuple[int, ...], dtype[float64]]) – Input data array of shape (n_data, n_features).

  • parameters (ndarray[tuple[int, ...], dtype[float64]]) – Learnable parameter vector of shape (n_params,).

Returns:

Tuple of (circuit, batched_params) where batched_params has shape (n_data, parameter_count) with each row ready to bind to the circuit.

Return type:

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

scikit_quri.circuit.circuit.preprocess_x(x, i)[source]#
Parameters:
Return type:

float

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)[source]#

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.preprocess_x(x, i)[source]#
Parameters:
Return type:

float

scikit_quri.circuit.pre_defined.create_farhi_neven_ansatz(n_qubit, c_depth, seed=0)[source]#
Parameters:
Return type:

LearningCircuit

scikit_quri.circuit.pre_defined.create_ibm_embedding_circuit(n_qubit)[source]#

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)[source]#
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)[source]#
Parameters:

  • n_qubit (int) –

  • c_depth (int) –

Return type:

LearningCircuit

scikit_quri.circuit.pre_defined.create_qcnn_ansatz(n_qubit, seed=0)[source]#

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)[source]#

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#
input_functions: dict[int, Callable[[numpy.ndarray[tuple[int, ...], numpy.dtype[numpy.float64]]], float]]#
add_gate(gate)[source]#

Add arbitrary gate.

Parameters:

gate (QuantumGate) – Gate to add.

Return type:

None

add_X_gate(index)[source]#
Parameters:

index (int) – Index of qubit to add X gate.

Return type:

None

add_Y_gate(index)[source]#
Parameters:

index (int) – Index of qubit to add Y gate.

Return type:

None

add_Z_gate(index)[source]#
Parameters:

index (int) – Index of qubit to add Z gate.

Return type:

None

add_RX_gate(index, angle)[source]#
Parameters:

  • index (int) – Index of qubit to add RX gate.

  • angle (float) – Rotation angle.

Return type:

None

add_RY_gate(index, parameter)[source]#
Parameters:

  • index (int) – Index of qubit to add RY gate.

  • angle – Rotation angle.

  • parameter (float) –

Return type:

None

add_RZ_gate(index, parameter)[source]#
Parameters:

  • index (int) – Index of qubit to add RZ gate.

  • angle – Rotation angle.

  • parameter (float) –

Return type:

None

add_CNOT_gate(control_index, target_index)[source]#
Parameters:

  • control_index (int) – Index of control qubit.

  • target_index (int) – Index of target qubit.

Return type:

None

add_H_gate(index)[source]#
Parameters:

index (int) – Index of qubit to put H gate.

Return type:

None

add_input_RX_gate(qubit, input_function)[source]#

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

Parameters:

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

  • input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(x) -> float that maps input data to the rotation angle.

Return type:

None

add_input_RY_gate(qubit, input_function)[source]#

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

Parameters:

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

  • input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(x) -> float that maps input data to the rotation angle.

Return type:

None

add_input_RZ_gate(qubit, input_function)[source]#

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

Parameters:

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

  • input_function (Callable[[ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(x) -> float that maps input data to the rotation angle.

Return type:

None

add_parametric_RX_gate(qubit, share_with=None, share_with_coef=None)[source]#

Add a trainable RX gate and return its parameter ID.

Parameters:

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

  • share_with (Optional[int]) – If given, this gate shares 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). Only used 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)[source]#

Add a trainable RY gate and return its parameter ID.

Parameters:

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

  • share_with (Optional[int]) – If given, this gate shares 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). Only used when share_with is set.

Returns:

Index of the learnable parameter assigned to this gate.

Return type:

parameter_id

add_parametric_RZ_gate(qubit, share_with=None, share_with_coef=None)[source]#

Add a trainable RZ gate and return its parameter ID.

Parameters:

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

  • share_with (Optional[int]) – If given, this gate shares 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). Only used when share_with is set.

Returns:

Index of the learnable parameter assigned to this gate.

Return type:

parameter_id

add_parametric_multi_Pauli_rotation_gate(targets, pauli_ids)[source]#

Add a trainable multi-qubit Pauli rotation gate.

Parameters:

  • targets (List[int]) – List of target qubit indices.

  • pauli_ids (List[int]) – List of Pauli operator IDs for each target qubit (1=X, 2=Y, 3=Z).

Returns:

The Parameter object associated with this gate.

Return type:

Parameter

add_parametric_input_RX_gate(index, input_func=<function LearningCircuit.<lambda>>)[source]#

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

Parameters:

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

  • input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(theta, x) -> float that computes the rotation angle from the current learnable parameter value and input data. Defaults to lambda theta, x: x[0].

Return type:

None

add_parametric_input_RY_gate(index, input_func=<function LearningCircuit.<lambda>>)[source]#

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

Parameters:

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

  • input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(theta, x) -> float that computes the rotation angle from the current learnable parameter value and input data. Defaults to lambda theta, x: x[0].

Return type:

None

add_parametric_input_RZ_gate(index, input_func=<function LearningCircuit.<lambda>>)[source]#

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

Parameters:

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

  • input_func (Callable[[float, ndarray[tuple[int, ...], dtype[float64]]], float]) – Function f(theta, x) -> float that computes the rotation angle from the current learnable parameter value and input data. Defaults to lambda theta, x: x[0].

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()[source]#

Return circuit-level indices of all learnable parameter slots. A single learnable parameter may occupy multiple slots when share_with is used.

Returns:

List of gate-position indices for every learnable slot in the circuit.

Return type:

List[int]

get_minimum_learning_param_indexes()[source]#

Return the minimal set of circuit-level indices needed to represent all learnable parameters. Returns only the first slot for each learnable parameter, ignoring shared duplicates.

Returns:

List of gate-position indices, one per unique learnable parameter.

Return type:

List[int]

get_input_params_indexes()[source]#

Return circuit-level indices of all input-data-driven parameter slots.

Returns:

List of gate-position indices for every input parameter slot in the circuit.

Return type:

List[int]

bind_input_and_parameters(x, parameters)[source]#

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

Parameters:
Returns:

A fully bound (non-parametric) quantum circuit.

Return type:

ImmutableBoundParametricQuantumCircuit

generate_bound_params(x, parameters)[source]#

Compute the full parameter list to bind to the circuit from input data and learnable parameters.

Parameters:
Returns:

Sequence of float values with length parameter_count, ready to pass to circuit.bind_parameters().

Return type:

Sequence[float]

backprop_innner_product(x, theta, state)[source]#

Compute gradients of learnable parameters via qulacs backpropagation using inner product. Converts the circuit to qulacs format and calls backprop_inner_product.

Parameters:

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

  • theta (ndarray[tuple[int, ...], dtype[float64]]) – Learnable parameter vector of length learning_params_count.

  • state (QuantumState) – Target qulacs quantum state used in the inner product.

Returns:

Gradient array of shape (learning_params_count,).

Return type:

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

hadamard_gradient(x, theta, operator, estimator)[source]#

Compute gradients of learnable parameters via the Hadamard test.

For each learnable parameter θ_j, estimates ∂⟨O⟩/∂θ_j = ⟨O ⊗ Y⟩ on the Hadamard-test circuit, where the ancilla qubit is index n_qubits.

Parameters:
Returns:

Gradient array of shape (learning_params_count,).

Return type:

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

to_batched(data, parameters)[source]#

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

Parameters:

  • data (ndarray[tuple[int, ...], dtype[float64]]) – Input data array of shape (n_data, n_features).

  • parameters (ndarray[tuple[int, ...], dtype[float64]]) – Learnable parameter vector of shape (n_params,).

Returns:

Tuple of (circuit, batched_params) where batched_params has shape (n_data, parameter_count) with each row ready to bind to the circuit.

Return type:

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

scikit_quri.circuit.create_qcl_ansatz(n_qubit, c_depth, time_step=0.5, seed=0)[source]#

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)[source]#
Parameters:
Return type:

LearningCircuit

scikit_quri.circuit.create_ibm_embedding_circuit(n_qubit)[source]#

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

Parameters:

  • n_qubits – number of qubits

  • n_qubit (int) –

Return type:

LearningCircuit

Contents