Add MPAD instruction

[rafaelha]

Summary

• Implement MPAD gate that pads the measurement record with fixed bit values (0 or 1), with optional noise probability
• Uses the auxiliary qubit pattern (qubit -2): reset, conditionally X-flip, then measure

Closes #75

Test plan

• Unit tests for parsing: single/multiple targets, mixed with measurements, repeat blocks
• Integration tests for sampling: deterministic 0/1 values, interleaved with M, detector sampler

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-04-07 01:28 UTC

[github-actions]

☂️ Python Coverage

current status: ✅

Overall Coverage

Lines	Covered	Coverage	Threshold	Status
2161	2088	97%	0%	🟢

New Files

No new covered files...

Modified Files

File	Coverage	Status
src/tsim/core/instructions.py	98%	🟢
src/tsim/core/parse.py	94%	🟢
TOTAL	96%	🟢

updated for commit: ffafb99 by action🐍

[Copilot]

Pull request overview

This PR adds support for Stim’s MPAD instruction to the tsim pipeline, allowing circuits to pad the measurement record with fixed 0/1 results (optionally noisy) using the auxiliary qubit pattern.

Changes:

• Add MPAD handling to parse_stim_circuit, mapping targets into a new mpad core instruction.
• Implement mpad in the core instruction set using aux qubit -2 (reset → optional X → measure).
• Add unit parsing tests and integration sampler tests covering basic MPAD usage and interaction with DETECTOR.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
src/tsim/core/parse.py	Dispatches MPAD instructions during circuit parsing and forwards targets/arg to core logic.
src/tsim/core/instructions.py	Introduces the mpad instruction implementation using the aux-qubit measurement pattern.
test/unit/core/test_parse.py	Adds parsing-focused tests ensuring MPAD contributes the expected number of measurement record entries.
test/integration/test_sampler_circuits.py	Adds sampling and detector integration tests for deterministic MPAD outputs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

MPAD targets are documented as fixed bits (0 or 1), but mpad currently treats any non-1 value as 0 without raising. This can silently produce incorrect padding if an invalid target slips through (or if mpad is called directly). Consider validating value in (0, 1) and raising a ValueError otherwise.

[Copilot]

MPAD parsing currently takes the first gate arg as p and ignores any additional args. If MPAD is only supposed to allow 0 or 1 parens arg, it would be safer to validate the arg count and fail fast on unexpected input (instead of silently ignoring). Also consider validating that each target is a literal bit value (0/1) before passing it through.

Suggested change

	args = instruction.gate_args_copy()
	p = args[0] if args else 0
	for target in instruction.targets_copy():
	args = instruction.gate_args_copy()
	if len(args) > 1:
	raise ValueError(
	f"MPAD expects at most one gate argument, got {len(args)}: {args}"
	)
	p = args[0] if args else 0
	for target in instruction.targets_copy():
	if target.value not in (0, 1):
	raise ValueError(
	f"MPAD targets must be literal bit values 0 or 1, got: {target}"
	)

[Copilot]

The comment claims the final M 0 is "after implicit reset", but there is no reset of qubit 0 between the two M 0 instructions (only the auxiliary qubit used by MPAD is reset). Consider updating the comment to avoid implying behavior that isn't present in the circuit.

Suggested change

	# M 0 after X -> 1, MPAD 0 -> 0, M 0 after implicit reset -> 1
	# M 0 after X -> 1, MPAD 0 -> 0, final M 0 still -> 1 because qubit 0 is not reset

[Copilot]

The MPAD sampler tests only cover the noiseless case. Since this PR adds the optional noise probability argument, consider adding an integration test for MPAD(p) as well (e.g. using p=1 to deterministically flip the padded bit and avoid flaky statistical assertions).

Suggested change

	def test_mpad_with_noise_probability_one():
	c = Circuit("""
	MPAD(1) 0
	""")
	sampler = c.compile_sampler()
	samples = sampler.sample(10)
	assert (samples == 1).all()