providers

Quandela

Quandela is Perceval default Cloud provider. If no session is created, Quandela Cloud endpoints will be used.

When using Quandela Cloud, you have the same capabilities with and without using a session. It’s a matter of code style.

class perceval.providers.quandela.quandela_session.Session(platform_name, token, url=None)

Quandela Cloud session

Parameters:

platform_name (str) – Name of an available platform on Quandela Cloud (e.g. “sim:slos”)
token (str) – A valid authentication token to use within the session
url (Optional[str]) – URL prefix for the endpoint to connect to. If omitted the Quandela Cloud endpoints will be used.

build_remote_processor()

Build a remote processor from the session information

Return type:: RemoteProcessor

Scaleway

Scaleway Quantum-as-a-Service provides access to allocate and program Quantum Processing Units (QPUs), physical or emulated.

Scaleway authentication

To use Scaleway QaaS as a provider you need a Scaleway account, a Scaleway Project ID and an API key.

ScalewaySession

class perceval.providers.scaleway.Session(platform_name, project_id, token, max_idle_duration_s=1200, max_duration_s=3600, deduplication_id=None, url=None, proxies=None, provider_name=None)

Scaleway session used to keep a connexion opened with Scaleway Cloud for the duration of a Python scope.

Parameters:

platform_name (str) – platform on which circuits will be executed
project_id (str) – UUID of the Scaleway Project the session is attached to
token (str) – authentication token required to access the Scaleway API
deduplication_id (Optional[str]) – optional value, name mapping to a unique running session, allowing to share an alive session among multiple users
max_idle_duration_s (int) – optional value, duration in seconds that can elapsed without activity before the session terminates
max_duration_s (int) – optional value, duration in seconds for a session before it automatically terminates
url (Optional[str]) – optional value, endpoint URL of the API
proxies (Optional[dict[str, str]]) – optional value, dictionary mapping protocol to the URL of the proxy

build_remote_processor()

Build a RemoteProcessor object given the session data

Return type:: RemoteProcessor

start()

Start session

Return type:: None

stop()

Stop session

Return type:: None

Allocate a QPU session

Let’s see step by step how to instantiate and use a Scaleway session.

Import the library and Scaleway from the providers library:

>>> import perceval as pcvl
>>> import perceval.providers.scaleway as scw

Provide your Scaleway Project ID and API key:

>>> PROJECT_ID = "your-scaleway-project-id"
>>> TOKEN = "your-scaleway-api-key"

Choose one of the Perceval compatible platforms provided by Scaleway:

>>> PLATFORM_NAME = "EMU-SAMPLING-L4" # For emulated QPU
>>> # PLATFORM_NAME = "QPU-BELENOS-12PQ" # For real QPU

You can now create a Scaleway session:

>>> session = scw.Session(platform_name=PLATFORM_NAME, project_id=PROJECT_ID, token=TOKEN)
>>> session.start()
>>> /*
...  * Session scope
...  */
>>> session.stop()

You can also create a Scaleway session using a with block:

>>> with scw.Session(platform_name=PLATFORM_NAME, project_id=PROJECT_ID, token=TOKEN) as session:
...     #
...     # Session scope
...     #

Note: using a with block you do not need to start and stop your session: it starts automatically at the beginning of the block and stops automatically at its end.

Note

while using a Jupyter Notebook for convenience python objects are kept alive and we recommend using directly start and stop methods.

Using an existing Scaleway QPU session

If you created your session from the Scaleway console, you can retrieve it from Perceval.

For this, you only have to go to your session’s settings on the console, copy the deduplication identifier and put it to the session creation on your Perceval code.

>>> DEDUPLICATION_ID = "my-quantum-workshop-identifier"
>>> session = scw.Session(platform=PLATFORM_NAME, project_id=PROJECT_ID, token=TOKEN, deduplication_id=DEDUPLICATION_ID)

A session can be fetched until termination or timeout. If there is no alive session matching the deduplication_id, a new one will be created and returned. It is highly convenient if you wish to keep a specific amount of session alive at a time.

Send a circuit to a Scaleway QPU session

Now you are handling a session, you can instantiate a RemoteProcessor linked to the session:

>>> processor = session.build_remote_processor()

Then, we can attach a toy circuit and send it on our session

>>> processor.set_circuit(pcvl.Circuit(m=2, name="a-toy-circuit") // pcvl.BS.H())
>>> processor.with_input(pcvl.BasicState("|0,1>"))
>>> processor.min_detected_photons_filter(1)
>>> sampler = pcvl.algorithm.Sampler(processor, max_shots_per_call=10_000)
>>> job = sampler.samples(100)
>>> print(job)

Congratulation you can now design and send jobs to Scaleway QaaS through your processor. You can continue with the documentation of algorithm.

Kipu Quantum Hub

The Kipu Quantum Hub brokers quantum jobs to multiple quantum providers. Through it, Perceval can run Quandela photonic backends hosted on the Hub.

This provider relies on an optional dependency (the qhub-api package). Install it with:

pip install perceval[kipu]

If the dependency is missing, creating a Kipu RemoteProcessor raises an ImportError telling you to run the command above.

Kipu authentication

To use the Kipu Quantum Hub as a provider you need a Kipu Quantum account and a Personal Access Token (PAT).

Create a Kipu Quantum account at the Kipu Quantum Hub dashboard.
Copy your Personal Access Token (PAT) from the dashboard.
(Optional) Provide an organization_id to run within an organization context. If omitted, your personal account is used.

Alternatively, authenticate with the qhubctl CLI instead of passing a token:

qhubctl login

Once logged in, create the session without a token — it is resolved automatically from the environment or the qhubctl credentials file.

KipuSession

class perceval.providers.kipu.Session(platform_name, token=None, organization_id=None, url=None, proxies=None)

Kipu Quantum Hub session.

Parameters:

platform_name (str) – Hub backend id or alias (e.g. “quandela.sim.belenos”)
token (Optional[str]) – optional Kipu Personal Access Token (PAT); when omitted it is resolved from the environment or the qhubctl login config file
organization_id (Optional[str]) – optional Kipu organization id; when omitted your personal account is used
url (Optional[str]) – optional Hub base URL; when omitted the qhub-api client uses its own default Hub endpoint
proxies (Optional[dict]) – optional protocol->URL proxy mapping

build_remote_processor()

Build a RemoteProcessor wired to the Kipu Hub.

Return type:: RemoteProcessor

Available platforms

The platform_name is a Hub backend id, or one of its aliases:

Backend id	Alias
`quandela.sim.belenos`	`sim:belenos`
`quandela.qpu.belenos`	`qpu:belenos`

Create a Kipu session

Import the library and the Kipu Quantum Hub provider:

>>> import perceval as pcvl
>>> import perceval.providers.kipu as kipu

Provide your Personal Access Token (PAT) and choose a platform:

>>> TOKEN = "your-personal-access-token"
>>> PLATFORM_NAME = "quandela.sim.belenos"

Create the session (organization_id is optional):

>>> session = kipu.Session(platform_name=PLATFORM_NAME, token=TOKEN)

If you authenticated via qhubctl login, omit the token:

>>> session = kipu.Session(platform_name=PLATFORM_NAME)

Note

The Kipu session is stateless: there is no start/stop to call and no with block lifecycle to manage, unlike the Scaleway session.

Note

JobGroup (batch job submission) is not supported by the Kipu Quantum Hub provider, like the Scaleway provider.

Send a circuit to a Kipu-hosted backend

Build a RemoteProcessor from the session:

>>> processor = session.build_remote_processor()

Attach a toy circuit and send it:

>>> processor.set_circuit(pcvl.Circuit(m=2, name="a-toy-circuit") // pcvl.BS.H())
>>> processor.with_input(pcvl.BasicState("|0,1>"))
>>> processor.min_detected_photons_filter(1)
>>> sampler = pcvl.algorithm.Sampler(processor, max_shots_per_call=10_000)
>>> job = sampler.samples(100)
>>> print(job)

You can now design and send jobs to Quandela backends through the Kipu Quantum Hub. Continue with the documentation of algorithm.