diff --git a/README.md b/README.md index 6732f67ef..867966085 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,10 @@ # 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. +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. ![diagram](./docs/images/qs_diagram.png) @@ -35,34 +35,44 @@ For user convenience, this section assumes that users will deploy the infrastruc 1. Prepare local QuantumServerless infrastructure 1. Install Docker If Docker is not installed on your system, follow the directions on the [Docker website](https://docs.docker.com/engine/install/) to install Docker on your system. + 1. Install quantum-serverless on your local system (we recommend using a [virtual environment](https://docs.python.org/3/library/venv.html)). + ```shell + pip install quantum-serverless + ``` + Optional: install [Jupyter Lab](https://jupyter.org/) + ```shell + pip install jupyterlab + ``` 1. Clone the Quantum Serverless repository ```shell git clone https://github.com/Qiskit-Extensions/quantum-serverless.git ``` 1. Run QuantumServerless infrastructure - Execute Docker Compose using the following commands. (Note: Make sure to stop any running Jupyter Notebook servers before proceeding.) + Execute Docker Compose using the following commands. ```shell cd quantum-serverless/ - sudo docker compose --profile jupyter up + sudo docker compose up ``` - + The output should resemble the following. ``` ~/quantum-serverless$ sudo docker compose --profile jupyter up - [+] Running 6/0 + [+] Running 5/0 ✔ Network public-quantum-serverless_safe-tier Created 0.0s ✔ Container ray-head Created 0.0s - ✔ Container qs-jupyter 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 ``` - Now you can access the deployed QuantumServerless infrastructure using the built-in JupyterLab. - -1. Access the JupyterLab environment - Open `localhost:8888` in your web browser. The default token for the JupyterLab is `123` + +1. Launch JupyterLab environment. + ```shell + cd docs/getting_started/ # the directory with sample notebooks + jupyter lab + ``` + This will open the Jupyter Lab environment in your web browser. 1. 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](https://github.com/Qiskit-Extensions/quantum-serverless/blob/main/docs/getting_started/basic/01_running_program.ipynb). @@ -75,7 +85,7 @@ For user convenience, this section assumes that users will deploy the infrastruc ``` 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 ``` @@ -85,7 +95,7 @@ For user convenience, this section assumes that users will deploy the infrastruc ``` That's all! - + For more detailed examples and explanations refer to the [Guide](https://qiskit-extensions.github.io/quantum-serverless/index.html): 1. [Getting Started](https://qiskit-extensions.github.io/quantum-serverless/getting_started/index.html#) diff --git a/docs/deployment/cloud.rst b/docs/deployment/cloud.rst index c79b62fd3..e00928d60 100644 --- a/docs/deployment/cloud.rst +++ b/docs/deployment/cloud.rst @@ -28,8 +28,6 @@ To deploy the infrastructure required for ``Quantum Serverless`` you need to hav Each of these tools' webpages contain instructions for installing on Windows, MacOS, and Linux. -* **Important**: before you download the above packages, check the `versions listed in our Github `_ of each tool to ensure that you download a compatible version. - Once you have these tools installed, you can check the installation by running the following commands in a terminal: .. code-block:: @@ -96,11 +94,10 @@ To connect with the different services, you have some options depending on your approach is to use the ``port-forward`` command: .. code-block:: - :caption: get gateway and jupyter pods + :caption: get gateway pod $ kubectl get service $ > ... - $ > jupyter ClusterIP 10.43.74.253 80/TCP $ > gateway ClusterIP 10.43.86.146 8000/TCP $ > ... @@ -110,14 +107,12 @@ Now that we have the desired services, we can expose their ports: :caption: ports 8265 and 8888 are the the default ports for each service $ kubectl port-forward service/gateway 3333:8000 - $ kubectl port-forward jupyter- 4444:80 Now you may access your cluster services from localhost. For development this is more than enough, but if you are considering deploying it remotely you will need to configure the various ``ingress`` properties in `values.yaml `_ -with the configuration of your domain and provider. In the ``Jupyter configs`` section you have a -configuration example to expose through ``ingress`` in ``localhost`` the Jupyter service (disabled by default). +with the configuration of your domain and provider. * **Important**: ``nginx-ingress-controller`` is disabled by default because third party providers should provide its own Ingress controller. To use it locally you need to activate it too. diff --git a/docs/deployment/local.rst b/docs/deployment/local.rst index d5a36dbaa..7881a9ceb 100644 --- a/docs/deployment/local.rst +++ b/docs/deployment/local.rst @@ -54,5 +54,5 @@ monitorying systems. Step 4: Run a program in the test environment Once the containers are running, you can simulate a remote cluster with the resources on your -local machine. To create and run programs in this simulated cluster, we recommend using [Jupyter Lab](https://jupyter.org/install). Refer to the :ref:`getting_started` guides +local machine. To create and run programs in this simulated cluster, we recommend using `Jupyter Lab `_. Refer to the :ref:`getting_started` guides for details about running your program remotely.