Result

Result models, interpreter and visualizer utilities.

Data models for interpreting and visualizing protein folding results.

class result.models.BeadPosition(index, symbol, x, y, z)

Bases: object

Data class for storing the position of a bead in 3D space.

Variables:

  • index (int) – The index of the bead.

  • symbol (str) – The chemical symbol of the bead.

  • x (float) – The x-coordinate of the bead.

  • y (float) – The y-coordinate of the bead.

  • z (float) – The z-coordinate of the bead.

__init__(index, symbol, x, y, z)
index: int
symbol: str
x: float
y: float
z: float
class result.models.SparseVQEOutput(bitstring, probability, state, energy_value)

Bases: object

Data class for storing sparse VQE output results.

Variables:

  • bitstring (str) – The bitstring representation of the quantum state.

  • probability (float) – The probability associated with the bitstring.

  • state (str) – The quantum state in string format.

  • energy_value (np.complex128) – The energy value corresponding to the quantum state.

__init__(bitstring, probability, state, energy_value)
bitstring: str
energy_value: complex128
probability: float
state: str

Subpackage: interpreter

Utilities for interpreting protein folding results.

This module provides the ResultInterpreter class, which processes the results of quantum simulations for protein folding, including detailed VQE results, decoded turn sequences, and 3D coordinate mappings.

class result.interpreter.result_interpreter.ResultInterpreter(protein, dirpath, raw_vqe_results, vqe_energies, vqe_iterations)

Bases: object

Interprets and processes the results of quantum protein folding simulations.

Variables:

  • coordinates_3d (list[BeadPosition]) – 3D coordinates of the protein beads.

  • turn_sequence (list[TurnDirection]) – Decoded sequence of turns for the protein chain.

__init__(protein, dirpath, raw_vqe_results, vqe_energies, vqe_iterations)

Initialize the ResultInterpreter with protein data and VQE results.

Parameters:

  • protein (Protein) – The Protein object containing chain information.

  • dirpath (Path) – Directory path for saving output files.

  • raw_vqe_results (SamplingMinimumEigensolverResult) – Raw VQE results from quantum simulation.

  • vqe_energies (list[float]) – List of VQE energy values per iteration.

  • vqe_iterations (list[int]) – List of VQE iteration numbers.

Raises:

ConformationEncodingError – If the conformation encoding is not recognized.

_dump_result_dict_to_json(filename, results_dict)

Dumps the given results dictionary to a JSON file.

Return type:

None

Parameters:

  • filename (str) – The name of the file to save the results.

  • results_dict (SparseVQEOutput | SamplingMinimumEigensolverResult) – The results data to be saved.

Raises:

Exception – If there is an error during sanitization or file writing.

_dump_vqe_iterations_to_file(filename)

Dumps the VQE iterations and their corresponding energies to a text file.

Return type:

None

Parameters:

filename (str) – The name of the file to save the VQE iterations and energies.

Raises:

Exception – If there is an error writing to the file.

_find_main_main_contacts()

Finds contacts between main chain beads based on the interaction bits.

This reads the first part of the raw VQE bitstring, which contains the on/off flags for potential interactions.

Return type:

dict[int, int]

Returns:

A dictionary mapping bead index i to bead index j for each detected interaction (we don’t store contacts symmetrically, assume contacts are bidirectional).

Return type:

dict[int, int]

_generate_3d_coordinates()

Generates the coordinates for the beads in the main chain in 3D tetrahedral lattice.

Return type:

list[BeadPosition]

Note

The 3D coordinates are generated based on the tetrahedral lattice structure, which is used to represent the spatial arrangement of the beads in the protein. Calculations use the FCC basis vectors to determine the position of each bead based on the turn sequence and the sublattice they belong to (determined by the bead index - alternating signs).

Returns:

List of 3D coordinates for each bead in the main chain.

Return type:

list[BeadPosition]

Raises:

ConformationEncodingError – If the decoded turns contain unknown encodings.

_generate_turn_sequence()

Generates the turn sequence from the processed bitstring.

Return type:

list[TurnDirection]

Returns:

The decoded sequence of turns.

Return type:

list[TurnDirection]

Raises:

ConformationEncodingError – If the decoded turns contain unknown encodings.

_get_target_sequence_length_main_chain()

Calculates the target length (in bits) of the turn sequence for the main chain.

Return type:

int

Note

Each turn is represented by a fixed number of qubits (QUBITS_PER_TURN). The number of turns is N - 1, where N is the number of beads in the main chain. However, by the symmetry of tetrahedral lattice we can assume that:

  • The first two turns are fixed.

  • (Sparse encoding only) If we don’t have a side bead attached to the second bead, we can encode the third turn as fixed value of “1”.

Returns:

Target turn sequence length for the main chain in bits.

Return type:

int

Raises:

ConformationEncodingError – If the conformation encoding is not recognized.

_interpret_raw_vqe_results()

Interprets the raw VQE results into a structured SparseVQEOutput.

Return type:

SparseVQEOutput

Returns:

The interpreted VQE results.

Return type:

SparseVQEOutput

Raises:

ValueError – If the best measurement data is incomplete or missing.

_log_coordinates_3d()

Logs the generated 3D coordinates.

Return type:

None

_log_turn_sequence()

Logs the decoded turn sequence.

Return type:

None

_preprocess_bitstring(bitstring)

Preprocesses the raw bitstring from VQE results to match the expected format.

Return type:

str

Note

Bitstring preprocessing includes: - Trimming to the target length. - Appending fixed turn indicators for the first two turns. - Handling special cases for the fifth bead’s sidechain in dense encoding

For details regarding processing, see _get_target_sequence_length_main_chain.

Parameters:

bitstring (str) – The raw bitstring from VQE results.

Returns:

The preprocessed bitstring ready for turn sequence decoding.

Return type:

str

property coordinates_3d: list[BeadPosition]

3D coordinates of the protein beads.

Type:

list[BeadPosition]

dump_results_to_files()

Dumps the interpreted results to output files in the specified directory.

Return type:

None

property main_main_contacts_detected: dict[int, int]

Main-main contacts detected in the result sequence.

Type:

dict[int, int]

property turn_sequence: list[TurnDirection]

Sequence of turns in the protein folding.

Type:

list[TurnDirection]

Subpackage: visualizer

Utilities for visualizing protein folding results.

This module provides the ResultVisualizer class, which processes the interpreted results of protein folding simulations and generates 3D and 2D visualizations of the folded protein structure.

class result.visualizer.result_visualizer.ResultVisualizer(dirpath, turn_sequence, coordinates_3d, main_main_contacts_detected)

Bases: object

Visualizes and processes interpreted results of quantum protein folding simulations.

__init__(dirpath, turn_sequence, coordinates_3d, main_main_contacts_detected)

Initialize the ResultVisualizer with contacts data from the main chain, directory path and decoded turn sequence and 3D coordinates.

Parameters:

  • dirpath (Path) – Directory path for saving output files.

  • turn_sequence (list[TurnDirection]) – Decoded turn sequence.

  • coordinates_3d (list[BeadPosition]) – 3D coordinates of the protein structure.

  • main_main_contacts_detected (dict[int, int]) – Detected contacts between main chain beads.

_generate_lattice_points(coords, padding=TETRAHEDRAL_LATTICE_PADDING)

Generate tetrahedral lattice points in range that matches the coordinates of the conformation (by taking the min/max values from the coordinates and padding them accordingly).

Return type:

ndarray[tuple[Any, ...], dtype[float64]]

Parameters:

  • coords (NDArray[np.float64]) – The coordinates of the conformation.

  • padding (int) – Value that determines the padding around the coordinates (how big should the space be). Defaults to TETRAHEDRAL_LATTICE_PADDING.

static _get_text_color(rgb_color, brightness_threshhold=0.5)

Helper function to choose black or white text depending on the brightness of the RGB color (using luminance formula for RGB).

Return type:

str

Parameters:

  • rgb_color (str) – The RGB color string in the format “rgb(r, g, b)”.

  • brightness_threshhold (float) – The brightness threshold for determining text color.

generate_3d_gif(filename=GIF_VISUALIZATION_FILENAME)

Generate interactive simplified 3D visualization of the resulting conformation as a rotating plot in the .html file format.

Return type:

None

Parameters:

filename (str) – The name of the file to save the rotating .gif plot. Defaults to GIF_VISUALIZATION_FILENAME constant.

visualize_2d(filename=FLAT_VISUALIZATION_FILENAME)

Generate flat, 2D visualization of the resulting conformation in the .png file format.

This plot is a 2D projection (top-down view) of the 3D coordinates.

Return type:

None

Parameters:

filename (str) – The name of the file to save the static .png visualization. Defaults to FLAT_VISUALIZATION_FILENAME.

visualize_3d(filename=HTML_VISUALIZATION_FILENAME)

Generate interactive 3D visualization of the resulting conformation in the .html file format.

Return type:

None

Parameters:

filename (str) – The name of the file to save the interactive .html visualization. Defaults to HTML_VISUALIZATION_FILENAME.