swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector HyperDriveExperiment API
schemes:
- https
tags:
- name: HyperDriveExperiment
paths:
  /hyperdrive/v1.0/{armScope}/runs:
    post:
      tags:
      - HyperDriveExperiment
      summary: Microsoft Azure Create An Experiment
      description: Create a HyperDrive Experiment.
      operationId: microsoftAzureHyperparametertuningCreateexperiment
      consumes:
      - multipart/form-data
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/ArmScopeParameter'
      - in: formData
        name: config
        description: The configuration file with experiment JSON content. A text file that is a JSON-serialized '#/definitions/HyperDriveCreateExperiment' object.
        type: file
        required: true
      responses:
        '201':
          description: OK
          schema:
            $ref: '#/definitions/HyperDriveExperimentResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/HyperDriveErrorResponse'
      x-ms-examples:
        Create a HyperDrive experiment:
          $ref: ./examples/createHyperDriveExperiment.json
  /hyperdrive/v1.0/{armScope}/runs/{runId}/cancel:
    post:
      tags:
      - HyperDriveExperiment
      summary: Microsoft Azure Cancel An Experiment
      description: Cancel a HyperDrive Experiment.
      operationId: microsoftAzureHyperparametertuningCancelexperiment
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/ArmScopeParameter'
      - name: runId
        in: path
        description: Hyperdrive run id to cancel.
        required: true
        type: string
      - in: header
        name: RunHistoryHost
        description: The host for run location.
        type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/HyperDriveCancelExperimentResponse'
        default:
          description: Error
          schema:
            $ref: '#/definitions/HyperDriveErrorResponse'
      x-ms-examples:
        Cancel a HyperDrive experiment:
          $ref: ./examples/cancelHyperDriveExperiment.json
definitions:
  HyperDriveErrorResponse:
    properties:
      code:
        format: int32
        type: integer
        description: Error response code.
      message:
        type: string
        description: Error message.
    required:
    - code
    - message
    type: object
    description: Response in case of an error.
  HyperDriveCancelExperimentResponse:
    properties:
      code:
        format: int32
        type: integer
        description: Response code.
      result:
        type: string
        description: Message indicating operation success.
    required:
    - code
    - result
    type: object
    description: Response for HyperDrive_CancelExperiment in case of success.
  HyperDriveExperimentResponse:
    description: Response for HyperDrive_CreateExperiment in case of success.
    properties:
      code:
        format: int32
        type: integer
        description: Response code.
      result:
        description: Details about created Hyperdrive run.
        $ref: '#/definitions/HyperDriveExperiment'
    required:
    - code
    - result
    type: object
  HyperDriveExperimentBase:
    description: Base object for both request and response of HyperDrive_CreateExperiment api.
    properties:
      description:
        maxLength: 511
        type: string
        x-nullable: true
        description: The description for Hyperdrive run.
      generator_config:
        description: Hyperparameter space and the sampling method configuration.
        properties:
          name:
            type: string
            enum:
            - RANDOM
            - GRID
            - BAYESIANOPTIMIZATION
            description: Hyperparameter sampling method.
            x-ms-enum:
              name: Name
              modelAsString: true
          parameter_space:
            type: object
            additionalProperties:
              type: array
              items: {}
              minItems: 2
              maxItems: 2
              description: "The first element in the array is a string identifying the parameter expression type like choice, uniform etc. The second element is a parameter expressions corresponding to the type.\r\n Please refer to https://docs.microsoft.com/en-us/python/api/azureml-train-core/azureml.train.hyperdrive.parameter_expressions?view=azure-ml-py for a list of supported types and options for each type.\r\n choice parameters are specified as ['choice', [[1, 2, 3, 4]]]. randint is in format ['randint', [1]].\r\n uniform, loguniform, normal, lognormal are in format [expression type, [0.01, 0.05]].\r\n quniform, qloguniform, qnormal, qlognormal are in format [expression type, [0.01, 0.05, 3]].\r\n"
              example:
              - choice
              - - - 1
                  - 2
                  - 3
                  - 4
            description: Dictionary specifying hyperparameter space.
        required:
        - name
        - parameter_space
        type: object
      max_concurrent_jobs:
        format: int32
        maximum: 100
        minimum: 1
        type: integer
        description: Maximum number of runs to run concurrently.
      max_duration_minutes:
        format: int32
        maximum: 43200
        minimum: 1
        type: integer
        description: Maximum duration of the Hyperdrive run.
      max_total_jobs:
        format: int32
        maximum: 1000
        minimum: 1
        type: integer
        description: Maximum number of runs.
      name:
        maxLength: 255
        type: string
        description: Name of the Hyperdrive run.
      platform:
        type: string
        enum:
        - AML
        description: Platform of the Hyperdrive run.
        x-ms-enum:
          name: Platform
          modelAsString: true
      platform_config:
        type: object
        description: Platform config object specifying the run definition structure.
      policy_config:
        description: Early termination policy configuration.
        $ref: '#/definitions/HyperDrivePolicyConfigBase'
      primary_metric_config:
        description: Name of the primary metric and goal of optimizing.
        properties:
          goal:
            type: string
            enum:
            - MAXIMIZE
            - MINIMIZE
            description: Determines if the primary metric has to be minimized/maximized.
            x-ms-enum:
              name: Goal
              modelAsString: true
          name:
            type: string
            description: Name of the primary metric reported by runs.
        required:
        - goal
        - name
        type: object
      study_id:
        format: int32
        minimum: 0
        type: integer
        x-nullable: true
        description: Study Id of the Hyperdrive run.
    required:
    - generator_config
    - name
    - platform
    - platform_config
    - policy_config
    - primary_metric_config
    type: object
  HyperDriveExperiment:
    type: object
    description: Part of response for HyperDrive_CreateExperiment in case of success. Contains details about the created hyperdrive run.
    allOf:
    - $ref: '#/definitions/HyperDriveExperimentBase'
    - type: object
      properties:
        all_jobs_generated:
          type: boolean
          description: Indicates if all runs have been generated.
        cancellation_requested:
          type: boolean
          description: Indicates if cancellation has been requested for this Hyperdrive run.
        created:
          format: date-time
          type: string
          description: Hyperdrive run creation time.
        created_by_user_id:
          format: int32
          type: integer
          description: Id of the user who created the Hyperdrive run.
        experiment_id:
          type: string
          description: Hyperdrive run id.
        experiment_uri:
          type: string
          description: Hyperdrive run Uri.
        modified:
          format: date-time
          type: string
          description: Hyperdrive run modification time.
        status:
          type: string
          description: Hyperdrive run status.
        study_uri:
          type: string
          description: Study Uri of the Hyperdrive run.
        hyperdrive_run_id:
          type: string
          description: Hyperdrive run id.
      required:
      - all_jobs_generated
      - cancellation_requested
      - created
      - created_by_user_id
      - experiment_id
      - modified
      - status
      - hyperdrive_run_id
    properties: {}
  HyperDrivePolicyConfigBase:
    description: Early termination policy configuration.
    properties:
      name:
        type: string
        enum:
        - Default
        - Bandit
        - MedianStopping
        - TruncationSelection
        description: Type of early termination policy.
        x-ms-enum:
          name: Name
          modelAsString: true
    required:
    - name
    type: object
    discriminator: name
parameters:
  ArmScopeParameter:
    name: armScope
    in: path
    description: "The ARM scope passed in through URL with format:\r\n            subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/experiments/{experimentName}.\r\n"
    required: true
    type: string
    x-ms-skip-url-encoding: true
    x-ms-parameter-location: method
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'