caleb-johnson / quantum-serverless

A programming model for leveraging quantum and classical resources

Quantum serverless

Quantum Serverless is a user-friendly tool that enables you to easily run complex quantum computing tasks. With this software, you can execute Qiskit programs as long running jobs and distribute them across multiple CPUs, GPUs, and QPUs. This means you can take on more complex quantum-classical programs and run them with ease. You don't have to worry about configuration or scaling up computational resources, as Quantum Serverless takes care of everything for you.

Table of Contents

1. Quickstart
2. Modules
   1. Client
   2. Gateway
   3. Charts
3. How to Give Feedback
4. Contribution Guidelines
5. Deprecation Policy
6. References and Acknowledgements
7. License

---

Quickstart

This Quickstart section guides users to easily deploy QuantumServerless infrastructure and run a simple example. For user convenience, this section assumes that users will deploy the infrastructure in a local environment using Docker and test examples within the deployed Jupyter notebook.

1. Prepare local QuantumServerless infrastructure

   1. Install Docker If Docker is not installed on your system, follow the directions on the Docker website to install Docker on your system.

   2. Install quantum-serverless on your local system (we recommend using a virtual environment).

      pip install quantum-serverless

      Optional: install Jupyter Lab

      pip install jupyterlab

   3. Clone the Quantum Serverless repository

      git clone https://github.com/Qiskit-Extensions/quantum-serverless.git

   4. Run QuantumServerless infrastructure Execute Docker Compose using the following commands.

      cd quantum-serverless/
      sudo docker compose up

      The output should resemble the following.

      ~/quantum-serverless$ sudo docker compose --profile jupyter up
      [+] Running 5/0
       ✔ Network public-quantum-serverless_safe-tier     Created                                           0.0s
       ✔ Container ray-head                              Created                                           0.0s
       ✔ Container public-quantum-serverless-postgres-1  Created                                           0.0s
       ✔ Container gateway                               Created                                           0.0s
       ✔ Container scheduler                             Created                                           0.0s
      Attaching to gateway, public-quantum-serverless-postgres-1, qs-jupyter, ray-head, scheduler
      

2. Launch JupyterLab environment.

   cd docs/getting_started/ # the directory with sample notebooks
   jupyter lab

   This will open the Jupyter Lab environment in your web browser.

3. Write your first example Qiskit Pattern. In the JupyterLab, create a new file, pattern.py, in the work directory. You can include any arbitrary Python code in your program, or you can use the example Python file in this tutorial.

4. Run the program In the JupyterLab, create a new notebook in the same directory as your program, and execute the tutorial code.

   You can check the job status and get the result.

   job.status()
   # 'DONE'
   
   job.logs()
   # 2023-09-21 03:48:40,286\tINFO worker.py:1329 -- Using address 172.18.0.4:6379 set in the environment variable RAY_ADDRESS\n2023-09-21 03:48:40,286\tINFO worker.py:1458 -- Connecting to existing Ray cluster at address: 172.18.0.4:6379...\n2023-09-21 03:48:40,295\tINFO worker.py:1633 -- Connected to Ray cluster. View the dashboard at \x1b[1m\x1b[32m172.18.0.4:8265 \x1b[39m\x1b[22m\n
   

   job.status()
   # '{"quasi_dists": [{"1": 0.5071335183298108, "5": 0.4334908044837378, "7": 0.0593756771864515}, {"1": 0.9161860602334094, "5": 0.0838139397665906}, {"2": 0.4999999999999999, "3": 0.4999999999999999}]}'
   

   That's all!

For more detailed examples and explanations refer to the Guide:

1. Getting Started
2. Example Qiskit Patterns
3. Infrastructure
4. Migrating from Qiskit Runtime programs

---

How to Give Feedback

We encourage your feedback! You can share your thoughts with us by:

• Opening an issue in the repository

---

Contribution Guidelines

For information on how to contribute to this project, please take a look at our contribution guidelines.

---

Deprecation Policy

This project is meant to evolve rapidly and, as such, do not follow Qiskit's deprecation policy. We may occasionally make breaking changes in order to improve the user experience. When possible, we will keep old interfaces and mark them as deprecated, as long as they can co-exist with the new ones. Each substantial improvement, breaking change, or deprecation will be documented in release notes.

---

References and Acknowledgements

[1] Qiskit
https://github.com/Qiskit/qiskit

[2] Client for IBM Qiskit Runtime
https://github.com/Qiskit/qiskit-ibm-runtime

---

License

Apache License 2.0