Kipu Quantum Hub

The Kipu Quantum Hub brokers quantum jobs to multiple providers. Perceval can use it to run Quandela photonic backends through a KipuCommunicationLayer and a RemoteComputer.

Installation

The Kipu integration relies on the optional qhub-api dependency. Install Perceval with the kipu extra:

pip install perceval-quandela[kipu]

If the dependency is missing, creating a Kipu communication layer raises an ImportError containing the installation instruction.

Authentication

Create a Kipu Quantum Hub account and copy a Personal Access Token from the Hub dashboard. A token can be passed directly, stored in the KIPU_CLOUD_TOKEN environment variable, or managed with KipuConfig.

Alternatively, authenticate with the qhubctl CLI:

qhubctl login

When using qhubctl credentials, omit the token and let qhub-api resolve it. An optional organization_id runs jobs in an organization context; omitting it uses the personal account associated with the credentials.

KipuCommunicationLayer

The supported backend IDs and aliases are:

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

Create a communication layer and pass it to RemoteComputer:

>>> import perceval as pcvl
>>>
>>> communication_layer = pcvl.KipuCommunicationLayer(
...     platform_name="quandela.sim.belenos",
...     token="your-personal-access-token",
... )
>>> computer = pcvl.RemoteComputer(communication_layer)

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

Communication layer for the Kipu Quantum Hub.

It requires the optional qhub-api dependency, available through Perceval’s [kipu] extra.

Parameters:

platform_name (str) – Hub backend ID or supported alias, such as "quandela.sim.belenos".
token (Optional[str]) – Kipu Personal Access Token (PAT). When omitted, use KipuConfig, environment credentials, or credentials created by qhubctl login.
organization_id (Optional[str]) – Optional Kipu organization. When omitted, use KipuConfig or the personal account associated with the credentials.
url (Optional[str]) – Optional Hub base URL. When omitted, use KipuConfig or the qhub default endpoint.
proxies (Optional[dict]) – Mapping of protocols to proxy URLs.

KipuConfig

Note

Execution serialization does not store credentials. To be able to deserialize an execution made through a Kipu computer, the KipuConfig needs to be configured.

KipuConfig manages the Personal Access Token, optional Hub URL, proxies, and organization ID. Values set on the class are cached for the current Python process. Call save() only on a personal machine when they should also be written to Perceval’s persistent configuration:

>>> config = pcvl.KipuConfig()
>>> config.set_token("your-personal-access-token")
>>> config.set_organization_id("your-organization-id")
>>> config.save()

After configuration, the token and organization ID may be omitted:

>>> communication_layer = pcvl.KipuCommunicationLayer("sim:belenos")

To return to the personal account context, set the organization ID to None before creating the communication layer:

>>> config.set_organization_id(None)

Note

Do not persist authentication tokens on shared or public computers. Using qhubctl, an environment variable, or the in-memory configuration cache avoids writing the token through Perceval.

class perceval.providers.kipu.kipu_config.KipuConfig(persistent_data=<perceval.utils.persistent_data.PersistentData object>)

Handle the remote configuration for the Kipu API.

Tokens are read from the in-memory cache, the KIPU_CLOUD_TOKEN environment variable, or persistent Perceval configuration. The Hub URL, proxies, and optional organization ID can also be stored. If no token is found, the communication layer lets qhub-api resolve credentials, including credentials created by qhubctl login.

classmethod clear_cache(): Delete the RemoteConfig cache.

get_organization_id()

Find the configured organization ID, cache it, and return it.

The priority for the organization id search is as follows: * An organization id already in cache (e.g. set by the user or already found in a previous call) * The value in Perceval persistent configuration

Return type:: Optional[str]
Returns:: The organization id

get_proxies()

Get the proxy configuration as a mapping of protocols to URLs.

Return type:: dict[str, str]

get_token()

Search a valid token from the environment, put it in cache and return it.

The priority for the token search is as follows: * A token already in cache (e.g. set by the user or already found in a previous call) * The value of the environment variable given by self.get_token_env_var() * The value in Perceval persistent configuration

Return type:: str
Returns:: The token

classmethod get_token_env_var()

Get the name of the environment variable storing a token.

Return type:: str

get_url()

Search a valid cloud URL from the environment, put it in cache and return it.

The priority for the URL search is as follows: * A URL already in cache (e.g. set by the user or already found in a previous call) * The value in Perceval persistent configuration

Return type:: str
Returns:: The cloud URL

save()

Save the current remote configuration on disk. After this, the configuration is persistent and can be found in other Perceval sessions (even in different virtual envs).

Return type:: None

classmethod set_organization_id(organization_id)

Set an organization id in the configuration cache. It is not saved on disk before the save method is called.

Parameters:: organization_id (Optional[str]) – The organization id to use by default. Set None to use your personal account.
Return type:: None

static set_proxies(proxies)

Set the proxy configuration. The proxy configuration is shared between all configurations.

Usage example:

>>> rc = RemoteConfig()
>>> rc.set_proxies({"http": "http://user:pass@192.168.0.1",
...                 "https": "http://user:pass@192.168.0.1:8080"
...                })

Parameters:: proxies (dict[str, str]) – proxy configuration in the form of a dictionary which maps protocols to URLs
Return type:: None

classmethod set_token(token)

Set a user authentication token in the configuration cache. It is not saved on disk before the save method is called.

Parameters:: token (str) – The token
Return type:: None

classmethod set_token_env_var(env_var)

Change the name of the environment variable storing a token.

Parameters:: env_var (str) – name of the new environment variable to search for
Return type:: None

classmethod set_url(url)

Set a cloud URL in the configuration cache. It is not saved on disk before the save method is called.

Parameters:: url (str) – The cloud URL
Return type:: None

Legacy Session

Warning

Session belongs to the legacy processor workflow. New code should use KipuCommunicationLayer with RemoteComputer.

class perceval.providers.kipu.kipu_session.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