Builder

Hamiltonian builder utilities.

Utilities for building the hamiltonian of a protein for quantum simulations.

This module provides the HamiltonianBuilder class, which constructs hamiltonian operators for a given protein, including backbone interactions, backtracking penalties, and neighbor-based contact terms, using distance and interaction maps.

class builder.hamiltonian_builder.HamiltonianBuilder(protein, interaction, distance_map, contact_map)

Bases: object

Constructs hamiltonian operators for a given protein, including backbone interactions and backtracking penalties.

Variables:

  • protein (Protein) – The Protein object that includes all information about protein.

  • interaction (Interaction) – Interaction model between beads of the protein.

  • distance_map (DistanceMap) – Matrix of pairwise distances between residues.

  • contact_map (ContactMap) – Matrix indicating residue-residue contacts.

__init__(protein, interaction, distance_map, contact_map)

Initializes the HamiltonianBuilder with required protein data and interaction maps.

Parameters:

  • protein (Protein) – The Protein object that includes all information about protein.

  • interaction (Interaction) – Interaction model between beads of the protein.

  • distance_map (DistanceMap) – Matrix of pairwise distances between residues.

  • contact_map (ContactMap) – Matrix indicating residue-residue contacts.

_add_backtracking_penalty()

Adds a penalty term to the hamiltonian to discourage backtracking in the main chain configuration.

Return type:

SparsePauliOp

Returns:

hamiltonian term representing backtracking penalties.

Return type:

SparsePauliOp

_build_backbone_contact_term()

Builds the hamiltonian term corresponding to backbone_backbone (BB-BB) interactions. Includes both 1st neighbor and 2nd neighbor contributions (with shifts i±1, j±1).

Return type:

SparsePauliOp

Note

Only pairs that belong to different sublattices are considered for first-neighbor interactions. For each valid pair, two contributions are added: one for first-neighbor interactions and one for second-neighbor interactions with nearby beads. The second-neighbor contribution applies a penalty to avoid overlaps.

Returns:

hamiltonian term representing BB-BB interactions.

Return type:

SparsePauliOp

get_first_neighbor_hamiltonian(lower_bead_idx, upper_bead_idx, lambda_1)

Computes the hamiltonian contribution for first-neighbor bead pairs, combining distance-based and interaction contact energies.

Return type:

SparsePauliOp

Note

lambda_0 combines the bounding constant, bead separation, and lambda_1

to scale the distance-based penalty. MJ_ENERGY_MULTIPLIER scales the contribution from the Miyazawa-Jernigan interaction energy.

Parameters:

  • lower_bead_idx (int) – Index of the lower bead in the main chain.

  • upper_bead_idx (int) – Index of the upper bead in the main chain.

  • lambda_1 (float) – Penalty coefficient for first neighbor interaction.

Returns:

Quantum operator representing the first neighbor hamiltonian term.

Return type:

SparsePauliOp

Raises:

InvalidOperatorError – If the number of qubits in the operator is None.

get_second_neighbor_hamiltonian(lower_bead_idx, upper_bead_idx, lambda_1)

Computes the hamiltonian contribution for second-neighbor bead pairs, including distance-based and interaction terms.

Return type:

SparsePauliOp

Parameters:

  • lower_bead_idx (int) – Index of the lower bead in the main chain.

  • upper_bead_idx (int) – Index of the upper bead in the main chain.

  • lambda_1 (float) – Penalty coefficient for second neighbor interaction.

Returns:

Quantum operator representing the second neighbor hamiltonian term.

Return type:

SparsePauliOp

Raises:

InvalidOperatorError – If the number of qubits in the operator is None.

get_turn_operators(lower_bead, upper_bead)

Builds the combined turn operators for two consecutive beads in the main chain.

Generates a quantum operator representing allowed directional turns between two beads based on their turn functions. If either bead lacks defined turn functions, an identity operator is returned.

Return type:

SparsePauliOp

Parameters:

  • lower_bead (Bead) – The bead from the main chain at the lower index.

  • upper_bead (Bead) – The bead from the main chain at the upper index.

Returns:

Combined turn operator describing the interaction between the two beads.

Return type:

SparsePauliOp

sum_hamiltonians()

Build and sum all hamiltonian components, padding to a common qubit size.

Constructs the backbone and backtracking terms, checks qubit consistency, pads them to the same qubit count, and sums them into a single hamiltonian.

Return type:

SparsePauliOp

Note

The padding step ensures that all SparsePauliOp operators have the same number of qubits, which is required for valid operator addition. The total hamiltonian is initialized with an identity operator and then each padded component is added sequentially.

Returns:

The total hamiltonian operator, simplified and ready for use.

Return type:

SparsePauliOp

Raises:

InvalidOperatorError – If any part hamiltonian has num_qubits set to None.