CUDA-Q quantum transformer tutorial

[anthonysmaldone]

Description

This is a ipynb notebook and corresponding scripts that include a tutorial of a hybrid quantum-classical transformer model from the paper: A Hybrid Transformer Architecture with a Quantized Self-Attention Mechanism Applied to Molecular Generation - a collaborative effort between NVIDIA and Yale University.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[sacpis]

@anthonysmaldone Thanks for putting up this PR.

Would you please run the following commands to fix the CI build failures?

1. yapf --style google --recursive -i docs/sphinx/applications/python/quantum_transformer_src/*.py
2. bash scripts/run_all_spelling.sh (from cuda-quantum directory)

[sacpis]

/ok to test

Command Bot: Processing...

[sacpis]

When I run to run the notebook in local dev container, I see the following error

ERROR: Could not find a version that satisfies the requirement cudaq==0.9.1 (from versions: none)
ERROR: No matching distribution found for cudaq==0.9.1
Note: you may need to restart the kernel to use updated packages.

[anthonysmaldone]

@sacpis I have fixed the installation issue and restyled the code. There are basic machine learning and chemistry terms that fail during spellcheck (such as 'logits', 'dataset', 'stereocenters', 'physicochemical', etc) should I add some of these to the spelling_allowlist.txt in the workflow config?

[sacpis]

@anthonysmaldone You can wrap those in ``. I think those are in the comments, right?

[anthonysmaldone]

@sacpis Yes, they should all be in comments/docstrings

[anthonysmaldone]

@sacpis I have made the requested changes, please let me know if there is anything else I can do.

[sacpis]

/ok to test

Command Bot: Processing...

[sacpis]

@anthonysmaldone We are getting the following doc error

https://github.com/NVIDIA/cuda-quantum/actions/runs/13570884770/job/37937243190?pr=2614#step:9:276

Would you please include the python notebook in docs/sphinx/using/applications.rst file?

[anthonysmaldone]

@sacpis I've added the notebook to the application.rst file

[sacpis]

/ok to test

Command Bot: Processing...

[sacpis]

LGTM. Thanks @anthonysmaldone.

[sacpis]

/ok to test

Command Bot: Processing...

[github-actions]

CUDA Quantum Docs Bot: A preview of the documentation can be found here.

[sacpis]

/ok to test

Command Bot: Processing...

[github-actions]

CUDA Quantum Docs Bot: A preview of the documentation can be found here.

[sacpis]

/ok to test

Command Bot: Processing...

[github-actions]

CUDA Quantum Docs Bot: A preview of the documentation can be found here.

[github-actions]

CUDA Quantum Docs Bot: A preview of the documentation can be found here.

[sacpis]

/ok to test

Command Bot: Processing...

[sacpis]

@bmhowe23 Is it safe to skip the conversion of quantum_transformer notebook? It is taking long and failing.
https://github.com/NVIDIA/cuda-quantum/actions/runs/13591336814/job/37999481528?pr=2614

[bmhowe23]

@bmhowe23 Is it safe to skip the conversion of quantum_transformer notebook? It is taking long and failing. https://github.com/NVIDIA/cuda-quantum/actions/runs/13591336814/job/37999481528?pr=2614

That should probably be answered by @bettinaheim. We normally like to be able to test our published examples on a regular basis to ensure they don't break with any new cuda-quantum code updates. Skipping testing of this notebook would expose us to the risk of it breaking and us not knowing about it.

Are you proposing skipping testing of this in just the per-PR CI (CPU only), all CI (even tests w/ GPUs), or all automated testing (even release-level QA testing)?

[sacpis]

Thank you @bmhowe23.

Are you proposing skipping testing of this in just the per-PR CI (CPU only), all CI (even tests w/ GPUs), or all automated testing (even release-level QA testing)?

I am proposing to skip this in just the per-PR CI (CPU only).

[github-actions]

CUDA Quantum Docs Bot: A preview of the documentation can be found here.

[anthonysmaldone]

@sacpis After checking the docs preview, I noticed the sections of the transformer notebook are headings under "Applications", let if know if I should change the notebook

[sacpis]

@anthonysmaldone Sure. Would you please tell me where should it go?

[anthonysmaldone]

@sacpis It should still be under 'Applications". However now I see that Applications has subheadings "Installation", "Algorithm and Examples" and "Usage" -which are the section titles in the notebook. Do they need to be one level smaller in the tutorial notebook?

[sacpis]

Ah, I see what you are referring to.

Please use # <title> to mention the title of your notebook. Then you can use ### <sub-headings> inside the notebook for Installations, Algorithm and Examples, Usages etc.

[anthonysmaldone]

@sacpis Sounds good, ive made the updates