real2quantum 0.1.1

Quantum-inspired optimization and modeling framework

Real2Quantum v0.1

Introduction

Real2Quantum is a package designed to make quantum computing more accessible for a wide range of applications. It provides implementations of various optimization problems, with version v0.1 focusing on finance use cases such as portfolio optimization and risk minimization. Future releases aim to expand into additional domains, including logistics, transportation, and energy distribution. Real2Quantum is framework-agnostic and can generate the Hamiltonian in Pennylane, Qiskit, Cirq and D-wave format.

With Real2Quantum, you can define an optimization problem and incorporate domain-specific constraints in a natural way. The framework then automatically maps the problem into its quantum formulation by constructing the corresponding Hamiltonian. Other options are also available, such as solving the problem using the QAOA algorithm on a PennyLane simulator.

Installation

1. Clone this repository:

git clone https://github.com/rscadrien/Real2Quantum.git

2. Install dependencies

pip install -r requirements.txt

How to use it

We will illustrate for the portfolio optimization problem (binary version). The other implemented problems (risk minimization and the multibit variations) follows the same structure. It is simply defined by the number of assets, the expected returns, the covariance matrix, and a risk–return trade-off parameter:

#Defining parameters
n = 5  # number of assets

mu = np.array([0.10, 0.12, 0.07, 0.09, 0.11])

Sigma = np.array([
    [0.10, 0.02, 0.01, 0.03, 0.02],
    [0.02, 0.08, 0.02, 0.01, 0.03],
    [0.01, 0.02, 0.09, 0.02, 0.01],
    [0.03, 0.01, 0.02, 0.07, 0.02],
    [0.02, 0.03, 0.01, 0.02, 0.06]
])
lam = 1.0
PFO_test = PortfolioOptimization_Binary(n= mu.size, mu=mu, Sigma=Sigma, lam=lam)

This creates a PFO_test object representing the optimization problem.

You can then add constraints directly through class methods. For instance, if you want to invest in exactly K assets out of the n available, you can include a budget constraint:

K=3
P = 5.0 # penalty parameter enforcing the constraint
PFO_test.add_budget_constraint(P,K)

When the problem is defined and all constraints are included, you can derive the Hamiltonian of your problem. This Hamiltonian can then be used in your preferred quantum optimization algorithms (e.g., Grover’s algorithm, QAOA, etc.).

By setting the eco option, you can choose between different frameworks: PennyLane (default), Qiskit, Cirq or D-Wave.

for Pennylane:

H = PFO_test.build_hamiltonian(eco = 'PennyLane')

for Qiskit:

H = PFO_test.build_hamiltonian(eco = 'Qiskit')

for Cirq

H = PFO_test.build_hamiltonian(eco = 'Cirq')

for D-wave

h_dwave, J_dwave, offset_dwave = PFO_test.build_hamiltonian(eco = 'DWave')

By default, the offset is included in the Hamiltonian. You can exclude it by setting offset_incl=False.

The translation of the real-world problem into a Hamiltonian is the main output of Real2Quantum. However, the framework also provides additional functionalities.

You can visualize the graph corresponding to the optimization problem as follows:

Graph = PFO_test.build_graph()

Finally, you can solve the optimization problem locally using the QAOA algorithm on a PennyLane simulator:

p=3 #Number of QAOA layer
Solution = PFO_test.solver(p)

How to contribute to Real2Quantum

Real2Quantum is flexible enough to make it easy for anyone to create a new optimization problem for quantum computing. In the current version, there are two parent classes, QUBOProblem_Binary and QUBOProblem_Multibit, which contain common methods such as building the graph, constructing the Hamiltonian, and solving the problem using the QAOA algorithm.

To define a new problem, you only need to specify how to build the objective function and how to add constraints. For example, for portfolio optimization:

class PortfolioOptimization_Binary(QUBOProblem_Binary):

    def __init__(self, n, mu, Sigma, lam=1.0):
        self.mu = mu
        self.Sigma = Sigma
        self.lam = lam

        super().__init__(n)  # calls _build_objective()

    def _build_objective(self):
        """
        Construct the mean-variance QUBO objective function.

        The objective encodes:

            x^T Σ x  -  λ μ^T x

        where:
        - The quadratic term (x^T Σ x) represents portfolio risk.
        - The linear term (μ^T x) represents expected return.
        """

        self.H_pyqubo += sum(
            self.Sigma[i, j] * self.x[i] * self.x[j]
            for i in range(self.n)
            for j in range(self.n)
        )
        self.H_pyqubo += -self.lam * sum(
            self.mu[i] * self.x[i] for i in range(self.n)
        )

    def add_budget_constraint(self, P, K):
        """
        Add a budget constraint enforcing exactly K selected assets.

        Constraint: (sum(x_i) - K)^2
        """
        self.H_pyqubo += P * (sum(self.x[i] for i in range(self.n))-K)**2
        self._compiled = False
# + others constraints

Real2Quantum aims to be an open-source project. Contributions are welcome, feel free to improve it by adding new types of optimization problems, new constraints to the existing ones, or new methods to the parent classes.

License

MIT Licence