ffsim.qiskit.generate_lucj_pass_manager

ffsim.qiskit.generate_lucj_pass_manager(backend, norb, connectivity, interaction_pairs, two_qubit_error_threshold=1.0, readout_error_threshold=0.1, **qiskit_pm_kwargs)

Generate a Qiskit preset pass manager for the LUCJ ansatz.

Construct a pass manager that maps a local unitary cluster Jastrow (LUCJ) ansatz circuit onto a target backend using layout strategies, as described in the reference below. The layout is optimized for heavy-hex or square backend topologies, subject to hardware connectivity and error constraints.

References

• Motta, Sung, Whaley, Head-Gordon, and Shee, “Bridging physical intuition and hardware efficiency for correlated electronic states: the local unitary cluster Jastrow ansatz for electronic structure.” (2023)

Parameters:

• backend (BackendV2) – The target Qiskit backend.

• norb (int) – Number of spatial orbitals. The ansatz uses 2 * norb qubits, and transpilation may add ancilla qubits.

• connectivity (Literal['heavy-hex', 'square']) – Connectivity topology of the backend. Must be one of "heavy-hex" or "square".

• interaction_pairs (tuple[list[tuple[int, int]], list[tuple[int, int]] | None] | tuple[list[tuple[int, int]], list[tuple[int, int]] | None, list[tuple[int, int]]]) –

  Either a length-2 or length-3 tuple describing alpha-alpha, alpha-beta, and optional beta-beta interaction pairs.

  The first item in the tuple is the alpha-alpha interaction pairs (pairs_aa). The second item is the alpha-beta interaction pairs (pairs_ab). And, the optional third item is the beta-beta interaction pairs (pairs_bb).

  Each entry (orb1, orb2) in above three lists of interaction pairs must satisfy 0 <= orb1, orb2 < norb.

  pairs_ab interaction pairs are requested by a user to be include in the ansatz. If hardware connectivity cannot accommodate all requested pairs, pairs are dropped from the end of the list until a valid layout is found. List pairs in descending order of priority to control which are dropped first.

  If None, defaults to pairs as follows:

  • heavy-hex: [(p, p) for p in range(norb) if p % 4 == 0]

  • square: [(p, p) for p in range(norb)]

• two_qubit_error_threshold (float) – Two-qubit gate error threshold. Edges in the backend coupling graph with error rate >= two_qubit_error_threshold are removed. The default value, 1.0, results in only completely faulty edges being removed.

• readout_error_threshold (float) – Readout error threshold. Nodes in the backend coupling graph with readout error >= readout_error_threshold are removed.

• **qiskit_pm_kwargs – Additional keyword arguments forwarded to qiskit.transpiler.generate_preset_pass_manager(). The arguments initial_layout and layout_method are not supported and will be ignored with a warning if provided.

Return type:

tuple[StagedPassManager, list[tuple[int, int]]]

Returns:

• A configured Qiskit preset pass manager with the LUCJ layout and a VF2PostLayout pass enabled.

• The subset of requested alpha-beta pairs that can be accommodated given the backend’s connectivity and error constraints.

Raises:

• ValueError – If any entry in interaction_pairs references an orbital index >= norb.

• ValueError – If connectivity is not "heavy-hex" or "square".

Note

Providing initial_layout to generate_preset_pass_manager() normally disables the VF2PostLayout pass. This function re-enables it explicitly so that the transpiler can search for a better noise-aware isomorphic subgraph mapping after routing.