Guides

  • Copying local files to your QMI
    If you've developed a program on your local computer, you can move this file to your QMI for execution in the quantum environment by using SCP (secure copy protocol), or through a third-party client for FTP (file transfer protocol).
    • SCP
      Open up a terminal and:
      scp -r /path/to/directory forest@qmi:/home/forest
      scp /path/to/file forest@qmi:/home/forest
    • Third-party FTP 
      We recommend using a third-party FTP client such as FileZilla or Cyberduck for transferring and managing files on your QMI.

  • Editing QMI files locally
    To easily edit a file that is stored on your QMI, we recommend the following third-party tools:
    • PyCharm 
      Python IDE which you can use to create a remote server on your QMI using the following guide
    • Sublime Text
      1. Install the SFTP Package
      a. Open command palette: ctrl+shift+p (Win, Linux) or cmd+shift+p (Mac)
      b. Select "Package Control: Install package" (by typing install and pressing enter)
      c. Type SFTP and hit enter

      2. Set up the server
      a. Go to File > SFTP > Setup Server
      b. "remote_path" : "/home/forest/"
      c. "host" : "<YOUR_QMI_IP_ADDRESS>"
      d. "user" : "forest"

      3. Browse one file at a time
      a. File > SFTP > Browse Server

      4. Work on a single folder locally, and upload all changes to your QMI upon saving any file in the folder— recommended
      a. In your QMI, use mkdir <folder_name> to create a new folder to sync your files to
      b. In Sublime Text, on your local machine, open the folder you would like to sync
      c. Right click on the folder name in the side bar (View > Side Bar > Hide Side Bar)
      d. Select SFTP/FTP > Map to Remote. This will open up a file called sftp-config.json in your folder.
      e. Set upload_on_save to true
      f. Change host and user as in section 2 above for setting up a server
      g. Set the remote path to the name of the directory you created in your QMI. This must be a full path, such as /home/forest/my_work/
      h. Right click on the folder name again. Go to SFTP/FTP > Upload Folder to move all your local files to your QMI.
    • Emacs
      1. Read about TRAMP (built-in), which allows your local Emacs to interface with one or more remote machines. You won't need to copy your configuration to QMI, nor be relegated to running Emacs in terminal mode.
      2. Navigate to /ssh:forest@<YOUR_QMI_IP_ADDRESS>:/home/forest/hello_qmi.py to test your TRAMP configuration. Ensure the key you registered with the QMI is added to your ssh agent
      3. Notice that your usual modes and configuration are still active, even though you are editing a buffer for a remote file. When you save the buffer, TRAMP ensures the file is updated on the QMI.
      4. Many Emacs tools like shells, bookmarks, file explorers, project management, Docker interfaces, and Git clients have automatic TRAMP support. These enable advanced navigation and manipulation of projects on the QMI, and obviate running terminal commands over SSH for most use-cases.
  • Pulling from Github repositories
    1. Generate an ssh-key pair from your QMI, similar to the process used to authenticate your QMI connection.
    2. Add the public key you just generated to your Github account. Now you should have permission to pull your private and public Github repositories.
  • Queuing programs for auto-execution
    To queue a program to be automatically executed at the start time of your reservation, rather than manually initializing it, you can use the exec_on_engage.sh script (located in the root directory of your QMI).

    To view the contents of this script, enter the following command from your QMI:
    cat exec_on_engage.sh

    By default, this script will execute the example hello_qmi.py file, as mentioned previously, on the QVM simulator:
    python hello_qmi.py 9q-generic-qvm


    To customize this script to queue your own program, update the above line of code in your exec_on_engage.sh file and replace hello_qmi.py with the file name of your program. If you've reserved a QPU lattice, replace 9q-generic-qvm with the name of your lattice. 

  • Aliasing your QMI
    As a shortcut to connecting to your QMI, you can create an alias so that you can simply type ssh forest@<ALIAS> instead of copying the IP address of your QMI from your Dashboard each time. 

    On your local machine:

    sudo vim /etc/hosts

     
    Next, add the following line: qmi <YOUR_QMI_IP_ADDRESS>
    You can replace qmi with whichever alias you prefer.

  • Launching a virtual environment
    As a best practice, we recommend using virtual environments on your QMI to help isolate your python projects from potentially conflicting with each other. Your QMI comes pre-installed with both conda and virtualenv

    To launch conda, type the following command in your terminal (when connected to your QMI):

    conda activate


    Alternatively, to launch virtualenv:

    source ~/.virtualenvs/venv/bin/activate


    If you would like to launch a virtual environment automatically every time you connect to your QMI, then you can edit the ~./bashrc file in your QMI and add either of the above commands to your script.

  • Getting started with ForestTM SDK
    In your QMI, launch a python shell. You may use either conda or virtualenv. 

    To get started using conda:

    conda activate
    ipython
    import pyquil


    To get started using virtualenv:

    source ./virtualenvs/venv/bin/activate
    ipython
    import pyquil


    Reference the ForestTM SDK docs to learn more. 

  • Setting up a Jupyter Notebook on your QMI
    1. Install Jupyter Notebook on your QMI:

    tmux new -s <session-name>
    source .virtualenvs/venv/bin/activate
    pip install jupyter
    cd <YOUR_DIRECTORY_FOR_YOUR_NOTEBOOK>
    jupyter notebook


    2. Copy the token printed to the console by the notebook server:

    http://localhost:8888/?token=<TOKEN>


    3. Locally:

    ssh -N -L 8889:localhost:8888 forest@<YOUR_QMI_IP_ADDRESS>


    4. Open a web browser on your computer and go to http://localhost:8889

    5. Submit the token from the Jupyter Notebook server on the QMI to log in

    6. If you experience any issues while running on the QPU, your configuration variables may have updated — simply restart your notebook kernel and try again.