Utils

Utility functions used by the project.

Module providing tools to create and manipulate Pauli operators, manage main chain bead states, and prepare operators for qubit-based protein folding simulations.

utils.qubit_utils._calc_updated_coeffs(table_z, coeff, *, has_side_chain_second_bead)

Update coefficients based on fixed qubit positions.

Return type:

float

Parameters:

table_z (NDArray[np.bool]) – Z values for each qubit.
coeff (float) – Original coefficient.
has_side_chain_second_bead (bool) – Whether second bead of side chain exists.

Returns:

Updated coefficient.

Return type:

float

utils.qubit_utils._preset_binary_vals(table_z, *, has_side_chain_second_bead)

Set False for main bead indices in the Z table.

Return type:

None

Parameters:

table_z (NDArray[np.bool]) – Z values for each qubit.
has_side_chain_second_bead (bool) – Whether second bead of side chain exists.

utils.qubit_utils._preset_single_binary_val(table_z, index)

Set a single qubit value to False.

Return type:

None

Parameters:

table_z (NDArray[np.bool]) – Z values for each qubit.
index (int) – Qubit index to set.

utils.qubit_utils.build_identity_op(num_qubits, coeff=IDENTITY_OP_COEFF)

Builds a full identity Pauli operator for a given number of qubits.

Return type:

SparsePauliOp

Parameters:

num_qubits (int) – Number of qubits in the operator.
coeff (float, optional) – Coefficient for the operator. Defaults to IDENTITY_OP_COEFF.

Returns:

Identity Pauli operator.

Return type:

SparsePauliOp

utils.qubit_utils.build_pauli_z_operator(num_qubits, pauli_z_indices)

Build a Pauli operator with Z operators at specified positions and I elsewhere.

Return type:

SparsePauliOp

Parameters:

num_qubits (int) – Total number of qubits.
pauli_z_indices (set[int]) – Indices where Z operators should be applied.

Returns:

Constructed Pauli operator.

Return type:

SparsePauliOp

utils.qubit_utils.build_turn_qubit(z_index, num_qubits)

Builds a turn qubit Pauli operator with Z at the specified index.

Return type:

SparsePauliOp

Parameters:

z_index (int) – Index of the qubit to place a Z operator.
num_qubits (int) – Total number of qubits.

Returns:

Pauli operator representing the turn qubit.

Return type:

SparsePauliOp

utils.qubit_utils.convert_to_qubits(pauli_op)

Convert a Pauli operator to a qubit operator using the identity and normalization factor.

Return type:: SparsePauliOp
Parameters:: pauli_op (SparsePauliOp) – Pauli operator to convert.
Returns:: Converted operator.
Return type:: SparsePauliOp
Raises:: InvalidOperatorError – If the Pauli operator does not have a defined number of qubits.

utils.qubit_utils.find_unused_qubits(op)

Return indices of qubits that are identity (I) in every term of the operator.

Return type:: list[int]
Parameters:: op (SparsePauliOp) – Operator to check.
Returns:: List of unused qubit indices.
Return type:: list[int]
Raises:: InvalidOperatorError – If op.num_qubits is None.

utils.qubit_utils.fix_qubits(operator, *, has_side_chain_second_bead=False)

Fixes specific qubits in a SparsePauliOp to predefined values for main chain turns.

Qubits at positions 0, 1, 2, 3, and 5 correspond to fixed turn positions in the main chain and are not subject to optimization.

Return type:

SparsePauliOp

Parameters:

operator (SparsePauliOp) – Operator to fix.
has_side_chain_second_bead (bool, optional) – Whether second bead of side chain exists. Defaults to False.

Returns:

Operator with fixed qubits.

Return type:

SparsePauliOp

utils.qubit_utils.pad_to_n_qubits(op, target)

Extends a Pauli operator with identity qubits to reach the target size.

Return type:

SparsePauliOp

Parameters:

op (SparsePauliOp) – Operator to pad.
target (int) – Target number of qubits.

Returns:

Padded operator.

Return type:

SparsePauliOp

Raises:

InvalidOperatorError – If op.num_qubits is None.

utils.qubit_utils.remove_unused_qubits(op)

Remove qubits that are identity in all terms.

Return type:: SparsePauliOp
Parameters:: op (SparsePauliOp) – Operator to remove unused qubits from.
Returns:: Operator without unused qubits.
Return type:: SparsePauliOp
Raises:: InvalidOperatorError – If op.num_qubits is None.

Module providing tools to interpret and handle protein folding results, including XYZ file creation and JSON sanitization.

utils.result_interpretation_utils.create_xyz_file(coords, dirpath)

Create an .xyz file from the given bead positions.

Return type:: Path

Note

XYZ file format reference: https://en.wikipedia.org/wiki/XYZ_file_format Since no formal standard exists, this implementation follows the most common convention.

Parameters:

coords (list[BeadPosition]) – List of bead positions to include in the XYZ file.
dirpath (Path) – Directory path where the XYZ file will be created.

Returns:

The path to the created XYZ file.

Return type:

Path

Raises:

Exception – If there is an error creating the XYZ file.

utils.result_interpretation_utils.read_xyz_file(filepath)

Read bead positions from an .xyz file.

Return type:: list[BeadPosition]

Note

XYZ file format reference: https://en.wikipedia.org/wiki/XYZ_file_format Since no formal standard exists, this implementation follows the most common convention.

Parameters:: filepath (Path) – Path to the XYZ file.
Returns:: List of bead positions read from the file.
Return type:: list[BeadPosition]
Raises:: Exception – If there is an error reading the XYZ file.

utils.result_interpretation_utils.sanitize_for_json(obj)

Recursively sanitize an object to make it JSON serializable.

Return type:: Any
Parameters:: obj (Any) – The object to sanitize.
Returns:: A JSON-serializable representation of the input object.
Return type:: Any

Module providing setup utilities for protein folding quantum simulation, including Hamiltonian construction, VQE setup, and result processing.

utils.setup_utils.build_and_compress_hamiltonian(protein, interaction, contact_map, distance_map)

Build and compress the final Hamiltonian for the protein folding system.

Return type:

tuple[SparsePauliOp, SparsePauliOp]

Parameters:

protein (Protein) – The protein instance.
interaction (Interaction) – The interaction model.
contact_map (ContactMap) – The contact map.
distance_map (DistanceMap) – The distance map.

Returns:

The original and compressed Hamiltonians

Return type:

tuple[SparsePauliOp, SparsePauliOp]

utils.setup_utils.run_vqe_optimization(vqe, hamiltonian)

Run the VQE optimization process.

Return type:

SamplingMinimumEigensolverResult

Parameters:

vqe (SamplingVQE) – The VQE instance.
hamiltonian (SparsePauliOp) – The Hamiltonian to optimize.

Returns:

The raw results from the VQE optimization.

Return type:

SamplingMinimumEigensolverResult

utils.setup_utils.setup_folding_system(main_chain, side_chain)

Setup the protein folding system components.

Return type:

tuple[Protein, Interaction, ContactMap, DistanceMap]

Parameters:

main_chain (str) – Main chain protein sequence.
side_chain (str) – Side chain protein sequence.

Returns:

The protein, interaction model, contact map, and distance map.

Return type:

tuple[Protein, Interaction, ContactMap, DistanceMap]

Raises:

InvalidInteractionTypeError – If the interaction type is invalid (class not inheriting from Interaction).

utils.setup_utils.setup_result_analysis(raw_results, protein, vqe_iterations, vqe_energies)

Setup the result analysis components.

Return type:

tuple[ResultInterpreter, ResultVisualizer]

Parameters:

raw_results (SamplingMinimumEigensolverResult) – The raw results from the VQE optimization.
protein (Protein) – The protein instance.
vqe_iterations (list[int]) – The VQE evaluation counts (iterations).
vqe_energies (list[float]) – The VQE energy values.

Returns:

The result interpreter and visualizer instances.

Return type:

tuple[ResultInterpreter, ResultVisualizer]

utils.setup_utils.setup_vqe_optimization(num_qubits)

Setup the VQE optimization process.

Return type:: tuple[SamplingVQE, list[int], list[float]]
Parameters:: num_qubits (int) – Number of qubits for the ansatz.
Returns:: The VQE instance, evaluation counts (iterations), and their respective energy values.
Return type:: tuple[SamplingVQE, list[int], list[float]]