Braket

2023/09/22 - Braket - 3 updated api methods

Changes  This release adds support to view the device queue depth (the number of queued quantum tasks and hybrid jobs on a device) and queue position for a quantum task and hybrid job.

GetDevice (updated) Link ¶
Changes (response) 
{'deviceQueueInfo': [{'queue': 'QUANTUM_TASKS_QUEUE | JOBS_QUEUE',
                      'queuePriority': 'Normal | Priority',
                      'queueSize': 'string'}]}

Retrieves the devices available in Amazon Braket.

Note

For backwards compatibility with older versions of BraketSchemas, OpenQASM information is omitted from GetDevice API calls. To get this information the user-agent needs to present a recent version of the BraketSchemas (1.8.0 or later). The Braket SDK automatically reports this for you. If you do not see OpenQASM results in the GetDevice response when using a Braket SDK, you may need to set AWS_EXECUTION_ENV environment variable to configure user-agent. See the code examples provided below for how to do this for the AWS CLI, Boto3, and the Go, Java, and JavaScript/TypeScript SDKs.

See also: AWS API Documentation

Request Syntax

client.get_device(
    deviceArn='string'
)
type deviceArn

string

param deviceArn

[REQUIRED]

The ARN of the device to retrieve.

rtype

dict

returns

Response Syntax

{
    'deviceArn': 'string',
    'deviceCapabilities': 'string',
    'deviceName': 'string',
    'deviceQueueInfo': [
        {
            'queue': 'QUANTUM_TASKS_QUEUE'|'JOBS_QUEUE',
            'queuePriority': 'Normal'|'Priority',
            'queueSize': 'string'
        },
    ],
    'deviceStatus': 'ONLINE'|'OFFLINE'|'RETIRED',
    'deviceType': 'QPU'|'SIMULATOR',
    'providerName': 'string'
}

Response Structure

  • (dict) --

    • deviceArn (string) --

      The ARN of the device.

    • deviceCapabilities (string) --

      Details about the capabilities of the device.

    • deviceName (string) --

      The name of the device.

    • deviceQueueInfo (list) --

      List of information about tasks and jobs queued on a device.

      • (dict) --

        Information about tasks and jobs queued on a device.

        • queue (string) --

          The name of the queue.

        • queuePriority (string) --

          Optional. Specifies the priority of the queue. Tasks in a priority queue are processed before the tasks in a normal queue.

        • queueSize (string) --

          The number of jobs or tasks in the queue for a given device.

    • deviceStatus (string) --

      The status of the device.

    • deviceType (string) --

      The type of the device.

    • providerName (string) --

      The name of the partner company for the device.

GetJob (updated) Link ¶
Changes (request, response)
Request 
{'additionalAttributeNames': ['QueueInfo']}
Response 
{'queueInfo': {'message': 'string',
               'position': 'string',
               'queue': 'QUANTUM_TASKS_QUEUE | JOBS_QUEUE'}}

Retrieves the specified Amazon Braket job.

See also: AWS API Documentation

Request Syntax

client.get_job(
    additionalAttributeNames=[
        'QueueInfo',
    ],
    jobArn='string'
)
type additionalAttributeNames

list

param additionalAttributeNames

A list of attributes to return information for.

  • (string) --

type jobArn

string

param jobArn

[REQUIRED]

The ARN of the job to retrieve.

rtype

dict

returns

Response Syntax

{
    'algorithmSpecification': {
        'containerImage': {
            'uri': 'string'
        },
        'scriptModeConfig': {
            'compressionType': 'NONE'|'GZIP',
            'entryPoint': 'string',
            's3Uri': 'string'
        }
    },
    'billableDuration': 123,
    'checkpointConfig': {
        'localPath': 'string',
        's3Uri': 'string'
    },
    'createdAt': datetime(2015, 1, 1),
    'deviceConfig': {
        'device': 'string'
    },
    'endedAt': datetime(2015, 1, 1),
    'events': [
        {
            'eventType': 'WAITING_FOR_PRIORITY'|'QUEUED_FOR_EXECUTION'|'STARTING_INSTANCE'|'DOWNLOADING_DATA'|'RUNNING'|'DEPRIORITIZED_DUE_TO_INACTIVITY'|'UPLOADING_RESULTS'|'COMPLETED'|'FAILED'|'MAX_RUNTIME_EXCEEDED'|'CANCELLED',
            'message': 'string',
            'timeOfEvent': datetime(2015, 1, 1)
        },
    ],
    'failureReason': 'string',
    'hyperParameters': {
        'string': 'string'
    },
    'inputDataConfig': [
        {
            'channelName': 'string',
            'contentType': 'string',
            'dataSource': {
                's3DataSource': {
                    's3Uri': 'string'
                }
            }
        },
    ],
    'instanceConfig': {
        'instanceCount': 123,
        'instanceType': 'ml.m4.xlarge'|'ml.m4.2xlarge'|'ml.m4.4xlarge'|'ml.m4.10xlarge'|'ml.m4.16xlarge'|'ml.g4dn.xlarge'|'ml.g4dn.2xlarge'|'ml.g4dn.4xlarge'|'ml.g4dn.8xlarge'|'ml.g4dn.12xlarge'|'ml.g4dn.16xlarge'|'ml.m5.large'|'ml.m5.xlarge'|'ml.m5.2xlarge'|'ml.m5.4xlarge'|'ml.m5.12xlarge'|'ml.m5.24xlarge'|'ml.c4.xlarge'|'ml.c4.2xlarge'|'ml.c4.4xlarge'|'ml.c4.8xlarge'|'ml.p2.xlarge'|'ml.p2.8xlarge'|'ml.p2.16xlarge'|'ml.p3.2xlarge'|'ml.p3.8xlarge'|'ml.p3.16xlarge'|'ml.p3dn.24xlarge'|'ml.p4d.24xlarge'|'ml.c5.xlarge'|'ml.c5.2xlarge'|'ml.c5.4xlarge'|'ml.c5.9xlarge'|'ml.c5.18xlarge'|'ml.c5n.xlarge'|'ml.c5n.2xlarge'|'ml.c5n.4xlarge'|'ml.c5n.9xlarge'|'ml.c5n.18xlarge',
        'volumeSizeInGb': 123
    },
    'jobArn': 'string',
    'jobName': 'string',
    'outputDataConfig': {
        'kmsKeyId': 'string',
        's3Path': 'string'
    },
    'queueInfo': {
        'message': 'string',
        'position': 'string',
        'queue': 'QUANTUM_TASKS_QUEUE'|'JOBS_QUEUE'
    },
    'roleArn': 'string',
    'startedAt': datetime(2015, 1, 1),
    'status': 'QUEUED'|'RUNNING'|'COMPLETED'|'FAILED'|'CANCELLING'|'CANCELLED',
    'stoppingCondition': {
        'maxRuntimeInSeconds': 123
    },
    'tags': {
        'string': 'string'
    }
}

Response Structure

  • (dict) --

    • algorithmSpecification (dict) --

      Definition of the Amazon Braket job created. Specifies the container image the job uses, information about the Python scripts used for entry and training, and the user-defined metrics used to evaluation the job.

      • containerImage (dict) --

        The container image used to create an Amazon Braket job.

        • uri (string) --

          The URI locating the container image.

      • scriptModeConfig (dict) --

        Configures the paths to the Python scripts used for entry and training.

        • compressionType (string) --

          The type of compression used by the Python scripts for an Amazon Braket job.

        • entryPoint (string) --

          The path to the Python script that serves as the entry point for an Amazon Braket job.

        • s3Uri (string) --

          The URI that specifies the S3 path to the Python script module that contains the training script used by an Amazon Braket job.

    • billableDuration (integer) --

      The billable time the Amazon Braket job used to complete.

    • checkpointConfig (dict) --

      Information about the output locations for job checkpoint data.

      • localPath (string) --

        (Optional) The local directory where checkpoints are written. The default directory is /opt/braket/checkpoints/ .

      • s3Uri (string) --

        Identifies the S3 path where you want Amazon Braket to store checkpoints. For example, s3://bucket-name/key-name-prefix .

    • createdAt (datetime) --

      The date and time that the Amazon Braket job was created.

    • deviceConfig (dict) --

      The quantum processing unit (QPU) or simulator used to run the Amazon Braket job.

      • device (string) --

        The primary quantum processing unit (QPU) or simulator used to create and run an Amazon Braket job.

    • endedAt (datetime) --

      The date and time that the Amazon Braket job ended.

    • events (list) --

      Details about the type and time events occurred related to the Amazon Braket job.

      • (dict) --

        Details about the type and time events occurred related to the Amazon Braket job.

        • eventType (string) --

          The type of event that occurred related to the Amazon Braket job.

        • message (string) --

          A message describing the event that occurred related to the Amazon Braket job.

        • timeOfEvent (datetime) --

          TThe type of event that occurred related to the Amazon Braket job.

    • failureReason (string) --

      A description of the reason why an Amazon Braket job failed, if it failed.

    • hyperParameters (dict) --

      Algorithm-specific parameters used by an Amazon Braket job that influence the quality of the traiing job. The values are set with a string of JSON key:value pairs, where the key is the name of the hyperparameter and the value is the value of th hyperparameter.

      • (string) --

        • (string) --

    • inputDataConfig (list) --

      A list of parameters that specify the name and type of input data and where it is located.

      • (dict) --

        A list of parameters that specify the input channels, type of input data, and where it is located.

        • channelName (string) --

          A named input source that an Amazon Braket job can consume.

        • contentType (string) --

          The MIME type of the data.

        • dataSource (dict) --

          The location of the channel data.

          • s3DataSource (dict) --

            Information about the data stored in Amazon S3 used by the Amazon Braket job.

            • s3Uri (string) --

              Depending on the value specified for the S3DataType , identifies either a key name prefix or a manifest that locates the S3 data source.

    • instanceConfig (dict) --

      The resource instances to use while running the hybrid job on Amazon Braket.

      • instanceCount (integer) --

        Configures the number of resource instances to use while running an Amazon Braket job on Amazon Braket. The default value is 1.

      • instanceType (string) --

        Configures the type resource instances to use while running an Amazon Braket hybrid job.

      • volumeSizeInGb (integer) --

        The size of the storage volume, in GB, that user wants to provision.

    • jobArn (string) --

      The ARN of the Amazon Braket job.

    • jobName (string) --

      The name of the Amazon Braket job.

    • outputDataConfig (dict) --

      The path to the S3 location where job artifacts are stored and the encryption key used to store them there.

      • kmsKeyId (string) --

        The AWS Key Management Service (AWS KMS) key that Amazon Braket uses to encrypt the job training artifacts at rest using Amazon S3 server-side encryption.

      • s3Path (string) --

        Identifies the S3 path where you want Amazon Braket to store the job training artifacts. For example, s3://bucket-name/key-name-prefix .

    • queueInfo (dict) --

      Queue information for the requested job. Only returned if QueueInfo is specified in the additionalAttributeNames" field in the GetJob API request.

      • message (string) --

        Optional. Provides more information about the queue position. For example, if the job is complete and no longer in the queue, the message field contains that information.

      • position (string) --

        Current position of the job in the jobs queue.

      • queue (string) --

        The name of the queue.

    • roleArn (string) --

      The Amazon Resource Name (ARN) of an IAM role that Amazon Braket can assume to perform tasks on behalf of a user. It can access user resources, run an Amazon Braket job container on behalf of user, and output resources to the s3 buckets of a user.

    • startedAt (datetime) --

      The date and time that the Amazon Braket job was started.

    • status (string) --

      The status of the Amazon Braket job.

    • stoppingCondition (dict) --

      The user-defined criteria that specifies when to stop a job running.

      • maxRuntimeInSeconds (integer) --

        The maximum length of time, in seconds, that an Amazon Braket job can run.

    • tags (dict) --

      A tag object that consists of a key and an optional value, used to manage metadata for Amazon Braket resources.

      • (string) --

        • (string) --

GetQuantumTask (updated) Link ¶
Changes (request, response)
Request 
{'additionalAttributeNames': ['QueueInfo']}
Response 
{'queueInfo': {'message': 'string',
               'position': 'string',
               'queue': 'QUANTUM_TASKS_QUEUE | JOBS_QUEUE',
               'queuePriority': 'Normal | Priority'}}

Retrieves the specified quantum task.

See also: AWS API Documentation

Request Syntax

client.get_quantum_task(
    additionalAttributeNames=[
        'QueueInfo',
    ],
    quantumTaskArn='string'
)
type additionalAttributeNames

list

param additionalAttributeNames

A list of attributes to return information for.

  • (string) --

type quantumTaskArn

string

param quantumTaskArn

[REQUIRED]

the ARN of the task to retrieve.

rtype

dict

returns

Response Syntax

{
    'createdAt': datetime(2015, 1, 1),
    'deviceArn': 'string',
    'deviceParameters': 'string',
    'endedAt': datetime(2015, 1, 1),
    'failureReason': 'string',
    'jobArn': 'string',
    'outputS3Bucket': 'string',
    'outputS3Directory': 'string',
    'quantumTaskArn': 'string',
    'queueInfo': {
        'message': 'string',
        'position': 'string',
        'queue': 'QUANTUM_TASKS_QUEUE'|'JOBS_QUEUE',
        'queuePriority': 'Normal'|'Priority'
    },
    'shots': 123,
    'status': 'CREATED'|'QUEUED'|'RUNNING'|'COMPLETED'|'FAILED'|'CANCELLING'|'CANCELLED',
    'tags': {
        'string': 'string'
    }
}

Response Structure

  • (dict) --

    • createdAt (datetime) --

      The time at which the task was created.

    • deviceArn (string) --

      The ARN of the device the task was run on.

    • deviceParameters (string) --

      The parameters for the device on which the task ran.

    • endedAt (datetime) --

      The time at which the task ended.

    • failureReason (string) --

      The reason that a task failed.

    • jobArn (string) --

      The ARN of the Amazon Braket job associated with the quantum task.

    • outputS3Bucket (string) --

      The S3 bucket where task results are stored.

    • outputS3Directory (string) --

      The folder in the S3 bucket where task results are stored.

    • quantumTaskArn (string) --

      The ARN of the task.

    • queueInfo (dict) --

      Queue information for the requested quantum task. Only returned if QueueInfo is specified in the additionalAttributeNames" field in the GetQuantumTask API request.

      • message (string) --

        Optional. Provides more information about the queue position. For example, if the task is complete and no longer in the queue, the message field contains that information.

      • position (string) --

        Current position of the task in the quantum tasks queue.

      • queue (string) --

        The name of the queue.

      • queuePriority (string) --

        Optional. Specifies the priority of the queue. Quantum tasks in a priority queue are processed before the tasks in a normal queue.

    • shots (integer) --

      The number of shots used in the task.

    • status (string) --

      The status of the task.

    • tags (dict) --

      The tags that belong to this task.

      • (string) --

        • (string) --