Test channel inclusion in random circuit generators.

[rosspeili]

Behavioral coverage for include_channels=True/False in util_test, including channel presence, non-parameterization, and TFQ serialization round-trips. Document include_channels in random circuit helper docstrings.

Fixes #1066

[gemini-code-assist]

Code Review

This pull request documents the include_channels argument in several random circuit generation utility functions and adds comprehensive unit tests to verify channel generation, handling, and serialization. The reviewer pointed out that the newly added tests only seed Python's built-in random module, whereas the underlying utility functions rely on NumPy's random generator. This can lead to non-deterministic and flaky tests, so the reviewer suggested seeding np.random as well in all three test cases.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[mhucka]

Thank you for this work!

Please see the comment about the test that may miss some possible cases.

Also, I did not have time to look further down to see if there's a similar situation elsewhere in util_test.py, so please check that.

[mhucka]

I think there's a subtle flaw there:

1. random_symbol_circuit in util.py can call _apply_random_control
2. _apply_random_control may wrap a gate inside cirq.ControlledOperation
3. the test above checks if op.gate is a supported channel type. However, op.gate can be a ControlledGate wrapper …
4. which in _is_supported_channel will be tested against raw channel classes …
5. which will return False …
6. which means the test cirq.is_parametrized inside the if condition will not be tested …
7. which means those cases are silently ignored by the test.

So I think the function needs to be changed to something like the following:

def _assert_channels_not_parameterized_or_controlled(testcase, circuit):
    """Asserts that channels are neither parameterized nor controlled."""
    for moment in circuit:
        for op in moment:
            sub_op = op
            is_controlled = False

            if isinstance(op, cirq.ControlledOperation):
                sub_op = op.sub_operation
                is_controlled = True

            gate = sub_op.gate
            if isinstance(gate, cirq.ControlledGate):
                gate = gate.sub_gate
                is_controlled = True

            if isinstance(gate, _supported_channel_types()):
                testcase.assertFalse(
                    is_controlled,
                    msg=f"Found controlled channel operation: {op}"
                )
                testcase.assertFalse(
                    cirq.is_parameterized(op),
                    msg=f"Found parameterized channel operation: {op}"
                )

The calls to _assert_channels_not_parameterized also should be changed to the new function. (Maybe a shorter name can be found, because the one above is kind of ridiculously long, but right now I can't think of a better one.)

[rosspeili]

Thanks for the direction @mhucka, and you were right to assume similar gaps. Same unwrapping logic applied also to the channel presence helper. Channel ops are now checked as neither controlled nor parameterized via _assert_channel_ops_valid. Let me know how this looks, or if you want a better name for the function. <3