parityos 0.0.6__py3-none-any.whl

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/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/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/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/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/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

parityos/base/circuit.py

@@ -0,0 +1,219 @@
+"""
+Parity Quantum Computing GmbH
+Rennweg 1 Top 314
+6020 Innsbruck, Austria
+
+Copyright (c) 2020-2024.
+All rights reserved.
+
+Classes that store information on sequences of quantum gates
+"""
+
+from collections.abc import Iterator, Mapping, Sequence
+from math import pi
+from typing import Union
+
+from parityos.base.exceptions import ParityOSException
+from parityos.base.gates import Gate, CNOT, RMixin, Rx, Ry, Rz, Rzz
+from parityos.base.qubits import Qubit
+from parityos.base.utils import json_wrap, JSONLoadSaveMixin, JSONType
+
+
+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))
+
+    @property
+    def parameters(self) -> set[str]:
+        """
+        :return: the set of parameters (strings)
+        """
+        parameters = set()
+        for gate_or_circuit_element in self:
+            if hasattr(gate_or_circuit_element, "parameters"):
+                parameters.update(gate_or_circuit_element.parameters)
+
+        return parameters
+
+    def get_hermitian_conjugate(self) -> "Self":
+        """
+        Returns the Hermitian conjugate (inverse) of the circuit
+        :return: a new Circuit instance
+        """
+        return type(self)(element.get_hermitian_conjugate() for element in reversed(self))
+
+    def generate_flat_gate_sequence(self) -> Iterator[Gate]:
+        """
+        Generates a sequence of all gates in the circuit and its subcircuits.
+
+        :returns: A generator that loops over all gates in the circuit and its subcircuits.
+        """
+        for element in self:
+            if isinstance(element, Gate):
+                yield element
+            else:
+                yield from element.generate_flat_gate_sequence()
+
+    @classmethod
+    def from_json(cls, data: Sequence[Sequence[JSONType]]) -> "Self":
+        """
+        Creates a Circuit from a list of elements in json
+
+        :param data: a list of elements in json format
+        :return: a Circuit object
+        """
+        args = (
+            (
+                Gate.from_json(element_data)
+                if isinstance(element_data[0], str)
+                else cls.from_json(element_data)
+            )
+            for element_data in data
+            if element_data
+        )
+        return cls(args)
+
+    def to_json(self) -> list[JSONType]:
+        """
+        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 modify_angle(
+        self,
+        angle_map: Mapping[frozenset[Qubit], float],
+        gate_type: type[RMixin] = None,
+        parameter_name: str = None,
+    ) -> "Self":
+        """
+        Create a new circuit with the same subcircuits and gates as this one, except for the
+        rotation gates of the given gate type and with the given parameter_name as parameter,
+        for which the angle will be changed to the values given by the angle map, in function
+        of the qubit(s) on which the gate acts. If the qubit(s) are not included in the angle map,
+        then the angle is left unchanged.
+
+        If the gate type is not specified, then all rotation gates might be affected. If the
+        parameter name is not specified, then also gates without parameters might be affected.
+
+        :param angle_map: A mapping that provides a new angle for each of the qubit sets on which
+                          the gates might act.
+        :param gate_type: Optional. If given, then only gates of this type will be updated. Other
+                          gates will be copied into the new circuit without changes. Default is
+                          None.
+        :param parameter_name: Optional. If given, then only gates with this parameter name will be
+                               updated. Other gates will be copied into the new circuit without
+                               changes. Default is None.
+
+        :returns: A new circuit with all the gates copied over from the current circuit, except for
+                  selected rotation gates for which the rotation angle will have been modified.
+                  Default is None.
+
+        """
+        return type(self)(
+            element.modify_angle(angle_map, gate_type=gate_type, parameter_name=parameter_name)
+            for element in self
+        )
+
+    def __repr__(self):
+        args = ", ".join(repr(element) for element in self)
+        return f"{self.__class__.__name__}([{args}])"
+
+    def __add__(self, other):
+        return type(self)(list.__add__(self, other))
+
+    def __mul__(self, other):
+        return type(self)(list.__mul__(self, other))
+
+    def __rmul__(self, other):
+        return type(self)(list.__rmul__(self, other))
+
+    def __getitem__(self, key):
+        # Convert slices of circuits to again to Circuits
+        item = list.__getitem__(self, key)
+        return type(self)(item) if isinstance(key, slice) else item
+
+
+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.make_args()
+            # 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)