Clearly distinguish the different meanings of "parametric"

[karalekas]

The word "parametric" is overloaded in our documentation, and causes confusion. Here are the three different things it means (as far as I am aware):

1. There are two types of standard quantum gates. Ones that have no parameters (e.g. H) and ones that do (e.g. RX(θ)). The latter are referred to as "parametric gates" in the documentation. For clarity, I think they should instead be called "standard parameterized gates".
2. Users can additionally define custom gates (via DEFGATE), which may or may not have parameters. There is a section "Defining Parametric Gates" that talks about this functionality, and it is on the same page as the section about "Parametric Compilation" (see point 3) which has a vastly different purpose. This section should maybe just be about defining custom gates, making it clear that they can have parameters or not (or we could just call them "custom parameterized gates"). I'd argue that defining gates should be on a completely different page from standard programs and gates.
3. We have memory references that can be declared (e.g. DECLARE ro BIT) and then passed as arguments to the "standard parameterized gates" from point 1. Users can then leverage a feature called "Parametric Compilation", which is a critical component of Quantum Cloud Services, our hybrid quantum cloud platform. This feature lets users compile programs once and run them many times for different parameter values, which allows for very fast execution of variational hybrid algorithms like VQE and QAOA.

This is undoubtedly confusing and could use some work.

References:

• https://pyquil.readthedocs.io/en/stable/basics.html#parametric-compilation
• https://pyquil.readthedocs.io/en/stable/basics.html#defining-parametric-gates

P.S. In 2018 we published a paper about our "parametrically"-activated CZ gate, which is itself not a parameterized gate (although it is a special case of the parameterized gate CPHASE). 😛

[jlapeyre]

Do you mean to say something like DECLARE theta REAL[1] rather than DECLARE ro BIT ?

[karalekas]

@jlapeyre either counts as a declared memory reference, but you are right that we typically think of something like DECLARE theta REAL as an argument to parameterized gates rather than DECLARE ro BIT