feature: Added counts based on operator name and qubits specified

[ACE07-Sev]

Issue #, if available: Closes #1235

Description of changes:
Added instruction counting to Circuit with additional filtering based on specific gate name and/or qubits applied to.

Testing done:
Added a unit tester to test_circuit.py which asserts the desired behavior, and ensures a ValueError is raised for out of bounds qubits specified.

Merge Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your pull request.

General

• I have read the CONTRIBUTING doc
• I used the PR title format described in CONTRIBUTING
• I have updated any necessary documentation, including READMEs and API docs (if appropriate)

Tests

• I have added tests that prove my fix is effective or that my feature works (if appropriate)
• I have checked that my tests are not configured for a specific region or account (if appropriate)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[ACE07-Sev]

I added the qubit specifier you requested, but not quite sure what you meant by density of operators. If you can kindly guide me on that, I can add that as well today.

[ACE07-Sev]

@sesmart Can I please get a review?

[sesmart]

Hi @ACE07-Sev , @aniksd-braket will be reviewing this issue.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (a5ee47d) to head (5d8d274).

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1275   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          169       169           
  Lines        10963     10975   +12     
  Branches      1412      1416    +4     
=========================================
+ Hits         10963     10975   +12     

☔ 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.

[jaimeajl]

This looks like a useful direction. I think the “operator density” stretch goal from the issue could be implemented as a small complementary layer on top of raw instruction counts.

My interpretation would be a deterministic circuit summary that includes both counts and normalized densities, for example:

• total instruction count
• count by operator name
• count filtered by qubits
• operator density: operator_count / total_instruction_count
• per-qubit instruction count
• per-qubit instruction density

This would make the feature useful not only as a convenience method, but also for benchmarking, sanity checks, and comparing generated or transformed circuits.

A possible output shape could be:

{
"total": 10,
"by_operator": {"h": 2, "cnot": 3, "rz": 5},
"operator_density": {"h": 0.2, "cnot": 0.3, "rz": 0.5},
"per_qubit": {0: 6, 1: 4},
"per_qubit_density": {0: 0.6, 1: 0.4}
}

If this interpretation aligns with the maintainers’ expectations, I can open a focused follow-up PR for the density/summary part, without duplicating the existing count implementation.

[ACE07-Sev]

@jaimeajl may I ask if you're part of the maintainer team?

[ACE07-Sev]

@aniksd-braket Can I please get a review?

[aniksd-braket]

Would be great if you could also add the case of getting counts for of operations on all qubits specified, instead of just any of the qubits specified

[aniksd-braket]

Here do you consider all operators, including noise operations?

[ACE07-Sev]

Any instruction applied to the circuit (if we go with just ones applied to qubits then gphase would need to be skipped I suppose). Are there exclusions you want me to skip?

[aniksd-braket]

I was referring to these - https://amazon-braket-sdk-python.readthedocs.io/en/latest/_apidoc/braket.circuits.noise.html

[ACE07-Sev]

@aniksd-braket Understood. Should these be skipped?

[aniksd-braket]

Maybe have an option to either include or exclude them. Exclude them by default?

[ACE07-Sev]

Greetings @aniksd-braket

Thank you very much for the review. Sure thing, I'll get to it first thing in the morning.