Add amplitude and angular quantum embeddings

[ssmswapnil]

Add common quantum embeddings

Closes #2982

Summary

Adds built-in APIs for two common quantum embedding methods used in Quantum Machine Learning (QML):

1. cudaq.amplitude_encode(data, pad=None) — Encodes classical feature vectors as quantum state amplitudes, with automatic L2-normalization and optional padding to the nearest power of 2.

2. cudaq.angular_encode(kernel, qubits, data, num_qubits, rotation='Y') — Encodes classical features as single-qubit rotation angles (Rx, Ry, or Rz), following the same builder-API pattern as cudaq.kernels.hwe.

Design Decisions

• Separated into two distinct functions rather than a single overloaded function, since amplitude encoding and angular encoding have fundamentally different signatures and return types (amplitude_encode returns a cudaq.State, while angular_encode modifies a kernel in-place).
• angular_encode follows the hwe convention — takes kernel and qubits arguments and appends gates via the builder API, consistent with existing kernel library functions.
• angular_encode supports parameterized kernels — works with both concrete list[float] data and QuakeValue parameters for variational workflows.
• Top-level access uses lazy loading — amplitude_encode and angular_encode are registered in _LAZY_ATTRS, following the existing PEP 562 pattern used by evolve, Schedule, etc.

Examples

import cudaq

# (1) Amplitude encoding
state = cudaq.amplitude_encode([0.5, 0.5, 0.5], pad=0)
# Returns cudaq.State with amplitudes [0.5773, 0.5773, 0.5773, 0.0]

# (2) Angular encoding
kernel = cudaq.make_kernel()
qubits = kernel.qalloc(3)
cudaq.kernels.angular_encode(kernel, qubits, [0.1, 0.2, 0.3], 3, rotation='Y')
print(cudaq.draw(kernel))
#      ╭─────────╮
# q0 : ┤ ry(0.1) ├
#      ├─────────┤
# q1 : ┤ ry(0.2) ├
#      ├─────────┤
# q2 : ┤ ry(0.3) ├
#      ╰─────────╯

Changes

File	Action	Description
python/cudaq/kernels/embeddings.py	New	Implementation of amplitude_encode and angular_encode
python/tests/test_embeddings.py	New	20 unit tests covering both functions
python/cudaq/kernels/__init__.py	Modified	Added import for new embeddings module
python/cudaq/__init__.py	Modified	Added _LAZY_ATTRS entries for top-level access

Testing

All 20 tests pass:

• 11 tests for amplitude_encode (normalization, padding, numpy input, complex values, edge cases, error handling)
• 9 tests for angular_encode (Rx/Ry/Rz axes, case insensitivity, parameterized kernels, error handling)

[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.

[1tnguyen]

Hi @ssmswapnil,

Thank you for your contribution!

There are a couple of things to fix for the CI:

• We need all commits to be signed off. Please take a look at the instructions to rectify that.

• The code format, spelling, and license header checks are failing. You can follow the instructions here to check and fix them locally.

[1tnguyen]

/ok to test b81d101

Command Bot: Processing...

[github-actions]

CI Summary (push) — ✅ passed

Run #26936459494 · ✅ 6 · ⏩ 7 · ❌ 0 · ⛔ 0

Top-level jobs (13)

Job	Result
binaries	⏩ skipped
build_and_test	✅ success
config_devdeps	✅ success
config_source_build	⏩ skipped
config_wheeldeps	✅ success
devdeps	✅ success
docker_image	⏩ skipped
gen_code_coverage	⏩ skipped
metadata	✅ success
python_metapackages	⏩ skipped
python_wheels	⏩ skipped
source_build	⏩ skipped
wheeldeps	✅ success

⏩ Skipped jobs (7) — intentionally skipped on PR builds; run on merge_group / workflow_dispatch

Job
binaries
config_source_build
docker_image
gen_code_coverage
python_metapackages
python_wheels
source_build

All sub-jobs (42) — every matrix leg, with links

Job	Status	Link
Build and test (amd64, gcc12, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (amd64, gcc12, openmpi) / Dev environment (Python)	✅ success	view
Build and test (amd64, llvm, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (amd64, llvm, openmpi) / Dev environment (Python)	✅ success	view
Build and test (arm64, llvm, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (arm64, llvm, openmpi) / Dev environment (Python)	✅ success	view
CI Summary	❔ in_progress	view
Configure build (devdeps)	✅ success	view
Configure build (source_build)	⏩ skipped	view
Configure build (wheeldeps)	✅ success	view
Create CUDA Quantum installer	⏩ skipped	view
Create Docker images	⏩ skipped	view
Create Python metapackages	⏩ skipped	view
Create Python wheels	⏩ skipped	view
Gen code coverage	⏩ skipped	view
Load dependencies (amd64, gcc12) / Caching	✅ success	view
Load dependencies (amd64, gcc12) / Finalize	✅ success	view
Load dependencies (amd64, gcc12) / Metadata	✅ success	view
Load dependencies (amd64, llvm) / Caching	✅ success	view
Load dependencies (amd64, llvm) / Finalize	✅ success	view
Load dependencies (amd64, llvm) / Metadata	✅ success	view
Load dependencies (arm64, gcc12) / Caching	✅ success	view
Load dependencies (arm64, gcc12) / Finalize	✅ success	view
Load dependencies (arm64, gcc12) / Metadata	✅ success	view
Load dependencies (arm64, llvm) / Caching	✅ success	view
Load dependencies (arm64, llvm) / Finalize	✅ success	view
Load dependencies (arm64, llvm) / Metadata	✅ success	view
Load source build cache	⏩ skipped	view
Load wheel dependencies (amd64, 12.6) / Caching	✅ success	view
Load wheel dependencies (amd64, 12.6) / Finalize	✅ success	view
Load wheel dependencies (amd64, 12.6) / Metadata	✅ success	view
Load wheel dependencies (amd64, 13.0) / Caching	✅ success	view
Load wheel dependencies (amd64, 13.0) / Finalize	✅ success	view
Load wheel dependencies (amd64, 13.0) / Metadata	✅ success	view
Load wheel dependencies (arm64, 12.6) / Caching	✅ success	view
Load wheel dependencies (arm64, 12.6) / Finalize	✅ success	view
Load wheel dependencies (arm64, 12.6) / Metadata	✅ success	view
Load wheel dependencies (arm64, 13.0) / Caching	✅ success	view
Load wheel dependencies (arm64, 13.0) / Finalize	✅ success	view
Load wheel dependencies (arm64, 13.0) / Metadata	✅ success	view
Prepare cache clean-up	❔ in_progress	view
Retrieve PR info	✅ success	view

✅ Required checks (6/6) — declared in .github/required-checks.yml for push

Required check	Status	Link
Build and test (amd64, llvm, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (amd64, llvm, openmpi) / Dev environment (Python)	✅ success	view
Build and test (arm64, llvm, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (arm64, llvm, openmpi) / Dev environment (Python)	✅ success	view
Build and test (amd64, gcc12, openmpi) / Dev environment (Debug)	✅ success	view
Build and test (amd64, gcc12, openmpi) / Dev environment (Python)	✅ success	view

[ssmswapnil]

Hi @1tnguyen, thanks for the review!

I've pushed both the fixes:

• Added commit sign-off
• Reformatted files

Let me know if anything else needs to be addressed.

[schweitzpgi]

C++?

[ssmswapnil]

Hi @schweitzpgi ,
The issue examples were Python-only, and I followed the existing pattern from hwe.py and uccsd.py which are also Python-only. I'm not familiar enough with the C++ side of the codebase to add that confidently. Would a Python-only implementation work for this issue, or is C++ needed?

[bettinaheim]

@ssmswapnil Thank you for this contribution!

• Can you please update the PR to have this go into the contrib module/contrib namespace?
• We'll help to unify this contribution with Add two quantum embeddings #4667, which contains C++ support and lists the API in the docs.
  We appreciate if you are willing to help bring this across the finish line in a collaborative manner.

[ssmswapnil]

Hi @bettinaheim ,
Thanks for the feedback! I've moved the implementation to the contrib module. I've also looked at #4667 and am happy to help unify the two contributions. Let me know how you'd like to coordinate.