API

class qhdopt.qhd.QHD(func: Function, syms: List[Symbol], bounds: Tuple | List | None = None)

Provides functionality to run Quantum Hamiltonian Gradient Descent as introduced by https://arxiv.org/pdf/2303.01471.pdf

A user should initialize QHD through the use of the functions: QHD.QP and QHD.Sympy

classmethod QP(Q: List[List[float]], b: List[float], bounds: Tuple | List | None = None) → QHD

Initialize QHD with a quadratic programming format

Parameters:

  • Q -- Quadratic matrix

  • b -- Linear vector

  • bounds -- Bounds of the function

Returns:

An instance of QHD

Return type:

QHD

classmethod SymPy(func: Function, syms: List[Symbol], bounds: Tuple | List | None = None) → QHD

Initialize QHD with a sympy function and its symbols

Parameters:

  • func -- Sympy function

  • syms -- List of symbols

  • bounds -- Bounds of the function

Returns:

An instance of QHD

Return type:

QHD

affine_mapping(minimizer: ndarray, minimum: float, samples: List[ndarray]) → Tuple[ndarray, float, List[ndarray]]

Maps the minimizer and samples from the normalized space to the original space.

Parameters:

  • minimizer -- The minimizer in the normalized space.

  • minimum -- The minimum value of the function.

  • samples -- The samples in the normalized space.

Returns:

Tuple of the minimizer, minimum, and samples in the original space.

affine_transformation(x: ndarray) → ndarray

Applies an affine transformation to the input array.

Parameters:

x -- The input array to be transformed.

Returns:

Transformed array according to the defined scaling factor and lower bounds.

baseline_setup(shots: int = 100, post_processing_method: str = 'TNC')

Sets up the baseline configuration for classical optimization comparison.

Parameters:

  • shots -- The number of solution samples to generate.

  • post_processing_method -- The classical optimization algorithm to use.

classical_optimizer_helper(samples: List[ndarray], bounds: Bounds, solver: str, f: Callable) → Tuple[List[ndarray], ndarray, float, float]

Helper function to optimize a given function classically over a set of samples and within specified bounds.

Parameters:

  • samples -- Initial samples for the optimization.

  • bounds -- Bounds within which the optimization is to be performed.

  • solver -- The optimization method

  • f -- The function to be optimized

Returns:

Tuple of samples, minimizer, minimum, and post-processing time

classically_optimize(verbose=0, initial_guess=None, num_shots=100, solver='IPOPT') → Response

Optimizes a given function classically over a set of samples and within specified bounds.

Parameters:

  • samples -- Initial samples for the optimization.

  • bounds -- Bounds within which the optimization is to be performed.

  • solver -- The optimization method

Returns:

Response object containing samples, minimum, minimizer, and other info

dwave_setup(resolution: int, shots: int = 100, api_key: str | None = None, api_key_from_file: str | None = None, embedding_scheme: str = 'unary', anneal_schedule: List[List[int]] | None = None, penalty_coefficient: float = 0, penalty_ratio: float = 0.75, chain_strength_ratio: float = 1.05, post_processing_method: str = 'TNC')

Configures the settings for quantum optimization using D-Wave systems.

Parameters:

  • resolution -- The number of bits representing each variable.

  • shots -- The number of times the quantum device runs to find the solution.

  • api_key -- Direct API key for connecting to D-Wave's cloud service.

  • api_key_from_file -- Path to a file containing the D-Wave API key.

  • embedding_scheme -- Method used for mapping logical variables to physical qubits.

  • anneal_schedule -- Custom annealing schedule for quantum annealing.

  • penalty_coefficient -- Coefficient used to enforce constraints in the quantum model.

  • penalty_ratio -- Ratio used to calculate penalty coefficients.

  • post_processing_method -- Classical optimization method used after quantum sampling.

  • chain_strength_ratio -- Ratio of strength of chains in embedding.

fun_eval(x: ndarray)

function evaluation when x is in the original box (non-normalized)

generate_affined_func() → Tuple[Function, List[Symbol]]

Internal method for generating a new Sympy function with an affine transformation which calculated from the bounds property inputted from the user

generate_guess_in_box(shots: int = 1) → List[ndarray]

Generates initial guesses within the defined bounds. By default, generate a sample with a single guess (shots = 1)

Parameters:

shots -- Number of guesses to generate.

Returns:

A list containing the generated guesses.

get_solution(var=None)

var can be - None (return all values) - a Symbol (return the value of the symbol) - a list of Symbols (return a list of the values of the symbols)

ionq_setup(resolution: int, shots: int = 100, api_key: str | None = None, api_key_from_file: str | None = None, embedding_scheme: str = 'onehot', penalty_coefficient: float = 0, time_discretization: int = 10, gamma: float = 5, post_processing_method: str = 'TNC', on_simulator: bool = False)

Configures the settings for running QHD using IonQ systems.

Parameters:

  • resolution -- The resolution of the quantum representation.

  • shots -- Number of measurements to perform on the quantum state.

  • api_key -- API key for accessing IonQ's quantum computing service.

  • api_key_from_file -- Path to file containing the API key for IonQ.

  • embedding_scheme -- Strategy for encoding problem variables into quantum states.

  • penalty_coefficient -- Multiplier for penalty terms in the quantum formulation.

  • time_discretization -- Number of time steps for simulating quantum evolution.

  • gamma -- Scaling factor for the quantum evolution's time discretization.

  • post_processing_method -- Algorithm for refining quantum results classically.

  • on_simulator -- Flag to indicate if the quantum simulation should run on a simulator.

optimize(refine: bool = True, verbose: int = 0) → Response

User-facing function to run QHD on the optimization problem

Parameters:

  • refine -- Flag to indicate if fine-tuning should be performed.

  • compile_only -- Flag to indicate if only the compilation should be performed.

  • verbose -- Verbosity level (0, 1, 2 for increasing detail).

Returns:

Response object containing samples, minimum, minimizer, and other info

post_process() → Tuple[ndarray, float, float]

Private function to post-process the QHD samples returned from a quantum backend.

Returns:

Tuple of minimizer, minimum, and post-processing time

qutip_setup(resolution: int, shots: int = 100, embedding_scheme: str = 'onehot', penalty_coefficient: float = 0, time_discretization: int = 10, gamma: float = 5, post_processing_method: str = 'TNC')

Configures the settings for quantum simulation of QHD using QuTiP.

Parameters:

  • resolution -- The resolution for encoding variables into quantum states.

  • shots -- Number of repetitions for the quantum state measurement.

  • embedding_scheme -- Encoding strategy for representing problem variables.

  • penalty_coefficient -- Coefficient for penalties in the quantum problem formulation.

  • time_discretization -- Number of intervals for the quantum evolution simulation.

  • gamma -- Parameter controlling the strength of the quantum system evolution.

  • post_processing_method -- Classical method used for post-processing quantum results.

validate_guess_in_box(guesses: List[ndarray]) → None

Validates if the provided guesses are within the bounds.

Parameters:

guesses -- List of guesses to validate.

class qhdopt.qhd_base.QHD_Base(func: Function, syms: List[Symbol], info: Dict[str, int | float | str])

Provides functionality to run Quantum Hamiltonian Gradient Descent as introduced by https://arxiv.org/pdf/2303.01471.pdf

A user should initialize QHD through the use of the functions: QHD_Base.QP and QHD_Base_Sympy

baseline_setup(shots: int = 100) → None

Sets up a classical baseline backend.

Parameters:

shots -- Number of sampling shots for baseline method.

dwave_setup(resolution: int, shots: int = 100, api_key: str | None = None, api_key_from_file: str | None = None, embedding_scheme: str = 'unary', anneal_schedule: List[List[int]] | None = None, penalty_coefficient: float = 0, penalty_ratio: float = 0.75, chain_strength_ratio: float = 1.05) → None

Sets up the D-Wave backend for quantum optimization.

Parameters:

  • resolution -- Resolution for discretizing variable space.

  • shots -- Number of sampling shots for the D-Wave device.

  • api_key -- API key for accessing D-Wave services.

  • api_key_from_file -- Path to a file containing the API key.

  • embedding_scheme -- Embedding scheme for problem mapping.

  • anneal_schedule -- Custom annealing schedule.

  • penalty_coefficient -- Coefficient for penalty terms.

  • penalty_ratio -- Ratio of penalty terms in the objective function.

  • chain_strength_ratio -- Ratio of strength of chains in embedding.

ionq_setup(resolution: int, shots: int = 100, api_key: str | None = None, api_key_from_file: str | None = None, embedding_scheme: str = 'onehot', penalty_coefficient: float = 0, time_discretization: int = 10, gamma: float = 5, on_simulator: bool = False) → None

Sets up the IonQ backend for quantum optimization.

Parameters:

  • resolution -- Resolution for discretizing variable space.

  • shots -- Number of sampling shots for the IonQ device.

  • api_key -- API key for accessing IonQ services.

  • api_key_from_file -- Path to a file containing the API key.

  • embedding_scheme -- Embedding scheme for problem mapping.

  • penalty_coefficient -- Coefficient for penalty terms.

  • time_discretization -- Number of time steps for discretization.

  • gamma -- Coefficient for transverse field in quantum annealing.

  • on_simulator -- Flag to run on simulator instead of actual device.

optimize(verbose: int = 0) → Response | None

Executes the optimization process.

Parameters:

verbose -- Verbosity level (0, 1, 2 for increasing detail).

Returns:

An instance of Response containing optimization results, None if compile_only is True.

qutip_setup(resolution: int, shots: int = 100, embedding_scheme: str = 'onehot', penalty_coefficient: float = 0, time_discretization: int = 10, gamma: float = 5) → None

Sets up the QuTiP backend for quantum simulation.

Parameters:

  • resolution -- Resolution for discretizing variable space.

  • shots -- Number of simulation shots.

  • embedding_scheme -- Embedding scheme for problem mapping.

  • penalty_coefficient -- Coefficient for penalty terms.

  • time_discretization -- Number of time steps for discretization.

  • gamma -- Coefficient for transverse field in quantum annealing.

class qhdopt.backend.backend.Backend(resolution, dimension, shots, embedding_scheme, univariate_dict, bivariate_dict)

Abstract backend class which defines common functions for all backends and an abstract function: exec which each backend needs to implement.

H_p(qubits: List[Qubit], univariate_dict: dict, bivariate_dict: dict) → TIHamiltonian

Generates the problem hamiltonian, as defined in https://arxiv.org/pdf/2303.01471.pdf (F.24) for the hamming embedding, and modified for the unary and one-hot embedding in ways that can be found in https://arxiv.org/pdf/2401.08550.pdf.

Parameters:

  • qubits -- List of qubits

  • univariate_dict -- Dictionary of univariate terms

  • bivariate_dict -- Dictionary of bivariate terms

Returns:

Problem Hamiltonian

Return type:

TIHamiltonian

H_pen(qubits: List[Qubit]) → TIHamiltonian

Generates the penalty hamiltonian across all dimensions of the problem uses unary_penalty as a key subroutine.

Parameters:

qubits -- List of qubits

Returns:

Penalty Hamiltonian

Return type:

TIHamiltonian

S_x(qubits: List[Qubit]) → TIHamiltonian

Generates the hamiltonian S_x hamiltonian as defined in https://arxiv.org/pdf/2303.01471.pdf equation (F.38)

Parameters:

qubits -- List of qubits

Returns:

S_x Hamiltonian

Return type:

TIHamiltonian

compile(info)

Compiles the problem description into a format that the backend can run.

Parameters:

info -- Dictionary to store information about the compilation

decoder(raw_samples: List[int], f_eval: Callable) → Tuple[ndarray, int, List[ndarray]]

decodes the raw samples returned from the backend into samples which are the form (a_1, a_2,...,a_d) where d is the dimension of the problem and a_j is a number between 0 and 1.

Parameters:

  • raw_samples -- List of raw samples

  • f_eval -- Function to evaluate the samples

Returns:

minimizer, minimum, qhd_samples

Return type:

Tuple

abstract exec(verbose: int, info: dict)

Executes the quantum backend to run QHD

Parameters:

  • verbose -- Verbosity level

  • info -- Dictionary to store information about the execution

unary_penalty(k: int, qubits: List[Qubit])

Generates the unary penalty hamiltonian on the kth sub-system as defined in https://arxiv.org/pdf/2401.08550.pdf

class qhdopt.backend.dwave_backend.DWaveBackend(resolution, dimension, univariate_dict, bivariate_dict, shots=100, api_key=None, api_key_from_file=None, embedding_scheme='unary', anneal_schedule=None, penalty_coefficient=0, penalty_ratio=0.75, chain_strength_ratio=1.05)

Backend implementation for Dwave. Find more information about Dwave's backend here: https://docs.dwavesys.com/docs/latest/c_gs_2.html

calc_h_and_J() → Tuple[List, dict]

Function for debugging to provide h and J which uniquely specify the problem hamiltonian

Returns:

List of h values J: Dictionary of J values

Return type:

h

calc_penalty_coefficient_and_chain_strength() → Tuple[float, float]

Calculates the penalty coefficient and chain strength using self.penalty_ratio.

compile(info)

Compiles the problem description into a format that the backend can run.

Parameters:

info -- Dictionary to store information about the compilation

exec(verbose: int, info: dict, compile_only=False) → List[List[int]]

Execute the Dwave quantum backend using the problem description specified in self.univariate_dict and self.bivariate_dict. It uses self.H_p to generate the problem hamiltonian and then uses Simuq's DwaveProvider to run the evolution on Dwave.

Parameters:

  • verbose -- Verbosity level.

  • info -- Dictionary to store information about the execution.

  • compile_only -- If True, the function only compiles the problem and does not run it.

Returns:

A list of raw samples from the Dwave backend.

Return type:

raw_samples