parityos 2.1.1__tar.gz

parityos-2.1.1/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-2.1.1/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.1
+Name: parityos
+Version: 2.1.1
+Summary: Python bindings to the ParityOS API
+Home-page: https://parityqc.com/
+Requires-Python: >=3.7
+Provides-Extra: cirq
+Provides-Extra: qiskit
+Provides-Extra: spinz
+Provides-Extra: all
+License-File: License.txt

parityos-2.1.1/README.md

@@ -0,0 +1,103 @@
+# 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 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-2.1.1/parityos/__init__.py

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

parityos-2.1.1/parityos/api_interface/__init__.py

@@ -0,0 +1,13 @@
+"""
+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 and to process the results.
+"""
+from .compiler_run import CompilerRun, CompilerRunStatus
+from .connection import ClientBase
+from .exceptions import ParityOSAuthError, ParityOSRequestError

parityos-2.1.1/parityos/api_interface/authentication.py

@@ -0,0 +1,86 @@
+"""
+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.
+"""
+import getpass
+import os
+from typing import Dict, Iterator
+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-2.1.1/parityos/api_interface/compiler_run.py

@@ -0,0 +1,83 @@
+"""
+Parity Quantum Computing GmbH
+Rennweg 1 Top 314
+6020 Innsbruck, Austria
+
+Copyright (c) 2020-2022.
+All rights reserved.
+
+Tools to process the results from the ParityOS cloud service.
+"""
+from enum import Enum
+
+from parityos.base import JSONMappingType
+
+
+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).
+    """
+
+    def __init__(
+        self,
+        id,
+        submission_id,
+        status,
+        submitted_at,
+        started_at=None,
+        finished_at=None,
+        failed_at=None,
+        failure_reason=None,
+    ):
+        """
+        :param id: id of the compiler run in ParityOS cloud database
+        :param submission_id: id of the submission which triggered compile run
+        :param status: status of the submission; see CompilerRunStatus enum
+        :param submitted_at: time at which run was queued for execution
+        :param started_at: time at which run started being executed
+        :param finished_at: time at which run was completed
+        :param failed_at: time at which run failed
+        :param failure_reason: reason for which run failed
+        """
+        self.id = id
+        self.submission_id = submission_id
+        self.status = CompilerRunStatus(status)
+        self.submitted_at = submitted_at
+        self.started_at = started_at
+        self.finished_at = finished_at
+        self.failed_at = failed_at
+        self.failure_reason = failure_reason
+
+    @classmethod
+    def from_json(cls, data: JSONMappingType) -> "CompilerRun":
+        """
+        Creates a CompilerRun object from a JSON-like data dictionary.
+        :return: a CompilerRun object
+        """
+        return cls(**data)
+
+    def __repr__(self):
+        args = (
+            self.id,
+            self.submission_id,
+            self.status.value,
+            self.submitted_at,
+            self.started_at,
+            self.finished_at,
+            self.failed_at,
+            self.failure_reason,
+        )
+        return f"{self.__class__.__name__}{args}"
+
+
+class CompilerRunStatus(Enum):
+    """
+    Enum for compiler run status.
+    """
+
+    SUBMITTED = "S"
+    RUNNING = "R"
+    COMPLETED = "C"
+    FAILED = "F"

parityos-2.1.1/parityos/api_interface/connection.py

@@ -0,0 +1,138 @@
+"""
+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 typing import Dict, Tuple
+
+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,
+        )
+        for credentials_data in authentication_intents:
+            response = self.http.post(f"{self.base_url}/auth", data=credentials_data)
+            data = response.json()
+            if "token" in data:
+                return credentials_data["username"], data["token"]
+
+        # No authentication intents left after failed logins
+        username = credentials_data["username"]
+        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 an 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-2.1.1/parityos/api_interface/exceptions.py

@@ -0,0 +1,27 @@
+"""
+Parity Quantum Computing GmbH
+Rennweg 1 Top 314
+6020 Innsbruck, Austria
+
+Copyright (c) 2020-2022.
+All rights reserved.
+
+Exceptions for errors from the ParityOS cloud services.
+"""
+from requests.exceptions import RequestException
+
+
+class ParityOSAuthError(RequestException, ValueError):
+    """
+    Exception for failed logins to the ParityAPI server.
+    """
+
+    pass
+
+
+class ParityOSRequestError(RequestException):
+    """
+    Exception for failed logins to the ParityAPI server.
+    """
+
+    pass

parityos-2.1.1/parityos/base/__init__.py

@@ -0,0 +1,7 @@
+from .circuit import Circuit
+from .constraints import EqualityConstraint
+from .exceptions import ParityOSException, ParityOSImportError
+from .gates import Gate, CNOT, H, X, Y, Z, Rx, Ry, Rz, Rzz
+from .problem_representation import ProblemRepresentation
+from .qubits import Qubit
+from .utils import json_wrap, dict_filter, JSONType, JSONMappingType, JSONLoadSaveMixin

parityos-2.1.1/parityos/base/circuit.py

@@ -0,0 +1,142 @@
+"""
+Parity Quantum Computing GmbH
+Rennweg 1 Top 314
+6020 Innsbruck, Austria
+
+Copyright (c) 2020-2022.
+All rights reserved.
+
+Classes that store information on sequences of quantum gates
+"""
+from math import pi
+from typing import Iterator, Mapping, Set, Union
+
+from parityos.base.qubits import Qubit
+from parityos.base.gates import Gate, CNOT, Rx, Ry, Rz, Rzz
+from parityos.base.utils import json_wrap, JSONLoadSaveMixin
+from parityos.base.exceptions import ParityOSException
+
+
+class Circuit(JSONLoadSaveMixin, list):
+    """
+    A sequence of Gate and/or Circuit objects.
+    """
+
+    @property
+    def qubits(self) -> Set[Qubit]:
+        """
+        :return: All qubits from the elements in the circuit
+        """
+        return set().union(*(element.qubits for element in self))
+
+    @classmethod
+    def from_json(cls, data):
+        """
+        Creates a Circuit from a list of elements in json
+
+        :param data: a list of elements in json format
+        :return: a Circuit object
+        """
+        data = _remove_empty_lists(data)
+        args = (
+            Gate.from_json(element_data)
+            if isinstance(element_data[0], str)
+            else cls.from_json(element_data)
+            for element_data in data
+        )
+        return cls(args)
+
+    def to_json(self):
+        """
+        Converts the Container to json
+
+        :return: a list with the elements of the circuit in json format
+        """
+        return [json_wrap(element) for element in self]
+
+    def remap(self, context: Mapping = None, **kwargs) -> "Circuit":
+        """
+        Creates a copy of the circuit where the remap has been applied to all parametrized gates
+        in the circuit (see `gates.RMixin.remap` for details).
+
+        :param context: a mapping of parameter names (strings) to parameter values (number-like
+                        objects) or to new parameter names (strings).
+        """
+        return Circuit((element.remap(context=context, **kwargs) for element in self))
+
+    def __repr__(self):
+        args = ", ".join(repr(element) for element in self)
+        return f"{self.__class__.__name__}([{args}])"
+
+
+CircuitElement = Union[Gate, Circuit]
+HALF_PI = 0.5 * pi
+
+
+def convert_cnots_to_rzzs(circuit: Circuit) -> Circuit:
+    """
+    ZZ rotations instead of CNOTs.
+
+    Replaces the standards CNOTs on the optimized circuit with an equivalent implementation based on
+    ZZ and local rotations. The resulting circuit will contain additional subcircuits to account
+    for the necessary Rx, Ry and Rz rotations.
+
+    :param circuit: a circuit containing moments with CNOT gates.
+    :type circuit: Circuit
+    :return: a new circuit where all CNOTs have been replaced by ZZ and local rotations.
+    :rtype: Circuit
+    """
+    new_circuit = Circuit()
+    for subcircuit in circuit:
+        if not isinstance(subcircuit, Circuit):
+            # This situation can occur when gates and subcircuits were mixed together at the same
+            # level. We raise an error in this case, because this method expects gates to be grouped
+            # in moments (i.e. parallelizable subcircuits).
+            raise ParityOSException(
+                "Unexpected mix of gates and subcircuits encountered. Please "
+                "organize gates in moments (parallelizable subcircuits)."
+            )
+        elif all(isinstance(element, Gate) for element in subcircuit):
+            new_circuit.extend(_convert_moment(subcircuit))
+        else:
+            new_circuit.append(convert_cnots_to_rzzs(subcircuit))
+
+    return new_circuit
+
+
+def _convert_moment(circuit) -> Iterator[Circuit]:
+    """
+    A helper function for convert_cnots_to_rzzs.
+    Lowest level circuits are expanded and have cnots turned into rzzs. This results in additional
+    circuits to be added before and after the moment circuit to account for the necessary Rx, Ry
+    and Rz rotations.
+
+    :return: a list of circuits representing the original circuit where cnots have been converted to
+        rzz gates.
+    """
+    before, moment, after1, after2 = Circuit(), Circuit(), Circuit(), Circuit()
+    # Representing a Cnot as a ZZ interaction requires the injection of a moment before and two
+    # moments after the original moment.
+    for gate in circuit:
+        if not isinstance(gate, CNOT):
+            # Copy the other gates directly to the new moment.
+            moment.append(gate)
+        else:
+            control, target = gate.qubit_list
+            # Add the necessary rotation before the ZZ interaction.
+            before.append(Ry(target, -HALF_PI))
+            # Replace the CNOT with a ZZ rotation.
+            moment.append(Rzz(control, target, -HALF_PI))
+            # Add the remaining rotations after the ZZ interaction.
+            after1.append(Rx(target, HALF_PI))
+            after2.append(Rz(control, HALF_PI))
+            after2.append(Rz(target, HALF_PI))
+
+    return (subcircuit for subcircuit in [before, moment, after1, after2] if subcircuit)
+
+
+def _remove_empty_lists(data):
+    empty_list = []
+    for _ in range(data.count(empty_list)):
+        data.remove(empty_list)
+    return data