feat: add default zero state to QubitCircuit.run()

[satishkc7]

Closes #374.

Summary

qc.run() previously required an explicit state argument in every call. In the large majority of use cases the initial state is the all-zero ket |00...0>. This PR makes state optional by defaulting to that state when none is provided.

Changes

• circuit.py: add basis and tensor to the qutip import, change state to state=None, and insert a one-liner that constructs the zero state from self.dims when the argument is omitted.
• test_circuit.py: add test_run_default_zero_state covering a single-qubit and a two-qubit circuit.

Before

qc = QubitCircuit(2)
qc.add_gate("X", targets=0)
result = qc.run(tensor(basis(2, 0), basis(2, 0)))  # state required

After

qc = QubitCircuit(2)
qc.add_gate("X", targets=0)
result = qc.run()  # defaults to |00>

Passing an explicit state still works exactly as before.

[Mayank447]

Suggested change

	qc.add_gate("X", targets=0)
	qc.add_gate(X, targets=0)

[Mayank447]

Same as above

[Mayank447]

Please use relative and absolute tolerances

[Mayank447]

Just some minor changes.

@satishkc7 In case you used AI tools, we expect you to mention that in the PR description as per our Contribution guidelines.

[Mayank447]

Suggested change

	fid = pytest.approx(qutip.fidelity(result, basis(2, 1)), rel=1e-6, abs=1e-6)
	assert fid == 1.0
	assert qutip.fidelity(result, basis(2, 1)) == pytest.approx(1.0, rel=1e-6, abs=1e-6)

[Mayank447]

Same as above

[BoxiLi]

Please run the test locally and confirm that it passes before raising a PR and please state explicitly if and how AI tools are used.

[satishkc7]

Thanks for the review feedback.

All requested changes have been addressed:

• Replaced string gate names with object references (gates.X)
• Updated assertions to use inline pytest.approx(1.0, rel=1e-6, abs=1e-6) pattern
• Fixed an invalid escape sequence (\|) in the docstring that causes a SyntaxError on Python 3.14

Tests confirmed passing locally:

tests/test_circuit.py::TestQubitCircuit::test_run_default_zero_state PASSED

Regarding AI tools - yes, I used Claude (Claude Code) to assist with drafting the implementation and tests. Happy to note this in the PR description as well if needed.

[Copilot]

Pull request overview

This PR updates QubitCircuit.run() to make the state argument optional, defaulting to the all-zero computational basis ket for the circuit’s configured subsystem dimensions. This aligns the API with the common workflow where circuits are run from |00…0⟩ unless otherwise specified.

Changes:

• Make QubitCircuit.run(state=...) accept state=None and synthesize the default initial ket from self.dims.
• Update the run() docstring to describe the new default behavior.
• Add tests covering the default initial state for 1- and 2-qubit circuits.

Reviewed changes

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

File	Description
src/qutip_qip/circuit/circuit.py	Defaults run()’s input state to the all-zero ket constructed from self.dims when omitted.
tests/test_circuit.py	Adds regression tests ensuring run() without state starts from |00…0⟩ and produces expected outputs.

---

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

[Mayank447]

@BoxiLi You can merge this PR. Do a squash merge btw.