Core modules

Core and small utility modules that define constants, enumerations, exceptions, and main execution logic.

Constants

Definitions of constants used throughout the protein folding simulations.

This module centralizes configuration parameters, file paths, numeric constants, energy coefficients, and backend options required by different components of the project.

ROOT_PROJECT_PATHPath

Root directory of the repository.

LOGS_DIRPATHPath

Directory where log files are stored.

MJ_INTERACTION_MATRIX_FILEPATHPath

Path to the Miyazawa-Jernigan interaction matrix file.

HP_INTERACTION_MATRIX_FILEPATHPath

Path to the hydrophobic-polar matrix file.

DEFAULT_TIMEZONEtzinfo

Timezone used for timestamping logs and outputs.

CONFORMATION_ENCODINGConformationEncoding

Selected encoding type for representing turns in the lattice.

QUBITS_PER_TURNint

Number of qubits required to encode a single turn.

EMPTY_SIDECHAIN_PLACEHOLDERstr

Placeholder symbol for missing side-chain positions.

NORM_FACTORfloat

Normalization factor applied during distance vector construction.

SIGN_FLIP_SECOND_QUBIT_INDEXint

Index of the second qubit whose sign may require inversion.

SIGN_FLIP_SIXTH_QUBIT_INDEXint

Index of the sixth qubit whose sign may require inversion.

DIST_VECTOR_AXESint

Number of axes in the distance operator vector.

BOUNDING_CONSTANTint

Limits how far the chain is allowed to spread in space, preventing exploration of physically impossible conformations.

MJ_ENERGY_MULTIPLIERfloat

Scaling factor applied to Miyazawa-Jernigan energies.

HP_HH_CONTACT_ENERGYfloat

Energy contribution for hydrophobic-hydrophobic contact in the HP model.

HP_NON_HH_CONTACT_ENERGYfloat

Energy contribution for non-hydrophobic contacts in the HP model.

GLOBAL_LOGGER_NAMEstr

Name of the root logger for the project.

LOGGER_DEFAULT_LEVELint

Default logging verbosity.

MIN_DISTANCE_BETWEEN_CONTACTSint

Smallest allowed distance along the chain for beads to form a valid contact.

MAIN_CHAIN_FIXED_POSITIONSlist[int]

Main-chain bead indices that must be assigned predefined values during encoding.

MAIN_CHAIN_FIFTH_FIXED_POSITIONint

Index of the bead with a predetermined position in the chain.

INTERACTION_TYPEInteractionType

Selected interaction model (MJ or HP).

IDENTITY_OP_COEFFfloat

Coefficient applied to the identity operator when building the Hamiltonian.

EMPTY_OP_COEFFfloat

Coefficient used when an operator contributes no term.

SPARSE_TURN_INDICATORSdict[TurnDirection, str]

Sparse encoding for turn directions.

DENSE_TURN_INDICATORSdict[TurnDirection, str]

Dense encoding for turn directions.

XYZ_FILE_LINE_START_INDEXint

Number of header lines in .xyz coordinate files.

XYZ_FILE_PARTS_PER_LINEint

Expected number of fields per line in .xyz files.

RESULTS_DATA_DIRPATHPath

Directory where simulation’s results are written.

RAW_VQE_RESULTS_FILENAMEstr

Filename for raw VQE results.

XYZ_FILENAMEstr

Name of the output XYZ coordinate file.

SPARSE_VQE_RESULTS_FILENAMEstr

Filename for sparse VQE result summaries.

VQE_ITERATIONS_FILENAMEstr

Filename recording energy per iteration.

GIF_VISUALIZATION_FILENAMEstr

Name of the generated 3D GIF visualization.

HTML_VISUALIZATION_FILENAMEstr

Name of the interactive HTML visualization.

FLAT_VISUALIZATION_FILENAMEstr

Name of the 2D conformational plot.

TETRAHEDRAL_LATTICE_PADDINGint

Extra spacing added to bead coordinates to prevent index conflicts.

INDEX_COLNAMEstr

Column name for bead indices.

SYMBOL_COLNAMEstr

Column name for residue symbols.

ITERATION_COLNAMEstr

Column name for iteration counters.

COORDINATES_COLUMN_WIDTHint

Output formatting width for coordinate columns.

FCC_EDGE_LENGTHfloat

Edge length of fractional FCC unit vectors.

FCC_BASISndarray

Basis vectors of the face-centered cubic lattice.

SIDE_CHAIN_FIFTH_POSITION_INDEXint

Index of the side-chain bead associated with the fifth main-chain position.

BACKEND_TYPEBackendType

Selected quantum backend type.

IBM_QUANTUM_TOKENstr or None

IBM Quantum API token loaded from environment.

IBM_QUANTUM_BACKEND_NAMEstr

Name of the IBM Quantum device to execute circuits on.

IBM_QUANTUM_SHOTSint

Number of measurement shots for hardware execution.

MIN_CHAIN_LENGTHint

Minimum allowed protein chain length for simulations.

Enums

Defines key enumerations for modeling protein folding constraints and encodings.

class enums.BackendType(*values)

Bases: Enum

Enum representing quantum backend types for VQE execution.

IBM_QUANTUM = 'ibm_quantum'

LOCAL_STATEVECTOR = 'local_statevector'

class enums.ConformationEncoding(*values)

Bases: IntEnum

Enum representing a map of encoding types and qubit counts.

DENSE = 2

SPARSE = 4

class enums.InteractionType(*values)

Bases: IntEnum

Enum representing interaction types.

HP = 1

MJ = 0

class enums.Penalties(*values)

Bases: IntEnum

Enum representing penalty types for protein folding constraints.

BACK_PENALTY = 10

CHIRALITY_PENALTY = 10

OVERLAP_PENALTY = 10

class enums.SubLattice(*values)

Bases: IntEnum

Enum representing the sublattices in the protein chain.

A = 0

B = 1

class enums.TurnDirection(*values)

Bases: IntEnum

Enum representing turn directions on a tetrahedral lattice.

DIR_0 = 0

DIR_1 = 1

DIR_2 = 2

DIR_3 = 3

Exceptions

Defines custom exceptions for protein folding simulations, including errors for conformation encoding, chain length, and amino acid validity.

exception exceptions.ChainLengthError(message='Invalid chain length. Make sure that the chain length is correct.')

Bases: Exception

Exception raised for errors in the chain length.

__init__(message='Invalid chain length. Make sure that the chain length is correct.')

exception exceptions.ConformationEncodingError(message='Invalid conformation encoding. Make sure that the encoding is of type ConformationEncoding.')

Bases: Exception

Exception raised for errors in the conformation encoding.

__init__(message='Invalid conformation encoding. Make sure that the encoding is of type ConformationEncoding.')

exception exceptions.InvalidBackendError(message='Invalid backend/API key configuration or unsupported backend type.')

Bases: Exception

Exception raised when backend configuration is invalid or unsupported.

__init__(message='Invalid backend/API key configuration or unsupported backend type.')

exception exceptions.InvalidInteractionTypeError(message='Invalid interaction type. Make sure that the interaction type is of type InteractionType.')

Bases: Exception

Exception raised when an invalid interaction type is encountered.

__init__(message='Invalid interaction type. Make sure that the interaction type is of type InteractionType.')

exception exceptions.InvalidOperatorError(message='Invalid quantum operator encountered. Make sure that the operator is valid.')

Bases: Exception

Exception raised when an invalid quantum operator is encountered.

__init__(message='Invalid quantum operator encountered. Make sure that the operator is valid.')

exception exceptions.UnsupportedAminoAcidSymbolError(message='Invalid amino acid symbol. Make sure that the amino acid symbol is compatible with the solution.')

Bases: Exception

Exception raised when amino acid symbol is not included in interaction.

__init__(message='Invalid amino acid symbol. Make sure that the amino acid symbol is compatible with the solution.')

Main

Main execution script for the quantum protein folding workflow.

main.main()

Executes the full quantum protein folding workflow for a sample chain.

This includes system setup, hamiltonian construction and compression, VQE optimization, and result analysis and visualization in 2D and 3D.

Return type:

None

Note

The main chain sequence is hardcoded here for demonstration purposes.