qrunch.quantum.internal
Unified Python module that contains all Rust-backed quantum classes. This consolidates all #[pyclass] definitions into a single .so file, which solves PyO3’s type identity issues across module boundaries.
Functions
Combined excitation index generation + metric computation + top-k selection (BigUint measurements). |
|
Combined excitation index generation + metric computation + top-k selection (u64 measurements). |
|
Combined pair-excitation index generation + metric computation + top-k selection (BigUint measurements). |
|
Combined pair-excitation index generation + metric computation + top-k selection (u64 measurements). |
|
|
|
|
Generate the operators needed for the 1-particle reduced density matrix. |
|
Generate the operators needed for the 2-particle reduced density matrix. |
|
Generate the operators needed for the 3-particle reduced density matrix. |
|
Generate the operators needed for the 4-particle reduced density matrix. |
Generate all excitation gate pool indices for a molecular electron configuration. |
|
|
Generate all C(dimension, 2) HermitianPauliSums, each containing a single X⊗X Pauli string over every unique 2-qubit combination. |
|
Generate all |
|
Generate (X[x]*X[y]+Y[x]*Y[y]) * Z[p] operators. |
|
Generate (X[x]*X[y]+Y[x]*Y[y]) * Z[p]*Z[q] operators. |
|
Generate all C(dimension, 4) HermitianPauliSums, each containing two terms: X⊗X⊗X⊗X + Y⊗Y⊗Y⊗Y over every unique 4-qubit combination. |
|
Generate XXYY operators for pair-of-pairs iteration. |
|
Generate all |
|
Generate all C(dimension, 2) HermitianPauliSums, each containing a single Z⊗Z Pauli string over every unique 2-qubit combination. |
|
Generate all C(dimension, 3) HermitianPauliSums, each containing a single Z⊗Z⊗Z Pauli string over every unique 3-qubit combination. |
|
Generate all C(dimension, 4) HermitianPauliSums, each containing a single Z⊗Z⊗Z⊗Z Pauli string over every unique 4-qubit combination. |
|
Generate all C(dimension, 5) HermitianPauliSums, each containing a single Z⊗Z⊗Z⊗Z⊗Z Pauli string over every unique 5-qubit combination. |
Generate Z⊗Z⊗Z⊗Z⊗Z operators for a subset of qubit quintuples determined by active pair-breaking terms. |
|
|
|
|
|
|
|
|
|
Compute the top-k double-excitation heuristic gradient metrics directly from the molecular electron-repulsion integrals (ERIs) using the Slater–Condon rules, without building the qubit Hamiltonian. |
|
Compute the top-k pair-excitation metrics for the BEAST Hamiltonian directly from the reduced one-body integrals |
|
Compute the top-k first-order single-excitation metrics (Fock matrix off-diagonal elements) directly from one-body and two-body integrals, without building the qubit Hamiltonian. |
|
|
Compute the top-k second-order single-excitation metrics from the BCH expansion directly from one-body and two-body integrals, without building the qubit Hamiltonian. |
Classes
- class AntiHermitianPauliSum
Bases:
object- classmethod __new__(*args, **kwargs)
- constant()
Returns the constant as a complex number (re=0)
- indices()
- len()
- number_of_qubits
- prune(tolerance)
- string_coefficient_pairs()
- terms_as_int
- class ExcitationGate
Bases:
object- static new_double_excitation_gate(number_of_qubits, creation_index1, creation_index2, annihilation_index1, annihilation_index2, theta, float_type=Ellipsis, particle_conservation=Ellipsis, gate_zs=Ellipsis)
- static new_single_excitation_gate(number_of_qubits, creation_index, annihilation_index, theta, float_type=Ellipsis, particle_conservation=Ellipsis, gate_zs=Ellipsis)
- class ExcitationGateCircuit
Bases:
object- classmethod __new__(*args, **kwargs)
- add_gate(gate)
- get_energy(shots=None, hamiltonian=None, eps=None)
- get_parameters()
- get_samples(shots, eps=None)
- get_state_vector()
- run_circuit()
- set_gates(gates)
- set_grouping(grouping)
- set_hamiltonian(hamiltonian)
- update_parameter_at_index(parameter, index)
- update_parameters(parameters)
- class Hamiltonian
Bases:
object- classmethod __new__(*args, **kwargs)
- static from_hermitian_pauli_sum(pauli_sum, float_type=Ellipsis)
- class HermitianPauliSum
Bases:
object- classmethod __new__(*args, **kwargs)
- constant()
Expose the constant_value
- filter_untouched_qubits(untouched_mask)
Filters the sum based on a bitmask of untouched qubits. Any term acting with X or Y on an untouched qubit is removed.
- format_complex_str(suffix)
- indices()
Returns a sorted list of unique qubit indices acted upon by this sum.
- len()
- number_of_qubits
- prune(tolerance)
- string_coefficient_pairs()
- terms_as_int
- class ParallelSetting
Bases:
object- Parallel = ParallelSetting.Parallel
- Serial = ParallelSetting.Serial
- class ParticleConservation
Bases:
object- Spin = ParticleConservation.Spin
- Total = ParticleConservation.Total
- class PauliString
Bases:
object- classmethod __new__(*args, **kwargs)
- as_ints()
Returns bitmasks (x, y, z) as Python ints (via BigUint).
- commutative_sign(other)
Returns the sign when commuting with another PauliString (-1 or 1).
- classmethod from_sorted_and_disjoint_sets(x_indices=None, y_indices=None, z_indices=None)
- classmethod from_stabilizer(stabilizer)
- classmethod from_z_indices(z_indices)
- is_commuting(other)
Check if the Pauli string commutes with another.
- is_diagonal()
Check if the Pauli string only contains diagonal (I and Z) operators.
- is_identity()
- max_index
- min_index
- multiply(other)
Multiply with another PauliString.
- to_stabilizer(num_qubits=None)
Converts to Stabilizer.
- x_indices
- y_indices
- z_indices
- class RustCircuit
Bases:
object- classmethod __new__(*args, **kwargs)
- cx(control_qubit_index, target_qubit_index)
Append a gate corresponding to the CXGate in Kvantify Qrunch.
- decay(random_threshold, index)
Append a gate corresponding to the Decay.
- dephasing(random_threshold, index)
Append a gate corresponding to the Dephasing.
- double_excitation(parameter, creation_qubit_index_1, creation_qubit_index_2, annihilation_qubit_index_1, annihilation_qubit_index_2)
Append a gate corresponding to the DoubleExcitationGate in Kvantify Qrunch.
- num_qubits()
- requires_complex_numbers()
- rx(parameter, qubit_index)
Append a gate corresponding to the RXGate in Kvantify Qrunch.
- ry(parameter, qubit_index)
Append a gate corresponding to the RYGate in Kvantify Qrunch.
- rz(parameter, qubit_index)
Append a gate corresponding to the RZGate in Kvantify Qrunch.
- single_excitation(parameter, creation_qubit_index, annihilation_qubit_index)
Append a gate corresponding to the SingleExcitationGate in Kvantify Qrunch.
- x(qubit_index)
Append a gate corresponding to the XGate in Kvantify Qrunch.
- class RustEstimatingResult
Bases:
object- expectation_values
- number_of_amplitudes_used
- state_vector_error
- class RustMemoryRestrictedSimulator
Bases:
object- classmethod __new__(*args, **kwargs)
- estimate(observables, circuit)
- get_cached_effective_max_number_of_amplitudes()
- sample(circuit, shots)
- class Stabilizer
Bases:
objectStabilizer of Pauli strings, represented by z and x one-hot vectors. Each entry is 0 or 1.
- classmethod __new__(*args, **kwargs)
- multiply(other)
Multiplies with another stabilizer. Returns (Resulting Stabilizer, Complex Phase)
- x
- z
- compute_excitation_metrics_topk_biguint(observable, measurements_integer_dict, num_alpha_electrons, num_beta_electrons, num_spatial_orbitals, include_single, include_double, excluded_indices, metric_type, expectation_value, top_k, single_scaling_factor)
Combined excitation index generation + metric computation + top-k selection (BigUint measurements).
Same as compute_excitation_metrics_topk_u64 but for systems with >= 65 qubits. Excitations are processed in batches to limit peak memory.
- compute_excitation_metrics_topk_u64(observable, measurements_integer_dict, num_alpha_electrons, num_beta_electrons, num_spatial_orbitals, include_single, include_double, excluded_indices, metric_type, expectation_value, top_k, single_scaling_factor)
Combined excitation index generation + metric computation + top-k selection (u64 measurements).
This function combines three steps in a single Rust call, avoiding repeated Python↔Rust boundary crossings and the overhead of creating millions of Python GatePoolOperator objects:
Generate excitation indices in batches (filtering excluded ones)
Compute importance metrics for each batch
Stream results into a top-k accumulator
Excitations are processed in batches of EXCITATION_BATCH_SIZE to limit peak memory usage when the total count scales as O(N⁴).
- Parameters:
observable – The Hamiltonian / observable
measurements_integer_dict – Sparse measurement map {bitstring_int: probability}
num_alpha_electrons – Number of alpha (spin-up) electrons
num_beta_electrons – Number of beta (spin-down) electrons
num_spatial_orbitals – Number of spatial orbitals
include_single – Whether to include single excitations
include_double – Whether to include double excitations
excluded_indices – Indices to exclude (already selected/excluded gates)
metric_type – 0 = heuristic_gradient, 1 = full_heuristic_gradient, 2 = selected_ci
expectation_value – Current expectation value (only used for selected_ci)
top_k – Number of top entries to return
single_scaling_factor – Scaling factor applied to single excitation metrics
- Returns:
Tuple of (top_k_results, total_metric_sum) where top_k_results is a list of (indices, metric) tuples sorted by metric descending.
- compute_pair_excitation_metrics_topk_biguint(observable, measurements_integer_dict, num_electron_pairs, num_spatial_orbitals, include_single, include_double, excluded_indices, metric_type, expectation_value, top_k, single_scaling_factor)
Combined pair-excitation index generation + metric computation + top-k selection (BigUint measurements).
Same as compute_pair_excitation_metrics_topk_u64 but for systems with >= 65 qubits.
- compute_pair_excitation_metrics_topk_u64(observable, measurements_integer_dict, num_electron_pairs, num_spatial_orbitals, include_single, include_double, excluded_indices, metric_type, expectation_value, top_k, single_scaling_factor)
Combined pair-excitation index generation + metric computation + top-k selection (u64 measurements).
This is the BEAST analogue of compute_excitation_metrics_topk_u64. Instead of alpha/beta spin sectors, pair excitations operate on a single set of spatial orbitals with occupied pairs in [0, num_electron_pairs) and virtual orbitals in [num_electron_pairs, num_spatial_orbitals).
- Parameters:
observable – The Hamiltonian / observable
measurements_integer_dict – Sparse measurement map {bitstring_int: probability}
num_electron_pairs – Number of occupied electron pairs
num_spatial_orbitals – Number of spatial orbitals
include_single – Whether to include single pair excitations
include_double – Whether to include double pair excitations
excluded_indices – Indices to exclude (already selected/excluded gates)
metric_type – 0 = heuristic_gradient, 1 = full_heuristic_gradient, 2 = selected_ci
expectation_value – Current expectation value (only used for selected_ci)
top_k – Number of top entries to return
single_scaling_factor – Scaling factor applied to single pair excitation metrics
- create_hermitian_pauli_sum_from_fermionic_hamiltonian(one_body_alpha_alpha, one_body_beta_beta, two_body_alpha_alpha, two_body_beta_beta, two_body_beta_alpha, number_of_qubits, tolerance=1e-10)
- create_hermitian_pauli_sum_from_hardcore_bosonic_hamiltonian(one_body_matrix, two_body_matrix, number_of_qubits, tolerance=1e-10)
- full_heuristic_gradient_metrics_biguint(observable, measurements_integer_dict, gate_pool_as_generator_indices)
- full_heuristic_gradient_metrics_for_custom_operators(observable, measurements_integer_dict, gate_pool_as_generator_dict_list)
- full_heuristic_gradient_metrics_u64(observable, measurements_integer_dict, gate_pool_as_generator_indices)
- generate_1_rdm_operators(num_qubits)
Generate the operators needed for the 1-particle reduced density matrix.
Returns two lists: 1. diagonal_operators – n operators of the form 0.5*Z(p) + 0.5*Z(p+n). 2. off_diagonal_operators – C(n,2) operators for p < q with alpha+beta XX+YY terms.
The Python side uses them as: gamma[p,p] = 1 - <diagonal_op_p> and gamma[p,q] = gamma[q,p] = <off_diagonal_op_{p,q}>.
- generate_2_rdm_operators(num_qubits)
Generate the operators needed for the 2-particle reduced density matrix.
Returns a tuple of: 1. operators – the list of HermitianPauliSum to estimate. 2. skip_indexes – the set of (p, r, s, q) tuples that produced zero operators. 3. canonical_indices – the canonical (p, r, s, q) tuples from the iteration.
- generate_3_rdm_operators(num_qubits)
Generate the operators needed for the 3-particle reduced density matrix.
- generate_4_rdm_operators(num_qubits)
Generate the operators needed for the 4-particle reduced density matrix.
- generate_excitation_indices(num_alpha_electrons, num_beta_electrons, num_spatial_orbitals, include_single, include_double)
Generate all excitation gate pool indices for a molecular electron configuration.
This is a fast Rust implementation that generates all valid single and/or double excitation operators, returning them as index lists that can be directly used by the metric calculators.
- Parameters:
num_alpha_electrons – Number of alpha (spin-up) electrons
num_beta_electrons – Number of beta (spin-down) electrons
num_spatial_orbitals – Number of spatial orbitals
include_single – Whether to include single excitations
include_double – Whether to include double excitations
- Returns:
A list of index lists. Single excitations have 2 indices, double excitations have 4.
- generate_xx_operators(dimension)
Generate all C(dimension, 2) HermitianPauliSums, each containing a single X⊗X Pauli string over every unique 2-qubit combination.
- generate_xx_plus_yy_operators(dimension)
Generate all
C(dimension, 2)two-term HermitianPauliSumsX[x]*X[y] + Y[x]*Y[y]for each unique pair(x, y).
- generate_xx_plus_yy_with_z_operators(dimension)
Generate (X[x]*X[y]+Y[x]*Y[y]) * Z[p] operators.
For each (x, y) with x < y, and each p ∉ {x, y}, produce a two-term sum.
- generate_xx_plus_yy_with_zz_operators(dimension)
Generate (X[x]*X[y]+Y[x]*Y[y]) * Z[p]*Z[q] operators.
For each (x, y) with x < y, and each (p, q) with p < q and {p,q} ∩ {x,y} = ∅, produce a two-term sum.
- generate_xxxx_plus_yyyy_operators(dimension)
Generate all C(dimension, 4) HermitianPauliSums, each containing two terms: X⊗X⊗X⊗X + Y⊗Y⊗Y⊗Y over every unique 4-qubit combination.
- generate_xxyy_operators(dimension)
Generate XXYY operators for pair-of-pairs iteration.
For each (x, y) with x < y, and each (p, q) with p < q and {p,q} ∩ {x,y} = ∅, produce a single-term sum: X[x]*X[y]*Y[p]*Y[q].
- generate_z_operators(dimension)
Generate all
dimensionHermitianPauliSums, each containing a single Z Pauli string on one qubit.
- generate_zz_operators(dimension)
Generate all C(dimension, 2) HermitianPauliSums, each containing a single Z⊗Z Pauli string over every unique 2-qubit combination.
- generate_zzz_operators(dimension)
Generate all C(dimension, 3) HermitianPauliSums, each containing a single Z⊗Z⊗Z Pauli string over every unique 3-qubit combination.
- generate_zzzz_operators(dimension)
Generate all C(dimension, 4) HermitianPauliSums, each containing a single Z⊗Z⊗Z⊗Z Pauli string over every unique 4-qubit combination.
- generate_zzzzz_operators(dimension)
Generate all C(dimension, 5) HermitianPauliSums, each containing a single Z⊗Z⊗Z⊗Z⊗Z Pauli string over every unique 5-qubit combination.
- generate_zzzzz_operators_for_active_terms(active_terms, dimension)
Generate Z⊗Z⊗Z⊗Z⊗Z operators for a subset of qubit quintuples determined by active pair-breaking terms.
For each active term
(y, x, v, u)and each qubitein0..dimensionthat is not in{y, x, v, u}, produce a single-termHermitianPauliSumcontainingZ(y)*Z(x)*Z(v)*Z(u)*Z(e).The ordering exactly matches the Python loop:
for active_term in active_terms: for e in range(n): if e in {y, x, v, u}: continue ...
- heuristic_gradient_metrics_biguint(observable, measurements_integer_dict, gate_pool_as_generator_indices)
- heuristic_gradient_metrics_for_custom_operators(observable, measurements_integer_dict, gate_pool_as_generator_dict_list)
- heuristic_gradient_metrics_u64(observable, measurements_integer_dict, gate_pool_as_generator_indices)
- multiply_paulis(paulis)
- selected_ci_metrics_biguint(observable, measurements_integer_dict, gate_pool_as_generator_indices, expectation_value)
- selected_ci_metrics_for_custom_operators(observable, measurements_integer_dict, gate_pool_as_generator_dict_list, expectation_value)
- selected_ci_metrics_u64(observable, measurements_integer_dict, gate_pool_as_generator_indices, expectation_value)
- top_k_double_excitation_metrics_from_integrals(eri_aa, eri_bb, eri_ba, n_alpha_occ, n_beta_occ, n_spatial, top_k)
Compute the top-k double-excitation heuristic gradient metrics directly from the molecular electron-repulsion integrals (ERIs) using the Slater–Condon rules, without building the qubit Hamiltonian.
For a double excitation i_ρ → a_ρ , j_ν → b_ν the first-order metric is:
- Same-spin (ρ = ν):
M = abs(⟨a b || i j⟩) = abs(g[a,j,b,i] − g[a,i,b,j])
- Mixed-spin (ρ ≠ ν):
M = abs(eri_ba[b,j,a,i])(or transposed, depending on which spin is alpha)
The function enumerates all spin-conserving double excitations, keeps only the top_k largest, and returns them sorted descending.
Generator-indices convention:
[c1, c2, a1, a2]where c1 < c2 are creation (virtual) qubit indices, a1 < a2 are annihilation (occupied) qubit indices. Alpha qubits are[0, n_spatial), beta are[n_spatial, 2·n_spatial).- Parameters:
eri_aa – Alpha-alpha 4-index ERI tensor, shape (n_sp, n_sp, n_sp, n_sp).
eri_bb – Beta-beta 4-index ERI tensor.
eri_ba – Beta-alpha 4-index ERI tensor.
n_alpha_occ – Number of occupied alpha orbitals.
n_beta_occ – Number of occupied beta orbitals.
n_spatial – Number of spatial orbitals.
top_k – Maximum number of results to return.
- top_k_pair_excitation_metrics_from_integrals(single_excitation_array, n_occ, n_spatial, top_k)
Compute the top-k pair-excitation metrics for the BEAST Hamiltonian directly from the reduced one-body integrals
h^{(r1)}.For a pair excitation i → a (moving a pair from occupied spatial orbital i to virtual spatial orbital a) the first-order metric derived from the BEAST Hamiltonian is:
M_{ai} = |h^{(r1)}_{a,i}|where
h^{(r1)}_{p,q} = h_{p,q} δ_{pq} + (pq|pq). For a ≠ i this simplifies to(ai|ai)– the pair-transfer integral.The function enumerates all pair excitations from occupied orbitals
[0, n_occ)to virtual orbitals[n_occ, n_spatial), keeps only the top_k largest by absolute value, and returns them sorted descending.Generator-indices convention:
[creation_qubit, annihilation_qubit]where qubit indices are in[0, n_spatial).- Parameters:
single_excitation_array – The
h^{(r1)}matrix, shape(n_spatial, n_spatial).n_occ – Number of occupied (pair-occupied) spatial orbitals.
n_spatial – Total number of spatial orbitals.
top_k – Maximum number of results to return.
- top_k_single_excitation_metrics_from_integrals(h_alpha, h_beta, eri_aa, eri_bb, eri_ba, n_alpha_occ, n_beta_occ, n_spatial, top_k)
Compute the top-k first-order single-excitation metrics (Fock matrix off-diagonal elements) directly from one-body and two-body integrals, without building the qubit Hamiltonian.
For a single excitation i_ρ → a_ρ the first-order metric is the absolute value of the Fock matrix element:
- Alpha excitation (a, i both in alpha sector):
F_{ai} = h_α[a,i] + Σ_j∈occ_α (g_αα[a,i,j,j] − g_αα[a,j,j,i]) + Σ_j∈occ_β g_βα[j,j,a,i]
- Beta excitation (a, i both in beta sector):
F_{ai} = h_β[a,i] + Σ_j∈occ_β (g_ββ[a,i,j,j] − g_ββ[a,j,j,i]) + Σ_j∈occ_α g_βα[a,i,j,j]
M =
abs(F_{ai})Generator-indices convention: [creation_qubit, annihilation_qubit]. Alpha qubits are [0, n_spatial), beta are [n_spatial, 2·n_spatial).
- Parameters:
h_alpha – Alpha one-body integrals, shape (n_spatial, n_spatial).
h_beta – Beta one-body integrals, shape (n_spatial, n_spatial).
eri_aa – Alpha-alpha 4-index ERI tensor, shape (n_sp, n_sp, n_sp, n_sp).
eri_bb – Beta-beta 4-index ERI tensor.
eri_ba – Beta-alpha 4-index ERI tensor.
n_alpha_occ – Number of occupied alpha orbitals.
n_beta_occ – Number of occupied beta orbitals.
n_spatial – Number of spatial orbitals.
top_k – Maximum number of results to return.
- top_k_single_excitation_metrics_second_order_from_integrals(h_alpha, h_beta, eri_aa, eri_bb, eri_ba, n_alpha_occ, n_beta_occ, n_spatial, top_k)
Compute the top-k second-order single-excitation metrics from the BCH expansion directly from one-body and two-body integrals, without building the qubit Hamiltonian.
For a single excitation i_ρ → a_ρ the second-order metric is:
M_{ai}^{(2)} = abs(2 * (ε_a − ε_i − J_{ai} + K_{ai}))where ε_p is the Fock diagonal (orbital energy), and J_{ai}, K_{ai} are Coulomb and exchange integrals between orbitals a and i.
- Alpha (a, i in alpha sector):
ε_p = h_α[p,p] + Σ_k∈occ_α (g_αα[p,p,k,k] − g_αα[p,k,k,p]) + Σ_k∈occ_β g_βα[k,k,p,p]J_{ai} = g_αα[a,a,i,i]K_{ai} = g_αα[a,i,a,i]
- Beta (a, i in beta sector):
ε_p = h_β[p,p] + Σ_k∈occ_β (g_ββ[p,p,k,k] − g_ββ[p,k,k,p]) + Σ_k∈occ_α g_βα[p,p,k,k]J_{ai} = g_ββ[a,a,i,i]K_{ai} = g_ββ[a,i,a,i]
Generator-indices convention: [creation_qubit, annihilation_qubit]. Alpha qubits are [0, n_spatial), beta are [n_spatial, 2·n_spatial).
- Parameters:
h_alpha – Alpha one-body integrals, shape (n_spatial, n_spatial).
h_beta – Beta one-body integrals, shape (n_spatial, n_spatial).
eri_aa – Alpha-alpha 4-index ERI tensor, shape (n_sp, n_sp, n_sp, n_sp).
eri_bb – Beta-beta 4-index ERI tensor.
eri_ba – Beta-alpha 4-index ERI tensor.
n_alpha_occ – Number of occupied alpha orbitals.
n_beta_occ – Number of occupied beta orbitals.
n_spatial – Number of spatial orbitals.
top_k – Maximum number of results to return.