run_context.proto

syntax = "proto3";

package cirq.google.api.v2;

option java_package = "com.google.cirq.google.api.v2";
option java_outer_classname = "RunContextProto";
option java_multiple_files = true;

// The context for running a quantum program.
message RunContext {
  // The parameters for operations in a program.
  repeated ParameterSweep parameter_sweeps = 1;
}

// Specifies how to repeatedly sample a circuit, with or without sweeping over
// varying parameter-dicts.
message ParameterSweep {
  // How many times to sample, for each parameter-dict that is swept over.
  // This must be set to a value strictly greater than zero.
  int32 repetitions = 1;

  // Which parameters, that control gates in the circuit, to try.
  //
  // The keys of the parameters generated by this sweep must be a superset
  // of the keys in the program's operation's Args. When this is not specified,
  // no parameterization is assumed (and the program must have no
  // args with symbols).
  Sweep sweep = 2;
}

// A sweep over all of the parameters in a program.
message Sweep {

  // The sweep is either a function of sweeps or an actual assignment of
  // a symbol to a list of values.
  oneof sweep {
    SweepFunction sweep_function = 1;
    SingleSweep single_sweep = 2;
  }
}

// A function that takes multiple sweeps and produces more sweeps.
message SweepFunction {
  // The type of sweep function.
  enum FunctionType {
    // The function type is not specified. Should never be used.
    FUNCTION_TYPE_UNSPECIFIED = 0;

    // A Cartesian product of parameter sweeps.
    //
    // Example of product:
    // If one of the sweeps assigns
    // "a": 0.0
    // "a": 1.0
    // and another assigns
    // "b": 2.0
    // "b": 3.0
    // then the product of these assigns all possible combinations.
    // "a": 0.0, "b": 2.0
    // "a": 0.0, "b": 3.0
    // "a": 1.0, "b": 2.0
    // "a": 1.0, "b": 3.0
    PRODUCT = 1;

    // A zip product of parameter sweeps.
    //
    // Example of zip:
    // If one of the sweeps assigns
    // "a": 0.0
    // "a": 1.0
    // and another assigns
    // "b": 2.0
    // "b": 3.0
    // then the product of these assigns
    // "a": 0.0, "b": 2.0
    // "a": 1.0, "b": 3.0
    // Note: if one sweep is shorter, the others will be truncated.
    ZIP = 2;
  }

  FunctionType function_type = 1;

  // The argument sweeps to the function.
  repeated Sweep sweeps = 2;
}

message DeviceParameter {

    // Path to the parameter key
    repeated string path = 1;

    // If the value is an array, the index of the array to change.
    int64 idx = 2;

    // String representation of the units, if any.
    // Examples: "GHz", "ns", etc.
    string units = 3;

    // Note that the device parameter values will be populated
    // by the sweep values themselves.
}


// A set of values to loop over for a particular parameter.
message SingleSweep {
  // The parameter key being varied. This cannot be the empty string.
  // These are must appear as string Args in the quantum program.
  string parameter_key = 1;

  // How to vary the parameter.
  oneof sweep {
    // An explicit list of points to try.
    Points points = 2;
    // Uniformly-spaced sampling over a range.
    Linspace linspace = 3;
  }

  // Optional arguments for if this is a device parameter.
  // (as opposed to a circuit symbol)
  DeviceParameter parameter = 4;
}

// A list of explicit values.
message Points {
  // The values.
  repeated float points = 1;
}

// A range of evenly-spaced values.
//
// Example: if the first_point is 1.0, the last_point is 2.0 ,
// and the num_points is 5, thi corresponds to the points
//   1.0, 1.25, 1.5, 1.75, 2.0
message Linspace {
  // The start of the range.
  float first_point = 1;
  // The end of the range.
  float last_point = 2;
  // The number of points in the range (including first and last). Must be
  // greater than zero. If it is 1, the first_point and last_point must be
  // the same.
  int64 num_points = 3;
}