service¶

class parityos.services.service.InputDataT¶

A contravariant TypeVar representing input data of any type.

alias of TypeVar(‘InputDataT’, contravariant=True)

class parityos.services.service.OutputDataT¶

A covariant TypeVar representing output data of any type.

alias of TypeVar(‘OutputDataT’, covariant=True)

parityos.services.service.to_raw_serialized_data(obj: Any) → Any¶

Serialize obj and only return the raw serialized data without injected class information.

This is used for objects that are sent in json format directly over the API, which only handles raw serialized data without injected class tags.

Parameters:: obj – Object to serialize.
Returns:: Serialized data without class tag.

parityos.services.service.from_raw_serialized_data(data: Any, cls: type[T]) → T¶

Construct an instance of class cls from its raw serialized data dict representation that has no class tag injected. The class to deserialize to needs to be given explicitly.

This is used for objects that are sent in json format directly over the API, which only handles raw serialized data without injected class tags.

Parameters:

data – Serialized data.
cls – Type of the class to construct.

Returns:

Instance of class cls reconstructed from data.

class parityos.services.service.ServiceJobData(input_data: InputDataT, configuration, description: str = '')¶

Bases: Generic[InputDataT]

Data passed to the service for a service job.

Fields correspond to input parameters of Service.run or AsyncService.submit.

input_data: InputDataT¶: Input data to start from as input for the service (e.g. problem representation)

configuration: str | dict[str, Any]¶: Parameters for the service itself (e.g. number of iterations)

description: str¶: Description of job data as string. Defaults to empty.

class parityos.services.service.Service(*args, **kwargs)¶

Bases: Protocol[InputDataT, OutputDataT]

Interface for running services in ParityOS.

run(input_data: InputDataT, configuration: str | dict[str, Any] | None = None, description: str = '') → OutputDataT¶: Runs the full service synchronously, from input to output.

class parityos.services.service.AsyncService(*, time_between_trials: float = 2, timeout: float = 900)¶

Bases: Service[InputDataT, OutputDataT], Protocol

Interface for services that can run asynchronously.

time_between_trials: float¶: Time between checks if the result is ready in seconds. Defaults to 2.

timeout: float¶: Maximum time for a single job in seconds. Defaults to 900 (15 minutes).

run(input_data: InputDataT, configuration: str | dict[str, Any] | None = None, description: str = '') → OutputDataT¶

A synchronous blocking wrapper around the asynchronous functionality of this class.

It performs the following steps:

Submit job with passed parameters

Query status of submitted job every time_between_trials seconds for at most
timeout seconds.

If the status of the job has turned to JobStatus.COMPLETED, fetch and return the result.

Raise if job failed or didn’t finish before timeout.

Parameters:

input_data – Input data to start from as input for the service (e.g. problem representation).
configuration – preset string or configuration dict with concrete configuration parameters (if license permits). Optional.
description – Description of the job. Defaults to empty string.

Returns:

The result returned by the service.

Raises:

ParityOSTimeoutException – if the maximum time for a job has elapsed.

submit(input_data: InputDataT, configuration: str | dict[str, Any] | None = None, description: str = '') → str¶: Submit input data and return a job id string that can be used to get results.

get_info(job_id: str) → JobInfo¶

Get information on the current status of a submission.

Parameters:: job_id – The unique id of the job for which to get information.
Returns:: Current status of the job.

get_result(job_id: str) → OutputDataT¶

Get the output for a submission, the caller is responsible for making sure the job is complete (by calling get_info).

Parameters:: job_id – The unique id of the job for which to get results.
Returns:: Current status of the job.
Raises:: ParityOSJobError – If no results are available for the job.

class parityos.services.service.APIService(client: Client, *, time_between_trials: float = 2, timeout: float = 900)¶

Bases: AsyncService[InputDataT, OutputDataT], Protocol

Interface for services that can connect to ParityAPI.

name: ClassVar[str]¶: Name of this service. Subclasses must implement this ClassVar.

input_data_type: ClassVar[type[InputDataT]]¶: Input data type for submit. Used for serialization. Subclasses must implement this ClassVar.

output_data_type: ClassVar[type[OutputDataT]]¶: Return type of submit. Used for deserialization. Subclasses must implement this ClassVar.

client: Client¶: API client that manages communication with ParityAPI.

submit(input_data: InputDataT, configuration: str | dict[str, Any] | None = None, description: str = '') → str¶

Asynchronously submit a request and return a submission id which can be used to fetch the results.

Parameters:

input_data – Input data to start from as input for the service (e.g. problem
representation).
configuration – Parameters for the service itself (e.g. number of iterations).
description – Description of the job.

Returns:

The ID of the job returned by the API.

get_info(job_id: str) → JobInfo¶

Get information on the current status of a submission.

Parameters:: job_id – The unique id of the job for which to get information.
Returns:: Current status of the job.

get_result(job_id: str) → OutputDataT¶

Get the output for a submission, the caller is responsible for making sure the job is complete (by calling get_info).

Parameters:: job_id – The unique id of the job for which to get results.
Returns:: Current status of the job.
Raises:: ParityOSJobError – If no results are available for the job.

class parityos.services.service.LayoutInput(problem: ProblemRepresentation[Qubit[int] | Qubit[str]], device: DeviceConnectivity[Qubit[Point2D[int]]])¶

Bases: object

Input for a LayoutService job.

final class parityos.services.service.LayoutService(client: Client, *, time_between_trials: float = 2, timeout: float = 900)¶

Bases: APIService[LayoutInput, ParityMapping[Qubit, Qubit]]

Service for generating an optimal ParityMapping for a given LayoutInput.

name: ClassVar[str] = 'layout'¶: Name of this service. Subclasses must implement this ClassVar.

input_data_type¶: alias of LayoutInput

output_data_type¶: alias of ParityMapping

class parityos.services.service.CircuitInput(operator_polynomial: OperatorPolynomial[Z[Qubit[Point2D[int]]]] | OperatorPolynomial[X[Qubit[Point2D[int]]]], device: DeviceConnectivity[Qubit[Point2D[int]]])¶

Bases: object

Input for a CircuitService job.

final class parityos.services.service.CircuitService(client: Client, *, time_between_trials: float = 2, timeout: float = 900)¶

Bases: APIService[CircuitInput, FrozenCircuit[Qubit[Point2D[int]]]]

Service for preparing a circuit for applying (the exponential of) an OperatorPolynomial on a given device connectivity.

name: ClassVar[str] = 'circuit'¶: Name of this service. Subclasses must implement this ClassVar.

input_data_type¶: alias of CircuitInput

output_data_type¶: alias of FrozenCircuit

class parityos.services.service.DriverInput(compiled_problem: ProblemRepresentation[Qubit[Point2D[int]]], device: DeviceConnectivity[Qubit[Point2D[int]]])¶

Bases: object

Input for a DriverService job.

class parityos.services.service.DriverOutput(constraint_hamiltonian: OperatorPolynomial[Z[Qubit[Point2D[int]]]], x_driver_hamiltonian: OperatorPolynomial[X[Qubit[Point2D[int]]]], exchange_driver_hamiltonian: OperatorPolynomial[ExchangeTerm[Qubit[Point2D[int]]]])¶

Bases: object

Output from a DriverService job.

final class parityos.services.service.DriverService(client: Client, *, time_between_trials: float = 2, timeout: float = 900)¶

Bases: APIService[DriverInput, DriverOutput]

Service for for generating constraint preserving QAOA driver Hamiltonians from a given compiled ProblemRepresentation on a given device connectivity.

name: ClassVar[str] = 'driver'¶: Name of this service. Subclasses must implement this ClassVar.

input_data_type¶: alias of DriverInput

output_data_type¶: alias of DriverOutput

class parityos.services.service.InitialStateInput(x_driver_hamiltonian: OperatorPolynomial[X[Qubit[Point2D[int]]]], sum_constraints: frozenset[SumConstraint[Qubit[Point2D[int]]]], device: DeviceConnectivity[Qubit[Point2D[int]]])¶

Bases: object

Input for a InitialStateService job.

final class parityos.services.service.InitialStateService(client: Client, *, time_between_trials: float = 2, timeout: float = 900)¶

Bases: APIService[InitialStateInput, FrozenCircuit[Qubit[Point2D[int]]]]

Service for preparing a suitable initial state for a constraint preserving QAOA optimization from a constraint preserving driver Hamiltonian and explicit constraints on a given device connectivity.

Outputs of the DriverService can be used as inputs for this service.

name: ClassVar[str] = 'initial_state'¶: Name of this service. Subclasses must implement this ClassVar.

input_data_type¶: alias of InitialStateInput

output_data_type¶: alias of FrozenCircuit

class parityos.services.service.TwineQAOAInput(problem: ProblemRepresentation[Qubit], device: DeviceModel[Qubit, BasicQubitProperties | None, BasicGateProperties | None])¶

Bases: object

Input for a TwineQAOAService job.

class parityos.services.service.TwineQAOAOutput(parameterized_circuit: CircuitLike[Qubit], relabeling_map: dict[Qubit, Qubit])¶

Bases: object

Output from a TwineQAOAService job.

final class parityos.services.service.TwineQAOAService(client: Client, *, time_between_trials: float = 2, timeout: float = 900)¶

Bases: APIService[TwineQAOAInput, TwineQAOAOutput]

Service for generating a Parity Twine circuit for applying (the exponential of) a problem Hamiltonian on a given DeviceModel in the context of a QAOA optimization.

name: ClassVar[str] = 'twine_qaoa'¶: Name of this service. Subclasses must implement this ClassVar.

input_data_type¶: alias of TwineQAOAInput

output_data_type¶: alias of TwineQAOAOutput

class parityos.services.service.TwineQFTInput(number_of_qubits: int, device: DeviceModel[Qubit, BasicQubitProperties | None, BasicGateProperties | None])¶

Bases: object

Input for a TwineQFTService job.

class parityos.services.service.TwineQFTOutput(parameterized_circuit: CircuitLike[Qubit], relabeling_map: dict[Qubit, int])¶

Bases: object

Output from a TwineQFTService job.

final class parityos.services.service.TwineQFTService(client: Client, *, time_between_trials: float = 2, timeout: float = 900)¶

Bases: APIService[TwineQFTInput, TwineQFTOutput]

Service for generating a Parity Twine circuit for QFT.

name: ClassVar[str] = 'twine_qft'¶: Name of this service. Subclasses must implement this ClassVar.

input_data_type¶: alias of TwineQFTInput

output_data_type¶: alias of TwineQFTOutput