feat: Add a with_loop method to Program
#1717
Conversation
☂️ Python Coverage
Overall Coverage
New FilesNo new covered files... Modified Files
|
|
Haven't looked over it in detail, but one thought I had immediately was: the time seems ripe to get away from the "numshots" nomenclature, and instead use the generic "loop". |
There was a problem hiding this comment.
Code-wise, looks good.
I don't think I'm a fan of the UX, however. Having to do both p.wrap_in_numshots_loop() and p.apply_numshots_loop() feels awkward/unintuitive to me.
What about calling the new method with_loop(iterations, mem_ref, start_label, end_label)?
docs/source/programs_and_gates.rst
Outdated
| # labels to mark the beginning and end of the loop. | ||
| looped_program = p.apply_numshots_loop(shot_count, Label("start-loop"), Label("end-loop")) | ||
| print(looped_program.out()) | ||
| print(looped_program.num_shots) |
There was a problem hiding this comment.
I think it would also be useful to extend the example to include execution (i.e. that the memory reference has to be provided a value in qc.run or whatever).
Co-authored-by: Mark Skilbeck <mark.skilbeck@rigetti.com>
|
@notmgsk I hear you there, that's essentially how the API is implemented for In the context of pyQuil, |
I like this. It's a good point - so long as Further, letting both methods "start from scratch" rather than working in series does match the reality that there can be two loops: one in metadata as
I also agree with this. |
MarquessV
changed the title
apply_numshots_loop method to Programwith_loop method to Program
pyquil/quil.py
Outdated
| Return a copy of the ``Program`` wrapped in a Quil loop that will execute ``num_iterations`` times. | ||
|
|
||
| This loop is implemented with Quil and should not be confused with the ``num_shots`` property set by | ||
| :py:meth:`~pyquil.quil.Program.wrap_in_numshots_loop`. The latter is metadata on the program that | ||
| can tell an executor how many times to run the program. In comparison, this method adds Quil | ||
| instructions to your program to specify a loop in the Quil program itself. | ||
|
|
||
| The loop is constructed by wrapping the body of the program in classical Quil instructions. | ||
| The given ``iteration_count_reference`` must refer to an INTEGER memory region. The value at the | ||
| reference given will be set to ``num_iterations`` and decremented in the loop. The loop will | ||
| terminate when the reference reaches 0. For this reason your program should not itself | ||
| modify the value at the reference unless you intend to modify the remaining number of | ||
| iterations (i.e. to break the loop). | ||
|
|
||
| The given ``start_label`` and ``end_label`` will be used as the entry and exit points for | ||
| the loop, respectively. You should provide unique ``JumpTarget``\\s that won't be used elsewhere | ||
| in the program. | ||
|
|
||
| If ``num_iterations`` is 1, then a copy of the program is returned without any changes. Raises a | ||
| ``TypeError`` if ``num_iterations`` is negative. | ||
|
|
||
| :param loop_count_reference: The memory reference to use as the loop counter. | ||
| :param start_label: The ``JumpTarget`` to use at the start of the loop. | ||
| :param end_label: The ``JumpTarget`` to use to at the end of the loop. |
MarquessV
deleted the
1712-utility-apply-num-shots-loop-directly-to-program-quil
branch
Description
Closes #1712
Checklist
masterbranch