[surface code] DataBlock refactor

[mpharrigan]

This is the first part of polishing the API for surface code physical cost estimation. This PR deals with the data blocks. Changes:

• Disentangle the DataBlock class hierarchy. There is now one abstract base class and four implementations.
• Document!
• The simple data block can process an unbounded number of magic states (since it assumes you don't push out all cliffords and that the computation is bounded by the time it takes to produce the magic states).

Some shims are present to enable further refactoring:

• Grouping QECScheme and phys_err into a little callable LogicalErrorModel.
• Shims to support removing MagicCount in favor of qualtran.resource_counting.GateCounts.

[NoureldinYosri]

nice 👍

[NoureldinYosri]

logi?

[mpharrigan]

"logical" :D

naming things is hard, and -- in this module in particular -- there's a balance between ambiguity and readability. I'd like to use consistent, unambiguous names throughout. That means the variable names could get quite long if we don't abbreviate; so I'd like to abbreviate

• num_physical_qubits -> n_phys_qubits
• num_logical_gates -> n_logi_gates

Also the MagicCount type annotation will change to GateCounts from qualtran.resource_counting which will make the variable name make more sense

[NoureldinYosri]

naming things is hard, and -- in this module in particular -- there's a balance between ambiguity and readability

you are the native english speaker in this conversation so I will let this to your judgement

---

Also the MagicCount type annotation will change to GateCounts

wouldn't that be confusing? since GateCounts could imply all gates including say cliffords?!

[mpharrigan]

this is an abstract interface, so yes -- it should generally be able to depend on the gate counts. If the implementation doesn't care about clifford counts it can ignore them. You can imagine a data block being able to do only a certain number of cliffords per cycle

[tanujkhattar]

abbreviating logical -> logi seems very awkward to me as well. I'd have a preference towards using IDE to manage the longer names but avoid non-standard abbreviations, especially for logical -> logi.

Abbreviating by deleting letters of a word is also generally discouraged by the google style guide. Please consider using the full word for logical

[mpharrigan]

I mean "phys" and "prob" and "err" are already used everywhere

[mpharrigan]

I've updated all the things within the scope of this PR to use full names

[NoureldinYosri]

"zero"

I don't think this is true ... the CCZ2T doesn't talk about this and focuses on routing and distillation as the dominant factors but it also prefly mentions the work needed to teleport the CCZ magic state without specifying how long it takes in page 11

[mpharrigan]

The distinction is if you have e.g. 50 factories in a litinski data block you're limited by the number of t states you can consume. If you're using a gidney model, you are not. They pay heed to the time it takes to transport the magic state, yes, but assume that that can be intelligently routed and parallelized so the magic state throughput (not time/latency) is unbounded.

With these models, there isn't "right" or "wrong" but rather fidelity to the original model, and I think in this case assuming unbounded t state consumption is closer to the original model than the restrictive 1-state-per-step. The gidney spreadsheet (in the supplementary materials) doesn't ever consider the data block being the time-limiting factor

[NoureldinYosri]

they way I have reconcilled these is by taking the max between generation and consumption cycles ... but I'm okay with saying it is zero for now

[mpharrigan]

the "identity value" for max is 0. The prior behavior, if you just want the generation cycle because you're doing gidney form the max might still choose the consumption as the limiting factor