general_superstaq.models

Data models used when communicating with the superstaq server.

Attributes

`TERMINAL_CIRCUIT_STATES`
`TargetStr`
`UNSUCCESSFUL_CIRCUIT_STATES`

Classes

`AQTConfigs`	Model for AQT configs.
`BalanceResponse`	Model for returning a single user balance.
`CircuitStatus`	The possible statuses of a job/circuit.
`CircuitType`	The different languages that are recognized by Superstaq.
`DefaultPydanticModel`	Default pydantic model used across the superstaq server.
`ExternalProviderCredentials`	Model for storing a user's credentials for external providers.
`GetTargetsFilterModel`	Model for /get_target requests.
`JobCancellationResults`	The results from cancelling a job.
`JobData`	A class to store data for a Superstaq job which is returned through to the client.
`JobQuery`	The query model for retrieving jobs. Using multiple values in a field is interpreted as
`JobType`	The different types of jobs that can be submitted through Superstaq.
`NewJob`	The data model for submitting new jobs.
`NewJobResponse`	Model for the response when a new job is submitted.
`NewUser`	Model for creating new users.
`NewWorker`	Model for declaring a new machine worker.
`RetrieveTargetInfoModel`	Model for retrieving detailed target info.
`SimMethod`	The different simulation methods that are available.
`TargetInfo`	Model containing details info about a specific instance of a target.
`TargetModel`	Model for the details of a target.
`TargetStatus`	The current status of a Superstaq Target.
`UpdateUserDetails`	Model for requests which modify user details.
`UserInfo`	Model for the user info returned to the client.
`UserQuery`	Model for querying the database to retrieve users. Use of lists implied logical OR. Providing
`UserTokenResponse`	Model for returning a user token to the client, either when adding a new user or
`WorkerTask`	The data model used for sending task data to machine workers.
`WorkerTaskResults`	The data sent by the machine workers when returning job results.
`WorkerTaskStatus`	Response for when the status of a task is returned.
`WorkerTokenResponse`	Model containing new credentials for a machine worker.

Module Contents

class general_superstaq.models.AQTConfigs(/, **data: Any)

Bases: DefaultPydanticModel

Model for AQT configs.

pulses: str: The serialized pulses.

variables: str: The serialized variables.

class general_superstaq.models.BalanceResponse(/, **data: Any)

Bases: DefaultPydanticModel

Model for returning a single user balance.

balance: float: The user’s balance.

email: pydantic.EmailStr: The user’s email address.

class general_superstaq.models.CircuitStatus

Bases: str, enum.Enum

The possible statuses of a job/circuit.

AWAITING_COMPILE = 'awaiting_compile': The job is waiting for a worker to compile.

AWAITING_SIMULATION = 'awaiting_simulation': The job is waiting for a worker to simulate.

AWAITING_SUBMISSION = 'awaiting_submission': The job is waiting for a worker to submit the circuit to an external device.

CANCELLED = 'cancelled': The job was cancelled. A reason should be stored in the job.

COMPILING = 'compiling': The job is being compiled by a worker.

COMPLETED = 'completed': The job is completed.

DELETED = 'deleted': When a job has been deleted.

FAILED = 'failed': The job failed. A reason should be stored in the job.

PENDING = 'pending': When a job has been submitted and is waiting to be run on a QPU. SUBMIT jobs only.

RECEIVED = 'received': The job has been received (and accepted) to the server and is awaiting further action.

RUNNING = 'running': The job is currently running on a device. SUBMIT jobs only

SIMULATING = 'simulating': The job is currently being simulated. SIMULATE jobs only

UNRECOGNIZED = 'unrecognized': Something has gone wrong! (Treated as terminal)

class general_superstaq.models.CircuitType

Bases: str, enum.Enum

The different languages that are recognized by Superstaq.

CIRQ = 'cirq'

QASM = 'qasm'

QISKIT = 'qiskit'

class general_superstaq.models.DefaultPydanticModel(/, **data: Any)

Bases: pydantic.BaseModel

Default pydantic model used across the superstaq server.

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

class general_superstaq.models.ExternalProviderCredentials(/, **data: Any)

Bases: DefaultPydanticModel

Model for storing a user’s credentials for external providers.

cq_org_id: str | None = None

cq_project_id: str | None = None

cq_token: str | None = None

ibmq_channel: str | None = None

ibmq_instance: str | None = None

ibmq_token: str | None = None

qtm_email: pydantic.EmailStr | None = None

qtm_token: str | None = None

class general_superstaq.models.GetTargetsFilterModel(/, **data: Any)

Bases: DefaultPydanticModel

Model for /get_target requests.

accessible: bool | None = None: Include only Superstaq targets that are/aren’t accessible to the user.

available: bool | None = None: Include Superstaq targets that are/not currently available.

retired: bool | None = None: Include Superstaq targets that are retired.

simulator: bool | None = None: Include Superstaq targets that are/not simulators.

supports_compile: bool | None = None: Include Superstaq targets that allow/do not allow circuit compilation.

supports_submit: bool | None = None: Include Superstaq targets that allow/do not allow job submission.

supports_submit_qubo: bool | None = None: Include Superstaq targets that allow/do not allow QUBO submission.

class general_superstaq.models.JobCancellationResults(/, **data: Any)

Bases: DefaultPydanticModel

The results from cancelling a job.

message: str: The server message.

succeeded: list[str]: List of circuits that successfully cancelled.

class general_superstaq.models.JobData(/, **data: Any)

Bases: DefaultPydanticModel

A class to store data for a Superstaq job which is returned through to the client.

circuit_type: CircuitType: The circuit type used for representing the circuits.

compiled_circuits: list[str | None]: Compiled versions of each input circuits.

counts: list[dict[str, int] | None]: Counts for each input circuit (if available/relevant).

dry_run: bool: Flag to indicate a dry-run job.

final_logical_to_physicals: list[dict[int, int] | None]: Serialized initial final-to-physical mapping for each circuit.

initial_logical_to_physicals: list[dict[int, int] | None]: Serialized initial logical-to-physical mapping for each circuit.

input_circuits: list[str]: The input circuits as serialized strings.

job_type: JobType: The type of job being submitted.

last_updated_timestamp: list[datetime.datetime | None]: Timestamp for when each circuit was last updated.

logical_qubits: list[str | None]: Serialized logical qubits of compiled circuit. Only provided for CIRQ circuit type.

metadata: dict[str, Any] = None: Additional metadata passed by the user.

num_circuits: int: Number of circuits in the job.

physical_qubits: list[str | None]: Serialized physical qubits of the device. Only provided for CIRQ circuit type.

provider_id: list[str | None]: Any provider side ID’s for each circuit in the job.

results_dicts: list[str | None]: Serialized results dictionary for each input circuit (if available/relevant).

shots: list[int]: Number of shots for each circuit.

status_messages: list[str | None]: Any status messages for each circuit in the job.

statuses: list[CircuitStatus]: The current status of each circuit in the job.

submission_timestamp: datetime.datetime: Timestamp when the job was submitted.

tags: list[str] = []: Any tags attached to this job.

target: TargetStr: The target that the job was submitted to.

user_email: pydantic.EmailStr: The email address of the use who submitted the job.

class general_superstaq.models.JobQuery(/, **data: Any)

Bases: DefaultPydanticModel

The query model for retrieving jobs. Using multiple values in a field is interpreted as logical OR while providing values for multiple fields is interpreted as logical AND.

job_id: list[uuid.UUID] | None = None: List of job IDs to include.

max_priority: int | None = None: Maximum priority to include.

min_priority: int | None = None: Minimum priority to include.

status: list[CircuitStatus] | None = None: List of statuses to include.

submitted_after: datetime.datetime | None = None: Filter for jobs submitted after this date.

submitted_before: datetime.datetime | None = None: Filter for jobs submitted before this date.

tags: list[str] | None = None: Filter for jobs with a given tag.

target_name: list[TargetStr] | None = None: List of targets to include.

user_email: list[pydantic.EmailStr] | None = None: List of user emails to include.

class general_superstaq.models.JobType

Bases: str, enum.Enum

The different types of jobs that can be submitted through Superstaq.

COMPILE = 'compile': A job that only involves compiling a circuit for some given device.

CONVERT = 'convert': A job that only involves converting circuits between e.g. qiskit and cirq

SIMULATE = 'simulate': A job that requires superstaq to simulate circuits.

SUBMIT = 'submit': A job that involves submitting circuits to an external device.

class general_superstaq.models.NewJob(/, **data: Any)

Bases: DefaultPydanticModel

The data model for submitting new jobs.

circuit_type: CircuitType: The input circuit type.

circuits: str: Serialized input circuits.

dry_run: bool = None: Flag for a dry-run.

job_type: JobType: The job type.

metadata: dict[str, Any] = None: Additional metadata passed by the user.

options_dict: dict[str, Any] = None: Options dictionary with additional configuration detail.

priority: int = None: Optional priority level. Note that different roles have their own maximum priority level which will limit the priority that users can submit.

shots: int = None: Number of shots.

sim_method: SimMethod | None = None: The simulation method to use. Only used on simulation jobs.

tags: list[str] = None: Optional tags.

target: TargetStr: The target.

verbatim: bool = None: Whether to skip compile step.

class general_superstaq.models.NewJobResponse(/, **data: Any)

Bases: DefaultPydanticModel

Model for the response when a new job is submitted.

job_id: uuid.UUID: The job ID for the submitted job.

num_circuits: int: The number of circuits in the job.

class general_superstaq.models.NewUser(/, **data: Any)

Bases: DefaultPydanticModel

Model for creating new users.

email: pydantic.EmailStr: User email.

initial_balance: float | None = None: Initial balance.

name: str: User name.

role: str | None = None: User role.

class general_superstaq.models.NewWorker(/, **data: Any)

Bases: DefaultPydanticModel

Model for declaring a new machine worker.

name: str

served_target: str

class general_superstaq.models.RetrieveTargetInfoModel(/, **data: Any)

Bases: DefaultPydanticModel

Model for retrieving detailed target info.

options_dict: dict[str, Any] = None: The details of the target.

target: TargetStr: The target’s name.

class general_superstaq.models.SimMethod

Bases: str, enum.Enum

The different simulation methods that are available.

NOISE_SIM = 'noise-sim': The simulation applies noise. If used with device_simulation this applies realistic device noise otherwise the noise needs to be provided by the user (via the options dict).

SIM = 'sim': Samples the circuits without any noise.

class general_superstaq.models.TargetInfo(/, **data: Any)

Bases: DefaultPydanticModel

Model containing details info about a specific instance of a target.

target_info: dict[str, object]

class general_superstaq.models.TargetModel(/, **data: Any)

Bases: DefaultPydanticModel

Model for the details of a target.

accessible: bool: Target is accessible to user.

available: bool: Target is currently available.

retired: bool: Target is retired.

simulator: bool: Target is simulator.

supports_compile: bool: Target allows circuit compilation.

supports_submit: bool: Targets allow job submission.

supports_submit_qubo: bool: Targets allows QUBO submission.

target_name: TargetStr: The target name.

class general_superstaq.models.TargetStatus

Bases: str, enum.Enum

The current status of a Superstaq Target.

AVAILABLE = 'available': Target is currently accepting new jobs.

DEV_ONLY = 'dev_only': Target is in maintenance mode.

OFFLINE = 'offline': Target is temporarily unavailable for job submission.

RETIRED = 'retired': Target has been permanently retired.

UNSUPPORTED = 'unsupported': Target does not support job submission through Superstaq.

class general_superstaq.models.UpdateUserDetails(/, **data: Any)

Bases: DefaultPydanticModel

Model for requests which modify user details.

balance: float | None = None: New user balance.

name: str | None = None: New user name.

role: str | None = None: New user role.

class general_superstaq.models.UserInfo(/, **data: Any)

Bases: DefaultPydanticModel

Model for the user info returned to the client.

balance: float: User balance.

email: pydantic.EmailStr: User email.

name: str: User name.

role: str: User role.

token: str: User API token.

user_id: uuid.UUID: User id.

class general_superstaq.models.UserQuery(/, **data: Any)

Bases: DefaultPydanticModel

Model for querying the database to retrieve users. Use of lists implied logical OR. Providing multiple fields (e.g. name and email) implies logical AND.

email: collections.abc.Sequence[pydantic.EmailStr] | None = None: List of user emails to filter for.

name: collections.abc.Sequence[str] | None = None: List of user names to filter for.

role: collections.abc.Sequence[str] | None = None: List of user roles to filter for.

user_id: collections.abc.Sequence[uuid.UUID] | None = None: List of explicit user IDs to filter for.

class general_superstaq.models.UserTokenResponse(/, **data: Any)

Bases: DefaultPydanticModel

Model for returning a user token to the client, either when adding a new user or regenerating the token.

email: pydantic.EmailStr: The user’s email address.

token: str: The user’s new token.

class general_superstaq.models.WorkerTask(/, **data: Any)

Bases: DefaultPydanticModel

The data model used for sending task data to machine workers.

circuit: str: Serialized representation of the circuit.

circuit_ref: str: The circuit reference.

metadata: dict[str, Any] = None: Additional metadata passed by the user.

shots: int: The number of shots to perform.

user_email: pydantic.EmailStr | None = None: The user’s email.

class general_superstaq.models.WorkerTaskResults(/, **data: Any)

Bases: DefaultPydanticModel

The data sent by the machine workers when returning job results.

validate_measurements() → WorkerTaskResults: Check all measurement keys are bitstrings of the same length, all values have the expected number of shots and all indices are present.

circuit_ref: str: The circuit reference.

measurements: dict[str, set[pydantic.NonNegativeInt]] | None = None: Mapping of bitstrings to a list of shot indexes.

status: CircuitStatus: The current status of the task.

status_message: str | None = None: Description of the task status.

successful_shots: pydantic.NonNegativeInt | None = None: The total number of successful shots (used for validation).

class general_superstaq.models.WorkerTaskStatus(/, **data: Any)

Bases: DefaultPydanticModel

Response for when the status of a task is returned.

circuit_ref: str: The circuit reference.

status: CircuitStatus: The current status of the task.

class general_superstaq.models.WorkerTokenResponse(/, **data: Any)

Bases: DefaultPydanticModel

Model containing new credentials for a machine worker.

token: str

worker_name: str

general_superstaq.models.TERMINAL_CIRCUIT_STATES

general_superstaq.models.TargetStr

general_superstaq.models.UNSUCCESSFUL_CIRCUIT_STATES