parityos 0.0.6__tar.gz

parityos-0.0.6/License.txt

@@ -0,0 +1,37 @@
+ParityOS Client Software License Terms (BSD-3-Clause)
+=====================================================
+
+Copyright 2023 Parity Quantum Computing GmbH (ParityQC)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS”
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+===============================================================================
+
+Parity Quantum Computing GmbH
+Rennweg 1 / Top 314 / 6020 Innsbruck, Austria
+info@parityqc.com / www.parityqc.com
+
+===============================================================================

parityos-0.0.6/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.1
+Name: parityos
+Version: 0.0.6
+Summary: Python bindings to the ParityOS API
+Home-page: https://parityqc.com/
+Requires-Python: >=3.9
+License-File: License.txt
+Requires-Dist: requests
+Provides-Extra: cirq
+Requires-Dist: cirq-core; extra == "cirq"
+Provides-Extra: qiskit
+Requires-Dist: qiskit; extra == "qiskit"
+Provides-Extra: spinz
+Requires-Dist: sympy; extra == "spinz"
+Provides-Extra: benchmarking
+Requires-Dist: pandas; extra == "benchmarking"
+Requires-Dist: numpy; extra == "benchmarking"
+Provides-Extra: all
+Requires-Dist: sympy; extra == "all"
+Requires-Dist: numpy; extra == "all"
+Requires-Dist: cirq-core; extra == "all"
+Requires-Dist: pandas; extra == "all"
+Requires-Dist: qiskit; extra == "all"
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: pip-tools; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: qiskit-aer; extra == "dev"
+Requires-Dist: sympy; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: cirq-core; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Requires-Dist: qiskit; extra == "dev"

parityos-0.0.6/README.md

@@ -0,0 +1,113 @@
+# ParityOS
+Parity Quantum Computing GmbH  
+Rennweg 1 Top 314  
+6020 Innsbruck, Austria  
+Copyright (c) 2020-2023.
+
+This package contains the client software to use the ParityOS cloud service. 
+
+## Installation
+It is recommended to install this package in a separate Python `venv` or Conda environment.
+```commandline
+   # To create a standard Python environment:
+   python -m venv my_new_venv  && source my_new_venv/bin/activate
+   # Or, alternatively, to create a Anaconda/Miniconda environment:
+   conda create --name my_new_conda_env  &&  conda activate my_new_conda_env
+```
+
+Installation is done with the following command:
+```commandline
+pip install parityos
+```
+This will install two Python libraries: `parityos` and `parityos_addons`.
+
+Some addons depend on external libraries like Cirq, Sympy or Qiskit. 
+The `pip` command will resolve these dependencies automatically if you specify which addons you 
+want to include. E.g. to include dependencies for the `spin_hamiltonians` and `qiskit_exporter` 
+addons, use this command:
+```commandline
+pip install 'parityos[spinz,qiksit]' 
+```
+or to use `spin_hamiltonians` and `cirq_exporter`: 
+```commandline
+pip install 'parityos[spinz,cirq]'
+```
+These commands will make sure that additional dependencies like `sympy`, `qiskit` or `cirq` 
+are installed correctly.
+If you want to make sure that all optional dependencies are included, use:
+```commandline
+pip install 'parityos[all]'
+```
+
+
+## ParityOS
+A Python package that provides the `CompilerClient` class to connect to 
+the ParityOS cloud service. The package defines data structures to construct
+the inputs and to process the outputs from the ParityOS cloud service.
+
+    from parityos import CompilerClient, RectangularDigitalDevice
+
+    username = ''  # Put here your ParityOS username or set the PARITYOS_USER environment variable.
+    compiler_client = CompilerClient(username)
+    device_model = RectangularDigitalDevice(4, 4)
+    parityos_output = compiler_client.compile(hamiltonian, device_model)
+
+## ParityOS Addons
+Additional tools that help you to get the most out of the ParityOS framework. 
+
+### addon documentation
+Detailed documentation on how to use the ParityOS framework, including a 
+quickstart guide and a QAOA tutorial.
+
+To open the documentation in your web browser, type the following command
+on the command line:
+
+    python -m parityos_addons.documentation.show
+
+### addon examples
+Some examples of ParityOS compilations can be found in `parityos_addons_examples`.
+These can be run directly from the command line:
+
+    python -m parityos_addons.examples.example1
+    python -m parityos_addons.examples.example2
+    python -m parityos_addons.examples.example3
+    python -m parityos_addons.examples.example4
+    python -m parityos_addons.examples.example5
+
+### addon spin_hamiltonians
+A Python package that provides tools to construct a spin Hamiltonian as a product
+of Pauli spin Z operators. An example:
+
+    from parityos_addons.spin_hamiltonians import spinz_to_hamiltonian, SpinZ as Z
+
+    hamiltonian = spinz_to_hamiltonian(
+        Z('a') + Z('b') - 2 * Z('c') + 4 * Z('a') * Z('b') - (Z('a') + Z('b')) * Z('c')
+    ) 
+
+### addon qaoa
+A Python package that provides tools to construct a QAOA circuit from the 
+output returned by the ParityOS cloud service.
+
+    from parityos_addons.qaoa import generate_qaoa
+
+    parityos_circuit, parameter_bounds = generate_qaoa(parityos_output=parityos_output,
+                                                       unitary_pattern='ZCX' * 4)
+
+### addon interfaces
+Provides the tools to export quantum circuits from ParityOS to other 
+frameworks like Cirq or Qiskit. Here is an example with Qiskit:
+
+    from qiskit.circuit import Parameter
+    from parityos_addons.interfaces import QiskitExporter
+
+    # Map ParityOS parameters onto Qiskit parameters
+    parameter_map = {key: Parameter(str(key)) for key in parameter_bounds.keys()}
+    # Instantiate the exporter
+    qiskit_exporter = QiskitExporter(parameter_map=parameter_map, qubit_map=qubit_map)
+    # Convert the ParityOS circuit to a qiskit circuit
+    qiskit_circuit = qiskit_exporter.to_qiskit(parityos_circuit)
+
+## License
+Since version 2.1.0, the ParityOS Client software package is made available 
+under the 3-Clause BSD License. See the file `License.txt` for details.
+ 

parityos-0.0.6/parityos/__init__.py

@@ -0,0 +1,15 @@
+"""
+Parity Quantum Computing GmbH
+Rennweg 1 Top 314
+6020 Innsbruck, Austria
+
+Copyright (c) 2020-2024.
+All rights reserved.
+
+Tools to use the ParityOS cloud services.
+"""
+
+from .base import Hamiltonian, ProblemRepresentation, ParityOSException, ParityOSImportError, Qubit
+from .device_model import RectangularAnalogDevice, RectangularDigitalDevice
+from .encodings.parityos_output import ParityOSOutput
+from .compiler_client import CompilerClient

parityos-0.0.6/parityos/api_interface/authentication.py

@@ -0,0 +1,87 @@
+"""
+Parity Quantum Computing GmbH
+Rennweg 1 Top 314
+6020 Innsbruck, Austria
+
+Copyright (c) 2020-2023.
+All rights reserved.
+
+Tools to authenticate with the ParityOS cloud services.
+"""
+
+from collections.abc import Iterator
+import getpass
+import os
+import warnings
+
+
+def generate_credentials(
+    username: str = None,
+    username_variable: str = "",
+    password_variable: str = "",
+    intents: int = 3,
+) -> Iterator[dict[str, str]]:
+    """
+    Generates a series of JSON compatible dictionaries with a username and a password.
+    The username can be provided as an argument. Otherwise, it is taken from the given system
+    variable (this is tried only once), or requested from the user on the prompt.
+    For security reasons, the password can not be provided as an argument. It is either taken
+    from the given system variable (this is tried only once), or requested from the user on the
+    prompt.
+    The argument `intents` sets the maximum number of times to ask for a username or password,
+    either from the environment or from the prompt.
+    To make this generator fully non-interactive, set intents to 1 and set the correct system
+    variables.
+
+    :param str username: The username for the account on the server.
+    :param str username_variable: System variable to query for the username
+    :param str password_variable: System variable to query for the password
+    :param int intents: Maximum number of times to ask for a username or password.
+    """
+    # The credentials object allows for a number of intents to provide the password.
+    # First intent: get data from the environment variables or else from prompt.
+    username = username or _get_username(username, username_variable)
+    password = _get_password(password_variable=password_variable)
+    yield {"username": username, "password": password}
+
+    # The next intents are always interactive.
+    for intent in range(1, intents):
+        print("Login failed. Please provide the correct credentials.")
+        username = _get_username(username)
+        password = _get_password(password)
+        yield {"username": username, "password": password}
+
+
+def _get_username(username: str = "", username_variable: str = "") -> str:
+    """
+    Ask for a username, either from the provided environment variable or on the prompt.
+    If a username argument is given, then this is shown as a suggestion on the prompt
+    and returned as the result if the user only types return.
+    """
+    if username_variable and not username:
+        username = os.getenv(username_variable)
+        if username:
+            return username
+
+    suggestion = f" [{username}]" if username else ""
+    username = input(f"ParityOS Username{suggestion}: ") or username
+    return username
+
+
+def _get_password(password: str = "", password_variable: str = "") -> str:
+    """
+    Ask for a password, either from the provided environment variable or on the prompt.
+    If a password argument is given, then "***" is shown as a suggestion on the prompt
+    and the given value is returned as the result if the user only types return.
+    """
+    if password_variable and not password:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            password = os.getenv(password_variable)
+
+        if password:
+            return password
+
+    suggestion = " [***]" if password else ""
+    password = getpass.getpass(f"ParityOS Password{suggestion}: ") or password
+    return password

parityos-0.0.6/parityos/api_interface/compiler_run.py

@@ -0,0 +1,113 @@
+"""
+Parity Quantum Computing GmbH
+Rennweg 1 Top 314
+6020 Innsbruck, Austria
+
+Copyright (c) 2020-2024.
+All rights reserved.
+
+Tools to process the results from the ParityOS cloud service.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Optional, Union
+
+from parityos.base import JSONMappingType
+
+
+DateStr = Union[datetime, str]  # type: TypeAlias
+
+
+class CompilerRunStatus(Enum):
+    """
+    Enum for compiler run status.
+    """
+
+    SUBMITTED = "S"
+    RUNNING = "R"
+    COMPLETED = "C"
+    FAILED = "F"
+
+
+@dataclass
+class CompilerRun:
+    """
+    Encapsulates a compiler run; has attributes which describe relevant times
+    at which they were submitted, started, and eventually finished or failed
+    (in which case, a reason for failure is also given).
+
+    :param id: The UUID4 id of the compiler run in ParityOS cloud database.
+    :param submission_id: The UUID4 id of the submission which triggered compile run.
+    :param status: The status of the submission; see the `CompilerRunStatus` enum.
+    :param submitted_at: Time at which the run was queued for execution, as `datetime` object.
+    :param started_at: Time at which the run started being executed, as `datetime` object.
+    :param finished_at: Time at which the run was completed, as `datetime` object.
+    :param failed_at: time at which run failed
+    :param failure_reason: reason for which run failed
+    """
+
+    id: str
+    submission_id: str
+    status: Union[CompilerRunStatus, str]
+    submitted_at: Optional[DateStr] = None
+    started_at: Optional[DateStr] = None
+    finished_at: Optional[DateStr] = None
+    failed_at: Optional[DateStr] = None
+    failure_reason: Optional[str] = ""
+
+    def __post_init__(self):
+        """Convert attributes to their intended type if they were provided as strings."""
+        # Map the status to the corresponding Enum instance.
+        self.status = CompilerRunStatus(self.status)
+        # Map date times in string format to datetime instances
+        self.submitted_at = _str_to_datetime(self.submitted_at)
+        self.started_at = _str_to_datetime(self.started_at)
+        self.finished_at = _str_to_datetime(self.finished_at)
+        self.failed_at = _str_to_datetime(self.failed_at)
+
+    @classmethod
+    def from_json(cls, data: JSONMappingType) -> "Self":
+        """
+        Creates a CompilerRun object from a JSON-like data dictionary.
+        :return: a CompilerRun object
+        """
+        return cls(**data)
+
+    def __str__(self) -> str:
+        """
+        Return useful information about the compiler run in string format.
+        """
+        info_lines = [f"Compiler run {self.id}. ", f"Status: {self.status}"]
+        if self.submitted_at:
+            info_lines.append(f"The compiler run was submitted at {self.submitted_at.ctime()}.")
+
+        if self.started_at:
+            info_lines.append(f"The compilation started at {self.started_at.ctime()}.")
+            if self.finished_at:
+                duration_in_seconds = (self.finished_at - self.started_at).total_seconds()
+                info_lines.append(f"The compilation took {duration_in_seconds:0.2f} seconds.")
+
+        if self.failed_at:
+            if self.started_at:
+                duration_in_seconds = (self.failed_at - self.started_at).total_seconds()
+                info_lines.append(
+                    f"The compilation was aborted after {duration_in_seconds:0.2f} seconds."
+                )
+            else:
+                info_lines.append(f"An error occurred at {self.failed_at.ctime()}.")
+
+        if self.failure_reason:
+            info_lines.append(self.failure_reason)
+
+        return "\n".join(info_lines)
+
+
+def _str_to_datetime(date: Union[datetime, str]) -> datetime:
+    """Helper method to convert dates in string format to datetime instances."""
+    return (
+        datetime.fromisoformat(date.replace("Z", "+00:00"))
+        if date and isinstance(date, str)
+        else date
+    )

parityos-0.0.6/parityos/api_interface/connection.py

@@ -0,0 +1,139 @@
+"""
+Parity Quantum Computing GmbH
+Rennweg 1 Top 314
+6020 Innsbruck, Austria
+
+Copyright (c) 2020-2022.
+All rights reserved.
+
+Tools to connect to the ParityOS cloud services.
+"""
+
+from json.decoder import JSONDecodeError
+
+from requests import Session, Response
+from requests.adapters import HTTPAdapter
+from requests.packages.urllib3.util.retry import Retry
+
+from parityos.api_interface.authentication import generate_credentials
+from parityos.api_interface.exceptions import ParityOSAuthError, ParityOSRequestError
+
+
+DEFAULT_HOST = "api.parityqc.com"
+
+# Define environment variables that can hold the credentials for the default host.
+DEFAULT_ENVIRONMENT = dict(
+    username_variable="PARITYOS_USER",
+    password_variable="PARITYOS_PASS",
+)
+# Define the environment variables that can hold the credentials for alternative hosts.
+ALTERNATIVE_ENVIRONMENT = dict(
+    username_variable="PARITYOS_ALTUSER",
+    password_variable="PARITYOS_ALTPASS",
+)
+
+
+class ClientBase:
+    """
+    Base class that sets up HTTP parameters (authentication, API endpoints, and so on).
+    It should not be used directly unless you are debugging HTTP requests,
+    use parityos.CompilerClient instead.
+    """
+
+    def __init__(
+        self,
+        username: str = None,
+        host: str = DEFAULT_HOST,
+        url_prefix: str = "v1",
+        http_retries: int = 3,
+        http_timeout: int = 10,
+        http_backoff_factor: float = 0.02,
+        intents: int = 3,
+    ):
+        """
+        :param str username: ParityOS id of the user.
+        :param str host: ParityAPI host name.
+        :param str url_prefix: Prefix to REST API paths, used mostly for versioning.
+        :param int http_retries: Number of http retries.
+        :param int http_timeout: Maximum time in seconds to wait for a http response.
+        :param int http_backoff_factor: Http exponential backoff factor.
+        :param int intents: Maximum number of intents with different passwords.
+        """
+        self.username = username
+        self.host = host
+        self.url_prefix = url_prefix
+        self.base_url = f"https://{self.host}/{self.url_prefix}"
+        self.http_timeout = http_timeout
+        self.http_retries = http_retries
+        self.http_backoff_factor = http_backoff_factor
+        self.intents = intents
+        self._setup_connection()
+
+    def _setup_connection(self):
+        """
+        Connects to the ParityAPI server, logs the user in and stores the session token.
+        """
+        # Credentials are instantiated here so that the password information
+        # is garbage collected as soon as this method terminates.
+        self.http = Session()
+        adapter = HTTPAdapter(
+            max_retries=Retry(total=self.http_retries, backoff_factor=self.http_backoff_factor)
+        )
+        self.http.mount("https://", adapter)
+        self.username, token = self._get_authentication()
+        # Only the username is stored in self so that the password information
+        # can be garbage collected.
+        self.http.headers.update({"Authorization": f"Token {token}"})
+
+    def _get_authentication(self) -> tuple[str, str]:
+        """
+        Log in on the server to obtain an authentication token for future requests.
+        """
+        # The credentials object allows for a number of intents to provide the password.
+        environment_variables = (
+            DEFAULT_ENVIRONMENT if self.host == DEFAULT_HOST else ALTERNATIVE_ENVIRONMENT
+        )
+        authentication_intents = generate_credentials(
+            self.username,
+            **environment_variables,
+            intents=self.intents,
+        )
+        username = self.username
+        for credentials_data in authentication_intents:
+            response = self.http.post(f"{self.base_url}/auth", data=credentials_data)
+            data = response.json()
+            username = credentials_data["username"]
+            if "token" in data:
+                return username, data["token"]
+
+        # No authentication intents left after failed logins
+        raise ParityOSAuthError(f"Failed login for user {username} on server {self.host}.")
+
+    def _send_request(self, method: str, url: str, data: dict = None) -> Response:
+        """
+        Send a http request
+
+        :param method: request method to use ('GET', 'POST', 'PUT', ... )
+        :param url: target url
+        :param data: payload data as a dictionary
+        :return: requests.Response object
+        """
+        try:
+            response = self.http.request(method, url=url, json=data, timeout=self.http_timeout)
+        except Exception as err:
+            message = f"Failed to receive valid response after at most {self.http_retries} retries."
+            err.args = (*err.args, message)
+            raise err
+
+        if response.ok:
+            return response
+        else:
+            try:
+                error_data = response.json()
+            except JSONDecodeError:
+                error_data = "None"
+
+            raise ParityOSRequestError(
+                f"{method} on {url}: {response.status_code}, {error_data}",
+                response=response,
+            )

parityos-0.0.6/parityos/api_interface/exceptions.py

@@ -0,0 +1,36 @@
+"""
+Parity Quantum Computing GmbH
+Rennweg 1 Top 314
+6020 Innsbruck, Austria
+
+Copyright (c) 2020-2024.
+All rights reserved.
+"""
+
+from requests.exceptions import RequestException
+
+from parityos.base.exceptions import ParityOSException
+
+
+class ParityOSAuthError(RequestException, ValueError):
+    """
+    Exception for failed logins to the ParityAPI server.
+    """
+
+
+class ParityOSRequestError(RequestException):
+    """
+    Exception for failed logins to the ParityAPI server.
+    """
+
+
+class ParityOSCompilerError(ParityOSException):
+    """
+    Exception resulting from errors in the compiler on the ParityOS cloud server.
+    """
+
+
+class ParityOSTimeoutException(ParityOSException):
+    """
+    Exception resulting from time-outs waiting for a response from the ParityOS cloud server.
+    """

parityos-0.0.6/parityos/base/__init__.py

@@ -0,0 +1,48 @@
+"""
+Parity Quantum Computing GmbH
+Rennweg 1 Top 314
+6020 Innsbruck, Austria
+
+Copyright (c) 2020-2024.
+All rights reserved.
+
+Basic data structures to describe gates, circuits and optimization problems.
+"""
+
+from .circuit import Circuit
+from .constraints import ConfigurationType, EqualityConstraint, evaluate_parity, ParityConstraint
+from .exceptions import ParityOSException, ParityOSImportError
+from .gates import (
+    CCNOT,
+    CH,
+    CNOT,
+    CP,
+    CRx,
+    CRy,
+    CRz,
+    CY,
+    CZ,
+    DEFAULT_PARAMETER_NAME,
+    Gate,
+    H,
+    ISwap,
+    MultiControlledH,
+    MultiControlledRx,
+    MultiControlledRy,
+    MultiControlledRz,
+    Rx,
+    Ry,
+    Rz,
+    Rxx,
+    Ryy,
+    Rzz,
+    Rzzzz,
+    Swap,
+    SX,
+    X,
+    Y,
+    Z,
+)
+from .problem_representation import Hamiltonian, ProblemRepresentation
+from .qubits import Qubit, QubitLabel
+from .utils import json_wrap, dict_filter, JSONType, JSONMappingType, JSONLoadSaveMixin