Merge branch 'main' into undo-indent-size-for-makefiles

Author: mhucka

.github/workflows/pr-text-checker.yaml

@@ -0,0 +1,64 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Summary: check the subject and description of each PR for basic best
+# practices and fail with an error if a PR doesn't meet the conditions.
+
+name: Pull request text checker
+run-name: >-
+  Check title and description of
+  PR #${{github.event.inputs.pr-number || github.event.pull_request.number}}
+  by ${{github.actor}}
+
+on:
+  pull_request:
+    types:
+      - edited
+      - opened
+      - reopened
+      - synchronize
+    branches:
+      - main
+
+permissions: read-all
+
+jobs:
+  check-text-length:
+    name: "Minimum length check"
+    runs-on: ubuntu-slim
+    timeout-minutes: 5
+    steps:
+      - name: Check the lengths of the PR title and description
+        env:
+          SHELLOPTS: ${{runner.debug && 'xtrace' || '' }}
+        run: |
+          pr_title=$(jq -r ".pull_request.title" "${GITHUB_EVENT_PATH}")
+          pr_body=$(jq -r ".pull_request.body" "${GITHUB_EVENT_PATH}")
+
+          read -ra title_words <<< "${pr_title}"
+          if [[ ${#title_words[@]} -lt 2 ]]; then
+            echo "::error::PR title must contain at least two words."
+            error=1
+          fi
+          if [[ -z "${pr_body}" || ${#pr_body} -lt 10 ]]; then
+            echo "::error::PR description must be at least 10 characters long."
+            error=1
+          fi
+
+          if [[ -v error ]]; then
+            {
+            printf "❌ Problem(s) found with the PR title and/or description."
+            } >> "${GITHUB_STEP_SUMMARY}"
+            exit 1
+          fi

Makefile

@@ -46,6 +46,19 @@ CXXFLAGS := $(BASE_CXXFLAGS) $(CXXFLAGS)
 NVCCFLAGS := $(BASE_NVCCFLAGS) $(NVCCFLAGS)
 HIPCCFLAGS := $(BASE_HIPCCFLAGS) $(HIPCCFLAGS)
 
+# GCC 15 and Binutils 2.45+ generate SFrame stack unwinding info. The current
+# SFrame only supports a subset of x86_64 registers. When GCC optimizes AVX*
+# instructions, it uses additional registers, and that causes the assembler to
+# produce (many) warnings. They are harmless for qsim because it does not rely
+# on SFrame. Silence those warnings if the assembler supports it.
+SUPPORTS_GSFRAME := $(shell $(CXX) -Wa,--gsframe=no -c -x c++ /dev/null \
+    -o /dev/null 2>/dev/null && echo "true")
+ifeq ($(SUPPORTS_GSFRAME),true)
+    CXXFLAGS += -Wa,--gsframe=no
+    NVCCFLAGS += -Xcompiler -Wa,--gsframe=no
+    HIPCCFLAGS += -Wa,--gsframe=no
+endif
+
 LTO_FLAGS := -flto=auto
 USING_CLANG := $(shell $(CXX) --version | grep -isq clang && echo "true")
 ifeq ($(USING_CLANG),true)
@@ -126,7 +139,7 @@ ifneq (,$(strip $(CUQUANTUM_ROOT)))
     endif
 endif
 
-# Export all variables to subprocesses without having to export them individually.
+# Export all vars to subprocesses without having to export them individually.
 .EXPORT_ALL_VARIABLES:
 
 # The rest is build rules and make targets.
@@ -214,7 +227,7 @@ run-tests tests: $(TESTS)
 .PHONY: check-cuquantum-root-set
 check-cuquantum-root-set:
 	@if test -z "$(CUQUANTUM_ROOT)"; then \
-	    echo Error: '$$CUQUANTUM_ROOT must be set in order to use cuStateVec.'; \
+	    echo Error: 'Must set $$CUQUANTUM_ROOT to use cuStateVec.'; \
 	    exit 1; \
 	fi
 
@@ -241,7 +254,7 @@ clean:
 	-$(MAKE) -C pybind_interface/ clean
 
 LOCAL_VARS = TARGETS TESTS PYTESTS PYTESTFLAGS CXX CXXFLAGS NVCC NVCCFLAGS $\
-	HIPCC HIPCCFLAGS CUDA_PATH CUQUANTUM_ROOT CUSTATEVECFLAGS
+	HIPCC HIPCCFLAGS CUDA_PATH CUQUANTUM_ROOT CUSTATEVECFLAGS SUPPORTS_GSFRAME
 
 .PHONY: print-vars
 print-vars: ; @$(foreach n,$(sort $(LOCAL_VARS)),echo $n=$($n);)

docs/choose_hw.md

@@ -311,6 +311,18 @@ depth beyond 20 qubits.
     *   The total small circuits runtime overhead for an N qubit circuit
         depends on the circuit depth and on N. The overhead can be large enough to
         conceal the  $2^N$ growth in runtime.
+*   The NumPy version matters for large simulations:
+    *   NumPy 1.x defines a constant `NPY_MAXDIMS`, which is set to 32 in the
+        NumPy source code. Many internal NumPy structures, such as those for
+        iteration and coordinate tracking, use fixed-size buffers based on this
+        value. Although the C++ core of qsim is not affected by this (since it
+        does not use NumPy), this NumPy limit prevents state vectors from having
+        more than 32 qubits when using Python. Attempting to use 33 or more
+        qubits results in an error.
+    *   NumPy 2.x increased this limit to 64 dimensions, and qsim can work with
+        more than 32 qubit when NumPy 2.x is used. If you encounter unexpected
+        failures, memory errors, or hard limits on the number of qubits, ensure
+        you are running a recent NumPy version before further debugging.
 
 ## Sample benchmarks
 

lib/vectorspace_custatevecex.h

@@ -546,9 +546,6 @@ class VectorSpaceCuStateVecEx {
 
     ErrorCheck(custatevecExStateVectorSynchronize(dest.get()));
 
-    // TODO: do we need that?
-    dest.to_normal_order();
-
     return true;
   }
 
@@ -576,9 +573,6 @@ class VectorSpaceCuStateVecEx {
 
     ErrorCheck(custatevecExStateVectorSynchronize(dest.get()));
 
-    // TODO: do we need that?
-    dest.to_normal_order();
-
     return true;
   }
 

qsimcirq/qsim_simulator.py

@@ -525,8 +525,10 @@ def _simulate_impl(
                 qsim_state = fullstate_simulator_fn(options, initial_state)
             elif isinstance(initial_state, np.ndarray):
                 qsim_state = fullstate_simulator_fn(options, input_vector)
-            assert qsim_state.dtype == np.float32
-            assert qsim_state.ndim == 1
+            if qsim_state.dtype != np.float32:
+                raise TypeError("qsim_state must have dtype np.float32.")
+            if qsim_state.ndim != 1:
+                raise ValueError("qsim_state must be a 1D array.")
 
             yield prs, qsim_state.view(np.complex64), cirq_order
 

qsimcirq_tests/qsimcirq_test.py

@@ -18,6 +18,7 @@
 import sympy
 
 import qsimcirq
+import qsimcirq.qsim_circuit
 
 
 class NoiseTrigger(cirq.Gate):
@@ -128,6 +129,26 @@ def _unitary_(self):
         qsimSim.compute_amplitudes(cirq_circuit, bitstrings=[0b0, 0b1])
 
 
+def test_translate_matrix_gate_too_big():
+    gate = cirq.MatrixGate(np.eye(128))
+    with pytest.raises(
+        NotImplementedError, match="only up to 6-qubit gates are supported"
+    ):
+        qsimcirq.qsim_circuit._translate_MatrixGate(gate)
+
+
+def test_simulate_matrix_gate_too_big():
+    qubits = cirq.LineQubit.range(7)
+    gate = cirq.MatrixGate(np.eye(128))
+    circuit = cirq.Circuit(gate.on(*qubits))
+
+    qsim_sim = qsimcirq.QSimSimulator()
+    with pytest.raises(
+        NotImplementedError, match="only up to 6-qubit gates are supported"
+    ):
+        qsim_sim.compute_amplitudes(circuit, bitstrings=[0b0, 0b1])
+
+
 def test_cirq_giant_identity():
     # Pick qubits.
     a, b, c, d, e, f, g, h = [
@@ -180,6 +201,61 @@ def _decompose_(self, qubits):
     assert result_hist[1] > 0
 
 
+def test_translate_cirq_to_qtrajectory():
+    q0, q1 = cirq.LineQubit.range(2)
+
+    # General circuit with unitary, mixture, and channel.
+    circuit = cirq.Circuit(
+        cirq.H(q0),
+        cirq.CNOT(q0, q1),
+        cirq.bit_flip(0.1)(q0),
+        cirq.depolarize(0.1)(q1),
+    )
+    qsim_circuit = qsimcirq.QSimCircuit(circuit)
+    qsim_ncircuit, moment_indices = qsim_circuit.translate_cirq_to_qtrajectory()
+
+    assert isinstance(qsim_ncircuit, qsimcirq.qsim.NoisyCircuit)
+    assert qsim_ncircuit.num_qubits == 2
+    # The circuit has 3 moments, and 4 gates are translated in total.
+    assert moment_indices == [1, 2, 4]
+
+    # Edge case: empty circuit.
+    circuit_empty = cirq.Circuit()
+    qsim_circuit_empty = qsimcirq.QSimCircuit(circuit_empty)
+    qsim_ncircuit_empty, moment_indices_empty = (
+        qsim_circuit_empty.translate_cirq_to_qtrajectory()
+    )
+
+    assert isinstance(qsim_ncircuit_empty, qsimcirq.qsim.NoisyCircuit)
+    assert qsim_ncircuit_empty.num_qubits == 0
+    assert moment_indices_empty == []
+
+    # Edge case: circuit with only unitary gates.
+    circuit_unitary = cirq.Circuit(cirq.X(q0), cirq.H(q1))
+    qsim_circuit_unitary = qsimcirq.QSimCircuit(circuit_unitary)
+    qsim_ncircuit_unitary, moment_indices_unitary = (
+        qsim_circuit_unitary.translate_cirq_to_qtrajectory()
+    )
+
+    assert isinstance(qsim_ncircuit_unitary, qsimcirq.qsim.NoisyCircuit)
+    assert qsim_ncircuit_unitary.num_qubits == 2
+    assert moment_indices_unitary == [2]
+
+    # Edge case: unparseable operation.
+    class UnparseableOp(cirq.Operation):
+        @property
+        def qubits(self):
+            return (q0,)
+
+        def with_qubits(self, *new_qubits):
+            return self
+
+    circuit_unparseable = cirq.Circuit(UnparseableOp())
+    qsim_circuit_unparseable = qsimcirq.QSimCircuit(circuit_unparseable)
+    with pytest.raises(ValueError, match="Encountered unparseable op"):
+        qsim_circuit_unparseable.translate_cirq_to_qtrajectory()
+
+
 @pytest.mark.parametrize("mode", ["noiseless", "noisy"])
 def test_cirq_qsim_simulate(mode: str):
     # Pick qubits.
@@ -2196,3 +2272,21 @@ def test_1d_representation():
     want = np.array([0.0 - 0.5j, 0.0 + 0.5j, 0.0 - 0.5j, 0.0 + 0.5j])
     _, res, _ = qsim_sim.simulate_into_1d_array(c)
     np.testing.assert_allclose(res, np.array(want, dtype=np.complex64))
+
+
+def test_get_seed():
+    # Test range.
+    qsim_sim = qsimcirq.QSimSimulator(seed=42)
+    for _ in range(100):
+        seed = qsim_sim.get_seed()
+        assert 0 <= seed < 2**31 - 1
+
+    # Test determinism.
+    sim1 = qsimcirq.QSimSimulator(seed=42)
+    sim2 = qsimcirq.QSimSimulator(seed=42)
+    assert sim1.get_seed() == sim2.get_seed()
+
+    # Test subsequent calls.
+    sim = qsimcirq.QSimSimulator(seed=42)
+    seeds = {sim.get_seed() for _ in range(10)}
+    assert len(seeds) > 1

tests/Makefile

@@ -40,7 +40,7 @@ endif
 
 CXX_FILES := $(BASIC_FILES) $(SSE_FILES) $(AVX2_FILES) $(AVX512_FILES)
 CXX_TARGETS := $(CXX_FILES:%.cc=%.x)
-CXXFLAGS := $(CXXFLAGS) $(SSE_FLAGS) $(AVX2_FLAGS) $(AVX512_FLAGS) $(BMI2_FLAGS)
+CXXFLAGS += $(SSE_FLAGS) $(AVX2_FLAGS) $(AVX512_FLAGS) $(BMI2_FLAGS)
 
 CUDA_FILES := $(wildcard *cuda_test.cu)
 CUDA_TARGETS := $(CUDA_FILES:%cuda_test.cu=%cuda_test.x)