The Qunicorn Core - Unification Middleware for a sovereign Quantum Cloud

This package uses Poetry (documentation).

VSCode

For vscode install the python extension and add the poetry venv path to the folders the python extension searches for venvs.

On linux:

{
  "python.venvFolders": [
    "~/.cache/pypoetry/virtualenvs"
  ]
}

Development

Run poetry install to install dependencies.

Environment variables

The flask dev server loads environment variables from .flaskenv and .env. To override any variable create a .env file. Environment variables in .env take precedence over .flaskenv. See the content of the .flaskenv file for the default environment variables.

You can also add an IBM_TOKEN to the .env file to use the IBM backend without a token in each request. Set the EXECUTE_CELERY_TASK_ASYNCHRONOUS in your .env file to False, if you don't want to start a celery worker and execute all tasks synchronously. Set the ENABLE_EXPERIMENTAL_FEATURES in your .env file to True, if you want to use experimental features like the qasm to quil transpilation, and IBM File_Runner and File_Upload job types.

Available endpoints are:

• JOBS

  • GET /jobs/ (Get all jobs)
  • POST /jobs/ (Create/Register and run new job)
    • Needs a valid token to connect to IBM, local simulations from AWS or Rigetti work without a token
    • Runs asynchronously so the results are not shown in the api response
  • GET /jobs/{job_id}/ (Get details/results of a job)
  • DELETE /jobs/{job_id}/ (Delete a job and return Deleted Job Details)
  • POST /jobs/run/{job_id}/ (Executes an uploaded python file)
  • POST /jobs/rerun/{job_id}/ (Copies and Runs again an existing Job)
  • POST /jobs/cancel/{job_id}/ (Cancel a job that has be started)
  • GET /jobs/queue/ (Get all queued and currently running jobs)

• DEVICES

  • GET /devices/ (Get all currently saved devices)
  • POST /devices/ (Updates the device list from the provider)
  • GET /devices/{device_id}/ (Get details about one device)
  • POST /devices/{device_id}/status (To check if a device is available)
  • POST /devices/{device_id}/calibration (To get device properties for configuration)

• DEPLOYMENTS

  • GET /deployments/ (Get all Deployments)
  • POST /deployments/ (Create a Deployment)
  • GET /deployments/{deployment_id}/ (Get a Deployment by ID)
  • PUT /deployments/{deployment_id}/ (Update a Deployment)
  • DELETE /deployments/{deployment_id}/ (Deletes a Deployment)
  • GET /deployments/{deployment_id}/jobs (Get the details of all jobs with a specific deployment id)
  • DELETE /deployments/{deployment_id}/jobs (Delete all jobs with a specific deployment id)

• PROVIDER

  • GET /provider/ (Get all providers from the database)
  • GET /provider/{provider_id}/ (Get details of a provider)

Run manually

Run the development server with

poetry run flask run

Start Docker, init the celery worker and then start it

poetry run invoke start-broker
poetry run invoke worker

Create the initial database (If this doesn't work, try to delete the db-file from the "instance" folder)

flask recreate-and-load-db

Check Linting Errors

poetry run invoke check-linting

Trying out the tests -> See tests/README.md

poetry run pytest .

Run using docker-compose

Execute the following command the deployment will be started using docker-compose. This will build the dockerimage containing the application and creates all required containers including the database and the message queue.

Note that you might need to authorize with an Access Token in order to access the qunicorn package on GitHub. In this Case the following steps need to be performed.

1. Create a personal access token on Github (Account --> Settings --> Developer Settings --> Personal acces tokens)
2. Execute:

   echo PUT_PERSONAL_ACCESS_TOKEN_HERE | docker login ghcr.io -u USERNAME --password-stdin

Start the docker-compose:

docker-compose up -d

For testing with a local build use:

docker-compose -f docker-compose.yaml -f docker-compose.local.yaml up -d

Trying out the Template

For a list of all dependencies with their license open http://localhost:5005/licenses/. The Port for qunicorn_core is set to 5005 to not interfere with other flask default apps. Settings can be changed in the .flaskenv.

The API:

http://localhost:5005/

OpenAPI Documentation:

Configured in qunicorn_core/util/config/smorest_config.py.

• Redoc (view only): http://localhost:5005/redoc
• Rapidoc: http://localhost:5005/rapidoc
• Swagger-UI: http://localhost:5005/swagger-ui
• OpenAPI Spec (JSON): http://localhost:5005/api-spec.json

Authentication:

The authentication is done with Keycloak. All endpoints are available for everybody but jobs created by a user with a token can only be seen by the user himself. To authenticate yourself have a look at the following read the docs chapter: ArchitectureDocumentation/Authentication.

Debug pages:

• Index: http://localhost:5005/debug/
• Registered Routes: http://localhost:5005/debug/routes\ Useful for looking up which endpoint is served under a route or what routes are available.

Remarks

For more detailed information about additional commands see the readme.md in docs.

Disclaimer of Warranty

Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.

Haftungsausschluss

Dies ist ein Forschungsprototyp. Die Haftung für entgangenen Gewinn, Produktionsausfall, Betriebsunterbrechung, entgangene Nutzungen, Verlust von Daten und Informationen, Finanzierungsaufwendungen sowie sonstige Vermögens- und Folgeschäden ist, außer in Fällen von grober Fahrlässigkeit, Vorsatz und Personenschäden, ausgeschlossen.

Acknowledgements

The initial code contribution has been supported by the project SeQuenC.