qpanda3_runtime.task.program_set#

Program set binding module for quantum computing tasks.

This module provides classes for binding quantum circuits, ansatzs, gate parameters, and observables with flexible binding rules (zip and product).

Classes#

AnsatzParamsBinding: Binding manager for ansatz circuits and gate parameters.
CircuitObservableBinding: Binding manager for quantum circuits and observables.
AnsatzObservableBinding: Binding manager for ansatz-parameter combinations and observables.

Examples

>>> from pyqpanda3.vqcircuit import VQCircuit
>>> from pyqpanda3.hamiltonian import Hamiltonian
>>> from qpanda3_runtime.task.program_set import (
...     AnsatzParamsBinding,
...     CircuitObservableBinding,
...     AnsatzObservableBinding
... )

>>> # Create ansatz-parameter binding
>>> ansatzs = [vqcircuit1, vqcircuit2]
>>> params = [[0.1, 0.2], [0.3, 0.4]]
>>> ansatz_binder = AnsatzParamsBinding(ansatzs, params)
>>> ansatz_binder.zip([0, 1], [0, 1])

>>> # Create circuit-observable binding
>>> circuits = [qprog1, qprog2]
>>> observables = [hamiltonian1, hamiltonian2]
>>> circuit_binder = CircuitObservableBinding(circuits, observables)
>>> circuit_binder.product([0], [0, 1])

>>> # Create ansatz-observable binding
>>> ansatz_obs_binder = AnsatzObservableBinding(ansatz_binder, observables)
>>> ansatz_obs_binder.zip([0, 1], [0, 1])

Submodules#

Classes#

`AnsatzParamsBinding`	Binding manager for ansatz circuits and gate parameters.
`CircuitObservableBinding`	Binding manager for quantum circuits and observables.
`AnsatzObservableBinding`	Binding manager for ansatz-parameter combinations and observables.

Package Contents#

class qpanda3_runtime.task.program_set.AnsatzParamsBinding(ansatzs: [pyqpanda3.vqcircuit.VQCircuit], gate_params_s: List)#

Binding manager for ansatz circuits and gate parameters.

This class provides flexible binding rules (zip and product) to combine variational quantum circuits (ansatzs) with their corresponding gate parameters.

Parameters:

ansatzs (List[VQCircuit]) – List of variational quantum circuits (ansatzs).
gate_params_s (List) – List of gate parameter sets corresponding to the ansatzs.

Variables:

_ansatzs (List[VQCircuit]) – Internal storage for ansatz circuits.
_gate_params_s (List) – Internal storage for gate parameter sets.
_bind_rules (List[Tuple[List[int], List[int], int]]) – Binding rules where 0 represents zip rule and 1 represents product rule.
_circuits (List) – Generated quantum circuits after applying binding rules.

Examples

>>> ansatzs = [vqcircuit1, vqcircuit2]
>>> params = [[0.1, 0.2], [0.3, 0.4]]
>>> binder = AnsatzParamsBinding(ansatzs, params)
>>> binder.zip([0, 1], [0, 1])  # One-to-one binding
>>> binder.product([0], [0, 1])  # Cartesian product binding

zip(ansatz_idx_s, gate_params_idx_s)#

Add a zip binding rule (one-to-one correspondence).

This method creates a binding rule where ansatzs and gate parameters are paired in one-to-one correspondence, similar to Python’s zip function.

Parameters:

ansatz_idx_s (List[int]) – Indices of ansatzs to bind.
gate_params_idx_s (List[int]) – Indices of gate parameter sets to bind.

Raises:

RuntimeError – If any index exceeds the bounds of the corresponding list.

Notes

The two lists must have the same length for proper one-to-one binding.

product(ansatz_idx_s, gate_params_idx_s)#

Add a product binding rule (Cartesian product).

This method creates a binding rule where all combinations of specified ansatzs and gate parameters are generated, similar to Python’s itertools.product.

Parameters:

ansatz_idx_s (List[int]) – Indices of ansatzs to bind.
gate_params_idx_s (List[int]) – Indices of gate parameter sets to bind.

Notes

This generates all possible combinations between the specified ansatzs and gate parameters, unlike zip which creates one-to-one pairs.

ansatzs(serialized=True, encode_type: str = 'b64_ascii')#

Get the ansatz circuits.

Parameters:

serialized (bool, optional) – If True, return serialized representation of ansatzs. If False, return the original VQCircuit objects.
encode_type (str, optional) – Encoding type for serialization. Currently only ‘b64_ascii’ is supported.

Returns:

If serialized is True: List of serialized ansatz strings. If serialized is False: List of VQCircuit objects.

Return type:

List

Notes

Serialization converts VQCircuit objects to base64-encoded strings for transmission or storage purposes.

rules()#

Get all binding rules.

Returns:: List of binding rules where each rule is a tuple containing: - List[int]: Ansatz indices - List[int]: Gate parameter indices - int: Binding type (0 for zip, 1 for product)
Return type:: List[Tuple[List[int], List[int], int]]

gate_params(flatten)#

Get gate parameters.

Parameters:

flatten (bool) – If True, flatten the gate parameters and return both flattened lists and their dimensions. If False, return the original parameter structure.

Returns:

If flatten is False: Original gate parameter structure. If flatten is True: Tuple containing:

List[List[float]]: Flattened parameter lists

List[int]: Dimensions of each parameter list

Return type:

Union[List, Tuple[List, List]]

Notes

Flattening is useful for serialization or when parameters need to be transmitted as flat arrays.

circuits()#

Generate quantum circuits by applying all binding rules.

Returns:: List of generated quantum circuits.
Return type:: List

Notes

This method applies all registered binding rules to generate the final quantum circuits. The circuits are cached internally after generation.

data()#

Get internal data representation.

Returns:: Dictionary containing: - ‘gate_params_s’: Gate parameters - ‘bind_rules’: Binding rules - ‘ansatzs’: Ansatz circuits
Return type:: Dict

to_json_dict()#

Convert to JSON-serializable dictionary.

Returns:: JSON-serializable dictionary containing: - ‘gate_params_s’: Binary JSON representation of gate parameters - ‘bind_rules’: Binding rules - ‘ansatzs’: JSON-safe byte representation of ansatz circuits
Return type:: Dict

Notes

This method prepares the data for JSON serialization by converting binary data to JSON-safe formats.

static from_json_dict(json_data)#

Create AnsatzParamsBinding instance from JSON dictionary.

Parameters:: json_data (Dict) – JSON dictionary containing: - ‘bind_rules’: Binding rules - ‘ansatzs’: JSON-safe byte representation of ansatz circuits - ‘gate_params_s’: Binary JSON representation of gate parameters
Returns:: Reconstructed AnsatzParamsBinding instance.
Return type:: AnsatzParamsBinding

Notes

This is the inverse operation of to_json_dict().

get_prog_groups_with_measure(max_circuit_num_per_group, measure_qubits: list, return_originir: bool = True)#

Get quantum programs grouped with measurement operations.

Parameters:

max_circuit_num_per_group (int) – Maximum number of circuits per group.
measure_qubits (List[int]) – List of qubit indices to measure.
return_originir (bool, optional) – If True, return programs as OriginIR strings. If False, return QProg objects.

Returns:

List of program groups where each group contains: - ‘ansatz_id__gate_params_id_s’: List of (ansatz_id, gate_params_id) pairs - ‘progs’: List of quantum programs with measurement operations

Return type:

List[Dict]

Notes

This method adds measurement operations to all specified qubits and groups the resulting programs for batch processing.

get_progs(return_originir: bool = True)#

Get all quantum programs generated by binding rules.

Parameters:: return_originir (bool, optional) – If True, return programs as OriginIR strings. If False, return QProg objects.
Returns:: List of dictionaries where each contains: - ‘ansatz_id__gate_params_id’: Tuple of (ansatz_id, gate_params_id) - ‘progs’: List of quantum programs
Return type:: List[Dict]

Notes

This method applies all binding rules to generate the complete set of quantum programs with their corresponding ansatz-parameter mappings.

get_all_ansatz_params_pair()#

Get all ansatz-parameter pairs according to binding rules.

Returns:: List of (ansatz_index, parameter_index) pairs generated by applying all registered binding rules.
Return type:: List[Tuple[int, int]]
Raises:: RuntimeError – If an unknown binding type is encountered.

get_ansatz_params_group(max_circuit_num_per_group)#

Group ansatz-parameter pairs for batch processing.

Parameters:: max_circuit_num_per_group (int) – Maximum number of pairs per group.
Returns:: List of groups where each group contains up to max_circuit_num_per_group ansatz-parameter pairs.
Return type:: List[List[Tuple[int, int]]]

Notes

This method is useful for dividing large sets of quantum circuits into manageable batches for parallel or sequential execution.

class qpanda3_runtime.task.program_set.CircuitObservableBinding(circuits: List[qpanda3_runtime.utils.union_type.QProgUnionType] | None = None, observables: List[qpanda3_runtime.utils.union_type.ObservableUnionType] | None = None)#

Binding manager for quantum circuits and observables.

This class provides flexible binding rules (zip and product) to combine quantum circuits with their corresponding observables in quantum multi-objective decision-making scenarios.

Parameters:

circuits (Optional[List[QProgUnionType]]) – List of exploratory quantum circuits.
observables (Optional[List[ObservableUnionType]]) – List of target observables.

Variables:

_circuits (List[QProg]) – Internal storage for quantum circuits.
_observables (List[Hamiltonian]) – Internal storage for observables.
_bind_rules (List[Tuple[List[int], List[int], int]]) – Binding rules where 0 represents zip rule and 1 represents product rule.
_max_qubit_idx (int) – Maximum qubit index across all circuits and observables.

Raises:

RuntimeError – If circuits and observables are not provided together. If circuits and observables don’t share the same maximum qubit index.

Examples

>>> circuits = [qprog1, qprog2]
>>> observables = [hamiltonian1, hamiltonian2]
>>> binder = CircuitObservableBinding(circuits, observables)
>>> binder.zip([0, 1], [0, 1])  # One-to-one binding
>>> binder.product([0], [0, 1])  # Cartesian product binding

max_qubit_idx()#

Get the maximum qubit index across all circuits and observables.

Returns:: Maximum qubit index value.
Return type:: int

Notes

This value is validated during initialization to ensure all circuits and observables operate on the same qubit register.

static from_tuple(circuit_with_observable: Tuple[qpanda3_runtime.utils.union_type.QProgUnionType | List[qpanda3_runtime.utils.union_type.QProgUnionType], qpanda3_runtime.utils.union_type.ObservableUnionType])#

Create CircuitObservableBinding from a tuple.

Parameters:: circuit_with_observable (Tuple[Union[QProgUnionType, List[QProgUnionType]], ObservableUnionType]) – Tuple containing: - First element: Single quantum circuit or list of quantum circuits - Second element: Single observable
Returns:: Binding object with product rule applied between circuits and observable.
Return type:: CircuitObservableBinding

Notes

This convenience method automatically applies a product binding rule between all provided circuits and the single observable.

zip(circuit_idx_s, observable_idx_s)#

Add a zip binding rule (one-to-one correspondence).

This method creates a binding rule where circuits and observables are paired in one-to-one correspondence, similar to Python’s zip function.

Parameters:

circuit_idx_s (List[int]) – Indices of circuits to bind.
observable_idx_s (List[int]) – Indices of observables to bind.

Raises:

RuntimeError – If any index exceeds the bounds of the corresponding list.

Notes

The two lists must have the same length for proper one-to-one binding.

product(circuit_idx_s, observable_idx_s)#

Add a product binding rule (Cartesian product).

This method creates a binding rule where all combinations of specified circuits and observables are generated, similar to Python’s itertools.product.

Parameters:

circuit_idx_s (List[int]) – Indices of circuits to bind.
observable_idx_s (List[int]) – Indices of observables to bind.

Notes

This generates all possible combinations between the specified circuits and observables, unlike zip which creates one-to-one pairs.

observables(serialized=True)#

Get the observables.

Parameters:: serialized (bool, optional) – If True, return serialized representation of observables. If False, return the original Hamiltonian objects.
Returns:: If serialized is True: List of serialized observable strings. If serialized is False: List of Hamiltonian objects.
Return type:: Union[List[Hamiltonian], List[str]]

Notes

Serialization converts Hamiltonian objects to string representations for transmission or storage purposes.

circuits(serialized=True)#

Get the quantum circuits.

Parameters:: serialized (bool, optional) – If True, return serialized representation of circuits. If False, return the original QProg objects.
Returns:: If serialized is True: List of OriginIR strings. If serialized is False: List of QProg objects.
Return type:: Union[List[QProg], List[str]]

Notes

Serialization converts QProg objects to OriginIR strings for transmission or storage purposes.

data()#

Get internal data representation.

Returns:: Dictionary containing: - ‘observables’: Observable objects - ‘bind_rules’: Binding rules - ‘circuits’: Quantum circuit objects
Return type:: Dict

rules()#

Get all binding rules.

Returns:: List of binding rules where each rule is a tuple containing: - List[int]: Circuit indices - List[int]: Observable indices - int: Binding type (0 for zip, 1 for product)
Return type:: List[Tuple[List[int], List[int], int]]

get_all_circuit_observable_id_pairs()#

Get all circuit-observable pairs according to binding rules.

Returns:: List of (circuit_index, observable_index) pairs generated by applying all registered binding rules.
Return type:: List[Tuple[int, int]]

Notes

This method applies both zip and product rules to generate the complete set of circuit-observable combinations.

to_json_dict() → Dict#

Convert to JSON-serializable dictionary.

Returns:: JSON-serializable dictionary containing: - ‘type’: ‘CircuitObservableBinding’ - ‘circuits’: OriginIR strings of quantum circuits - ‘observables’: String representations of observables - ‘bind_rules’: Binding rules - ‘max_qubit_idx’: Maximum qubit index
Return type:: Dict

Notes

This method prepares the data for JSON serialization by converting quantum objects to string representations.

static from_json_dict(data: Dict)#

Create CircuitObservableBinding instance from JSON dictionary.

Parameters:: data (Dict) – JSON dictionary containing: - ‘circuits’: OriginIR strings of quantum circuits - ‘observables’: String representations of observables - ‘bind_rules’: Binding rules - ‘max_qubit_idx’: Maximum qubit index
Returns:: Reconstructed CircuitObservableBinding instance.
Return type:: CircuitObservableBinding

Notes

This is the inverse operation of to_json_dict().

class qpanda3_runtime.task.program_set.AnsatzObservableBinding(ansatz_with_params: qpanda3_runtime.task.program_set.gate_params_bind_rule.AnsatzParamsBinding, observables: List[qpanda3_runtime.utils.union_type.ObservableUnionType])#

Binding manager for ansatz-parameter combinations and observables.

This class provides flexible binding rules (zip and product) to combine ansatz-parameter combinations (from AnsatzParamsBinding) with observables.

Parameters:

ansatz_with_params (AnsatzParamsBinding) – Binding object containing ansatz circuits and their parameters.
observables (List[ObservableUnionType]) – List of target observables.

Variables:

_ansatz_with_params (AnsatzParamsBinding) – Internal storage for ansatz-parameter bindings.
_observables (List[Hamiltonian]) – Internal storage for observables.
_bind_rules (List[Tuple[List[int], List[int], int]]) – Binding rules where 0 represents zip rule and 1 represents product rule.
_max_qubit_idx (int) – Maximum qubit index across all ansatzs and observables.

Examples

>>> ansatz_binder = AnsatzParamsBinding(ansatzs, params)
>>> observables = [hamiltonian1, hamiltonian2]
>>> binder = AnsatzObservableBinding(ansatz_binder, observables)
>>> binder.zip([0, 1], [0, 1])  # One-to-one binding
>>> binder.product([0], [0, 1])  # Cartesian product binding

max_qubit_idx()#

Get the maximum qubit index across all ansatzs and observables.

Returns:: Maximum qubit index value.
Return type:: int

ansatzs(serialized=True, encode_type: str = 'b64_ascii')#

Get the ansatz circuits.

Parameters:

serialized (bool, optional) – If True, return serialized representation of ansatzs. If False, return the original VQCircuit objects.
encode_type (str, optional) – Encoding type for serialization.

Returns:

Result from underlying AnsatzParamsBinding.ansatzs() method.

Return type:

List

gate_params(flatten)#

Get the gate parameters.

Parameters:: flatten (bool) – If True, flatten the gate parameters.
Returns:: Result from underlying AnsatzParamsBinding.gate_params() method.
Return type:: Union[List, Tuple[List, List]]

ansatz_params_bind_rules()#

Get ansatz-parameter binding rules.

Returns:: Binding rules from the underlying AnsatzParamsBinding object.
Return type:: List[Tuple[List[int], List[int], int]]

observables(serialized=True)#

Get the observables.

Parameters:: serialized (bool, optional) – If True, return serialized representation of observables. If False, return the original Hamiltonian objects.
Returns:: If serialized is True: List of serialized observable strings. If serialized is False: List of Hamiltonian objects.
Return type:: Union[List[Hamiltonian], List[str]]

rules()#

Get all binding rules.

Returns:: List of binding rules where each rule is a tuple containing: - List[int]: Ansatz-parameter combination indices - List[int]: Observable indices - int: Binding type (0 for zip, 1 for product)
Return type:: List[Tuple[List[int], List[int], int]]

zip(ansatz_with_param_idx_s, observable_idx_s)#

Add a zip binding rule (one-to-one correspondence).

Parameters:

ansatz_with_param_idx_s (List[int]) – Indices of ansatz-parameter combinations to bind.
observable_idx_s (List[int]) – Indices of observables to bind.

Raises:

RuntimeError – If any index exceeds the bounds of the corresponding list.

Notes

The two lists must have the same length for proper one-to-one binding.

product(ansatz_with_param_idx_s, observable_idx_s)#

Add a product binding rule (Cartesian product).

Parameters:

ansatz_with_param_idx_s (List[int]) – Indices of ansatz-parameter combinations to bind.
observable_idx_s (List[int]) – Indices of observables to bind.

Notes

This generates all possible combinations between the specified ansatz-parameter combinations and observables.

data()#

Get internal data representation.

Returns:: Dictionary containing: - ‘observables’: Observable objects - ‘bind_rules’: Binding rules - ‘ansatz_with_params’: AnsatzParamsBinding object
Return type:: Dict

get_all_ansatz_observable_id_pairs()#

Get all ansatz-observable pairs according to binding rules.

Returns:: List of (ansatz_index, observable_index) pairs generated by applying all registered binding rules.
Return type:: List[Tuple[int, int]]

get_observables()#

Get the observables.

Returns:: List of Hamiltonian objects.
Return type:: List[Hamiltonian]

get_progs_grouped_by_ansatz_with_params(using_originir: bool = True)#

Get quantum programs grouped by ansatz-parameter combinations.

Parameters:: using_originir (bool, optional) – If True, return programs as OriginIR strings. If False, return QProg objects.
Returns:: Result from underlying AnsatzParamsBinding.get_progs() method.
Return type:: List[Dict]

to_json_dict() → Dict#

Convert to JSON-serializable dictionary.

Returns:: JSON-serializable dictionary containing: - ‘type’: ‘AnsatzObservableBinding’ - ‘ansatz_with_params’: JSON representation from AnsatzParamsBinding - ‘observables’: String representations of observables - ‘bind_rules’: Binding rules - ‘max_qubit_idx’: Maximum qubit index
Return type:: Dict

Notes

This method prepares the data for JSON serialization by converting quantum objects to string representations.

static from_json_dict(data: Dict)#

Create AnsatzObservableBinding instance from JSON dictionary.

Parameters:: data (Dict) – JSON dictionary containing: - ‘ansatz_with_params’: JSON representation from AnsatzParamsBinding - ‘observables’: String representations of observables - ‘bind_rules’: Binding rules - ‘max_qubit_idx’: Maximum qubit index
Returns:: Reconstructed AnsatzObservableBinding instance.
Return type:: AnsatzObservableBinding

Notes

This is the inverse operation of to_json_dict().