Types API

Public data types for the FastQSim SDK.

All classes are pure data containers populated from FastQubit API responses. No backend libraries (qiskit, cirq, pennylane) are imported here.

class fastqsim.qtypes.Job(data, client=None)

Bases: object

Represents a quantum simulation job submitted to the FastQSim platform.

Returned by FastQSimClient.run() and FastQSimClient.run_batch(). Call result() to block until completion and retrieve results, or use wait_for_completion() to poll and then inspect properties manually.

Parameters:

• data (Dict[str, Any])

• client (Any)

property backend: str

Backend used for execution (‘qiskit’, ‘cirq’, ‘pennylane’).

property billing_avg_memory_mb: float | None

average RSS memory usage in MB over execution.

Type:

Billing telemetry

property billing_cpu_millicore_seconds: float | None

integrated CPU usage in millicore-seconds.

Type:

Billing telemetry

property billing_memory_gb_seconds: float | None

integrated memory usage in GB-seconds.

Type:

Billing telemetry

property billing_memory_headroom_mb: float | None

memory headroom to pod limit in MB at completion.

Type:

Billing telemetry

property billing_psutil_available: bool | None

Whether psutil-based billing telemetry was available in the worker runtime.

cancel()

Request cancellation of a QUEUED or RUNNING job.

Return type:

bool

Returns:

True if the cancellation was accepted.

Raises:

JobCouldNotCancelError – Server rejected the cancellation request.

property completed_at: datetime | None

When the worker finalized the terminal state in persistent storage.

property cpu_seconds_total: float | None

Worker-reported process CPU time (user + system) consumed during execution.

property created_at: datetime | None

UTC time when the job record was first created.

property device: str

Device used for execution (‘cpu’, ‘gpu’, ‘quantum’).

property end_user_id: str

End-user identity asserted by the integrator who owns this job.

property error_message: str | None

Worker error message if the job failed. Contains the raw exception text from the Q-Pod (e.g. ParseError details).

property execution_finished_at: datetime | None

Timestamp emitted by the q-worker after simulation and artifact upload.

property execution_started_at: datetime | None

Timestamp emitted by the q-worker when simulation begins inside the pod.

property execution_time_seconds: float | None

Worker-reported wall-clock execution duration in seconds.

get_counts()

Return measurement counts for a completed job.

Raises:

• JobNotCompleteError – Job has not finished yet.

• JobDoesNotContainCountsError – Job was run without measurement shots.

Return type:

Optional[Dict[str, int]]

get_statevector()

Retrieve the statevector for a completed job.

Raises:

• JobNotCompleteError – Job has not finished yet.

• JobStatevectorTooLargeError – Statevector exceeds retrieval limit.

Return type:

List[complex]

property has_external_artifact: bool

True when the result was too large for inline storage and is persisted to S3. Use GET /jobs/{job_id}/result-url (client._fetch_external_artifact) to retrieve it.

property integrator_id: str | None

Integrator that submitted this job.

property job_id: str

Unique job identifier (UUID).

property job_name: str | None

Optional human-readable job label supplied at submission time.

property metadata: Dict[str, Any]

Opaque client metadata stored with the job at submission time.

property num_qubits: int | None

Number of qubits in the circuit (from circuit profile). None until analyzer is wired.

property ok: bool

True if the job’s current status is COMPLETED.

property options: Dict[str, Any]

Backend/device-specific execution options supplied at submission time.

property peak_memory_mb: float | None

Worker-reported peak RSS memory usage in MB sampled during execution.

property pod_name: str | None

Kubernetes pod name used for this job execution.

property profile: Dict[str, Any]

Circuit complexity metrics extracted by the AST analyzer. Fields: qubit_count, depth, gate_count, two_qubit_gate_count. All None until the analyzer is implemented.

property queue_dequeued_at: datetime | None

When the scheduler claimed the job and a worker pod was created.

property queue_enqueued_at: datetime | None

When the job was accepted and published to the RabbitMQ queue.

refresh()

Fetch the latest metadata for this job and update in place.

Return type:

Job

property resource_estimate: Dict[str, Any]

Predicted Kubernetes resource allocation for the worker pod. Fields: cpu_request, memory_request, cpu_limit, memory_limit. All None until adaptive sizing is implemented.

result(timeout=None)

Block until the job completes, then return the Result.

Parameters:

timeout (Optional[int]) – Maximum seconds to wait. Raises JobTimeoutError if exceeded.

Raises:

• JobTimeoutError – Job did not complete within timeout.

• JobFailedError – Job reached a failed terminal state.

Return type:

Result

property result_counts: Dict[str, int] | None

Inline measurement counts (bit-string → count). Populated when job completes.

property result_metadata: Dict[str, Any]

Additional result metadata emitted by the worker (backend name, simulation_type, engine version, etc.).

property result_url_expires_at: datetime | None

Expiry of the last issued presigned result download URL.

property seed: int | None

Optional deterministic RNG seed supplied at submission time.

property session_id: str

Session under which this job was submitted.

property shots: int | None

Number of measurement shots specified at submission time.

property simulation_type: str

Simulation mode used by the backend (‘statevector’, ‘density_matrix’, ‘mps’, ‘chp’).

property status: JobStatus

Current job status as a JobStatus enum value.

property tags: Dict[str, Any]

Key-value tags attached to the job at submission time.

property updated_at: datetime | None

UTC time when the job record was last modified.

wait_for_completion(poll_interval=5, timeout=None)

Block until the job reaches a terminal state.

Parameters:

• poll_interval (int) – Seconds between status checks.

• timeout (Optional[int]) – Maximum seconds to wait. Raises JobTimeoutError if exceeded.

Return type:

None

class fastqsim.qtypes.JobStatus(value)

Bases: str, Enum

All possible states a FastQSim job can be in.

Terminal states: completed, failed, cancelled Non-terminal: created, queued, running

CANCELLED = 'cancelled'

COMPLETED = 'completed'

CREATED = 'created'

FAILED = 'failed'

QUEUED = 'queued'

RUNNING = 'running'

property is_successful: bool

True only for COMPLETED.

property is_terminal: bool

True if the status is a final, non-changeable state.

class fastqsim.qtypes.Result(data)

Bases: object

Simulation results returned after a job reaches COMPLETED status.

Returned by Job.result() and Job.get_counts().

Parameters:

data (Dict[str, Any])

property counts: Dict[str, int]

512}.

Type:

Measurement counts dictionary, e.g. {‘00’

Type:

512, ‘11’

property execution_time: float

Wall-clock execution time in seconds as measured by the Q-Pod.

get_counts(key=None)

Get counts for a specific measurement register, or all counts.

Parameters:

key (Optional[str]) – Register name. If None, returns the full counts dict.

Return type:

Dict[str, int]

property memory: List[str] | None

Individual shot results as bit-strings, e.g. [‘00’, ‘11’, ‘00’, …]. Only populated when the job was submitted with memory=True.

property metadata: Dict[str, Any]

Job and result metadata returned by the server.

property probabilities: Dict[str, float]

0.5}.

Type:

Outcome probabilities, e.g. {‘00’

Type:

0.5, ‘11’

property statevector: List[complex] | None

Final statevector as a list of complex amplitudes, if available. None when statevector was not requested or is too large.

class fastqsim.qtypes.RunArgs(circuit, backend='qiskit', device='cpu', shots=1024, simulation_type=None, seed=None, metadata=None, job_name=None, options=None, tags=None)

Bases: object

Optional helper to construct job submission arguments.

Can be passed to FastQSimClient.run() instead of keyword arguments. All fields mirror the run() parameters exactly.

Parameters:

• circuit (str)

• backend (str)

• device (str)

• shots (int)

• simulation_type (Optional[str])

• seed (Optional[int])

• metadata (Optional[Dict[str, Any]])

• job_name (Optional[str])

• options (Optional[Dict[str, Any]])

• tags (Optional[Dict[str, Any]])

to_dict()

Serialize to a dictionary for passing to client.run(**args.to_dict()).

Return type:

Dict[str, Any]

class fastqsim.qtypes.Session(data, client=None)

Bases: object

Represents a FastQubit session payload.

In pod-token SDK mode, session lifecycle operations are handled by the integrator control plane, so helper methods like refresh_token() and close() may raise ValidationError.

Parameters:

• data (Dict[str, Any])

• client (Any)

property already_active: bool | None

Present on POST /sessions/start responses only. True when an existing active session was returned because the per-user limit was already reached. False when a new session was provisioned.

close()

Terminate the session and release server-side resources.

Raises ValidationError in pod-token SDK mode.

Return type:

None

property created_at: datetime | None

UTC time when the session was created.

property end_user_id: str

End-user identity asserted by the integrator who owns this session.

property error_message: str | None

Error detail when state is ‘failed’.

property execution_engine: str

Runtime engine used inside the user pod (e.g. ‘jupyter-kernel-gateway’).

property expires_at: datetime | None

Hard TTL for this session. The pod is terminated after this time.

property integrator_id: str | None

Integrator that created this session.

property kernel_id: str | None

Jupyter kernel ID. Populated after the pod is ready. None for terminal sessions.

property message: str | None

Human-readable note, e.g. instructions to terminate before starting a new session.

refresh_token()

Request a refreshed WebSocket authentication token from the server.

Raises ValidationError in pod-token SDK mode.

Return type:

None

property session_id: str

Unique session identifier (UUID).

property state: str

Current session lifecycle state. One of: creating | provisioning | ready | active | idle | terminating | terminated | failed.

property ws_token: str | None

Short-lived HMAC-signed session token for the WebSocket connection.

property ws_token_expires_at: datetime | None

UTC expiry of the current ws_token.

property ws_url: str | None

Fully resolved WSS URL for the active kernel channel. None until pod is ready.

class fastqsim.qtypes.SimulationType(value)

Bases: str, Enum

The simulation method used by the Q-Pod backend.

Determines both the physics model and the resource footprint:

• STATEVECTOR: Full state-vector sim. Memory ∝ 2^N. Supports all gates.

• DENSITY_MATRIX: Open-system sim with noise. Memory ∝ 4^N. Supports all gates.

• MPS: Matrix Product State. Memory ∝ N·χ². Best for low-entanglement circuits.

• CHP: Stabilizer / Clifford. Memory ∝ N². Clifford gates only (H, CNOT, S, measure).

CHP = 'chp'

DENSITY_MATRIX = 'density_matrix'

MPS = 'mps'

STATEVECTOR = 'statevector'