guppyalgos.algorithms.block_encoding.thc

Tensor hypercontraction Select, LCU, and preprocessing helpers.

Functions

build_select_data(terms, n_index_qubits, ...)

Encode (mu, nu, one-body, sign) for each flat alias index.

build_thc_alias_terms(parameters)

Build the unified term table consumed by alias-sampling PREPARE.

build_thc_lcu_data(parameters, *, ...)

Classically preprocess THC parameters for a controlled LCU.

encode_combined_givens_rotations(...)

Encode the combined rotation QROM addressed by little-endian [mu, c].

encode_givens_rotations(rotations, ...)

Encode supplied Givens angles without padding to n_indices rows.

generate_thc_parameters(n_orbitals, thc_rank, *)

Generate deterministic example coefficients and orbital rotations.

load_select_registers(select_data_loader, ...)

Toggle Select fields using the supplied data loader and alias index.

validate_thc_parameters(parameters)

Validate the array shapes and return (n_modes, thc_rank).

Classes

SelectTHCCntrl()

Composable BLISS-THC Select skeleton.

SelectTHCCntrlRegs()

Prepared registers consumed by the BLISS-THC Select circuit.

THCData(alias_probabilities, ...)

Classical data and Guppy QROMs used to construct a controlled THC LCU.

THCParameters(one_body_coefficients, ...)

Classical parameters appearing in the factorized THC Hamiltonian.

THCPreparedTerm(mu, nu, coefficient)

One term in the unified THC alias-sampling table.

THCWalkTargetRegs()

Spin-orbital target registers acted on by the THC Select circuit.
class guppyalgos.algorithms.block_encoding.thc.SelectTHCCntrl

Composable BLISS-THC Select skeleton.

The combined (mu, c) and two-body nu QROM callables are composed with the supplied cascade through SelectRotator. The same cascade is moved through each temporary rotator in turn, allowing it to retain and reuse any quantum resource it owns.

Both internal QROM rotations use identity as their uncompute operation. The initial QROM compute therefore leaves its angle data loaded through the central Pauli action, and the compute at the end of the daggered rotation clears it.

This implements the Select register flow shown in Fig. 1 of Caesura et al., “Faster quantum chemistry simulations on a quantum computer with improved tensor factorization and active volume compilation”, arXiv:2501.06165v1: https://arxiv.org/pdf/2501.06165v1.

Parameters:

  • combined_qrom_compute – QROM loading the combined one- or two-body angles selected by the little-endian address [mu..., c].

  • two_body_qrom_compute – QROM loading the selected two-body angles.

  • cascade – Rotator applying and undoing the loaded Givens cascade.

  • equality_cnx – Multi-controlled-X implementation used to compare the two index registers.

cascade: TypeVar(Cascade, bound= Rotator[array[array[qubit, TypeVar(n_data_q, bound= nat)], TypeVar(n_givens, bound= nat)], array[qubit, TypeVar(n_modes, bound= nat)]])
combined_qrom_compute: Callable[[array[qubit, TypeVar(n_combined_index_q, bound= nat)], array[array[qubit, TypeVar(n_data_q, bound= nat)], TypeVar(n_givens, bound= nat)]], None]
compose(control, prep_register, target_registers)

Apply a BLISS-THC Select circuit matching the Fig. 1 register flow.

Parameters:

  • control – External control for the encoded Select operation.

  • prep_register – Decoded THC indices and coefficient flags.

  • target_registers – Spin-up and spin-down orbital registers.

equality_cnx: Callable[[array[qubit, TypeVar(n_index_q, bound= nat)], qubit], None]
two_body_qrom_compute: Callable[[array[qubit, TypeVar(n_index_q, bound= nat)], array[array[qubit, TypeVar(n_data_q, bound= nat)], TypeVar(n_givens, bound= nat)]], None]
class guppyalgos.algorithms.block_encoding.thc.SelectTHCCntrlRegs

Prepared registers consumed by the BLISS-THC Select circuit.

The circuit and register names follow Fig. 1 of Caesura et al., “Faster quantum chemistry simulations on a quantum computer with improved tensor factorization and active volume compilation”, arXiv:2501.06165v1: https://arxiv.org/pdf/2501.06165v1.

Parameters:

  • one_body_flag – Flag c selecting the one-body contribution.

  • coefficient_sign – Sign qubit m for the selected LCU coefficient.

  • first_index_qreg – First QROM index register b0.

  • second_index_qreg – Second QROM index register b1.

coefficient_sign: qubit
first_index_qreg: array[qubit, TypeVar(n_index_q, bound= nat)]
one_body_flag: qubit
second_index_qreg: array[qubit, TypeVar(n_index_q, bound= nat)]
class guppyalgos.algorithms.block_encoding.thc.THCData(alias_probabilities, alias_precision, select_data_loader, qrom_1_and_2_body, qrom_2_body, n_alias_qubits, n_index_qubits, n_keep_qubits, n_modes, n_givens, rotation_precision_bits)

Classical data and Guppy QROMs used to construct a controlled THC LCU.

This value contains only the result of classical preprocessing: normalized coefficient magnitudes, encoded QROM tables, and the dimensions needed to allocate their registers. It does not choose a quantum rotation synthesis method or construct PREPARE, SELECT, and UNPREPARE.

In particular, the QROMs encode rotation angles without depending on the rotator that consumes them. A caller may combine them with a phase-gradient Givens cascade, a resource-free cascade, or any other signature-compatible Select implementation.

alias_precision: float
alias_probabilities: GenericAlias[float64]
n_alias_qubits: int
n_givens: int
n_index_qubits: int
n_keep_qubits: int
n_modes: int
qrom_1_and_2_body: GuppyFunctionDefinition
qrom_2_body: GuppyFunctionDefinition
rotation_precision_bits: int
select_data_loader: GuppyFunctionDefinition
class guppyalgos.algorithms.block_encoding.thc.THCParameters(one_body_coefficients, two_body_coefficients, one_body_rotations, two_body_rotations)

Classical parameters appearing in the factorized THC Hamiltonian.

Parameters:

  • one_body_coefficients (GenericAlias[float64]) – The \(t_k\) coefficients.

  • two_body_coefficients (GenericAlias[float64]) – Symmetric \(\zeta_{\mu\nu}\) coefficient matrix.

  • one_body_rotations (GenericAlias[float64]) – Full-turn neighboring-Givens angles defining \(V_k\).

  • two_body_rotations (GenericAlias[float64]) – Full-turn neighboring-Givens angles defining \(U_\mu\).

one_body_coefficients: GenericAlias[float64]
one_body_rotations: GenericAlias[float64]
two_body_coefficients: GenericAlias[float64]
two_body_rotations: GenericAlias[float64]
class guppyalgos.algorithms.block_encoding.thc.THCPreparedTerm(mu, nu, coefficient)

One term in the unified THC alias-sampling table.

Parameters:

  • mu (int) – Index of the first orbital transformation.

  • nu (int | None) – Index of the second orbital transformation for a two-body term, or None for a one-body term.

  • coefficient (float) – Signed coefficient prepared by the LCU construction.

coefficient: float
property is_one_body: bool

Whether this entry represents a one-body term.

mu: int
nu: int | None
class guppyalgos.algorithms.block_encoding.thc.THCWalkTargetRegs

Spin-orbital target registers acted on by the THC Select circuit.

Parameters:

  • spin_up – Spin-up orbital register.

  • spin_down – Spin-down orbital register.

spin_down: array[qubit, TypeVar(n_modes, bound= nat)]
spin_up: array[qubit, TypeVar(n_modes, bound= nat)]
guppyalgos.algorithms.block_encoding.thc.build_select_data(terms, n_index_qubits, one_body_sentinel)

Encode (mu, nu, one-body, sign) for each flat alias index.

A one-body entry has no mathematical nu index. For the fixed-width register layout used by SelectTHCCntrl, it is encoded in the conceptual extra column nu = one_body_sentinel.

Return type:

list[list[bool]]

guppyalgos.algorithms.block_encoding.thc.build_thc_alias_terms(parameters)

Build the unified term table consumed by alias-sampling PREPARE.

Two-body terms cover the upper triangle mu <= nu. Their off-diagonal weights are \(\zeta_{\mu\nu}\), while diagonal weights are \(\zeta_{\mu\mu}/4\). One-body terms have nu=None and weights \(-t_\mu\).

The paper’s fixed-width quantum encoding can be pictured as appending an extra column nu = M to the two-body coefficient matrix and placing the one-body terms in that column. This user-facing table represents that extra column with nu=None; build_select_data() introduces the integer sentinel M only when producing the QROM data.

Return type:

list[THCPreparedTerm]

guppyalgos.algorithms.block_encoding.thc.build_thc_lcu_data(parameters, *, rotation_precision_bits, alias_precision_bits)

Classically preprocess THC parameters for a controlled LCU.

This function validates the input data, normalizes the THC coefficient magnitudes, encodes the Select records and Givens angles, and builds Guppy QROM callables for those tables. It deliberately stops at that classical data boundary: it does not allocate qubits, prepare resource states, or instantiate PREPARE, SELECT, UNPREPARE, or a rotation cascade.

Consequently, the returned data are agnostic to the quantum Select and rotation implementation. For example, the QROM angle tables can feed a phase-gradient Givens cascade, but phase-gradient preparation and ownership belong to the caller. Another compatible rotator can consume the same data without changing this preprocessing function.

The generated Givens-angle QROM entries use the parallel data-register layout: each entry contains n_givens distinct little-endian binary angle registers, each of width rotation_precision_bits. A cascade therefore receives one data register for each neighboring Givens rotation, rather than reusing a single register to load its angles serially. This uses more angle-register qubits in exchange for the corresponding depth-efficient data-loading interface.

Parameters:

  • parameters (THCParameters) – Classical THC coefficients and neighboring-Givens angles.

  • rotation_precision_bits (int) – Number of bits used to encode each rotation.

  • alias_precision_bits (int) – Number of bits used by alias-sampling probabilities.

Return type:

THCData

Returns:

Normalized alias data, encoded Guppy QROMs, and dimensions from which a caller can construct its chosen controlled LCU.

guppyalgos.algorithms.block_encoding.thc.encode_combined_givens_rotations(two_body_rotations, one_body_rotations, precision_bits, n_index_qubits)

Encode the combined rotation QROM addressed by little-endian [mu, c].

The one-body flag c is the most-significant address bit. Consequently, two-body rows occupy addresses mu and one-body rows occupy addresses 2**n_index_qubits + mu. Unused two-body addresses between the physical THC rank and the start of the one-body block are filled with zero angles.

Parameters:

  • two_body_rotations (GenericAlias[float64]) – Givens angles defining each two-body U_mu.

  • one_body_rotations (GenericAlias[float64]) – Givens angles defining each one-body V_mu.

  • precision_bits (int) – Number of bits used to encode each angle.

  • n_index_qubits (int) – Width of the mu register before appending c.

Return type:

list[list[list[bool]]]

guppyalgos.algorithms.block_encoding.thc.encode_givens_rotations(rotations, precision_bits, n_indices)

Encode supplied Givens angles without padding to n_indices rows.

Raises:

ValueError – If the supplied rotation rows do not fit in the declared index space.

Return type:

list[list[list[bool]]]

guppyalgos.algorithms.block_encoding.thc.generate_thc_parameters(n_orbitals, thc_rank, *, seed=7)

Generate deterministic example coefficients and orbital rotations.

The generated arrays have the shapes required by the BLISS-THC expression. This helper is intended for examples and compilation studies; production applications should construct THCParameters from chemistry data.

Return type:

THCParameters

guppyalgos.algorithms.block_encoding.thc.load_select_registers(select_data_loader, alias_index, select_regs)

Toggle Select fields using the supplied data loader and alias index.

The QROM stores records of the form [mu, nu, one_body, sign]. This function temporarily joins the corresponding Select fields, applies the QROM, and splits them back into their named registers. Calling it again with the same alias index clears the fields during UNPREPARE.

Parameters:

  • select_data_loader – QROM loading one flattened Select record.

  • alias_index – Address of the sampled THC term.

  • select_regs – Named THC Select fields loaded by the QROM.

guppyalgos.algorithms.block_encoding.thc.validate_thc_parameters(parameters)

Validate the array shapes and return (n_modes, thc_rank).

Return type:

tuple[int, int]