In this tutorial, you configure and test a virtual machine (VM) to run GPU-based quantum simulations on Google Cloud.
1. Create a virtual machine
Follow the instructions in the Quickstart using a Linux VM guide to create a VM. In addition to the guidance specified in the Create a Linux VM instance section, ensure that your VM has the following properties:
- In the Machine Configuration section:
- Select the tab for the GPU machine family.
- In the GPU type option, choose NVIDIA Tesla A100.
- In the Number of GPUs option, choose 1.
- In the Boot disk section, click the Change button:
- In the Operating System option, choose Ubuntu.
- In the Version option, choose 20.04 LTS.
- In the Size field, enter 30 (minimum).
- The instructions above override steps 3 through 5 in the Create a Linux VM instance Quickstart.
- In the Firewall section, ensure that both the Allow HTTP traffic checkbox and the Allow HTTPS traffic checkboxs are selected.
When Google Cloud finishes creating the VM, you can see your VM listed in the Compute Instances dashboard for your project.
Find out more
- Choosing hardware for your qsim simulation
- Choosing the right machine family and type
- Creating a VM with attached GPUs
2. Prepare your computer
Use SSH in the glcoud
tool to communicate with your VM.
- Install the
gcloud
command line tool. Follow the instructions in the Installing Cloud SDK documentation. - After installation, run the
gcloud init
command to initialize the Google Cloud environment. You need to provide thegcloud
tool with details about your VM, such as the project name and the region where your VM is located.- You can verify your environment by using the
gcloud config list
command.
- You can verify your environment by using the
Connect to your VM by using SSH. Replace
[YOUR_INSTANCE_NAME]
with the name of your VM.gcloud compute ssh [YOUR_INSTANCE_NAME]
When the command completes successfully, your prompt changes from your local machine to your virtual machine.
3. Enable your virtual machine to use the GPU
- Install the GPU driver. Complete the steps provided in the following
sections of the Installing GPU
drivers:
guide:
- Examples, under the Ubuntu tab. For step 3, only perform the steps for Ubuntu 20.04 (steps 3a through 3f).
- Verifying the GPU driver install
Install the CUDA toolkit.
sudo apt install -y nvidia-cuda-toolkit
Add your CUDA toolkit to the environment search path.
Discover the directory of the CUDA toolkit that you installed.
ls /usr/local
The toolkit is the highest number that looks like the pattern
cuda-XX.Y
. The output of the command should resemble the following:bin cuda cuda-11 cuda-11.4 etc games include lib man sbin share src
In this case, the directory is
cuda-11.4
.Add the CUDA toolkit path to your environment. You can run the following command to append the path to your
~/.bashrc
file. Replace[DIR]
with the CUDA directory that you discovered in the previous step.echo "export PATH=/usr/local/[DIR]/bin${PATH:+:${PATH} }" >> ~/.bashrc
Run
source ~/.bashrc
to activate the new environment search path
4. Install build tools
Install the tools required to build qsim. This step might take a few minutes to complete.
sudo apt install cmake && sudo apt install pip && pip install pybind11
5. Create a GPU-enabled version of qsim
Clone the qsim repository.
git clone https://github.com/quantumlib/qsim.git
Run
cd qsim
to change your working directory to qsim.Run
make
to compile qsim. When make detects the CUDA toolkit during compilation, make builds the GPU version of qsim automatically.Run
pip install .
to install your local version of qsimcirq.Verify your qsim installation.
python3 -c "import qsimcirq; print(qsimcirq.qsim_gpu)"
If the installation completed successfully, the output from the command should resemble the following:
<module 'qsimcirq.qsim_cuda' from '/home/user_org_com/qsim/qsimcirq/qsim_cuda.cpython-38-x86_64-linux-gnu.so'>
6. Verify your installation
You can use the following code to verify that qsim uses your GPU. You can paste the code directly into the REPL, or paste the code in a file.
# Import Cirq and qsim
import cirq
import qsimcirq
# Instantiate qubits and create a circuit
q0, q1 = cirq.LineQubit.range(2)
circuit = cirq.Circuit(cirq.H(q0), cirq.CX(q0, q1))
# Instantiate a simulator that uses the GPU
gpu_options = qsimcirq.QSimOptions(use_gpu=True)
qsim_simulator = qsimcirq.QSimSimulator(qsim_options=gpu_options)
# Run the simulation
print("Running simulation for the following circuit:")
print(circuit)
qsim_results = qsim_simulator.compute_amplitudes(
circuit, bitstrings=[0b00, 0b01])
print("qsim results:")
print(qsim_results)
After a moment, you should see a result that looks similar to the following.
[(0.7071067690849304+0j), 0j]
Optional: Use the NVIDIA cuQuantum SDK
If you have the NVIDIA cuQuantum SDK
installed (instructions are provided
here,
cuStateVec v1.0.0 or higher is required),
you can use it with this tutorial. Before building qsim in step 5,
set the CUQUANTUM_DIR
environment variable from the command line:
export CUQUANTUM_DIR=[PATH_TO_CUQUANTUM_SDK]
Once you have built qsim, modify the gpu_options
line like so:
gpu_options = qsimcirq.QSimOptions(use_gpu=True, gpu_mode=1)
This instructs qsim to make use of its cuQuantum integration, which provides improved performance on NVIDIA GPUs. If you experience issues with this option, please file an issue on the qsim repository.
Next steps
After you finish, don't forget to stop or delete your VM on the Compute Instances dashboard to prevent further billing.
You are now ready to run your own large simulations on Google Cloud. For sample code of a large circuit, see the Simulate a large circuit tutorial.