general_superstaq.models ======================== .. py:module:: general_superstaq.models .. autoapi-nested-parse:: Data models used when communicating with the superstaq server. Attributes ---------- .. autoapisummary:: general_superstaq.models.TERMINAL_CIRCUIT_STATES general_superstaq.models.TargetStr general_superstaq.models.UNSUCCESSFUL_CIRCUIT_STATES Classes ------- .. autoapisummary:: general_superstaq.models.AQTConfigs general_superstaq.models.BalanceResponse general_superstaq.models.CircuitStatus general_superstaq.models.CircuitType general_superstaq.models.DefaultPydanticModel general_superstaq.models.ExternalProviderCredentials general_superstaq.models.GetTargetsFilterModel general_superstaq.models.JobCancellationResults general_superstaq.models.JobData general_superstaq.models.JobQuery general_superstaq.models.JobType general_superstaq.models.NewJob general_superstaq.models.NewJobResponse general_superstaq.models.NewUser general_superstaq.models.NewWorker general_superstaq.models.RetrieveTargetInfoModel general_superstaq.models.SimMethod general_superstaq.models.TargetInfo general_superstaq.models.TargetModel general_superstaq.models.TargetStatus general_superstaq.models.UpdateUserDetails general_superstaq.models.UserInfo general_superstaq.models.UserQuery general_superstaq.models.UserTokenResponse general_superstaq.models.WorkerTask general_superstaq.models.WorkerTaskResults general_superstaq.models.WorkerTaskStatus general_superstaq.models.WorkerTokenResponse Module Contents --------------- .. py:class:: AQTConfigs(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for AQT configs. .. py:attribute:: pulses :type: str The serialized pulses. .. py:attribute:: variables :type: str The serialized variables. .. py:class:: BalanceResponse(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for returning a single user balance. .. py:attribute:: balance :type: float The user's balance. .. py:attribute:: email :type: pydantic.EmailStr The user's email address. .. py:class:: CircuitStatus Bases: :py:obj:`str`, :py:obj:`enum.Enum` The possible statuses of a job/circuit. .. py:attribute:: AWAITING_COMPILE :value: 'awaiting_compile' The job is waiting for a worker to compile. .. py:attribute:: AWAITING_SIMULATION :value: 'awaiting_simulation' The job is waiting for a worker to simulate. .. py:attribute:: AWAITING_SUBMISSION :value: 'awaiting_submission' The job is waiting for a worker to submit the circuit to an external device. .. py:attribute:: CANCELLED :value: 'cancelled' The job was cancelled. A reason should be stored in the job. .. py:attribute:: COMPILING :value: 'compiling' The job is being compiled by a worker. .. py:attribute:: COMPLETED :value: 'completed' The job is completed. .. py:attribute:: DELETED :value: 'deleted' When a job has been deleted. .. py:attribute:: FAILED :value: 'failed' The job failed. A reason should be stored in the job. .. py:attribute:: PENDING :value: 'pending' When a job has been submitted and is waiting to be run on a QPU. SUBMIT jobs only. .. py:attribute:: RECEIVED :value: 'received' The job has been received (and accepted) to the server and is awaiting further action. .. py:attribute:: RUNNING :value: 'running' The job is currently running on a device. SUBMIT jobs only .. py:attribute:: SIMULATING :value: 'simulating' The job is currently being simulated. SIMULATE jobs only .. py:attribute:: UNRECOGNIZED :value: 'unrecognized' Something has gone wrong! (Treated as terminal) .. py:class:: CircuitType Bases: :py:obj:`str`, :py:obj:`enum.Enum` The different languages that are recognized by Superstaq. .. py:attribute:: CIRQ :value: 'cirq' .. py:attribute:: QASM :value: 'qasm' .. py:attribute:: QISKIT :value: 'qiskit' .. py:class:: DefaultPydanticModel(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` Default pydantic model used across the superstaq server. .. py:attribute:: model_config Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. .. py:class:: ExternalProviderCredentials(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for storing a user's credentials for external providers. .. py:attribute:: cq_org_id :type: str | None :value: None .. py:attribute:: cq_project_id :type: str | None :value: None .. py:attribute:: cq_token :type: str | None :value: None .. py:attribute:: ibmq_channel :type: str | None :value: None .. py:attribute:: ibmq_instance :type: str | None :value: None .. py:attribute:: ibmq_token :type: str | None :value: None .. py:attribute:: qtm_email :type: pydantic.EmailStr | None :value: None .. py:attribute:: qtm_token :type: str | None :value: None .. py:class:: GetTargetsFilterModel(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for /get_target requests. .. py:attribute:: accessible :type: bool | None :value: None Include only Superstaq targets that are/aren't accessible to the user. .. py:attribute:: available :type: bool | None :value: None Include Superstaq targets that are/not currently available. .. py:attribute:: retired :type: bool | None :value: None Include Superstaq targets that are retired. .. py:attribute:: simulator :type: bool | None :value: None Include Superstaq targets that are/not simulators. .. py:attribute:: supports_compile :type: bool | None :value: None Include Superstaq targets that allow/do not allow circuit compilation. .. py:attribute:: supports_submit :type: bool | None :value: None Include Superstaq targets that allow/do not allow job submission. .. py:attribute:: supports_submit_qubo :type: bool | None :value: None Include Superstaq targets that allow/do not allow QUBO submission. .. py:class:: JobCancellationResults(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` The results from cancelling a job. .. py:attribute:: message :type: str The server message. .. py:attribute:: succeeded :type: list[str] List of circuits that successfully cancelled. .. py:class:: JobData(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` A class to store data for a Superstaq job which is returned through to the client. .. py:attribute:: circuit_type :type: CircuitType The circuit type used for representing the circuits. .. py:attribute:: compiled_circuits :type: list[str | None] Compiled versions of each input circuits. .. py:attribute:: counts :type: list[dict[str, int] | None] Counts for each input circuit (if available/relevant). .. py:attribute:: dry_run :type: bool Flag to indicate a dry-run job. .. py:attribute:: final_logical_to_physicals :type: list[dict[int, int] | None] Serialized initial final-to-physical mapping for each circuit. .. py:attribute:: initial_logical_to_physicals :type: list[dict[int, int] | None] Serialized initial logical-to-physical mapping for each circuit. .. py:attribute:: input_circuits :type: list[str] The input circuits as serialized strings. .. py:attribute:: job_type :type: JobType The type of job being submitted. .. py:attribute:: last_updated_timestamp :type: list[datetime.datetime | None] Timestamp for when each circuit was last updated. .. py:attribute:: logical_qubits :type: list[str | None] Serialized logical qubits of compiled circuit. Only provided for CIRQ circuit type. .. py:attribute:: metadata :type: dict[str, Any] :value: None Additional metadata passed by the user. .. py:attribute:: num_circuits :type: int Number of circuits in the job. .. py:attribute:: physical_qubits :type: list[str | None] Serialized physical qubits of the device. Only provided for CIRQ circuit type. .. py:attribute:: provider_id :type: list[str | None] Any provider side ID's for each circuit in the job. .. py:attribute:: results_dicts :type: list[str | None] Serialized results dictionary for each input circuit (if available/relevant). .. py:attribute:: shots :type: list[int] Number of shots for each circuit. .. py:attribute:: status_messages :type: list[str | None] Any status messages for each circuit in the job. .. py:attribute:: statuses :type: list[CircuitStatus] The current status of each circuit in the job. .. py:attribute:: submission_timestamp :type: datetime.datetime Timestamp when the job was submitted. .. py:attribute:: tags :type: list[str] :value: [] Any tags attached to this job. .. py:attribute:: target :type: TargetStr The target that the job was submitted to. .. py:attribute:: user_email :type: pydantic.EmailStr The email address of the use who submitted the job. .. py:class:: JobQuery(/, **data: Any) Bases: :py:obj:`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. .. py:attribute:: job_id :type: list[uuid.UUID] | None :value: None List of job IDs to include. .. py:attribute:: max_priority :type: int | None :value: None Maximum priority to include. .. py:attribute:: min_priority :type: int | None :value: None Minimum priority to include. .. py:attribute:: status :type: list[CircuitStatus] | None :value: None List of statuses to include. .. py:attribute:: submitted_after :type: datetime.datetime | None :value: None Filter for jobs submitted after this date. .. py:attribute:: submitted_before :type: datetime.datetime | None :value: None Filter for jobs submitted before this date. .. py:attribute:: tags :type: list[str] | None :value: None Filter for jobs with a given tag. .. py:attribute:: target_name :type: list[TargetStr] | None :value: None List of targets to include. .. py:attribute:: user_email :type: list[pydantic.EmailStr] | None :value: None List of user emails to include. .. py:class:: JobType Bases: :py:obj:`str`, :py:obj:`enum.Enum` The different types of jobs that can be submitted through Superstaq. .. py:attribute:: COMPILE :value: 'compile' A job that only involves compiling a circuit for some given device. .. py:attribute:: CONVERT :value: 'convert' A job that only involves converting circuits between e.g. qiskit and cirq .. py:attribute:: SIMULATE :value: 'simulate' A job that requires superstaq to simulate circuits. .. py:attribute:: SUBMIT :value: 'submit' A job that involves submitting circuits to an external device. .. py:class:: NewJob(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` The data model for submitting new jobs. .. py:attribute:: circuit_type :type: CircuitType The input circuit type. .. py:attribute:: circuits :type: str Serialized input circuits. .. py:attribute:: dry_run :type: bool :value: None Flag for a dry-run. .. py:attribute:: job_type :type: JobType The job type. .. py:attribute:: metadata :type: dict[str, Any] :value: None Additional metadata passed by the user. .. py:attribute:: options_dict :type: dict[str, Any] :value: None Options dictionary with additional configuration detail. .. py:attribute:: priority :type: int :value: None Optional priority level. Note that different roles have their own maximum priority level which will limit the priority that users can submit. .. py:attribute:: shots :type: int :value: None Number of shots. .. py:attribute:: sim_method :type: SimMethod | None :value: None The simulation method to use. Only used on `simulation` jobs. .. py:attribute:: tags :type: list[str] :value: None Optional tags. .. py:attribute:: target :type: TargetStr The target. .. py:attribute:: verbatim :type: bool :value: None Whether to skip compile step. .. py:class:: NewJobResponse(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for the response when a new job is submitted. .. py:attribute:: job_id :type: uuid.UUID The job ID for the submitted job. .. py:attribute:: num_circuits :type: int The number of circuits in the job. .. py:class:: NewUser(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for creating new users. .. py:attribute:: email :type: pydantic.EmailStr User email. .. py:attribute:: initial_balance :type: float | None :value: None Initial balance. .. py:attribute:: name :type: str User name. .. py:attribute:: role :type: str | None :value: None User role. .. py:class:: NewWorker(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for declaring a new machine worker. .. py:attribute:: name :type: str .. py:attribute:: served_target :type: str .. py:class:: RetrieveTargetInfoModel(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for retrieving detailed target info. .. py:attribute:: options_dict :type: dict[str, Any] :value: None The details of the target. .. py:attribute:: target :type: TargetStr The target's name. .. py:class:: SimMethod Bases: :py:obj:`str`, :py:obj:`enum.Enum` The different simulation methods that are available. .. py:attribute:: NOISE_SIM :value: '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). .. py:attribute:: SIM :value: 'sim' Samples the circuits without any noise. .. py:class:: TargetInfo(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model containing details info about a specific instance of a target. .. py:attribute:: target_info :type: dict[str, object] .. py:class:: TargetModel(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for the details of a target. .. py:attribute:: accessible :type: bool Target is accessible to user. .. py:attribute:: available :type: bool Target is currently available. .. py:attribute:: retired :type: bool Target is retired. .. py:attribute:: simulator :type: bool Target is simulator. .. py:attribute:: supports_compile :type: bool Target allows circuit compilation. .. py:attribute:: supports_submit :type: bool Targets allow job submission. .. py:attribute:: supports_submit_qubo :type: bool Targets allows QUBO submission. .. py:attribute:: target_name :type: TargetStr The target name. .. py:class:: TargetStatus Bases: :py:obj:`str`, :py:obj:`enum.Enum` The current status of a Superstaq Target. .. py:attribute:: AVAILABLE :value: 'available' Target is currently accepting new jobs. .. py:attribute:: DEV_ONLY :value: 'dev_only' Target is in maintenance mode. .. py:attribute:: OFFLINE :value: 'offline' Target is temporarily unavailable for job submission. .. py:attribute:: RETIRED :value: 'retired' Target has been permanently retired. .. py:attribute:: UNSUPPORTED :value: 'unsupported' Target does not support job submission through Superstaq. .. py:class:: UpdateUserDetails(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for requests which modify user details. .. py:attribute:: balance :type: float | None :value: None New user balance. .. py:attribute:: name :type: str | None :value: None New user name. .. py:attribute:: role :type: str | None :value: None New user role. .. py:class:: UserInfo(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for the user info returned to the client. .. py:attribute:: balance :type: float User balance. .. py:attribute:: email :type: pydantic.EmailStr User email. .. py:attribute:: name :type: str User name. .. py:attribute:: role :type: str User role. .. py:attribute:: token :type: str User API token. .. py:attribute:: user_id :type: uuid.UUID User id. .. py:class:: UserQuery(/, **data: Any) Bases: :py:obj:`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. .. py:attribute:: email :type: collections.abc.Sequence[pydantic.EmailStr] | None :value: None List of user emails to filter for. .. py:attribute:: name :type: collections.abc.Sequence[str] | None :value: None List of user names to filter for. .. py:attribute:: role :type: collections.abc.Sequence[str] | None :value: None List of user roles to filter for. .. py:attribute:: user_id :type: collections.abc.Sequence[uuid.UUID] | None :value: None List of explicit user IDs to filter for. .. py:class:: UserTokenResponse(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model for returning a user token to the client, either when adding a new user or regenerating the token. .. py:attribute:: email :type: pydantic.EmailStr The user's email address. .. py:attribute:: token :type: str The user's new token. .. py:class:: WorkerTask(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` The data model used for sending task data to machine workers. .. py:attribute:: circuit :type: str Serialized representation of the circuit. .. py:attribute:: circuit_ref :type: str The circuit reference. .. py:attribute:: metadata :type: dict[str, Any] :value: None Additional metadata passed by the user. .. py:attribute:: shots :type: int The number of shots to perform. .. py:attribute:: user_email :type: pydantic.EmailStr | None :value: None The user's email. .. py:class:: WorkerTaskResults(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` The data sent by the machine workers when returning job results. .. py:method:: 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. .. py:attribute:: circuit_ref :type: str The circuit reference. .. py:attribute:: measurements :type: dict[str, set[pydantic.NonNegativeInt]] | None :value: None Mapping of bitstrings to a list of shot indexes. .. py:attribute:: status :type: CircuitStatus The current status of the task. .. py:attribute:: status_message :type: str | None :value: None Description of the task status. .. py:attribute:: successful_shots :type: pydantic.NonNegativeInt | None :value: None The total number of successful shots (used for validation). .. py:class:: WorkerTaskStatus(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Response for when the status of a task is returned. .. py:attribute:: circuit_ref :type: str The circuit reference. .. py:attribute:: status :type: CircuitStatus The current status of the task. .. py:class:: WorkerTokenResponse(/, **data: Any) Bases: :py:obj:`DefaultPydanticModel` Model containing new credentials for a machine worker. .. py:attribute:: token :type: str .. py:attribute:: worker_name :type: str .. py:data:: TERMINAL_CIRCUIT_STATES .. py:data:: TargetStr .. py:data:: UNSUCCESSFUL_CIRCUIT_STATES