[linq] Circuit convenience methods return self (closes #408)

[999purple999]

Closes #408.

Circuit.simplify() returns NoneType instead of an empty circuit, because the convenience wrapper splats the underlying function's result into self.__dict__ and returns nothing. Three sibling methods on Circuit have the exact same shape, so this PR fixes all four at once for consistency.

What changed

tangelo/linq/circuit.py — added return self to:

• Circuit.simplify()
• Circuit.remove_redundant_gates()
• Circuit.remove_small_rotations()
• Circuit.merge_rotations()

The two docstrings that already promised Returns: Circuit: The circuit without ... are tightened; the two that didn't get a matching Returns clause added.

tangelo/linq/tests/test_circuits.py — new regression test test_simplify_returns_circuit_when_everything_cancels that pins the exact failing one-liner from the issue body:

result = Circuit([Gate("H", 0)] * 2).simplify()
assert result is not None
assert isinstance(result, Circuit)
assert len(result._gates) == 0
assert result.width == 1

Plus analogous assertions for the other three methods.

FIX_ISSUE_408_README.md — design rationale (why return self over a separate simplified() API), full file listing.

Compatibility

The in-place semantic is preserved — these methods still mutate self.__dict__ before returning. The existing test_simplify_circuit passes unchanged because the assertions on circuit state after .simplify() are still valid.

The change enables the chainable expression form (Circuit(...).simplify().draw()) without breaking any existing code that called these methods for their side-effects and discarded the return value.

Open question for review

If you'd rather have a separate simplified() / remove_redundant_gates_copy() API (returning a new circuit, leaving the original untouched), this PR can be reworked in that direction — happy to align on whichever shape fits the linq module's broader conventions.

---

Francesco Pernice Botta · 999purple999

[alexfleury-sb]

Thanks for the PR @999purple999! This is still in draft mode, so I am assuming your work is not completed yet.

Code changes are pretty much good with me. Two things:

• I would like is that this PR targets the develop branch instead of the main one.
• Please remove the FIX_ISSUE_408_README.md file (and maybe post the content directly in issue [BUG] Circuit.simplify returns NoneType instead of an empty circuit #408 for archiving purposes).

[999purple999]

Thanks @alexfleury-sb! Both points addressed in 1eb1da6:

• Rebased onto develop (PR base also changed via gh).
• Removed FIX_ISSUE_408_README.md from the PR.

The README content (root-cause walk-through + design rationale for return self) can be archived as a comment on #408 if helpful happy to post it there separately, just say the word. Otherwise it lives in the commit message + PR description.

Let me know if anything else needs a tweak.

[999purple999]

Hi @alexfleury-sb — both changes applied in commit 1eb1da6:

• Branch rebased onto develop (single commit, no merge of unrelated work).
• FIX_ISSUE_408_README.md removed from the diff.

The PR is no longer marked as draft. Ready for re-review whenever you have a moment — thanks for taking the time on this one.

[alexfleury-sb]

LGTM