uniqc.algorithms.core.ansatz.hea module

Hardware-Efficient Ansatz (HEA).

Generates a parameterised circuit with configurable single-qubit rotations, entangling gates, and entanglement topologies, suitable for NISQ devices.

uniqc.algorithms.core.ansatz.hea.hea(n_qubits, depth=1, qubits=None, params=None, *, rotation_gates=None, entangling_gate=None, topology=None, custom_edges=None, backend_info=None)[source]

Build a Hardware-Efficient Ansatz (HEA) circuit.

The ansatz consists of depth repeated layers. Each layer applies:

  1. Single-qubit rotations on every qubit (parameterised).

  2. Entangling gates following the specified topology.

Parameters:

  • n_qubits (int) – Number of qubits.

  • depth (int) – Number of repeated layers (default 1).

  • qubits (list[int] | None) – Qubit indices. None → list(range(n_qubits)).

  • params (Parameters | ndarray | None) – 1-D array of rotation angles. None → random initialisation.

  • rotation_gates (list[str | RotationGate] | None) – List of single-qubit rotation types per qubit per layer. Default: [RotationGate.RZ, RotationGate.RY] (backward-compatible). Options: [RotationGate.RX], [RotationGate.RX, RotationGate.RY, RotationGate.RZ], etc.

  • entangling_gate (str | EntanglingGate | None) – Two-qubit entangling gate type. Default: EntanglingGate.CNOT (backward-compatible). Options: EntanglingGate.CZ, EntanglingGate.CRX, EntanglingGate.XX, etc. Parametric gates (CRX, CRY, CRZ, XX, YY, ZZ) consume 1 extra param per edge.

  • topology (str | EntanglementTopology | None) – Entanglement topology for the entangling layer. Default: EntanglementTopology.RING (backward-compatible). Options: - LINEAR: Chain (0-1, 1-2, 2-3, …) - RING: Linear plus wrap-around (0-1, 1-2, …, n-1, n-1-0) - FULL: All-to-all pairwise - STAR: One central qubit to all others - BRICKWORK: Alternating even/odd pairs (Qiskit-style) - CUSTOM: Use custom_edges parameter

  • custom_edges (list[tuple[int, int]] | None) – Required when topology is CUSTOM. List of (control, target) qubit pairs.

  • backend_info (BackendInfo | None) – Backend information for automatic topology/gate selection. When provided, automatically selects topology and entangling gate that match the hardware capabilities.

Returns:

A Circuit object containing the ansatz gates.

Raises:

ValueError – Parameter count mismatch or invalid configuration.

Return type:

Circuit

Example

>>> from uniqc.algorithms.core.ansatz import hea
>>> c = hea(n_qubits=4, depth=2)
>>> c.max_qubit + 1
4

Custom rotation gates (Rx + Rz): >>> c = hea(n_qubits=4, rotation_gates=[“rx”, “rz”])

CZ entangling gate with linear topology: >>> c = hea(n_qubits=4, entangling_gate=”cz”, topology=”linear”)

Hardware-aware (auto-select topology and gate): >>> from uniqc import get_backend >>> backend = get_backend(“originq:Simulator”) >>> c = hea(n_qubits=4, backend_info=backend)

uniqc.algorithms.core.ansatz.hea.hea_param_count(n_qubits, depth=1, *, qubits=None, rotation_gates=None, entangling_gate=None, topology=None, custom_edges=None, backend_info=None)[source]

Calculate the number of parameters required for an HEA circuit.

Use this to determine the parameter array size before building the circuit.

Parameters:

  • n_qubits (int) – Number of qubits.

  • depth (int) – Number of ansatz layers.

  • qubits (list[int] | None) – Qubit indices. None → list(range(n_qubits)).

  • rotation_gates (list[str | RotationGate] | None) – List of rotation gate types per qubit per layer.

  • entangling_gate (str | EntanglingGate | None) – Type of entangling gate.

  • topology (str | EntanglementTopology | None) – Entanglement topology type.

  • custom_edges (list[tuple[int, int]] | None) – Required for CUSTOM topology.

  • backend_info (BackendInfo | None) – Backend info for auto-configuration.

Returns:

Total number of parameters required.

Return type:

int