Add QubitPermutationGate and tuple input support to ClassicalStateSimulator

[Aqil-Ahmad]

Summary

This PR enhances the ClassicalStateSimulator by adding support for QubitPermutationGate operations and enabling tuple[int] input for the initial state parameter.

Fixes : #7566

Changes Made

• QubitPermutationGate Support: Implemented handling of qubit permutation operations in _act_on_fallback_ method
• Tuple Input Support: Added support for tuple[int, ...] as initial state input alongside existing int, list[int], and np.ndarray options
• Documentation Updates: Updated docstrings and error messages
• Testing: Added test coverage for:
  • QubitPermutationGate operations with various permutations
  • Tuple input validation and functionality
  • Edge cases and error conditions

Testing

• All existing tests pass
• New tests for QubitPermutationGate functionality and tuple input handling

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.50%. Comparing base (31df8ef) to head (38408a3).
⚠️ Report is 19 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7567      +/-   ##
==========================================
- Coverage   97.53%   97.50%   -0.04%     
==========================================
  Files        1095     1103       +8     
  Lines       99006    99609     +603     
==========================================
+ Hits        96570    97120     +550     
- Misses       2436     2489      +53     

☔ View full report in Codecov by Sentry.
📢 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.

[NoureldinYosri]

Suggested change

	initial_state: int | list[int] | tuple[int, ...] = 0,
	initial_state: int | Sequence[int] = 0,

[NoureldinYosri]

Suggested change

	initial_state: The initial state for the simulation. Accepts int, list[int],
	initial_state: The initial state for the simulation. Accepts int or a sequence of int.

[NoureldinYosri]

please check the definition of the permutation gate https://quantumai.google/reference/python/cirq/QubitPermutationGate

and make sure the ClassicalStateSimulator is consistent with the cirq.Simulator

[NoureldinYosri]

Sequence[

Suggested change

	raise ValueError('initial_state must be an int, list[int], tuple[int], or np.ndarray')
	raise ValueError('initial_state must be an int or Sequence[int]')

[NoureldinYosri]

Suggested change

	def test_qubit_permutation_gate():
	@pytest.mark.parameterize(['n', 'perm', 'state'], [
	(n, np.random.permutation(n).tolist(), np.random.choice(2, size=n)) for n in np.random.randint(3, 8, size=10)
	])
	def test_qubit_permutation_gate(n, perm, state):
	inv_perm = [perm.index(i) for i in range(n)]
	target = [state[p] for p in inv_perm]
	...
	np.testing.assert_equal(result.measurements['key'], target)