deprecation: warn on JaqcdProgram submission to local simulators (MCM-150287739)

[jacofeld]

Issue, if available

Internal: MCM-150287739 (Simulators broker migration removes JAQCD from Braket service device capabilities).

Coordinated deprecation across three Braket OSS Python packages:

• amazon-braket-schemas-python: deprecation: mark JAQCD action type and braket.ir.jaqcd module as deprecated (MCM-150287739) amazon-braket-schemas-python#221
• amazon-braket-sdk-python: deprecation: change Circuit.to_ir default to OPENQASM and warn on JAQCD (MCM-150287739) amazon-braket-sdk-python#1262
• amazon-braket-default-simulator-python: this PR

Description of changes

Amazon Braket service devices no longer accept JAQCD program submissions. LocalSimulator is offline (it doesn't depend on the service) so it can keep accepting JAQCD programs through the migration window — but it now emits a UserWarning telling customers to migrate to OpenQASMProgram. JAQCD support will be removed in a follow-up CR after a release cycle of warnings.

Code changes

• src/braket/default_simulator/simulator.py:
  • In BaseLocalSimulator.run(), add an isinstance(circuit_ir, JaqcdProgram) branch before the fallthrough to run_jaqcd that emits a UserWarning referencing MCM-150287739.
  • Added a .. deprecated:: 1.39.4 Sphinx directive to the run() docstring.
• setup.cfg: added a pytest filterwarnings rule that ignores the new JAQCD warning during the test session — see "Why a session-level filter?" below.

What is intentionally NOT changed

• run_jaqcd() and the JAQCD execution path remain fully functional. Customer code submitting JAQCD continues to run; only the warning is new.
• state_vector_simulator.py and density_matrix_simulator.py properties.action[\"braket.ir.jaqcd.program\"] blocks are preserved. Cached capability documents on customer machines continue to deserialize correctly through amazon-braket-schemas. The hard-removal CR will revisit these.

Why a session-level filter (not per-test wraps)

Many existing parametrized tests deliberately exercise the JAQCD code path (e.g. test_simulator_run_grcs_8[Jaqcd], test_simulator_run_no_results_no_shots, etc.) — wrapping each call site in pytest.warns(UserWarning) would create churn across multiple files and risks missing a call site.

Instead, setup.cfg adds:

[tool:pytest]
filterwarnings =
    ignore:Submitting JaqcdProgram to LocalSimulator is deprecated:UserWarning

This silences only this specific warning message in the test session. The new positive-assertion test (test_run_jaqcd_emits_warning) uses pytest.warns() which overrides this filter, so the warning contract is still verified.

Why UserWarning and not DeprecationWarning

DeprecationWarning is suppressed by default (PEP 565) for any warning attributed outside __main__. That hides it from customer code that wraps Braket calls in helper functions or libraries — exactly the cases we need to reach. UserWarning is visible by default and matches the existing warnings.warn call site in this package (e.g. the qubit_count is deprecated warning at simulator.py:949, which also uses UserWarning).

Testing done

tox -e unit-tests   # 1167 passed, 72 xfailed, 120 warnings, 0 leaked JAQCD warnings
tox -e linters      # ruff format + ruff check, all clean

New tests in test/unit_tests/braket/default_simulator/test_simulator.py:

• test_run_jaqcd_emits_warning — positive assertion using pytest.warns(UserWarning, match=\"JaqcdProgram\").
• test_run_openqasm_no_jaqcd_warning — negative assertion that the OpenQASM path stays silent (filters by message rather than erroring on all UserWarning so unrelated warnings like the density-matrix noise advisory don't false-fail).

Manual verification (visible-by-default warning, runs successfully):

import json
from braket.ir.jaqcd import Program as JaqcdProgram
from braket.default_simulator.state_vector_simulator import StateVectorSimulator

sim = StateVectorSimulator()
jaqcd = JaqcdProgram.parse_raw(json.dumps({
    'instructions': [{'type':'h','target':0}],
    'results': [{'type':'probability','targets':[0]}],
}))
sim.run(jaqcd, qubit_count=1, shots=10)
# stderr: <string>:10: UserWarning: Submitting JaqcdProgram to LocalSimulator
# is deprecated and will be removed in a future release. Submit
# OpenQASMProgram instead. ...

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

[codecov]

Codecov Report

❌ Patch coverage is 50.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 99.97%. Comparing base (e12f376) to head (a775221).

Files with missing lines	Patch %	Lines
src/braket/default_simulator/simulator.py	50.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##              main     #380      +/-   ##
===========================================
- Coverage   100.00%   99.97%   -0.03%     
===========================================
  Files           49       49              
  Lines         4882     4884       +2     
  Branches       561      562       +1     
===========================================
+ Hits          4882     4883       +1     
- Partials         0        1       +1     

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

[jacofeld]

Closing — replacing with a clean version that does not reference internal tracking IDs. No action needed from reviewers.