qdk_chemistry.algorithms.qubit_mapper.qdk_qubit_mapper module

QDK native qubit mapper using Majorana-level C++ building blocks.

This module provides the QdkQubitMapper class for transforming electronic structure Hamiltonians to qubit operators. The encoding is specified by a MajoranaMapping passed to run(), making the mapper encoding-agnostic.

class qdk_chemistry.algorithms.qubit_mapper.qdk_qubit_mapper.QdkQubitMapper(threshold=1e-12, integral_threshold=1e-12)

Bases: QubitMapper

QDK native qubit mapper using Majorana-level C++ engine.

This is a table-driven backend: it reads the Pauli-string table from the MajoranaMapping and passes it directly to the C++ majorana_map_hamiltonian engine. Any valid MajoranaMapping works — built-in (Jordan-Wigner, Bravyi-Kitaev, parity, BK-tree, SCBK) or custom user-defined tables. The mapping’s name and base_encoding are used only for metadata on the output QubitOperator, not for dispatch.

Both restricted (RHF) and unrestricted (UHF) Hamiltonians are supported. For unrestricted systems, the engine handles all four spin-channel ERI blocks (aa, ab, ba, bb) independently.

The two-body integrals are consumed in the native storage format of the Hamiltonian’s container (the C++ engine dispatches on the container type):

• SparseHamiltonianContainer: the engine iterates only the stored non-zero (p, q, r, s) entries, so both memory and runtime improve for the mostly-zero integrals of lattice / model Hamiltonians.

• CholeskyHamiltonianContainer: the three-center factors are kept in their O(N**2 * naux) form and the auxiliary index is contracted one (pq|.) row at a time, so the dense N**4 tensor is never built and peak additional memory is a single N**2 row.

• All other containers use the dense engine path.

In all cases the result is numerically equivalent (term-by-term, to within 1e-12) to the dense path.

The mapper uses canonical blocked spin-orbital ordering internally: qubits 0..N-1 for alpha spin, qubits N..2N-1 for beta spin (where N is the number of spatial orbitals). Use QubitOperator.to_interleaved() for alternative qubit orderings.

Examples

>>> from qdk_chemistry.algorithms import create
>>> from qdk_chemistry.data import MajoranaMapping
>>> mapper = create("qubit_mapper")
>>> mapping = MajoranaMapping.jordan_wigner(num_modes=n_spin_orbitals)
>>> qh = mapper.run(hamiltonian, mapping)

Parameters:

• threshold (float)

• integral_threshold (float)

__init__(threshold=1e-12, integral_threshold=1e-12)

Initialize the QdkQubitMapper with default settings.

Parameters:

• threshold (float) – Threshold for pruning small Pauli coefficients. Default: 1e-12.

• integral_threshold (float) – Threshold for filtering small integrals. Default: 1e-12.

Return type:

None

name()

Return the algorithm name.

Return type:

str

run(hamiltonian, mapping)

Map a fermionic Hamiltonian to a qubit operator.

Delegates entirely to _run_impl. Each backend is responsible for handling tapering (if mapping.tapering is set).

Return type:

QubitOperator

Parameters:

• hamiltonian (Hamiltonian) – The fermionic Hamiltonian.

• mapping (MajoranaMapping) – The Majorana-to-Pauli encoding (may include tapering).

Returns:

QubitOperator with encoding and tapering metadata set.

class qdk_chemistry.algorithms.qubit_mapper.qdk_qubit_mapper.QdkQubitMapperSettings

Bases: QubitMapperSettings

Settings configuration for a QdkQubitMapper.

Settings:

threshold (double, default=1e-12): Threshold for pruning small Pauli coefficients. integral_threshold (double, default=1e-12): Threshold for filtering small integrals.

__init__()

Initialize QdkQubitMapperSettings.

Return type:

None