qilisdk.speqtrum.speqtrum_models

Attributes

TFunctionalResult_co
TVariationalInnerResult
TExperimentResult
ResultExtractor	Type alias for a callable that extracts a typed result from an ExecuteResult.

Classes

SpeQtrumModel	Base Pydantic model for all SpeQtrum API data structures.
LoginPayload	Placeholder model for the login request payload.
Token	Represents the structure of the login response:
DeviceStatus	Enumeration of possible device statuses reported by the SpeQtrum API.
DeviceType	Enumeration of hardware device types available in SpeQtrum.
Device	Description of a quantum device registered in SpeQtrum.
ExecuteType	Discriminator for the type of functional or experiment being executed.
DigitalPropagationPayload	Payload model wrapping a DigitalPropagation and its readout methods for API submission.
AnalogEvolutionPayload	Payload model wrapping an AnalogEvolution and its readout methods for API submission.
QuantumReservoirPayload	Payload model wrapping a QuantumReservoir and its readout methods for API submission.
VariationalProgramPayload	Payload model wrapping a VariationalProgram and its readout methods for API submission.
ExperimentPayload	Generic payload wrapping any ExperimentFunctional for API submission.
ExecutePayload	Top-level execution payload sent to the SpeQtrum /execute endpoint.
ExecuteResult	Deserialized execution result returned by the SpeQtrum API.
JobHandle	Strongly typed reference to a submitted SpeQtrum job.
JobStatus	Enumeration of possible job lifecycle states.
JobType	Enumeration of job categories used by the SpeQtrum scheduler.
JobId	Handle/reference you normally get back immediately after POST /execute.
JobInfo	Light-weight representation suitable for 'list jobs' and polling
JobDetail	Full representation returned by GET /jobs/{id} when payload/result/logs
TypedJobDetail	JobDetail subclass that exposes a strongly typed get_results method.

Module Contents

class SpeQtrumModel(/, **data: Any)

Bases: pydantic.BaseModel

Base Pydantic model for all SpeQtrum API data structures.

Configures alias resolution and arbitrary-type support used throughout the SpeQtrum payload and response models.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class LoginPayload(/, **data: Any)

Bases: pydantic.BaseModel

Placeholder model for the login request payload.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

class Token(/, **data: Any)

Bases: SpeQtrumModel

Represents the structure of the login response: { “accessToken”: “…”, “expiresIn”: 123456789, “issuedAt”: “123456789”, “refreshToken”: “…”, “tokenType”: “bearer” }

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

access_token: str = None

expires_in: int = None

issued_at: int = None

refresh_token: str = None

token_type: str = None

class DeviceStatus

Bases: str, enum.Enum

Enumeration of possible device statuses reported by the SpeQtrum API.

Initialize self. See help(type(self)) for accurate signature.

ONLINE = 'online'

MAINTENANCE = 'maintenance'

OFFLINE = 'offline'

class DeviceType

Bases: str, enum.Enum

Enumeration of hardware device types available in SpeQtrum.

Initialize self. See help(type(self)) for accurate signature.

QPU_ANALOG = 'qpu.analog'

QPU_DIGITAL = 'qpu.digital'

SIMULATOR = 'simulator'

class Device(/, **data: Any)

Bases: SpeQtrumModel

Description of a quantum device registered in SpeQtrum.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

code: str = None

nqubits: int = None

name: str = None

description: str = None

type: DeviceType = None

status: DeviceStatus = None

class ExecuteType

Bases: str, enum.Enum

Discriminator for the type of functional or experiment being executed.

Initialize self. See help(type(self)) for accurate signature.

DIGITAL_PROPAGATION = 'digital_propagation'

ANALOG_EVOLUTION = 'analog_evolution'

QUANTUM_RESERVOIR = 'quantum_reservoir'

VARIATIONAL_PROGRAM = 'variational_program'

EXPERIMENT = 'experiment'

class DigitalPropagationPayload(/, **data: Any)

Bases: SpeQtrumModel

Payload model wrapping a DigitalPropagation and its readout methods for API submission.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

digital_propagation: qilisdk.functionals.DigitalPropagation = None

readout: qilisdk.readout.Readout = None

class AnalogEvolutionPayload(/, **data: Any)

Bases: SpeQtrumModel

Payload model wrapping an AnalogEvolution and its readout methods for API submission.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

analog_evolution: qilisdk.functionals.AnalogEvolution = None

readout: qilisdk.readout.Readout = None

class QuantumReservoirPayload(/, **data: Any)

Bases: SpeQtrumModel

Payload model wrapping a QuantumReservoir and its readout methods for API submission.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

quantum_reservoir: qilisdk.functionals.QuantumReservoir = None

readout: qilisdk.readout.Readout = None

class VariationalProgramPayload(/, **data: Any)

Bases: SpeQtrumModel

Payload model wrapping a VariationalProgram and its readout methods for API submission.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

variational_program: qilisdk.functionals.VariationalProgram = None

readout: qilisdk.readout.Readout = None

class ExperimentPayload(/, **data: Any)

Bases: SpeQtrumModel

Generic payload wrapping any ExperimentFunctional for API submission. Concrete experiment types are identified by their YAML tag inside the serialized experiment, so this single model handles every experiment and speqtrum never needs to import a concrete experiment class.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

experiment: qilisdk.experiments.ExperimentFunctional = None

class ExecutePayload(/, **data: Any)

Bases: SpeQtrumModel

Top-level execution payload sent to the SpeQtrum /execute endpoint.

Exactly one of the optional payload fields should be populated, matching the discriminator stored in type.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

type: ExecuteType = None

digital_propagation_payload: DigitalPropagationPayload | None = None

analog_evolution_payload: AnalogEvolutionPayload | None = None

quantum_reservoir_payload: QuantumReservoirPayload | None = None

variational_program_payload: VariationalProgramPayload | None = None

experiment_payload: ExperimentPayload | None = None

class ExecuteResult(/, **data: Any)

Bases: SpeQtrumModel

Deserialized execution result returned by the SpeQtrum API.

The type discriminator indicates which result field is populated. Use the corresponding accessor (e.g. functional_result, variational_program_result) to retrieve the typed payload.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

type: ExecuteType = None

functional_result: qilisdk.functionals.FunctionalResult | None = None

variational_program_result: qilisdk.functionals.VariationalProgramResult | None = None

experiment_result: qilisdk.experiments.ExperimentResult | None = None

TFunctionalResult_co

TVariationalInnerResult

TExperimentResult

ResultExtractor

Type alias for a callable that extracts a typed result from an ExecuteResult.

class JobHandle(/, **data: Any)

Bases: SpeQtrumModel, Generic[TFunctionalResult_co]

Strongly typed reference to a submitted SpeQtrum job.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

id: int

execute_type: ExecuteType

extractor: ResultExtractor[TFunctionalResult_co] = None

classmethod functional(job_id: int) → JobHandle[qilisdk.functionals.FunctionalResult]

Create a handle for a DigitalPropagation or AnalogEvolution job.

Parameters:

job_id (int) – Numeric identifier returned by the SpeQtrum service.

Returns:

A handle whose result type is FunctionalResult.

Return type:

JobHandle[FunctionalResult]

classmethod variational_program(job_id: int) → JobHandle[qilisdk.functionals.VariationalProgramResult]

classmethod variational_program(job_id: int, *, result_type: type[TVariationalInnerResult]) → JobHandle[VariationalProgramResult[TVariationalInnerResult]]

Create a variational-program handle for an existing job identifier.

Parameters:

• job_id – Numeric identifier returned by the SpeQtrum service.

• result_type – Optional functional result type expected within the variational program payload. When provided the returned handle enforces that the optimiser output matches this type.

Returns:

A handle whose get_results invocation yields a VariationalProgramResult preserving the requested inner result type when supplied.

Return type:

JobHandle

classmethod experiment(job_id: int) → JobHandle[qilisdk.experiments.ExperimentResult]

classmethod experiment(job_id: int, *, result_type: type[TExperimentResult]) → JobHandle[TExperimentResult]

Create a handle for any experiment job (generic path).

Parameters:

• job_id (int) – Numeric identifier returned by the SpeQtrum service.

• result_type – Optional concrete result type to validate against, taken from the submitted functional’s result_type. When provided, the returned handle enforces that the result matches this type.

Returns:

A handle whose get_results yields an ExperimentResult (the concrete type when result_type is supplied).

Return type:

JobHandle

bind(detail: JobDetail) → TypedJobDetail[TFunctionalResult_co]

Attach this handle’s typing information to a concrete job detail.

Parameters:

detail – Un-typed job detail payload returned by the SpeQtrum API.

Returns:

Wrapper exposing get_results with the typing captured when the handle was created.

Return type:

TypedJobDetail

class JobStatus

Bases: str, enum.Enum

Enumeration of possible job lifecycle states.

Initialize self. See help(type(self)) for accurate signature.

PENDING = 'pending'

Job has been queued but not yet validated

VALIDATING = 'validating'

Job has been validated and is queued for execution

QUEUED = 'queued'

Job is being executed on the device

RUNNING = 'running'

Job finished successfully

COMPLETED = 'completed'

Job failed due to an error

ERROR = 'error'

Job was cancelled by the user or system

CANCELLED = 'cancelled'

Job failed due to timeout

TIMEOUT = 'timeout'

class JobType

Bases: str, enum.Enum

Enumeration of job categories used by the SpeQtrum scheduler.

Initialize self. See help(type(self)) for accurate signature.

DIGITAL = 'digital'

PULSE = 'pulse'

ANALOG = 'analog'

QUANTUM_RESERVOIR = 'quantum_reservoir'

VARIATIONAL = 'variational'

class JobId(/, **data: Any)

Bases: SpeQtrumModel

Handle/reference you normally get back immediately after POST /execute.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

id: int = None

message: str | None = None

class JobInfo(/, **data: Any)

Bases: JobId

Light-weight representation suitable for ‘list jobs’ and polling when you do not need logs or results.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

name: str = None

description: str = None

device_id: int = None

status: JobStatus = None

created_at: pydantic.AwareDatetime = None

updated_at: pydantic.AwareDatetime | None = None

completed_at: pydantic.AwareDatetime | None = None

class JobDetail(/, **data: Any)

Bases: JobInfo

Full representation returned by GET /jobs/{id} when payload/result/logs are requested.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

payload: ExecutePayload | None = None

result: ExecuteResult | None = None

jobType: JobType | None = None

logs: str | None = None

error: str | None = None

error_logs: str | None = None

class TypedJobDetail(/, **data: Any)

Bases: JobDetail, Generic[TFunctionalResult_co]

JobDetail subclass that exposes a strongly typed get_results method.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

expected_type: ExecuteType = None

extractor: ResultExtractor[TFunctionalResult_co] = None

get_results() → TFunctionalResult_co

Return the strongly typed execution result.

Returns:

Result payload associated with the completed job, respecting the type information carried by the originating JobHandle.

Return type:

ResultT_co

Raises:

RuntimeError – If SpeQtrum has not populated the result payload or the execute type disagrees with the handle.