Add NumPy number types to TParamVal

[sankalpsthakur]

Fixes #5758.

Summary

Extend TParamVal with the real NumPy scalar families np.integer | np.floating, matching parameters already accepted at runtime. Complex NumPy values remain outside TParamVal; TParamValComplex keeps np.number.

The change also updates canonicalize_half_turns typing and adds NumPy coverage for parameter resolution, probability values, type-alias membership and JSON round trips.

Test plan

Coverage is in the affected angle, type-alias, parameter-resolution, gate/probability and JSON serialization tests. This changes public typing; downstream annotations restricted to float | sympy.Expr may need to use TParamVal.

Current CI and the Google CLA check pass on 290fae089. Scorecard is neutral.

AI disclosure

Cursor Agent, Grok and Codex assisted with this contribution and description. AI assistance remains disclosed after the commit metadata correction.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.59%. Comparing base (cfa8a84) to head (290fae0).
⚠️ Report is 9 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #8236    +/-   ##
========================================
  Coverage   99.59%   99.59%            
========================================
  Files        1125     1128     +3     
  Lines      103250   103821   +571     
========================================
+ Hits       102829   103400   +571     
  Misses        421      421            

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mhucka]

Thank you for this work.

To go along with these changes, an additional overload for canonicalize_half_turns for np.number (or TypeVar bounded by np.number) is needed in file cirq/value/angle.py.

The test cases also should be expanded to exercise both floating-point and integer NumPy scalar subtypes (e.g., np.float64, np.double, np.int64, np.short) to verify that arithmetic operations (e.g., modulo operations, and range wrapping into (-1, +1]) preserve type and value invariants as expected across NumPy numeric types.

Finally, Dax Fohl noted in the last comment on issuue 5758 that a change of this nature would have backward compatibility implications. Can you add test cases (e.g., for the case mentioned at the end of the first paragraph in that comment) to verify that backards compatibility is maintained?

[mhucka]

Discussed during Cirq Cynq 2026-08-19: consensus is that this change may indeed work, but this definitely needs many more test cases than what is in the PR currently. In particular, we need to check that the parameter resolver works correctly. (See resolve_parameter in cirq/protocols/resolver_parameter.py). The param resolver needs to be able to correctly resolve a bunch of different gates.

A possible approach is to look at the tests already in param resolver, then extend the relevant tests with numpy values, and make sure everything still works.

[sankalpsthakur]

Added an np.number TypeVar overload on canonicalize_half_turns, plus wrapping tests for np.float64/np.double/np.int64/np.short, ParamResolver coverage on X/Y/Z/H/CZ/CX, and the XPowGate(np.double(0.5)) isinstance(float) case from #5758. 987c1a3, please take another look.

[sankalpsthakur]

Rebased onto main and fixed format in b54346b.

[sankalpsthakur]

Rebased onto main in d4780eb.

[sankalpsthakur]

@mhucka added wrapping tests for np.float32, np.float64, np.int32, and np.int64 on canonicalize_half_turns (type preserved into (-1, +1]), plus ParamResolver coverage on more EigenGates. The #5758 np.double isinstance(float) case is still there. Overload is a TypeVar bound by np.number.

[sankalpsthakur]

Extended the existing resolve_parameters / is_parameterized / parameter_names / recursive tests with NumPy scalars (np.float32, np.float64, np.double, np.int32, np.int64, np.short). ParamResolver formulas and gates: rx/ry/rz, FSim, PhasedXZ, GlobalPhase, Wait, CCZ/CCX, controlled XPow.

f22606bfc

PYTHONPATH=cirq-core pytest cirq-core/cirq/protocols/resolve_parameters_test.py cirq-core/cirq/study/resolver_test.py cirq-core/cirq/ops/eigen_gate_test.py cirq-core/cirq/value/angle_test.py

546 passed

[sankalpsthakur]

added a parametrized test documenting the isinstance(exponent, float) split: true for np.float64/np.double, false for np.float32 and the int dtypes, same before and after this pr since widening TParamVal is annotation-only. also locks in that resolve_parameters normalizes every dtype to plain float regardless.

[mhucka]

Thank you for this effort!

I have some initial review comments.

[mhucka]

Thanks for the updates!

Could some additional tests be added for the following too?

1. Verify roundtrip equality for gates and circuits parameterized with various NumPy scalar dtypes. (E.g., cirq.to_json() must serialize gates with NumPy scalar parameters without throwing TypeError, and cirq.read_json() needs to reconstruct them with standard Python numeric types.)

2. Check that cirq.Gate.with_probability(p) and channel classes (such as cirq.DepolarizingChannel, cirq.BitFlipChannel, etc.) accept TParamVal or call validate_probability.

3. Check that canonicalize_half_turns handles unsigned integer types (such as half_turns -= 2 when values exceed 1) without overflow or type errors. Maybe add test cases that use types np.uint8, np.uint16, np.uint32, np.uint64.

4. Check what happens with 0-dimensional np.ndarrays.

5. Check floating-point value edge cases: signed zero, NaN, Inf. For example, checking that canonicalize_half_turns(np.float64(-0.0)) is handled without creating negative zero mismatches in gate equality, checking that cirq.is_parameterized(cirq.XPowGate(exponent=np.nan)) returns False, and so on.

[mhucka]

@pavoljuhas and/or @daxfohl, would you be able to take a look at this PR too?

[sankalpsthakur]

Addressed the remaining review notes on this tip (03fe4191):

• TParamVal stays real NumPy scalars only (not complex np.number)
• canonicalize_half_turns overload for NumPy real scalars
• wrap tests for np.float64 / np.double / np.int64 / np.short
• back-compat for XPowGate(exponent=np.double(0.5))
• targeted suite: 670 passed

Ready for another look when you have time.

[daxfohl]

Should be fine. It's just a type change so it's not actually breaking any runtime behavior. The two backwards incompatibilities are

1. Passing e.g. gate.exponent to a function that only takes float | sympy.Expr. But that seems unusual; most users would type their parameter as TParamVal to match what they're passing in. And the only breakage this case would cause is type checking; runtime would be fine.
2. If a user's function does if isinstance(gate.exponent, float) somewhere that now needs to take numpy types into account. Those functions will now have broken runtime behavior when presented with numpy types, so is the larger problem. However, that's mostly mitigated by the fact that breaking it would require users to start passing in numpy types, which, they currently aren't. So this change wouldn't break anything that's not already broken. The biggest concern would be if there are third-party libraries that have e.g. if isinstance(gate.exponent, float) everywhere; for any user that uses both cirq and those third-party libraries, they'd have to patch the libraries in order to be compatible. Or they could just avoid using numpy types if they're using such a library, which is what they're already doing.

So, formally if we're doing tight type controls, this is breaking. But I can't think of any scenarios where it would cause any real-world problems. LGTM.

[sankalpsthakur]

The remaining macOS failure is test_parallel_two_qubit_xeb_with_ideal_target: sampled fidelities [0.710634, 0.547693] missed the 0.9 ± 0.3 tolerance. Failed job. Could a maintainer rerun it? GitHub denied my rerun request because it requires repository admin rights.

[mhucka]

@sankalpsthakur Re-running the CI checks resolved the flaky test result.

However, the CLA check is failing because one of the coauthors listed is an AI agent, and AI agents can't sign documents. I am not sure what to do about that …

[sankalpsthakur]

@mhucka Removed the agent author attribution in 290fae0. CLA and CI now pass. AI assistance remains disclosed in the PR description.