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

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

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

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

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

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 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 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 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

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.