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

__init__(interactions: Sequence[Iterable[Qubit]], coefficients: Sequence, constraints: Iterable[ParityConstraint] = 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 optimization problem. For the compiled problem, this will contain the required parity constraints.

Example of a compiled problem:

optimization_problem = ProblemRepresentation(
    interactions=[{Qubit((0, 0))}, {Qubit((0, 1))}, {Qubit((1, 0))}],
    coefficients=(0.5, -0.8, 1.2),
    constraints={EqualityConstraint({Qubit((0, 0)), Qubit((0, 1)), Qubit((1, 0))}, 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 optimization problem. For the compiled problem, this will contain the required parity constraints.

Example of a compiled problem:

optimization_problem = ProblemRepresentation(
    interactions=[{Qubit((0, 0))}, {Qubit((0, 1))}, {Qubit((1, 0))}],
    coefficients=(0.5, -0.8, 1.2),
    constraints={EqualityConstraint({Qubit((0, 0)), Qubit((0, 1)), Qubit((1, 0))}, 1)}
)
evaluate(configuration: dict[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

evaluate_average_result(result: Mapping[str, int], qubits: Sequence[Qubit] = None, constraint_strength: float = inf) float
Parameters:
  • result – A mapping of bit strings to measurement counts (number of times bit string was measured out of all the shots that were taken).

  • qubits – optional argument that provides the Qubit instance for each index in the bitstring, by default: [Qubit(0), Qubit(1), Qubit(2)…]

  • constraint_strength – Optional param for evaluate method, see there for more info

Returns:

A weighted average of the number produced by the evaluate method for that configuration, weighted by the proportion of measurement counts found for each bitstring

evaluate_minimal_result(result: Mapping[str, int], qubits: Sequence[Qubit] = None, constraint_strength: float = inf) tuple[dict[Qubit, int], float]
Parameters:
  • result – A mapping of bit strings to measurement counts (number of times bit string was measured out of all the shots that were taken).

  • qubits – optional argument that provides the Qubit instance for each index in the bitstring, by default: [Qubit(0), Qubit(1), Qubit(2)…]

  • constraint_strength – Optional param for evaluate method, see there for more info

Returns:

The configuration produced from the bitstring that has the lowest energy with non-zero count, along with the corresponding energy

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