feat(qdp): hoist encode_from_gpu_ptr_f32 onto QuantumEncoder trait

[rich7420]

Related Issues

Changes

• Bug fix
• New feature
• Refactoring
• Documentation
• Test
• CI/CD pipeline
• Other

Why

The single-sample f32 zero-copy entry point exists as a standalone pub unsafe fn on each encoder type (AmplitudeEncoder / AngleEncoder / BasisEncoder), while the batch sibling (encode_batch_from_gpu_ptr_f32) lives on the QuantumEncoder trait with a default NotImplemented body.

That asymmetry means adding a new encoder with f32 zero-copy support requires updating three separate touch points (inherent fn on the encoder, dispatcher in engine.rs, engine-level entry method) instead of one. The batch side already enforces the trait-override discipline; the single-sample side should too.

This is a pure structural refactor — no new functionality, no behaviour change, no kernel changes.

How

Trait change (qdp-core/src/gpu/encodings/mod.rs)
Add encode_from_gpu_ptr_f32 to QuantumEncoder with a default body returning MahoutError::NotImplemented. Signature mirrors the existing encode_batch_from_gpu_ptr_f32. Cfg-gated to Linux / CUDA, same as the batch sibling.

Encoder overrides

• AmplitudeEncoder, AngleEncoder, BasisEncoder each gain a trait impl that delegates to the existing inherent _with_stream workhorse fn. Hot paths can keep calling the inherent fn directly without going through a vtable.
• Encoders that don't have an f32 zero-copy path yet (Phase, IQP, IQP-Z) inherit the default NotImplemented body — same pattern as the batch sibling.

Amplitude alignment (qdp-core/src/gpu/encodings/amplitude.rs)
AmplitudeEncoder previously had no standalone encode_from_gpu_ptr_f32_with_stream — the L2-norm + kernel-launch sequence was inlined in QdpEngine::encode_from_gpu_ptr_f32_with_stream (lib.rs). Add the missing inherent fn to mirror the angle / basis pattern, then have QdpEngine delegate to it (−62 LoC inline, no behaviour change).

Tests (qdp-core/tests/gpu_ptr_encoding.rs)
Four new trait-dispatch tests route through Encoding::encoder() (the trait object) rather than the inherent helper, so they exercise the new override mechanism:

• amplitude / angle / basis success via trait method
• phase's default body returns NotImplemented with the expected message

Local verification

• Rust unit + integration: all passing
• GPU-required tests (gpu_ptr_encoding, gpu_fidelity, gpu_angle_encoding): all passing (incl. the 4 new ones)
• Python pytest: all passing
• Clippy / fmt / license-header: clean
• Baseline throughput (16 qubits, batch_size = 64, RTX 2080 Ti) holds: amplitude 14,316 / angle 204,209 / basis 648,118 vec/s

Checklist

• Added or updated unit tests for all changes
• Added or updated documentation for all changes

[Copilot]

Pull request overview

Refactors the f32 single-sample zero-copy entry point onto the QuantumEncoder trait with a default NotImplemented body, mirroring the existing batch sibling. Encoders that support f32 (Amplitude, Angle, Basis) override the trait method and delegate to their inherent _with_stream workhorse; Amplitude gains the missing inherent workhorse (extracted verbatim from QdpEngine). Pure structural change, no behavior or kernel changes.

Changes:

• Add encode_from_gpu_ptr_f32 to QuantumEncoder (Linux/CUDA-gated) with default NotImplemented body, and override on Amplitude/Angle/Basis.
• Extract Amplitude's inlined f32 single-sample logic out of QdpEngine::encode_from_gpu_ptr_f32_with_stream into a new AmplitudeEncoder::encode_from_gpu_ptr_f32_with_stream workhorse.
• Add four trait-dispatch integration tests in gpu_ptr_encoding.rs covering amplitude/angle/basis success and phase default NotImplemented.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
qdp/qdp-core/src/gpu/encodings/mod.rs	Adds the f32 single-sample method to the QuantumEncoder trait with a default NotImplemented body.
qdp/qdp-core/src/gpu/encodings/amplitude.rs	Adds trait override and new inherent encode_from_gpu_ptr_f32_with_stream workhorse extracted from lib.rs.
qdp/qdp-core/src/gpu/encodings/angle.rs	Adds trait override delegating to the existing inherent workhorse.
qdp/qdp-core/src/gpu/encodings/basis.rs	Adds trait override delegating to the existing inherent workhorse (drops unused input_len).
qdp/qdp-core/src/lib.rs	QdpEngine::encode_from_gpu_ptr_f32_with_stream now delegates to the encoder workhorse.
qdp/qdp-core/tests/gpu_ptr_encoding.rs	Adds four trait-dispatch tests via Encoding::encoder().

---

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