pasqal-sdk


Namepasqal-sdk JSON
Version 0.2.0 PyPI version JSON
download
home_pagehttps://github.com/pasqal-io/cloud-sdk
SummarySoftware development kit for Pasqal cloud platform.
upload_time2023-04-18 16:45:04
maintainerPasqal Cloud Services
docs_urlNone
author
requires_python>=3.7
licenseApache 2.0
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Cloud SDK

SDK to be used to access Pasqal Cloud Services.

## Installation

To install the latest release of the `cloud-sdk`, have Python 3.8.0 or higher installed, then use pip:

```bash
pip install pasqal-sdk
```

If you wish to **install the development version of the cloud_sdk from source** instead, do the following from within this repository after cloning it:

```bash
git checkout develop
pip install -e .
```

Bear in mind that this installation will track the contents of your local
cloud_sdk repository folder, so if you checkout a different branch (e.g. `master`),
your installation will change accordingly.

### Development Requirements (Optional)

To run the tutorials or the test suite locally, run the following to install the development requirements:

```bash
pip install -e .[dev]
```

## Instanciation and Authentication

There are several ways to provide a correct authentication using the SDK.

```python
from sdk import SDK

group_id="your_group_id" # Replace this value by your group_id on the PASQAL platform.
username="your_username" # Replace this value by your username or email on the PASQAL platform.
password="your_password" # Replace this value by your password on the PASQAL platform.
# Ideally, do not write this password in a script but provide in through the command-line or as a secret environment variable.

""" Method 1: Username + Password
    If you know your credentials, you can pass them to the SDK instance on creation.
"""
sdk = SDK(username=username, password=password, group_id=group_id)

""" Method 2: Username only
    If you only want to insert your username, but want a solution to have your password being secret
    you can run the SDK without password. A prompt will then ask for your password
"""
sdk = SDK(username=username, group_id=group_id)
> Please, enter your password:

""" Method 3: Use a token
    If you already know your token, you can directly pass it as an argument
    using the following method.
"""
class NewTokenProvider(TokenProvider):
    def _query_token(self):
        # Custom token query that will be validated by the API Calls later.
        return {
            "access_token": "some_token",
            "id_token": "id_token",
            "scope": "openid profile email",
            "expires_in": 86400,
            "token_type": "Bearer"
        }

sdk = SDK(token_provider=NewTokenProvider, group_id=group_id)
```

/!\ For developers /!\

If you want to redefine the APIs used by the SDK, please, do the following.

```python
from sdk import SDK, Endpoints, Auth0COnf

endpoints = Endpoints(core = "my_new_core_endpoint")
auth0 = Auth0Conf(
    domain="new_domain",
    public_client_id="public_id",
    audience="new_audience"
)
sdk = SDK(..., endpoints=endpoints, auth0=auth0)
```

This enables you to target backend services running locally on your machine, or other environment like preprod or dev.

## Basic usage

The package main component is a python object called `SDK` which can be used to create a `Batch` and send it automatically
to Pasqal APIs using an API token generated in the [user portal](https://portal.pasqal.cloud).

A `Batch` is a group of jobs with the same sequence that will run on the same QPU. For each job of a given batch you must set a value for each variable, if any, defined in your sequence.  
The batch sequence can be generated using [Pulser](https://github.com/pasqal-io/Pulser). See their [documentation](https://pulser.readthedocs.io/en/stable/),
for more information on how to install the library and create your own sequence.

Below is an example of the creation of a simple sequence with a single variable and its serialization to a string.

```python
from pulser import devices, Pulse, Register, Sequence
from pulser.register.special_layouts import SquareLatticeLayout

# Define a register for your sequence
register = Register.square(2, spacing=5, prefix="q")
# Create a sequence for that register
sequence = Sequence(register, devices.IroiseMVP)
# Add a channel to your sequence
sequence.declare_channel("rydberg", "rydberg_global")
# Declare a variable
omega_max = sequence.declare_variable("omega_max")
# Add a pulse to that channel with the amplitude omega_max
generic_pulse = Pulse.ConstantPulse(100, omega_max, 2, 0.0)
sequence.add(generic_pulse, "rydberg")

# When you are done building your sequence, serialize it into a string
serialized_sequence = sequence.serialize()
```

Once you have serialized your sequence, you can send it with the SDK with the following code

```python
from sdk import SDK
from pulser import devices, Register, Sequence

group_id="your_group_id" # Replace this value by your group_id on the PASQAL platform.
username="your_username" # Replace this value by your username or email on the PASQAL platform.
password="your_password" # Replace this value by your password on the PASQAL platform.

sdk = SDK(username=username, password=password, group_id=group_id)

# When creating a job, select a number of runs and set the desired values for the variables
# defined in the sequence
job1 = {"runs": 20, "variables": {"omega_max": 6} }
job2 = {"runs": 50, "variables": {"omega_max": 10.5} }

# Send the batch of jobs to the QPU and wait for the results
batch = sdk.create_batch(serialized_sequence, [job1,job2], wait=True)

# You can also choose to run your batch on an emulator using the optional argument 'emulator'
# For using a basic single-threaded QPU emulator that can go up to 10 qubits, you can specify the "EMU_FREE" emulator.
from sdk.device import EmulatorType
batch = sdk.create_batch(serialized_sequence, [job1,job2], emulator=EmulatorType.EMU_FREE)

# Once the QPU has returned the results, you can access them with the following:
for job in batch.jobs.values():
    print(job.result)

```

### Extra emulator configuration (Soon publicly available)

Some emulators, such as EMU_TN and EMU_FREE, accept further configuration to control the emulation.
This is because these emulators are more advanced numerical simulation of the quantum system.

For EMU_TN you may add the integrator timestep in nanoseconds, the numerical accuracy desired in the tensor network compression, and the maximal bond dimension of tensor network state.

```python
# replace the corresponding section in the above code example with this to
# add further configuration
from sdk.device import EmulatorType, EmuTNConfig

configuration = EmuTNConfig(dt = 10.0, precision = "normal", max_bond_dim = 100)
batch = sdk.create_batch(serialized_sequence, [job1,job2], emulator=EmulatorType.EMU_TN, configuration=configuration)
```

For EMU_FREE you may add some default SPAM noise. Beware this makes your job take much longer.

```python
# replace the corresponding section in the above code example with this to
# add further configuration
from sdk.device import EmulatorType, EmuFreeConfig

configuration = EmuFreeConfig(with_noise=True)
batch = sdk.create_batch(serialized_sequence, [job1,job2], emulator=EmulatorType.EMU_FREE, configuration=configuration)
```

### List of supported device specifications

The SDK provides a method to retrieve the devices specs currently defined on PASQAL's cloud platform.
They define the physical constraints of our QPUs and these constraints enforce some rules on
the pulser sequence that can be run on QPUs (e.g. max amount of atoms, available pulse channels, ...)

```python
sdk.get_device_specs_list()
```

The method returns a dict object mapping a device type to a serialized device specs. These specs can be used
to instantiate a `Device` instance in the `Pulser` library.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/pasqal-io/cloud-sdk",
    "name": "pasqal-sdk",
    "maintainer": "Pasqal Cloud Services",
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "pcs@pasqal.io",
    "keywords": "",
    "author": "",
    "author_email": "",
    "download_url": "https://files.pythonhosted.org/packages/73/f8/19a2ce431e1eb15c6eb809ce5298e41c7ceba29fadd71572ccc9a3c153f6/pasqal-sdk-0.2.0.tar.gz",
    "platform": null,
    "description": "# Cloud SDK\n\nSDK to be used to access Pasqal Cloud Services.\n\n## Installation\n\nTo install the latest release of the `cloud-sdk`, have Python 3.8.0 or higher installed, then use pip:\n\n```bash\npip install pasqal-sdk\n```\n\nIf you wish to **install the development version of the cloud_sdk from source** instead, do the following from within this repository after cloning it:\n\n```bash\ngit checkout develop\npip install -e .\n```\n\nBear in mind that this installation will track the contents of your local\ncloud_sdk repository folder, so if you checkout a different branch (e.g. `master`),\nyour installation will change accordingly.\n\n### Development Requirements (Optional)\n\nTo run the tutorials or the test suite locally, run the following to install the development requirements:\n\n```bash\npip install -e .[dev]\n```\n\n## Instanciation and Authentication\n\nThere are several ways to provide a correct authentication using the SDK.\n\n```python\nfrom sdk import SDK\n\ngroup_id=\"your_group_id\" # Replace this value by your group_id on the PASQAL platform.\nusername=\"your_username\" # Replace this value by your username or email on the PASQAL platform.\npassword=\"your_password\" # Replace this value by your password on the PASQAL platform.\n# Ideally, do not write this password in a script but provide in through the command-line or as a secret environment variable.\n\n\"\"\" Method 1: Username + Password\n    If you know your credentials, you can pass them to the SDK instance on creation.\n\"\"\"\nsdk = SDK(username=username, password=password, group_id=group_id)\n\n\"\"\" Method 2: Username only\n    If you only want to insert your username, but want a solution to have your password being secret\n    you can run the SDK without password. A prompt will then ask for your password\n\"\"\"\nsdk = SDK(username=username, group_id=group_id)\n> Please, enter your password:\n\n\"\"\" Method 3: Use a token\n    If you already know your token, you can directly pass it as an argument\n    using the following method.\n\"\"\"\nclass NewTokenProvider(TokenProvider):\n    def _query_token(self):\n        # Custom token query that will be validated by the API Calls later.\n        return {\n            \"access_token\": \"some_token\",\n            \"id_token\": \"id_token\",\n            \"scope\": \"openid profile email\",\n            \"expires_in\": 86400,\n            \"token_type\": \"Bearer\"\n        }\n\nsdk = SDK(token_provider=NewTokenProvider, group_id=group_id)\n```\n\n/!\\ For developers /!\\\n\nIf you want to redefine the APIs used by the SDK, please, do the following.\n\n```python\nfrom sdk import SDK, Endpoints, Auth0COnf\n\nendpoints = Endpoints(core = \"my_new_core_endpoint\")\nauth0 = Auth0Conf(\n    domain=\"new_domain\",\n    public_client_id=\"public_id\",\n    audience=\"new_audience\"\n)\nsdk = SDK(..., endpoints=endpoints, auth0=auth0)\n```\n\nThis enables you to target backend services running locally on your machine, or other environment like preprod or dev.\n\n## Basic usage\n\nThe package main component is a python object called `SDK` which can be used to create a `Batch` and send it automatically\nto Pasqal APIs using an API token generated in the [user portal](https://portal.pasqal.cloud).\n\nA `Batch` is a group of jobs with the same sequence that will run on the same QPU. For each job of a given batch you must set a value for each variable, if any, defined in your sequence.  \nThe batch sequence can be generated using [Pulser](https://github.com/pasqal-io/Pulser). See their [documentation](https://pulser.readthedocs.io/en/stable/),\nfor more information on how to install the library and create your own sequence.\n\nBelow is an example of the creation of a simple sequence with a single variable and its serialization to a string.\n\n```python\nfrom pulser import devices, Pulse, Register, Sequence\nfrom pulser.register.special_layouts import SquareLatticeLayout\n\n# Define a register for your sequence\nregister = Register.square(2, spacing=5, prefix=\"q\")\n# Create a sequence for that register\nsequence = Sequence(register, devices.IroiseMVP)\n# Add a channel to your sequence\nsequence.declare_channel(\"rydberg\", \"rydberg_global\")\n# Declare a variable\nomega_max = sequence.declare_variable(\"omega_max\")\n# Add a pulse to that channel with the amplitude omega_max\ngeneric_pulse = Pulse.ConstantPulse(100, omega_max, 2, 0.0)\nsequence.add(generic_pulse, \"rydberg\")\n\n# When you are done building your sequence, serialize it into a string\nserialized_sequence = sequence.serialize()\n```\n\nOnce you have serialized your sequence, you can send it with the SDK with the following code\n\n```python\nfrom sdk import SDK\nfrom pulser import devices, Register, Sequence\n\ngroup_id=\"your_group_id\" # Replace this value by your group_id on the PASQAL platform.\nusername=\"your_username\" # Replace this value by your username or email on the PASQAL platform.\npassword=\"your_password\" # Replace this value by your password on the PASQAL platform.\n\nsdk = SDK(username=username, password=password, group_id=group_id)\n\n# When creating a job, select a number of runs and set the desired values for the variables\n# defined in the sequence\njob1 = {\"runs\": 20, \"variables\": {\"omega_max\": 6} }\njob2 = {\"runs\": 50, \"variables\": {\"omega_max\": 10.5} }\n\n# Send the batch of jobs to the QPU and wait for the results\nbatch = sdk.create_batch(serialized_sequence, [job1,job2], wait=True)\n\n# You can also choose to run your batch on an emulator using the optional argument 'emulator'\n# For using a basic single-threaded QPU emulator that can go up to 10 qubits, you can specify the \"EMU_FREE\" emulator.\nfrom sdk.device import EmulatorType\nbatch = sdk.create_batch(serialized_sequence, [job1,job2], emulator=EmulatorType.EMU_FREE)\n\n# Once the QPU has returned the results, you can access them with the following:\nfor job in batch.jobs.values():\n    print(job.result)\n\n```\n\n### Extra emulator configuration (Soon publicly available)\n\nSome emulators, such as EMU_TN and EMU_FREE, accept further configuration to control the emulation.\nThis is because these emulators are more advanced numerical simulation of the quantum system.\n\nFor EMU_TN you may add the integrator timestep in nanoseconds, the numerical accuracy desired in the tensor network compression, and the maximal bond dimension of tensor network state.\n\n```python\n# replace the corresponding section in the above code example with this to\n# add further configuration\nfrom sdk.device import EmulatorType, EmuTNConfig\n\nconfiguration = EmuTNConfig(dt = 10.0, precision = \"normal\", max_bond_dim = 100)\nbatch = sdk.create_batch(serialized_sequence, [job1,job2], emulator=EmulatorType.EMU_TN, configuration=configuration)\n```\n\nFor EMU_FREE you may add some default SPAM noise. Beware this makes your job take much longer.\n\n```python\n# replace the corresponding section in the above code example with this to\n# add further configuration\nfrom sdk.device import EmulatorType, EmuFreeConfig\n\nconfiguration = EmuFreeConfig(with_noise=True)\nbatch = sdk.create_batch(serialized_sequence, [job1,job2], emulator=EmulatorType.EMU_FREE, configuration=configuration)\n```\n\n### List of supported device specifications\n\nThe SDK provides a method to retrieve the devices specs currently defined on PASQAL's cloud platform.\nThey define the physical constraints of our QPUs and these constraints enforce some rules on\nthe pulser sequence that can be run on QPUs (e.g. max amount of atoms, available pulse channels, ...)\n\n```python\nsdk.get_device_specs_list()\n```\n\nThe method returns a dict object mapping a device type to a serialized device specs. These specs can be used\nto instantiate a `Device` instance in the `Pulser` library.\n",
    "bugtrack_url": null,
    "license": "Apache 2.0",
    "summary": "Software development kit for Pasqal cloud platform.",
    "version": "0.2.0",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "777394b9047417cdf9e9d889e4fe45aba3875a5c14a3dee1e017ac76d42436b9",
                "md5": "9855096f7ef05d4d5b847e6a6fd63844",
                "sha256": "e5de8d73324b0a727532edc372b02c08fec5daeb248f1a9cb77a66d97d2ee9f8"
            },
            "downloads": -1,
            "filename": "pasqal_sdk-0.2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "9855096f7ef05d4d5b847e6a6fd63844",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 28241,
            "upload_time": "2023-04-18T16:45:03",
            "upload_time_iso_8601": "2023-04-18T16:45:03.291574Z",
            "url": "https://files.pythonhosted.org/packages/77/73/94b9047417cdf9e9d889e4fe45aba3875a5c14a3dee1e017ac76d42436b9/pasqal_sdk-0.2.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "73f819a2ce431e1eb15c6eb809ce5298e41c7ceba29fadd71572ccc9a3c153f6",
                "md5": "43bee49d22e79ef26fe20a4444d12fe5",
                "sha256": "c0eaf3b1298d90704f325cc303552ddfde6f3e422e1ac6eb63451a46cf41e229"
            },
            "downloads": -1,
            "filename": "pasqal-sdk-0.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "43bee49d22e79ef26fe20a4444d12fe5",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 20672,
            "upload_time": "2023-04-18T16:45:04",
            "upload_time_iso_8601": "2023-04-18T16:45:04.809847Z",
            "url": "https://files.pythonhosted.org/packages/73/f8/19a2ce431e1eb15c6eb809ce5298e41c7ceba29fadd71572ccc9a3c153f6/pasqal-sdk-0.2.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-04-18 16:45:04",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "pasqal-io",
    "github_project": "cloud-sdk",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "pasqal-sdk"
}
        
Elapsed time: 0.05916s