add quration tutorial docs

[Kazutaka333]

This PR adds quration tutorial to quri-sdk.qunasys.com

[Kazutaka333]

Are there sources for what are written in this file? If otherwise, I wonder if a review from Quration developers are necessary.
I feel it would be more natural for this documentation to be added to Quration documentation. Shall we discuss it with Quration developers?

I removed the file from this PR and will create a PR on QunaSys/quration

[kwkbtr]

(Adding comments on file since it's not possible to add inline comments)

• At the beginning of the tutorial, you mention “the instruction set”, but I think users will not understand what this refers to from that phrase alone. It should be explained more explicitly as "the instruction set of an FTQC architecture (like surface code and lattice surgery)".
• The title “Quration Resource Estimation” is not very informative for people who don't know Quration (they may not be motivated to read the tutorial). I think the title should clearly indicate that the tutorial is about resource estimation for FTQC architectures.

[Kazutaka333]

I added the change thank you!

[kwkbtr]

# If quri-parts is not installed, install it with the following command:
# %pip install quri-parts

Since quri-parts-qret is an extra dependency you need to run pip install quri-parts[qret].

[Kazutaka333]

modified it accordingly 🫡

[kwkbtr]

# Build a 2-qubit circuit
# b = SubBuilder(2)
# q0, q1 = b.qubits
# b.add_op(CNOT, (q0, q1))

ctrl = Controlled(X)
sub = resolve_sub(ctrl)
draw(sub)

Are these commented lines necessary?

[Kazutaka333]

Sorry it was not. I removed them 🙏

[kwkbtr]

Resource Estimation with qsub (CNOT) section

No text description is in this section. I think it's better to add some description on what this section is about. (You can refer the main tutorial of qsub)

[Kazutaka333]

added short description and link to main qsub tutorial 🫶

[kwkbtr]

Temporary setup instructions for quri-parts-qret and quration-cli-bundle

I think this part should be updated (or removed).

[Kazutaka333]

I've removed pip install for qret and temporary branch, and left quration-cli-bundle install instruction

[kwkbtr]

Defining the Topology

Terms used in the table (data logical qubit cell, ancilla cell, magic factory cell) and those in the diagram (M = magic factory, Q = qubit, . = bus.routing cell) are different, which is a bit confusing.

[Kazutaka333]

fixed them 🙆‍♂️

[kwkbtr]

The term IR is used several times but there is no definition of it.

[Kazutaka333]

I've add the explanation of IR at section: Compilation to Surface Code / Lattice Surgery Architecture

[kwkbtr]

"Why it matters" column of key metrics tables: I feel many of them don't add information meaningful to users, so I suggest removing the column. Some useful information there can be merged to "Meaning" column (which I suggest renaming to e.g. "Description").

[Kazutaka333]

removed "Why it matters" column and keep description concise

[kwkbtr]

The T-gate count is a lower bound on the number of magic states consumed, but the two may not match depending on the Toffoli decomposition method and the use_magic_state_cultivation setting.

Is this true (or appropriate)? I think the Toffoli decomposition is handled at the logical circuit level and when you mention T gate count the decomposition is already taken into account.

[Kazutaka333]

removed the explanation

[kwkbtr]

These are classical feedback operations to correct byproducts (Pauli errors) that arise during logical gate implementation via lattice surgery. ... Measurement feedback is constrained by classical control system latency (reaction_time) and therefore directly affects runtime.

I don't think this is incorrect but my understanding is the reaction time only affects (logical) non-Clifford operations (which involves lattice surgery operations in the gate teleportation process), not all logical gate operations via lattice surgery.

Note that syndrome measurements (stabilizer measurements for error correction) are not counted here — qret already accounts for them as a fixed one-code-cycle overhead.

This seems somewhat misleading as well. Error correction with stabilizer measurements doesn't need active feedback since it can be classically handled with Pauli frame (as mentioned in the earlier section).

[Kazutaka333]

I've removed those explanation

[yasuo-ozu]

Is the quri-parts-qret installation from internal:quri-parts-qret-temp still required?

[yasuo-ozu]

use pathlib.Path(__file__).parent to reference "cnot/cnot_ir.json", "cnot/topology_for_cnot.yaml", etc. to keep the functionality independent of CWD.

[yasuo-ozu]

Both notebooks say "auto-generated topology files may have room for optimization" but never say when or how a user would know to change it. Even one example (e.g., "if T-gate count is high relative to qubit count, increase magic_factory_count") would be actionable.

[yasuo-ozu]

I cannot found referenced file cnot/cnot_pipeline.yaml in basic.ipynb

[Kazutaka333]

@yasuo-ozu

Is the quri-parts-qret installation from internal:quri-parts-qret-temp still required?

I removed it 🙆‍♂️

use pathlib.Path(file).parent to reference "cnot/cnot_ir.json", "cnot/topology_for_cnot.yaml", etc. to keep the functionality independent of CWD.

I guess a visitor to docusaurus website won't be able to run the code anyway? is your concern for CI?

Both notebooks say "auto-generated topology files may have room for optimization" but never say when or how a user would know to change it. Even one example (e.g., "if T-gate count is high relative to qubit count, increase magic_factory_count") would be actionable.

added "E.g.) Carefully placed magic factory can shorten the delivery of T gate to each qubit."

I cannot found referenced file cnot/cnot_pipeline.yaml in basic.ipynb

I added cnot_pipeline.yaml and toplogy_for_cnot.yaml