REST Resource: projects.locations.studies.trials

Resource: Trial

A message representing a Trial. A Trial contains a unique set of Parameters that has been or will be evaluated, along with the objective metrics got by running the Trial.

JSON representation
{
  "name": string,
  "id": string,
  "state": enum (State),
  "parameters": [
    {
      object (Parameter)
    }
  ],
  "finalMeasurement": {
    object (Measurement)
  },
  "measurements": [
    {
      object (Measurement)
    }
  ],
  "startTime": string,
  "endTime": string,
  "clientId": string,
  "infeasibleReason": string,
  "customJob": string
}
Fields
name

string

Output only. Resource name of the Trial assigned by the service.

id

string

Output only. The identifier of the Trial assigned by the service.

state

enum (State)

Output only. The detailed state of the Trial.

parameters[]

object (Parameter)

Output only. The parameters of the Trial.

finalMeasurement

object (Measurement)

Output only. The final measurement containing the objective value.

measurements[]

object (Measurement)

Output only. A list of measurements that are strictly lexicographically ordered by their induced tuples (steps, elapsedDuration). These are used for early stopping computations.

startTime

string (Timestamp format)

Output only. Time when the Trial was started.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

endTime

string (Timestamp format)

Output only. Time when the Trial's status changed to SUCCEEDED or INFEASIBLE.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

clientId

string

Output only. The identifier of the client that originally requested this Trial. Each client is identified by a unique clientId. When a client asks for a suggestion, Vizier will assign it a Trial. The client should evaluate the Trial, complete it, and report back to Vizier. If suggestion is asked again by same clientId before the Trial is completed, the same Trial will be returned. Multiple clients with different client_ids can ask for suggestions simultaneously, each of them will get their own Trial.

infeasibleReason

string

Output only. A human readable string describing why the Trial is infeasible. This is set only if Trial state is INFEASIBLE.

customJob

string

Output only. The CustomJob name linked to the Trial. It's set for a HyperparameterTuningJob's Trial.

State

Describes a Trial state.

Enums
STATE_UNSPECIFIED The Trial state is unspecified.
REQUESTED Indicates that a specific Trial has been requested, but it has not yet been suggested by the service.
ACTIVE Indicates that the Trial has been suggested.
STOPPING Indicates that the Trial should stop according to the service.
SUCCEEDED Indicates that the Trial is completed successfully.
INFEASIBLE Indicates that the Trial should not be attempted again. The service will set a Trial to INFEASIBLE when it's done but missing the finalMeasurement.

Parameter

A message representing a parameter to be tuned.

JSON representation
{
  "parameterId": string,
  "value": value
}
Fields
parameterId

string

Output only. The ID of the parameter. The parameter should be defined in StudySpec's Parameters.

value

value (Value format)

Output only. The value of the parameter. numberValue will be set if a parameter defined in StudySpec is in type 'INTEGER', 'DOUBLE' or 'DISCRETE'. stringValue will be set if a parameter defined in StudySpec is in type 'CATEGORICAL'.

Measurement

A message representing a Measurement of a Trial. A Measurement contains the Metrics got by executing a Trial using suggested hyperparameter values.

JSON representation
{
  "elapsedDuration": string,
  "stepCount": string,
  "metrics": [
    {
      object (Metric)
    }
  ]
}
Fields
elapsedDuration

string (Duration format)

Output only. Time that the Trial has been running at the point of this Measurement.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

stepCount

string (int64 format)

Output only. The number of steps the machine learning model has been trained for. Must be non-negative.

metrics[]

object (Metric)

Output only. A list of metrics got by evaluating the objective functions using suggested Parameter values.

Metric

A message representing a metric in the measurement.

JSON representation
{
  "metricId": string,
  "value": number
}
Fields
metricId

string

Output only. The ID of the Metric. The Metric should be defined in StudySpec's Metrics.

value

number

Output only. The value for this metric.

Methods

addTrialMeasurement

Adds a measurement of the objective metrics to a Trial.

checkTrialEarlyStoppingState

Checks whether a Trial should stop or not.

complete

Marks a Trial as complete.

create

Adds a user provided Trial to a Study.

delete

Deletes a Trial.

get

Gets a Trial.

list

Lists the Trials associated with a Study.

listOptimalTrials

Lists the pareto-optimal Trials for multi-objective Study or the optimal Trials for single-objective Study.

stop

Stops a Trial.

suggest

Adds one or more Trials to a Study, with parameter values suggested by Vertex Vizier.