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 QVM_URL
and QUILC_URL
environment variables)
to override configuration, see pyQuil Configuration.
Authentication¶
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 QuantumComputer
, QAM
, QPU
, and 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_memory
is no longer a method onQAM
but rather onProgram
andEncryptedProgram
.qc.run()
no longer accepts amemory_map
argument. All memory values must be set directly on theProgram
orEncryptedProgram
usingwrite_memory
.QAM.load()
,QAM.wait()
, andQAM.reset()
no longer exist, because theQAM
no 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]
Additionally, QuantumComputer.run()
and QAM.run()
now both return QAMExecutionResult
, rather
than the bitstrings which were read out following execution. So, to retrieve the bitstrings from region ro
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
QAMExecutionResult.readout_data
.
The notable exception to this is PyQVM
, which remains stateful, and whose memory you can still inspect using
PyQVM.read_memory()
.
Compatibility Utilities¶
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.