Workspace Class

Represents an Azure Quantum workspace.

When creating a Workspace object, callers have two options for identifying the Azure Quantum workspace (in order of precedence):

1. specify a valid location and resource ID; or
2. specify a valid location, subscription ID, resource group, and workspace name.

You can also use a connection string to specify the connection parameters to an Azure Quantum Workspace by calling from_connection_string.

If the Azure Quantum workspace does not have linked storage, the caller must also pass a valid Azure storage account connection string.

Inheritance

builtins.object

Workspace

Constructor

Workspace(subscription_id: str | None = None, resource_group: str | None = None, name: str | None = None, storage: str | None = None, resource_id: str | None = None, location: str | None = None, credential: object | None = None, user_agent: str | None = None, **kwargs: Any)

Parameters

Name	Description
subscription_id	The Azure subscription ID. Ignored if resource_id is specified. Default value: None
resource_group	The Azure resource group name. Ignored if resource_id is specified. Default value: None
name	The Azure Quantum workspace name. Ignored if resource_id is specified. Default value: None
storage	The Azure storage account connection string. Required only if the specified Azure Quantum workspace does not have linked storage. Default value: None
resource_id	The resource ID of the Azure Quantum workspace. Default value: None
location	The Azure region where the Azure Quantum workspace is provisioned. This may be specified as a region name such as "East US" or a location name such as "eastus". Default value: None
credential	The credential to use to connect to Azure services. Normally one of the credential types from Azure.Identity. Defaults to "DefaultAzureCredential", which will attempt multiple forms of authentication. Default value: None
user_agent	Add the specified value as a prefix to the HTTP User-Agent header when communicating to the Azure Quantum service. Default value: None

Methods

append_user_agent	Append a new value to the Workspace's UserAgent. The values are appended using a dash.
cancel_job	Requests the Workspace to cancel the execution of a job.
close_session	Closes a session in the given workspace if the session is not in a terminal state. Otherwise, just refreshes the session details.
from_connection_string	Creates a new Azure Quantum Workspace client from a connection string.
get_container_uri	Get container URI based on job ID or container name. Creates a new container if it does not yet exist.
get_job	Returns the job corresponding to the given id.
get_quotas	Get a list of quotas for the given workspace. Each quota is represented as a dictionary, containing the properties for that quota. Common Quota properties are: "dimension": The dimension that the quota is applied to. "scope": The scope that the quota is applied to. "provider_id": The provider that the quota is applied to. "utilization": The current utilization of the quota. "limit": The limit of the quota. "period": The period that the quota is applied to.
get_session	Gets a session from the workspace.
get_targets	Returns all available targets for this workspace filtered by Target name and Provider ID. If the target name is passed, a single Target object will be returned. Otherwise it returns a iterable/list of Target objects, optionally filtered by the Provider ID.
list_jobs	Returns list of jobs that meet optional (limited) filter criteria.
list_session_jobs	Gets all jobs associated with a session.
list_sessions	Get the list of sessions in the given workspace.
list_top_level_items	Get a list of top level items for the given workspace, which can be standalone Jobs (Jobs not associated with a Session) or Sessions (which can contain Jobs).
open_session	Opens/creates a session in the given workspace.
refresh_session	Updates the session details with the latest information from the workspace.
submit_job	Submits a job to be processed in the Workspace.

append_user_agent

Append a new value to the Workspace's UserAgent. The values are appended using a dash.

append_user_agent(value: str) -> None

Parameters

Name	Description
value Required	UserAgent value to add, e.g. "azure-quantum-"

cancel_job

Requests the Workspace to cancel the execution of a job.

cancel_job(job: Job) -> Job

Parameters

Name	Description
job Required	Job to cancel.

Returns

Type	Description
Job	Azure Quantum Job that was requested to be cancelled, with an updated status.

close_session

Closes a session in the given workspace if the session is not in a terminal state. Otherwise, just refreshes the session details.

close_session(session: Session) -> None

Parameters

Name	Description
session Required	The session to be closed.

from_connection_string

Creates a new Azure Quantum Workspace client from a connection string.

from_connection_string(connection_string: str, **kwargs) -> Workspace

Parameters

Name	Description
connection_string Required	A valid connection string, usually obtained from the Quantum Workspace -> Operations -> Access Keys blade in the Azure Portal.

Returns

Type	Description
Workspace	New Azure Quantum Workspace client.

get_container_uri

Get container URI based on job ID or container name. Creates a new container if it does not yet exist.

get_container_uri(job_id: str | None = None, container_name: str | None = None, container_name_format: str | None = 'job-{job_id}') -> str

Parameters

Name	Description
job_id	Job ID, defaults to None. Default value: None
container_name	Container name, defaults to None. Default value: None
container_name_format	Container name format, defaults to "job-{job_id}". Default value: job-{job_id}

Returns

Type	Description
str	Container URI.

get_job

Returns the job corresponding to the given id.

get_job(job_id: str) -> Job

Parameters

Name	Description
job_id Required	Id of a job to fetch.

Returns

Type	Description
Job	Azure Quantum Job.

get_quotas

Get a list of quotas for the given workspace. Each quota is represented as a dictionary, containing the properties for that quota.

Common Quota properties are:

• "dimension": The dimension that the quota is applied to.
• "scope": The scope that the quota is applied to.
• "provider_id": The provider that the quota is applied to.
• "utilization": The current utilization of the quota.
• "limit": The limit of the quota.
• "period": The period that the quota is applied to.

get_quotas() -> List[Dict[str, Any]]

Returns

Type	Description
List[Dict[str, Any]	Workspace quotas.

get_session

Gets a session from the workspace.

get_session(session_id: str) -> Session

Parameters

Name	Description
session_id Required	The id of session to be retrieved.

Returns

Type	Description
Session	Azure Quantum Session

get_targets

Returns all available targets for this workspace filtered by Target name and Provider ID. If the target name is passed, a single Target object will be returned. Otherwise it returns a iterable/list of Target objects, optionally filtered by the Provider ID.

get_targets(name: str | None = None, provider_id: str | None = None) -> Target | Iterable[Target]

Parameters

Name	Description
name	Optional target name to filter by, defaults to None. Default value: None
provider_id	Optional provider Id to filter by, defaults to None. Default value: None

Returns

Type	Description
Union[Target, Iterable[Target]]	A single Azure Quantum Target or a iterable/list of Targets.

list_jobs

Returns list of jobs that meet optional (limited) filter criteria.

list_jobs(name_match: str | None = None, status: JobStatus | None = None, created_after: datetime | None = None) -> List[Job]

Parameters

Name	Description
name_match	Optional Regular Expression for job name matching. Defaults to None. Default value: None
status	Optional filter by job status. Defaults to None. Default value: None
created_after	Optional filter by jobs that were created after the given time. Defaults to None. Default value: None

Returns

Type	Description
List[Job]	Jobs that matched the search criteria.

list_session_jobs

Gets all jobs associated with a session.

list_session_jobs(session_id: str) -> List[Job]

Parameters

Name	Description
session_id Required	The id of session.

Returns

Type	Description
List[Job]	List of all jobs associated with a session.

list_sessions

Get the list of sessions in the given workspace.

list_sessions() -> List[Session]

Returns

Type	Description
List[Session]	List of Workspace Sessions.

list_top_level_items

Get a list of top level items for the given workspace, which can be standalone Jobs (Jobs not associated with a Session) or Sessions (which can contain Jobs).

list_top_level_items() -> List[Job | Session]

Returns

Type	Description
List[Union[Job, Session]]	List of Workspace top level Jobs or Sessions.

open_session

Opens/creates a session in the given workspace.

open_session(session: Session) -> None

Parameters

Name	Description
session Required	The session to be opened/created.

Returns

Type	Description
Session	A new open Azure Quantum Session.

refresh_session

Updates the session details with the latest information from the workspace.

refresh_session(session: Session) -> None

Parameters

Name	Description
session Required	The session to be refreshed.

submit_job

Submits a job to be processed in the Workspace.

submit_job(job: Job) -> Job

Parameters

Name	Description
job Required	Job to submit.

Returns

Type	Description
Job	Azure Quantum Job that was submitted, with an updated status.

Attributes

credential

Returns the Credential used to connect to the Quantum Workspace.

Returns

Type	Description
Any	Azure SDK Credential from Azure.Identity.

location

Returns the Azure location of the Quantum Workspace.

Returns

Type	Description
str	Azure location name.

name

Returns the Name of the Quantum Workspace.

Returns

Type	Description
str	Azure Quantum Workspace name.

resource_group

Returns the Azure Resource Group of the Quantum Workspace.

Returns

Type	Description
str	Azure Resource Group name.

storage

Returns the Azure Storage account name associated with the Quantum Workspace.

Returns

Type	Description
str	Azure Storage account name.

subscription_id

Returns the Azure Subscription ID of the Quantum Workspace.

Returns

Type	Description
str	Azure Subscription ID.

user_agent

Returns the Workspace's UserAgent string that is sent to the service via the UserAgent header.

Returns

Type	Description
str	User Agent string.