Proposal: Organization of examples, useful circuit libraries, zoo.

[dabacon]

i propose that we create another top level package "cirqlib" (parallel to cirq). Within this we would have different subpackages:

examples: these should be explicit examples of features of Cirq algorithms; these should be implementations of algorithms, not just showing off features.
circuits: modules that implement useful circuit modules, i.e. these are methods that generate circuits in a reusable module tutorials: in contrast to examples, these are part of self contained tutorials and are mostly jupyter notebooks.

By using another top level namespace, we maintain the separation with cirqlib (cirq should never depend on cirqlib). This also tries to organize the different types of contributions that people would like to make. I'd be tempted to keep cirqlib in the cirq wheel. If we wanted to however, we could break it out into a different wheel which might be useful if we want to keep the cirq core dependencies as low as possible.

[dabacon]

@Strilanc thoughts?

[dabacon]

Oh I'd also add experiments: in contrast to algorithms these are explicitly for extracting physics type information about the device (tomography, randomized benchmarking, etc)

[Strilanc]

I think all of this content belongs inside of cirq, particularly the experiments. We should be very wary of creating artificial fragmentation.

Imaginary conversation:

A: Oh yeah, that example is in cirq lib B: But I installed the cirq library; I couldn't find what you were talking about? A: No, not cirq the library, just cirqlib. It's a library about using cirq. B: I... what? Am I installing cirq or not. A: cirq and cirqlib are different. Cirq is a library about quantum circuits. Cirqlib is a library about a library about quantum circuits. It's very meta. B: Oh I get it now. B: By the by, what's the wifi password? A: It's four words all upper case but one word all lower case.

[dabacon]

I think by this reasoning you'd package all pythons programs with python?

[dabacon]

Is your objection that it is under a different package, or a different wheel?

[vtomole]

My 2 cents; cirqlib shouldn't be a top-level package unless we want to break it off into it's own repo. As @Strilanc said, that might annoyingly fragment things for users and us. It will be frustrating to have something like

import cirq
import cirqlib

on most user programs.

from cirq import cirqlib

or

import cirq
cirq.cirqlib.experiments e.t.c

look better. Maybe call it lib instead of cirqlib?

[Strilanc]

I think the individual components you mentioned are all good to have, I just don't think it makes sense to group those components away from the others. Why are experiments part of "cirq lib" instead of "cirq non-lib"?

[verult]

@dabacon Are you thinking of limiting algorithms and circuits directories to NISQ only? Where should non-NISQ algorithms land?

[vtomole]

@verult Cirq is for NISQ circuits/algorithms. In my opinion, I don't think non-NISQ circuits/algorithms should land in the main repository because that's not how we're presenting ourselves. The paper you linked to in https://github.com/quantumlib/Cirq/issues/996 implements HHL on IBM hardware; which are NISQ devices. Maybe we can implement non-NISQ-y algorithms/circuits on Cirq's noisy simulator? @Strilanc

[vtomole]

@dabacon Regarding tutorials, what do you think about putting the Jupyter notebooks in examples/tutorials?

[Strilanc]

I would put tutorials it at the top level. I would also consider calling it notebooks or jupyter_notebooks or tutorial_notebooks.

[vtomole]

Sure. You said that you'll keep an eye out when adding to top level: https://github.com/quantumlib/Cirq/issues/748.

[dabacon]

@karlunho this was some old discussion of organizing examples, tutorials, etc.

I think this conversation is now obsolete by new efforts to sort this out. Closing.