[Python] Use cudaq.complex() rather than fixed complex type (#3549)

1tnguyen · web-flow · commit b3cd4b6658fc · 2025-10-29T03:16:33.000Z
* [Pytest]: use cudaq.complex() rather than hardcoded type

Signed-off-by: Thien Nguyen &lt;thiennguyen@nvidia.com&gt;

* Another round of audit

Signed-off-by: Thien Nguyen &lt;thiennguyen@nvidia.com&gt;

* Proper precision data reporting in Python

Signed-off-by: Thien Nguyen &lt;thiennguyen@nvidia.com&gt;

* Add some more tests and docs

Signed-off-by: Thien Nguyen &lt;thiennguyen@nvidia.com&gt;

---------

Signed-off-by: Thien Nguyen &lt;thiennguyen@nvidia.com&gt;
diff --git a/docs/sphinx/using/backends/hardware/iontrap.rst b/docs/sphinx/using/backends/hardware/iontrap.rst
@@ -234,3 +234,13 @@ Create a project in the Nexus portal. You can find the project ID in the URL of
 
 
 To see a complete example, take a look at :ref:`Quantinuum examples <quantinuum-examples>`.
+
+.. note:: 
+
+        In local emulation mode (``emulate`` flag set to ``True``), the program will be executed on the :ref:`default simulator <default-simulator>`.
+        The environment variable ``CUDAQ_DEFAULT_SIMULATOR`` can be used to change the emulation simulator. 
+        
+        For example, the simulation floating point accuracy and/or the simulation capabilities (e.g., maximum number of qubits, supported quantum gates),
+        depend on the selected simulator.  
+        
+        Any environment variables must be set prior to setting the target or running "`import cudaq`".
diff --git a/docs/sphinx/using/backends/hardware/neutralatom.rst b/docs/sphinx/using/backends/hardware/neutralatom.rst
@@ -124,6 +124,15 @@ To see a complete example, take a look at :ref:`Infleqtion examples <infleqtion-
 Moreover, for an end-to-end application workflow example executed on the Infleqtion QPU, take a look at the
 :doc:`Anderson Impurity Model ground state solver <../../../applications/python/logical_aim_sqale>` notebook.
 
+.. note:: 
+
+        In local emulation mode (``emulate`` flag set to ``True``), the program will be executed on the :ref:`default simulator <default-simulator>`.
+        The environment variable ``CUDAQ_DEFAULT_SIMULATOR`` can be used to change the emulation simulator. 
+        
+        For example, the simulation floating point accuracy and/or the simulation capabilities (e.g., maximum number of qubits, supported quantum gates),
+        depend on the selected simulator.  
+        
+        Any environment variables must be set prior to setting the target or running "`import cudaq`".
 
 Pasqal
 ++++++++++++++++
diff --git a/docs/sphinx/using/backends/hardware/superconducting.rst b/docs/sphinx/using/backends/hardware/superconducting.rst
@@ -534,3 +534,13 @@ Submitting
 
 To see a complete example of using Quantum Circuits' backends, please take a look at the
 :ref:`Quantum Circuits examples <quantum-circuits-examples>`.
+
+.. note:: 
+
+        In local emulation mode (``emulate`` flag set to ``True``), the program will be executed on the :ref:`default simulator <default-simulator>`.
+        The environment variable ``CUDAQ_DEFAULT_SIMULATOR`` can be used to change the emulation simulator. 
+        
+        For example, the simulation floating point accuracy and/or the simulation capabilities (e.g., maximum number of qubits, supported quantum gates),
+        depend on the selected simulator.  
+        
+        Any environment variables must be set prior to setting the target or running "`import cudaq`".
diff --git a/python/tests/backends/test_IQM.py b/python/tests/backends/test_IQM.py
@@ -208,7 +208,8 @@ def kernel(state: cudaq.State):
         qubits = cudaq.qvector(state)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     print(counts)
@@ -231,7 +232,8 @@ def test_IQM_state_synthesis_from_simulator_builder():
     qubits = kernel.qalloc(state)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
diff --git a/python/tests/backends/test_Infleqtion.py b/python/tests/backends/test_Infleqtion.py
@@ -161,7 +161,8 @@ def kernel(state: cudaq.State):
         mz(qubits)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
diff --git a/python/tests/backends/test_IonQ.py b/python/tests/backends/test_IonQ.py
@@ -196,7 +196,8 @@ def kernel(state: cudaq.State):
         qubits = cudaq.qvector(state)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
@@ -216,7 +217,8 @@ def test_ionq_state_synthesis_from_simulator_builder():
     qubits = kernel.qalloc(state)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
diff --git a/python/tests/backends/test_Ionq_LocalEmulation_kernel.py b/python/tests/backends/test_Ionq_LocalEmulation_kernel.py
@@ -101,7 +101,8 @@ def kernel(state: cudaq.State):
         qubits = cudaq.qvector(state)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
diff --git a/python/tests/backends/test_OQC.py b/python/tests/backends/test_OQC.py
@@ -197,7 +197,8 @@ def kernel(state: cudaq.State):
         qubits = cudaq.qvector(state)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
@@ -217,7 +218,8 @@ def test_OQC_state_synthesis_from_simulator_builder():
     qubits = kernel.qalloc(state)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
diff --git a/python/tests/backends/test_QCI.py b/python/tests/backends/test_QCI.py
@@ -175,7 +175,8 @@ def kernel(state: cudaq.State):
         mz(qubits)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
diff --git a/python/tests/backends/test_Quantinuum_LocalEmulation_builder.py b/python/tests/backends/test_Quantinuum_LocalEmulation_builder.py
@@ -142,7 +142,8 @@ def test_quantinuum_state_synthesis_from_simulator():
     qubits = kernel.qalloc(state)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
@@ -209,7 +210,7 @@ def test_capture_array():
 
 
 def test_capture_state():
-    s = cudaq.State.from_data(np.array([1., 0], dtype=np.complex128))
+    s = cudaq.State.from_data(np.array([1., 0], dtype=cudaq.complex()))
 
     kernel = cudaq.make_kernel()
     q = kernel.qalloc(s)
diff --git a/python/tests/backends/test_Quantinuum_LocalEmulation_kernel.py b/python/tests/backends/test_Quantinuum_LocalEmulation_kernel.py
@@ -196,7 +196,8 @@ def kernel(state: cudaq.State):
         qubits = cudaq.qvector(state)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
@@ -413,7 +414,7 @@ def kernel():
 
 
 def test_capture_state():
-    s = cudaq.State.from_data(np.array([1., 0], dtype=np.complex128))
+    s = cudaq.State.from_data(np.array([1., 0], dtype=cudaq.complex()))
 
     @cudaq.kernel
     def kernel():
diff --git a/python/tests/backends/test_Quantinuum_builder.py b/python/tests/backends/test_Quantinuum_builder.py
@@ -167,7 +167,8 @@ def test_quantinuum_state_synthesis_from_simulator():
     qubits = kernel.qalloc(state)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
diff --git a/python/tests/backends/test_Quantinuum_kernel.py b/python/tests/backends/test_Quantinuum_kernel.py
@@ -196,7 +196,8 @@ def kernel(state: cudaq.State):
         qubits = cudaq.qvector(state)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
diff --git a/python/tests/backends/test_Quantinuum_ng_kernel.py b/python/tests/backends/test_Quantinuum_ng_kernel.py
@@ -202,7 +202,8 @@ def kernel(state: cudaq.State):
         mz(qubits)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
diff --git a/python/tests/backends/test_braket.py b/python/tests/backends/test_braket.py
@@ -433,7 +433,8 @@ def kernel(state: cudaq.State):
         mz(qubits)
 
     state = cudaq.State.from_data(
-        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.], dtype=complex))
+        np.array([1. / np.sqrt(2.), 1. / np.sqrt(2.), 0., 0.],
+                 dtype=cudaq.complex()))
 
     counts = cudaq.sample(kernel, state)
     assert "00" in counts
diff --git a/python/tests/mlir/utils/target_env_var_check.py b/python/tests/mlir/utils/target_env_var_check.py
@@ -6,7 +6,7 @@
 # the terms of the Apache License 2.0 which accompanies this distribution.     #
 # ============================================================================ #
 
-# RUN: PYTHONPATH=../../ pytest -rP  %s
+# RUN: PYTHONPATH=../../.. pytest -rP  %s
 
 import os
 
@@ -15,13 +15,15 @@
 import pytest
 
 import cudaq
+import numpy as np
 
 
 def test_default_target():
     """Tests the default target set by environment variable"""
 
     assert ("density-matrix-cpu" == cudaq.get_target().name)
-
+    # This is a double-precision simulator
+    assert (cudaq.complex() is np.complex128)
     kernel = cudaq.make_kernel()
     qubits = kernel.qalloc(2)
     kernel.h(qubits[0])
@@ -40,6 +42,8 @@ def test_env_var_with_emulate():
     assert ("density-matrix-cpu" == cudaq.get_target().name)
     cudaq.set_target("quantinuum", emulate=True)
     assert ("quantinuum" == cudaq.get_target().name)
+    # The underlying simulator used for emulation is a double-precision simulator
+    assert (cudaq.complex() is np.complex128)
 
     kernel = cudaq.make_kernel()
     qubits = kernel.qalloc(2)
@@ -78,7 +82,7 @@ def test_target_override():
 # loosely be interpreted as "environment" checking, so hence placing the test
 # here.
 def test_version():
-    assert "CUDA Quantum Version" in cudaq.__version__
+    assert "CUDA-Q Version" in cudaq.__version__
 
 
 # leave for gdb debugging
diff --git a/python/tests/mlir/utils/target_env_var_check_fp32.py b/python/tests/mlir/utils/target_env_var_check_fp32.py
@@ -0,0 +1,110 @@
+# ============================================================================ #
+# Copyright (c) 2022 - 2025 NVIDIA Corporation & Affiliates.                   #
+# All rights reserved.                                                         #
+#                                                                              #
+# This source code and the accompanying materials are made available under     #
+# the terms of the Apache License 2.0 which accompanies this distribution.     #
+# ============================================================================ #
+
+# RUN: PYTHONPATH=../../.. pytest -rP  %s
+
+import os
+import subprocess
+try:
+    NUM_GPUS = int(subprocess.getoutput('nvidia-smi --list-gpus | wc -l'))
+except:
+    NUM_GPUS = 0
+
+os.environ[
+    "CUDAQ_DEFAULT_SIMULATOR"] = "nvidia" if NUM_GPUS > 0 else "density-matrix-cpu"
+
+import pytest
+
+import cudaq
+import numpy as np
+
+
+def test_default_target():
+    """Tests the default target set by environment variable"""
+    if NUM_GPUS > 0:
+        assert ("nvidia" == cudaq.get_target().name)
+        # This is a single-precision simulator
+        assert (cudaq.complex() is np.complex64)
+    else:
+        assert ("density-matrix-cpu" == cudaq.get_target().name)
+        # This is a double-precision simulator
+        assert (cudaq.complex() is np.complex128)
+
+    kernel = cudaq.make_kernel()
+    qubits = kernel.qalloc(2)
+    kernel.h(qubits[0])
+    kernel.cx(qubits[0], qubits[1])
+    kernel.mz(qubits)
+
+    result = cudaq.sample(kernel)
+    result.dump()
+    assert '00' in result
+    assert '11' in result
+
+
+def test_env_var_with_emulate():
+    """Tests the target when emulating a hardware backend"""
+    if NUM_GPUS > 0:
+        assert ("nvidia" == cudaq.get_target().name)
+    else:
+        assert ("density-matrix-cpu" == cudaq.get_target().name)
+    cudaq.set_target("quantinuum", emulate=True)
+    assert ("quantinuum" == cudaq.get_target().name)
+
+    # The underlying simulator used for emulation is the default simulator
+    if NUM_GPUS > 0:
+        # single-precision simulator
+        assert (cudaq.complex() is np.complex64)
+    else:
+        # double-precision simulator
+        assert (cudaq.complex() is np.complex128)
+
+    kernel = cudaq.make_kernel()
+    qubits = kernel.qalloc(2)
+    kernel.h(qubits[0])
+    kernel.cx(qubits[0], qubits[1])
+    kernel.mz(qubits)
+
+    result = cudaq.sample(kernel)
+    result.dump()
+    assert '00' in result
+    assert '11' in result
+
+
+def test_target_override():
+    """Tests the target set by environment variable is overridden by user setting"""
+
+    cudaq.set_target("qpp-cpu")
+    assert ("qpp-cpu" == cudaq.get_target().name)
+
+    kernel = cudaq.make_kernel()
+    qubits = kernel.qalloc(2)
+    kernel.h(qubits[0])
+    kernel.cx(qubits[0], qubits[1])
+    kernel.mz(qubits)
+
+    result = cudaq.sample(kernel)
+    result.dump()
+    assert '00' in result
+    assert '11' in result
+
+
+os.environ.pop("CUDAQ_DEFAULT_SIMULATOR")
+
+
+# This isn't really an environment variable test, but version checking could
+# loosely be interpreted as "environment" checking, so hence placing the test
+# here.
+def test_version():
+    assert "CUDA-Q Version" in cudaq.__version__
+
+
+# leave for gdb debugging
+if __name__ == "__main__":
+    loc = os.path.abspath(__file__)
+    pytest.main([loc, "-rP"])
diff --git a/python/tests/mlir/utils/target_env_var_check_stim.py b/python/tests/mlir/utils/target_env_var_check_stim.py
diff --git a/python/tests/mlir/utils/target_env_var_reset.py b/python/tests/mlir/utils/target_env_var_reset.py
diff --git a/python/tests/remote/test_remote_platform.py b/python/tests/remote/test_remote_platform.py
diff --git a/python/utils/LinkedLibraryHolder.cpp b/python/utils/LinkedLibraryHolder.cpp
