Encode -- Quantum State Encoding

API reference for the Encode class, which provides methods for encoding classical data into quantum states. Each encoding method maps input data onto qubits using a different strategy, producing a QCircuit that can be retrieved via get_circuit().

Encode

class Encode:
    def __init__() -> None

Constructs a new Encode instance.

---

Encoding Methods

basic_encode

Maps a classical binary string onto qubits. Each character in the string determines the basis state of a corresponding qubit.

Signature

basic_encode(qubits: list[int], data: str) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	str	Binary string data (e.g. "1010").

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

Example

from pyqpanda3.core import Encode

enc = Encode()
enc.basic_encode([0, 1, 2, 3], "1010")
circuit = enc.get_circuit()

---

amplitude_encode

Encodes classical data into a quantum state using amplitude encoding. The input vector is normalized and mapped onto the state vector amplitudes.

Signature

amplitude_encode(qubits: list[int], data: list[float]) -> None
amplitude_encode(qubits: list[int], data: list[complex]) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	list[float] or list[complex]	Classical data vector. Automatically normalized.

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

Example

from pyqpanda3.core import Encode

enc = Encode()
enc.amplitude_encode([0, 1], [0.5, 0.5, 0.5, 0.5])
circuit = enc.get_circuit()

---

amplitude_encode_recursive

Encodes classical data into a quantum state using recursive amplitude encoding. This method decomposes the encoding into smaller sub-problems for a more structured circuit.

Signature

amplitude_encode_recursive(qubits: list[int], data: list[float]) -> None
amplitude_encode_recursive(qubits: list[int], data: list[complex]) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	list[float] or list[complex]	Classical data vector. Automatically normalized.

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

---

angle_encode

Encodes classical data by mapping each value to a rotation angle on the corresponding qubit. Commonly used in variational quantum algorithms.

Signature

angle_encode(qubits: list[int], data: list[float], gate_type: GateType = GateType.RY) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	list[float]	Data values used as rotation angles.
gate_type	GateType	Rotation gate type. Defaults to GateType.RY.

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

Example

from pyqpanda3.core import Encode, GateType

enc = Encode()
enc.angle_encode([0, 1, 2], [0.5, 1.0, 1.5], gate_type=GateType.RX)
circuit = enc.get_circuit()

---

dense_angle_encode

Encodes two classical data values per qubit by using two rotation axes, providing a more compact encoding than standard angle encoding.

Signature

dense_angle_encode(qubits: list[int], data: list[float]) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	list[float]	Data values to encode.

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

---

iqp_encode

Encodes data using Instantaneous Quantum Polynomial (IQP) encoding, which applies parameterized diagonal gates in the Hadamard basis.

Signature

iqp_encode(
    qubits: list[int],
    data: list[float],
    control_list: list[tuple[int, int]] = [],
    bool_inverse: bool = False,
    repeats: int = 1,
) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	list[float]	Data values to encode.
control_list	list[tuple[int, int]]	Pairs defining qubit interactions. Defaults to empty.
bool_inverse	bool	Whether to apply the inverse of the IQP circuit. Defaults to False.
repeats	int	Number of times to repeat the encoding circuit. Defaults to 1.

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

---

bid_amplitude_encode

Encodes data using BID (Bidirectional) amplitude encoding, which decomposes the target state into smaller blocks iteratively.

Signature

bid_amplitude_encode(qubits: list[int], data: list[float], split: int = -1) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	list[float]	Amplitude vector representing the quantum state.
split	int	Block size for iterative decomposition. Defaults to -1 (automatic).

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

---

dc_amplitude_encode

Encodes data using DC (Divide-and-Conquer) amplitude encoding with a hierarchical decomposition approach.

Signature

dc_amplitude_encode(qubits: list[int], data: list[float]) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	list[float]	Amplitude vector representing the quantum state.

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

---

schmidt_encode

Encodes data using Schmidt decomposition. The target state is decomposed into a product of subsystems, with a cutoff for truncating small singular values.

Signature

schmidt_encode(qubits: list[int], data: list[float], cutoff: float = 0.0) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	list[float]	Amplitude vector representing the quantum state.
cutoff	float	Threshold for truncating small singular values. Defaults to 0.0 (no truncation).

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

Example

from pyqpanda3.core import Encode
import numpy as np

data = np.array([0.5, 0.5, 0.5, 0.5])
enc = Encode()
enc.schmidt_encode([0, 1], data.tolist(), cutoff=1)
circuit = enc.get_circuit()

---

sparse_isometry

Prepares a sparse quantum state using isometry decomposition. Accepts data in multiple formats: as a dictionary mapping basis-state strings to amplitudes, or as a full state vector.

Signature

sparse_isometry(qubits: list[int], data: dict[str, float]) -> None
sparse_isometry(qubits: list[int], data: dict[str, complex]) -> None
sparse_isometry(qubits: list[int], data: list[float]) -> None
sparse_isometry(qubits: list[int], data: list[complex]) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	dict[str, float], dict[str, complex], list[float], or list[complex]	Sparse state data. When a dictionary, keys are basis-state binary strings (e.g. "00", "11") and values are amplitudes. When a list, it is treated as a full state vector.

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

Example

from pyqpanda3.core import Encode
import numpy as np

enc = Encode()
enc.sparse_isometry([0, 1], {"00": 1.0/np.sqrt(2), "11": 1.0/np.sqrt(2)})
circuit = enc.get_circuit()

---

efficient_sparse

Prepares a sparse quantum state using an efficient sparse decomposition. Similar to sparse_isometry but optimized for reduced circuit depth. Accepts the same data formats.

Signature

efficient_sparse(qubits: list[int], data: dict[str, float]) -> None
efficient_sparse(qubits: list[int], data: dict[str, complex]) -> None
efficient_sparse(qubits: list[int], data: list[float]) -> None
efficient_sparse(qubits: list[int], data: list[complex]) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	dict[str, float], dict[str, complex], list[float], or list[complex]	Sparse state data in the same formats as sparse_isometry.

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

---

ds_quantum_state_preparation

Prepares a quantum state using double-sparse state preparation. Accepts data in multiple formats.

Signature

ds_quantum_state_preparation(qubits: list[int], data: dict[str, float]) -> None
ds_quantum_state_preparation(qubits: list[int], data: dict[str, complex]) -> None
ds_quantum_state_preparation(qubits: list[int], data: list[float]) -> None
ds_quantum_state_preparation(qubits: list[int], data: list[complex]) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	dict[str, float], dict[str, complex], list[float], or list[complex]	State parameters for preparation.

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

---

approx_mps_encode

Encodes data using Approximate Matrix Product State (MPS) encoding. MPS encoding uses a low-rank approximation optimized by iterative sweeps.

Signature

approx_mps_encode(qubits: list[int], data: list[float], layers: int = 3, sweeps: int = 100, double2float: bool = False) -> None
approx_mps_encode(qubits: list[int], data: list[complex], layers: int = 3, sweeps: int = 100) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Qubit indices to encode into.
data	list[float] or list[complex]	Classical input data to encode.
layers	int	Number of encoding layers. Defaults to 3.
sweeps	int	Number of optimization sweeps. Defaults to 100.
double2float	bool	Convert double data to float before encoding. Defaults to False. Only applicable for the list[float] overload.

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

---

topology_aware_mps_encode

Topology-aware MPS amplitude encoding. Prepares a quantum state using a topology-preserving MPS approximation. Two-qubit gates are generated only for physically connected qubit pairs specified by the topology edge list, achieving zero SWAP overhead.

Signature

topology_aware_mps_encode(qubits: list[int], data: list[float], topology: list[list[int]], depth: int = 3) -> None
topology_aware_mps_encode(qubits: list[int], data: list[complex], topology: list[list[int]], depth: int = 3) -> None

Parameters

Parameter	Type	Description
qubits	list[int]	Available qubits for encoding.
data	list[float] or list[complex]	Target amplitude vector. Must be normalized, size must be a power of 2 and >= 16.
topology	list[list[int]]	Chip topology edge list. Each element is [qubit_a, qubit_b] representing a physical coupling (e.g. [[0, 1], [1, 2], [2, 3]] for a 4-qubit linear chain).
depth	int	Number of disentanglement passes. Higher depth improves fidelity. Defaults to 3.

Returns

None. The circuit is stored internally and can be retrieved via get_circuit().

Raises

RuntimeError if data is not normalized, size is not a power of 2, size < 16, or the topology graph is not connected.

Example

from pyqpanda3.core import Encode

data = [0.25] * 16
topology = [[0, 1], [1, 2], [2, 3]]

encoder = Encode()
encoder.topology_aware_mps_encode([0, 1, 2, 3], data, topology, depth=3)

print(type(encoder.get_circuit()).__name__)
print(round(encoder.get_fidelity(data), 6))

Expected output:

QCircuit
1.0

---

Utility Methods

Encode.get_circuit

Retrieves the quantum circuit generated by the last encoding call.

Signature

Encode.get_circuit() -> QCircuit

Returns

The QCircuit produced by the encoding method.

---

Encode.get_out_qubits

Retrieves the output qubits from the encoding process.

Signature

Encode.get_out_qubits() -> list[int]

Returns

A list of qubit indices representing the output of the encoding.

---

Encode.get_fidelity

Computes the fidelity between the encoded quantum state and the target state described by the input data.

Signature

Encode.get_fidelity(data: list[float]) -> float
Encode.get_fidelity(data: list[complex]) -> float

Parameters

Parameter	Type	Description
data	list[float] or list[complex]	Input data used for the fidelity calculation.

Returns

The calculated fidelity value, indicating how closely the encoded state matches the target state.

---

See Also

• QCircuit
• QProg
• Simulator