Migrating from pyQuil v2 to v3¶
To begin migrating your pyQuil v2 code, we recommend first reading the Changelog and making adjustments according to the code affected. Most users should only need to make minimal changes.
If you’ve supplied
PyquilConfig objects to functions (or used the
QUILC_URL environment variables)
to override configuration, see pyQuil Configuration.
pyQuil v3 relies on an updated authentication model. To get started, install the new QCS CLI and log in with it before using pyQuil v3 with QCS and live QPUs.
Parameters & Memory¶
In order to give the user more control over and visibility into program execution, especially in
parallel, objects such as
QVM are no longer stateful
with respect to individual programs. These objects are now safe to
share among different threads, so you can execute and retrieve results in parallel for even better
performance. (See Advanced Usage for more information).
However, this required three small but important changes:
write_memoryis no longer a method on
QAMbut rather on
qc.run()no longer accepts a
memory_mapargument. All memory values must be set directly on the
QAM.reset()no longer exist, because the
QAMno longer “stores” program state.
This means that you should now execute your programs using one of these options:
qc = get_qc("Aspen-X") program = Program() theta = program.declare('theta', 'REAL') program += RZ(theta, 0) exe = qc.compile(program) # Previously, we would have called ``qc.qam.write_memory`` instead exe.write_memory(region_name='theta', value=np.pi) # Option 1 result = qc.run(exe) # Option 2 result = qc.qam.run(exe) # Option 3 job = qc.qam.execute(exe) result = qc.qam.get_result(job) # Run our program 10 times, enqueuing all the programs before retrieving results for any of them jobs = [qc.qam.execute(exe) for _ in range(10)] results = [qc.qam.get_result(job) for job in jobs]
QAM.run() now both return
than the bitstrings which were read out following execution. So, to retrieve the bitstrings from region
like you would have in pyQuil v2, query the readout data:
result = qc.run(exe) bitstrings = result.readout_data.get('ro')
Note that there is no “memory” in the result shape – yet. Readout data is inherently collected and returned
differently than memory values are, and that nuance is no longer masked in pyQuil v3. All of the results
that, in pyQuil v2, you would have expected to retrieve using
QAM.read_memory() are now present in
The notable exception to this is
PyQVM, which remains stateful, and whose memory you can still inspect using
We understand that the changes above regarding parameters might cause difficulty in migration, especially for large projects and lengthy scripts. So, to ease the migration path, we’ve added the following utility classes which allow you to upgrade your pyQuil projects without having to change any code.
from pyquil.compatibility.v2 import get_qc from pyquil.compatibility.v2.api import QuantumComputer, QAM, QVM, QPU
You can use these imported objects similarly how you use their counterparts in pyQuil v2. Once you’ve verified that your scripts still work with v3, we recommend that you gradually convert them to use the new versions of each object. This compatibility layer won’t see any new development, and without fully upgrading you’d miss out on all the new features to come in the future.