parityos — ParityOS 2.1.1 documentation

# parityos

class parityos.CompilerClient(username: str = None, host: str = 'api.parityqc.com', url_prefix: str = 'v1', http_retries: int = 3, http_timeout: int = 10, http_backoff_factor: float = 0.02, intents: int = 3)

  Class to be used to make requests to the ParityQC API. It provides methods for compiling a `ProblemRepresentation`, both synchronously and asynchronously, and gives access to all the ParityQC API services.

  compile(optimization_problem: ProblemRepresentation, device_model: DeviceModelBase, preset: str = None, timeout: int = 900, **kwargs) → ParityOSOutput

    Compiles a logical problem on the given device model. A preset defining the compiler options must be given.

    Parameters:

      - optimization_problem – ProblemRepresentation object defining the optimization problem.

      - device_model – DeviceModel object defining the target device.

      - preset – the compiler preset to be used. `analog_default` and `digital_default` are available for everyone; other allowed presets are communicated on a per-customer basis. Optional. If no value is provided, `device_model.preset` is used instead.

      - timeout – time in seconds after which this function is aborted.

    Returns:

      ParityOSOutput object containing all information about the compiled problem

  get_compiler_runs(submission_id: str) → list[CompilerRun]

    Get the compiler runs spawned by a submission.

    Parameters:

      submission_id – id of submission

    Returns:

      list of the compiler runs

  get_solutions(compiler_run: CompilerRun) → list[ParityOSOutput]

    Get the solutions found by a compiler run.

    Parameters:

      compiler_run – CompilerRun object

    Returns:

      List of ParityOSOutput objects representing the solutions

  get_submission(submission_id: str) → dict

    Returns the submission given a submission id

  submit(optimization_problem: ProblemRepresentation, device_model: DeviceModelBase, **options) → str

    Asynchronously submit a problem to the compiler, returns a submission id which can be used to request the corresponding compiler runs. The compiler run object can then be used to obtain the solutions.

    Parameters:

      - optimization_problem – ProblemRepresentation object defining the optimization problem.

      - device_model – DeviceModel object defining the target device.

      - options – options to pass to compilation algorithms. For now this is just a single key `preset` with value `analog_default` or `digital_default`. Other presets available upon request.

    Returns:

      id associated with the submission

class parityos.Hamiltonian(interactions: Sequence[Iterable[Qubit]], coefficients: Sequence, constraints: Iterable[ParityConstraint] = None)

  The deprecated version of the ProblemRepresentation class

  Representation of a Hamiltonian (diagonal in the Pauli-Z basis) together with an optional set of ParityConstraint objects.

  __init__(interactions: Sequence[Iterable[Qubit]], coefficients: Sequence, constraints: Iterable[ParityConstraint] = None)
    Parameters:

      - interactions – The interactions in the Hamiltonian. Each interaction should be given as a collection of Qubits.

      - coefficients – The coefficients in the Hamiltonian, in a sequence that aligns with the interaction sequence. Coefficients could be floats or any other type, but the evaluate method might not work for non-numerical types.

      - constraints – Optional hard parity constraints which must be satisfied by the solutions of the corresponding logical problem.

    Example:

        optimization_problem = Hamiltonian(
            [{Qubit(1)}, {Qubit(1), Qubit(2)}],
            (0.5, -0.8),
            constraints = {ParityConstraint({Qubit(0), Qubit(2)}, 1)},
        )

exception parityos.ParityOSException

  General exception thrown by ParityOS.

exception parityos.ParityOSImportError

  ImportError related to uninstalled optional ParityOS dependencies.

class parityos.ParityOSOutput(compiled_problem: ProblemRepresentation, mappings: Mappings, constraint_circuit: Circuit = None, problem_circuit: Circuit = None, driver_circuit: Circuit = None, initial_state_preparation_circuit: Circuit = None)
  __init__(compiled_problem: ProblemRepresentation, mappings: Mappings, constraint_circuit: Circuit = None, problem_circuit: Circuit = None, driver_circuit: Circuit = None, initial_state_preparation_circuit: Circuit = None)

    This class contains all the output that ParityOS produces, this may be extended with extra features in the future, but for now it contains the compiled problem, the mappings and in case of digital devices also the constraint circuit.

    Parameters:

      - compiled_problem – compiled problem representation with parity constraints

      - mappings – Mappings object representing the mapping between the logical and the physical problem.

      - constraint_circuit – constraint Circuit (\(e^{-i \theta Z_1 Z_2 Z_3 [Z_4] /2}\) ) for digital devices or None for analog devices.

      - problem_circuit – problem circuit implementing the spin Hamiltonian corresponding to the logical problem for digital devices or None for analog devices.

      - driver_circuit – optional driver Circuit for digital devices or None for analog devices.

      - initial_state_preparation_circuit – The initial-state preparation circuit tells how to make the initial state, starting from the computational basis state \(|0\langle^K\). For normal QAOA, one would want to start in the \(|+\langle^K\) state for all qubits, so it would be a combination of RX and RZ or a Hadamard. The gates in this circuit are fixed, as they do not have a QAOA parameter, but should be executed with this exact angle.

  create_default_problem_circuit() → Circuit

    Create a circuit that implements $ exp(i mbox{parameter} H) $, where H is the spin Hamiltonian of the compiled problem representation. This spin Hamiltonian encodes the spin interactions of the original problem representation. Equality conditions from the original problem representation will have been absorbed in the parity constraints, for which the constraint_circuit attribute provides a separate circuit.

    Returns:

      a Circuit instance that implements the exponential of the Hamiltonian.

  encode_problem(problem_representation: ProblemRepresentation) → Self

    Creates a new ParityOSOutput instance that encodes the logical problem representation given as an argument, but expressed in terms of the physical qubits and the parity constraints contained in the original ParityOSOutput instance.

    Parameters:

      problem_representation – A new problem representation whose interactions are compatible with the compiled problem of the ParityOSOutput.

    Returns:

      a new ParityOSOutput instance where the interaction coefficients are updated to the ones from the new problem representation. The mappings are copied from the original ParityOS output. If circuits are included in the original instance, then these are copied to the new instance, with updated angles for the parametrized gates in the problem circuit.

  classmethod from_json(data: Mapping[str, str | int | float | bool | None | dict[str, JSONType] | list[JSONType]]) → Self

    Creates the ParityOSOutput class from the format in the response schema.

    Parameters:

      data – a JSON-like dictionary as specified in the response schema.

    Returns:

      a ParityOSOutput object

  property logical_problem_circuit: Circuit

    The same as self.problem_circuit, for compatibility.

  replace_cnots_by_rzzs()

    Replace the CNOT gates in self.constraint_circuit by ZZ and local rotations. This is useful for devices that have native ZZ rotations instead of native CNOTs. It replaces the self.constraint_circuit attribute in place.

  to_json() → dict[str, str | int | float | bool | None | dict[str, str | int | float | bool | None | dict[str, JSONType] | list[JSONType]] | list[str | int | float | bool | None | dict[str, JSONType] | list[JSONType]]]

    Repackages self into the response schema dictionary.

    Returns:

      dictionary as specified in the response schema

class parityos.ProblemRepresentation(interactions: Sequence[Iterable[Qubit]], coefficients: Sequence = None, constraints: Iterable[EqualityConstraint] = None)

  Representation of an optimization problem as a spin Hamiltonian (diagonal in the Pauli-Z basis) together with an optional set of EqualityConstraint objects.

  __init__(interactions: Sequence[Iterable[Qubit]], coefficients: Sequence = None, constraints: Iterable[EqualityConstraint] = None)
    Parameters:

      - interactions – The interactions from the spin Hamiltonian that represents the optimization problem, including the single-body terms. The interactions should be given as collections of Qubits, where each collection of qubits specifies an operator equal to the product of Z operators on each of the qubits.

      - coefficients – Optional. The coefficients in the spin Hamiltonian, in a sequence that aligns with the interactions sequence. Defaults to a list of ones. Coefficients can be floats or any other type, but the evaluate method might not work for non-numerical types.

      - constraints – Optional equality constraints which must be satisfied by the solutions of the logical problem.

    Example:

        optimization_problem = ProblemRepresentation(
            [{Qubit(1)}, {Qubit(1), Qubit(2)}],
            (0.5, -0.8),
            constraints = {EqualityConstraint({Qubit(0), Qubit(2)}, 1)},
        )

  evaluate(configuration: Mapping[Qubit, int], constraint_strength: float = inf) → float

    Evaluates the value of the spin Hamiltonian and the constraints on a particular configuration of qubit spin values, where each qubit spin has a value Z = +1 or -1.

    Each qubit in the compiled problem must be in this dictionary. Use the ParityDecoder to obtain a full configuration from a partial configuration if necessary.

    Parameters:

      - configuration – a mapping from qubits to spin values Z = +1 or -1.

      - constraint_strength – the strength to use for the constraints. By default, if no constraint_strength is given, hard constraints are used. In this case a float(inf) value is returned if any of the constraints is violated, or the unconstrained energy of the spin Hamiltonian otherwise. A zero value for this parameter will always result in the unconstrained energy and no constraints will be checked. A non-zero value will result in soft constraints, with a bonus proportional to the constraint strength for each valid constraint and a penalty of equal size for each constraint that is violated.

    Returns:

      Value of the given configuration in this problem representation.

    Return type:

      float

  classmethod from_json(data: Mapping[str, str | int | float | bool | None | dict[str, JSONType] | list[JSONType]]) → Self

    Constructs a problem representation object from JSON data.

    Parameters:

      data – a JSON-like dictionary with `'interactions'`, `'coefficients'` and `'constraints'` fields

    Returns:

      a ProblemRepresentation object

  classmethod from_nx_graph(graph: networkx.Graph, *args, **kwargs)
    Parameters:

      graph – A graph representing an optimization problem; nodes are interpreted as binary variables, and edges between them are interpreted as interactions between them (with strength given by the `weight` data on each edge).

    Returns:

      the problem representation associated with the given `graph`

  property qubits: set[Qubit]

    Set of Qubits which appear in the interactions or in the constraints.

  property terms: Iterator[tuple[frozenset[Qubit], object]]

    A property that returns an iterable of all (interaction, coefficient) pairs

  to_json() → dict[str, str | int | float | bool | None | dict[str, str | int | float | bool | None | dict[str, JSONType] | list[JSONType]] | list[str | int | float | bool | None | dict[str, JSONType] | list[JSONType]]]

    Converts the problem representation to json.

    Returns:

      the problem representation in json-serializable format

class parityos.Qubit(label: int | str | tuple[int, ...])

  Represents a qubit, can be a physical qubit or a logical qubit.

  Parameters:

    label – The label of a qubit, can be either a string, an integer or a coordinate, such that it can be converted to a hashable form and exported to json. In the case of a coordinate, it is also possible to initialize it directly from json format, which for a tuple would be a list. This means that if you pass label = [2, 2], it will be converted to the coordinate label (2, 2).

  __init__(label: int | str | tuple[int, ...]) → None
  classmethod from_json(qubit_in_json: str | int | float | bool | None | dict[str, JSONType] | list[JSONType]) → Self

    Makes a Qubit object from a qubit in json

    Parameters:

      qubit_in_json – a qubit in json format

    Returns:

      a Qubit object

  to_json() → str | int | float | bool | None | dict[str, str | int | float | bool | None | dict[str, JSONType] | list[JSONType]] | list[str | int | float | bool | None | dict[str, JSONType] | list[JSONType]]
    Returns:

      qubit in json form

class parityos.RectangularAnalogDevice(length: int, width: int, include_triangles=True)

  Describes an analog rectangular quantum device.

  Attributes:
    qubit_connections: frozenset[frozenset[Qubit]]

      a list of connections (collections of qubits), which are the direct interactions that are available on the device.

    device_type: str

      the type of this device, can either be `'cnot'` or `'plaquette'`

    preset: str

      Determines the parameters that are passed on to the compiler in order to optimize the code for the device. Standard value is `'analog_default'`. Customer-specific presets can be provided upon request.

    shape: tuple(int, int)

      length and width of the rectangular device in number of qubits

    include_trianglesbool, default=True

      If True, then qubit connections for all triangles on each plaquette are included.

  __init__(length: int, width: int, include_triangles=True)
    Parameters:

      - length (int) – length of the rectangular lattice in qubits

      - width (int) – width of the rectangular lattice in qubits

      - include_triangles (bool) – if True, then qubit connections for all triangles on each plaquette are included. Defaults to True.

class parityos.RectangularDigitalDevice(length: int, width: int)

  Describes a digital rectangular quantum device.

  Attributes:
    qubit_connections: frozenset[frozenset[Qubit]]

      a list of connections (collections of qubits), which are the direct interactions that are available on the device.

    device_type: str

      the type of this device, can either be `'cnot'` or `'plaquette'`

    preset: str

      Determines the parameters that are passed on to the compiler in order to optimize the code for the device. Standard value is `'digital_default'`. Customer-specific presets can be provided upon request.

    shape: tuple(int, int)

      length and width of the rectangular device in number of qubits

  __init__(length: int, width: int)
    Parameters:

      - length (int) – length of the rectangular lattice in qubits

      - width (int) – width of the rectangular lattice in qubits