docs: Add example notebook on QAOA

[CalMacCQ]

EDIT: As of 2nd March I've finished off the explanatory text and acknowledged some of the performance limitations.

---

Implementation of QAOA in Guppy. The code was based on an pytket example notebook implementing QAOA which I ported over to Guppy.

The implementation works and gives the correct answer for the maxcut instnace for a seven vertex graph. However there are some outstanding issues.

1. The example takes a long time to run (over 1 minute)

Guppy performance (with Selene)
CPU times: user 31.8 s, sys: 3.21 s, total: 35 s
Wall time: 1min 10s

pytket with AerBackend 
(Note that compilation essentially plays no role here, not exactly apples to apples)
CPU times: user 3.35 s, sys: 1.35 s, total: 4.69 s
Wall time: 511 ms

I expect the overhead is in the repeated compilation of Guppy functions on every QAOA iteration (100 iterations in this case, 2000 shots, 7 qubits).

This was running afoul of the 120s timeout imposed by C.I. (The runners are slower than my local machine) This in turn means that I've had to skip the notebook execution test here which is unfortunate. See the changes I made to the test_notebooks.py file.

2. The classical optimisation strategy is very naive... I'm using the most basic possible strategy here. I'm just sampling parameter vales from a uniform distribution see solve_maxcut_instance. Note that this is not the cause of the slow runtime as the same optimisation strategy is applied in the pytket version.

I'd like to use a scipy optimizer or something but that would require a fair bit of refactoring. I only get a float back from scipy.optimize.minimize so I need to refactor to account for the fact that I'm not getting a QsysResult back in the loop.

[github-actions]

Bencher Report

Branch	cm/qaoa_example
Testbed	Linux

Click to view all benchmark results

Benchmark	Latency	Benchmark Result microseconds (µs) (Result Δ%)	Upper Boundary microseconds (µs) (Limit %)
tests/benchmarks/test_big_array.py::test_big_array_check	📈 view plot 🚷 view threshold	627,370.97 µs (-12.39%) Baseline: 716,097.98 µs	751,902.88 µs (83.44%)
tests/benchmarks/test_big_array.py::test_big_array_compile	📈 view plot 🚷 view threshold	1,650,130.31 µs (-10.06%) Baseline: 1,834,750.51 µs	1,926,488.03 µs (85.65%)
tests/benchmarks/test_big_array.py::test_big_array_executable	📈 view plot 🚷 view threshold	7,072,779.60 µs (-10.78%) Baseline: 7,927,422.23 µs	8,323,793.35 µs (84.97%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_check	📈 view plot 🚷 view threshold	44,611.66 µs (-12.11%) Baseline: 50,759.70 µs	53,297.69 µs (83.70%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_compile	📈 view plot 🚷 view threshold	95,195.87 µs (-13.94%) Baseline: 110,618.91 µs	116,149.86 µs (81.96%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_executable	📈 view plot 🚷 view threshold	528,578.88 µs (-11.96%) Baseline: 600,418.11 µs	630,439.01 µs (83.84%)
tests/benchmarks/test_prelude.py::test_import_guppy	📈 view plot 🚷 view threshold	39.33 µs (-26.70%) Baseline: 53.66 µs	56.34 µs (69.81%)

🐰 View full continuous benchmarking report in Bencher

[github-actions]

Bencher Report

Branch	cm/qaoa_example
Testbed	Linux

Click to view all benchmark results

Benchmark	hugr_bytes	Benchmark Result bytes x 1e3 (Result Δ%)	Upper Boundary bytes x 1e3 (Limit %)	hugr_nodes	Benchmark Result nodes (Result Δ%)	Upper Boundary nodes (Limit %)
tests/benchmarks/test_big_array.py::test_big_array_compile	📈 view plot 🚷 view threshold	141.73 x 1e3 (0.00%) Baseline: 141.73 x 1e3	143.15 x 1e3 (99.01%)	📈 view plot 🚷 view threshold	6,620.00 (0.00%) Baseline: 6,620.00	6,686.20 (99.01%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_compile	📈 view plot 🚷 view threshold	17.52 x 1e3 (0.00%) Baseline: 17.52 x 1e3	17.69 x 1e3 (99.01%)	📈 view plot 🚷 view threshold	581.00 (0.00%) Baseline: 581.00	586.81 (99.01%)

🐰 View full continuous benchmarking report in Bencher

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.39%. Comparing base (34293ed) to head (750d31d).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1331   +/-   ##
=======================================
  Coverage   93.39%   93.39%           
=======================================
  Files         128      128           
  Lines       11970    11970           
=======================================
  Hits        11179    11179           
  Misses        791      791           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR adds an example notebook demonstrating QAOA (Quantum Approximate Optimization Algorithm) implementation in Guppy, ported from a pytket example. The implementation correctly solves a maxcut problem for a seven-vertex graph but faces performance challenges requiring optimization work.

Key Changes:

• Implementation of QAOA algorithm in Guppy with basic classical optimization
• Exclusion of the new notebook from CI tests due to 1+ minute runtime exceeding the 120s timeout
• Documentation additions (noted as incomplete in PR description)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The hardcoded absolute path /home/runner/work/guppylang/guppylang/ will fail in local development environments and other CI systems. Use a relative path construction like Path(__file__).parent.parent.parent / 'examples' / 'qaoa_maxcut_example.ipynb' to match the pattern used for notebook_files discovery.

Suggested change

	Path("/home/runner/work/guppylang/guppylang/examples/qaoa_maxcut_example.ipynb")
	Path(__file__).parent.parent.parent / "examples" / "qaoa_maxcut_example.ipynb"

[CalMacCQ]

Updated numbers on local execution with my MAC. Seems even slower than before. Possible performance regression with new package versions?

[erinaldiq]

A few typos:

• the equation for the cost function assumes z variables are {+1,-1}
• After equation 1 -> colours" without opening quotation
• Use capital P in the last part of the equation of the layers that define the state
• The numbering of equations does not seem consistent, but it could be my notebook viewer doing that. How do I check how it would look rendered on the website?
• The constant part of the Hamiltonian for the 7-node graph is missing a factor of 2.

A few questions:

• Why using frozenarray?
• Should you explain that $|\psi_0\langle$ is the "plus" state?
• The global energy has a constant factor neglected by energy_from_result?
• eval_qaoa_energy builds the "empty" QAOA circuit every time. Isn't this an unnecessary step that might slow things down? Can the guppy function for the circuit qaoa_instance be passed as a reference?
• qaoa_instance takes frozenarray as input, but in main we pass it comptime(list) arguments. Is that ok?

[CalMacCQ]

Thanks a lot for the comments. I'll respond to them now.

[CalMacCQ]

* The constant part of the Hamiltonian for the 7-node graph is missing a factor of 2.

I'm not sure I see what is missing from the equation. I think the coefficent of $I$ should be equal to $\frac{\text{number of edges}}{2}$ in this case the 7 node graph has six edges so we have $6/2=3$. Is this understanding incorrect?

[CalMacCQ]

* After equation 1 -> `colours"` without opening quotation

* Use capital `P` in the last part of the equation of the layers that define the state

* The numbering of equations does not seem consistent, but it could be my notebook viewer doing that. How do I check how it would look rendered on the website?

Thanks. These were all formatting issues. I've fixed them now.