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
anddigital_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 valueanalog_default
ordigital_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
- 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 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