Add first version of the tutorial for solving the market split proble…

[murilo-kipu]

Tutorial: Solving the market split problem with Iskay Quantum Optimizer

This is the first version of the tutorial related to the market split use case. It is close related to the challenge being developed for the QDC 2025.

In this tutorial we give a brief introduction and background to the market split problem, to the algorithm behind Kipu's Qiskit Function and show how the users can solve instances of that problem in IBM. We also go a little further and analyse the result and compare it to different (simple) classical solvers, and by the end, hopefully the users are able to apply this knowledge to solve larger and harder instances, or even different problems.

I haven't run the full notebook with the Qiskit function yet, but here is the current notebook structure:

1. Solve Market Split Problem
   Introduction to the problem and Iskay optimizer.

2. Background
   Overview of the Market Split problem, its formulation, and computational challenges.

3. Requirements
   List of dependencies and setup instructions.

4. Setup
   Import libraries and configure credentials.

5. Step 1: Connect to Iskay Quantum Optimizer
   Establish connection to the optimizer.

6. Step 2: Load and Formulate the Problem
   Load problem data and convert it to QUBO format.

7. Step 3: Understanding bf-DCQO Algorithm
   Explanation of the quantum optimization algorithm.

8. Step 4: Configure and Run Optimization
   Set up and execute the optimization process.

9. Step 5: Analyze Results
   Validate and interpret the solution.

10. Step 6: Benchmark Against Classical Approaches
    Compare quantum results with classical methods.

11. Comparison Results and Analysis
    Evaluate solution quality and execution time.

12. Conclusion
    Summary of findings and next steps.

[qiskit-bot]

Thanks for contributing to Qiskit documentation!

Before your PR can be merged, it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient. Thanks! 🙌

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[miamico]

Quick overall comments:

• let's follow the qiskit patterns for the steps. In my reading, your steps 1,2,3 are Step 1. in the qiskit pattern framework; your step 4 is Step 2,3 in the qiskit patterns; Step 5 and onwards are Step 4 in the qiskit patterns
• could you comment on why the brute force calculation takes less than any of the other methods?
• add the QPU usage (4s?) to the top of the notebook
• if this example takes so little qpu time but is still too easy for classical, can we go to a larger/more difficult example?

[abbycross]

Hi! The lint check is failing because the title and description are missing from the metadata. Here are instructions for adding.

[valeriechiang]

Hi @murilo-kipu, just checking in to make sure we are on track. Please take a look at the comments from @miamico and @abbycross above when you have a moment. Thank you in advance !

cc: @pandasa123

[murilo-kipu]

Quick overall comments:

• let's follow the qiskit patterns for the steps. In my reading, your steps 1,2,3 are Step 1. in the qiskit pattern framework; your step 4 is Step 2,3 in the qiskit patterns; Step 5 and onwards are Step 4 in the qiskit patterns
• could you comment on why the brute force calculation takes less than any of the other methods?
• add the QPU usage (4s?) to the top of the notebook
• if this example takes so little qpu time but is still too easy for classical, can we go to a larger/more difficult example?

Thanks for the review! I will first give a quick answer to each point raised:

• For the first remark, I will adjust the steps to match the pattern you provided. Other than adjusting the step sections, do I need to trim down any of the content itself?
• On the matter of the brute force solver finding the answer so fast, this is an easy instance for classical solvers and brute force is just simply calculating the entire cost spectrum, which in this case is small, but will scale really badly with the problem size.
• About the 4s QPU time, Like I said in the PR message, I haven't run this notebook using the Qiskit Function from the catalog yet, so this was just a place holder to test the comparison. I was still updating the Qiskit function with some features that will help both in the tutorial and in the QDC challenge. The current version now already outputs the total QPU time in its result, for example. So I will run it and update these little details.
• Your final point is really pertinent. This is something we are still deciding for the challenge notebook as well. The instance that I used in the notebook is indeed really ease to solve classically. For quantum however, the encoding is a limitation given the problem connectivity, that leads to long circuits that do not fit in the IBM hardware coherence times. In our last updated to our qiskit function we introduced some parameters that the user can tweak and approximate the initial problem to counter that. In some quick tests, we were able to solve instances of m=3 and m=4 with our solver without any violation, but for more than that, unfortunately the circuits are still too deep. For the tutorial we either:
  • Change the instance to one with m=4, which we can still solve classically as well and compare only the time-to-solution (TTS), which I suspect optimized classical solvers (not sure about the ones I implemented in the notebook) would still show a shorter TTS, at least according to Fig. 21 of the Intractable Decathlon paper, where you can see classical solvers struggling with m=7.
  • The other option would be to tackle a larger problem and since this is a feasibility problem, compare the cost and violation for quantum and classical imposing a time limit.

[murilo-kipu]

One other question: Daniel Egger shared the link to this qiskit addon and I'm integrating it to the challenge notebook. Should I also do it in the tutorial notebook? This is compatible with the code I have there and would replace one of the functions I wrote, but I'm note sure if the addon it will released by the time you want to publish the tutorial.

[CLAassistant]

All committers have signed the CLA.

[valeriechiang]

One other question: Daniel Egger shared the link to this qiskit addon and I'm integrating it to the challenge notebook. Should I also do it in the tutorial notebook? This is compatible with the code I have there and would replace one of the functions I wrote, but I'm note sure if the addon it will released by the time you want to publish the tutorial.

@murilo-kipu Thank you for bringing this up! I was able to connect with Daniel, and the timing works well. The PyPi release is coming out very soon (scheduled for next Monday, Nov 3rd), so please include the addon!

cc: @pandasa123

[abbycross]

I've gotten the spelling and markdown checks to pass. You'll need to list the file in a couple other places in the repo so that it passes the other checks - see this section of the README for info on that. Thanks!