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

`compute_excitation_metrics_topk_biguint`(...)	Combined excitation index generation + metric computation + top-k selection (BigUint measurements).
`compute_excitation_metrics_topk_u64`(...)	Combined excitation index generation + metric computation + top-k selection (u64 measurements).
`create_hermitian_pauli_sum_from_fermionic_hamiltonian`(...)
`create_hermitian_pauli_sum_from_hardcore_bosonic_hamiltonian`(...)
`full_heuristic_gradient_metrics_biguint`(...)
`full_heuristic_gradient_metrics_for_custom_operators`(...)
`full_heuristic_gradient_metrics_u64`(...)
`generate_1_rdm_operators`(num_qubits)	Generate the operators needed for the 1-particle reduced density matrix.
`generate_2_rdm_operators`(num_qubits)	Generate the operators needed for the 2-particle reduced density matrix.
`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`(...)	Generate all excitation gate pool indices for a molecular electron configuration.
`generate_excitation_indices_filtered`(...)	Generate excitation indices with exclusion filtering (Rust-accelerated).
`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 HermitianPauliSums `X[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.
`generate_xx_plus_yy_with_zz_operators`(dimension)	Generate (X[x]X[y]+Y[x]Y[y]) * Z[p]*Z[q] operators.
`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.
`generate_z_operators`(dimension)	Generate all `dimension` HermitianPauliSums, 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`(...)	Generate Z⊗Z⊗Z⊗Z⊗Z operators for a subset of qubit quintuples determined by active pair-breaking terms.
`heuristic_gradient_metrics_biguint`(...)
`heuristic_gradient_metrics_for_custom_operators`(...)
`heuristic_gradient_metrics_u64`(observable, ...)
`multiply_paulis`(paulis)
`selected_ci_metrics_biguint`(observable, ...)
`selected_ci_metrics_for_custom_operators`(...)
`selected_ci_metrics_u64`(observable, ...)

Classes

HermitianPauliSum

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

classmethod __new__(*args, **kwargs)

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 FloatType

Bases: object

F32 = FloatType.F32

F64 = FloatType.F64

classmethod __new__(*args, **kwargs)

class GateZs

Bases: object

Exclude = GateZs.Exclude

Include = GateZs.Include

classmethod __new__(*args, **kwargs)

class Grouping

Bases: object

classmethod __new__(*args, **kwargs)

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

classmethod __new__(*args, **kwargs)

class ParticleConservation

Bases: object

Spin = ParticleConservation.Spin

Total = ParticleConservation.Total

classmethod __new__(*args, **kwargs)

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

classmethod __new__(*args, **kwargs)

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=None)

class RustSamplingResult

Bases: object

classmethod __new__(*args, **kwargs)

number_of_amplitudes_used

samples

state_vector_error

class Stabilizer

Bases: object

Stabilizer 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: 1. Generate excitation indices in batches (filtering excluded ones) 2. Compute importance metrics for each batch 3. 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.

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_excitation_indices_filtered(num_alpha_electrons, num_beta_electrons, num_spatial_orbitals, include_single, include_double, excluded_indices)

Generate excitation indices with exclusion filtering (Rust-accelerated).

Same as generate_excitation_indices but filters out any indices that appear in the provided exclusion set. This avoids the overhead of converting all indices to Python tuples and checking membership in a Python set.

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
excluded_indices – Set of index lists to exclude from the result

Returns:

A list of index lists with excluded entries removed.

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 HermitianPauliSums X[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 dimension HermitianPauliSums, 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 qubit e in 0..dimension that is not in {y, x, v, u}, produce a single-term HermitianPauliSum containing Z(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)