program.proto

syntax = "proto3";

package cirq.google.api.v2;

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

// A quantum program.
message Program {
  // The language in which the program is written.
  Language language = 1;

  // Programs can be specified by a circuit or a schedule.
  oneof program {
    // A circuit is an abstract representation as a series of moments, each
    // moment having a set of gates that act on disjoint qubits. Circuits don't
    // have absolute times for their operations (gates acting on qubits).
    Circuit circuit = 2;

    // Schedules are a list of operations (gates acting on qubits) that specify
    // absolute start times for the operations.
    Schedule schedule = 3;
  }

  // List to store global constants, such as strings used in many places.
  // constants are referred to their index in this list, starting at zero.
  repeated Constant constants = 4;
}

// Constants, such as long strings, that are used throughout the circuit.
// These constants can be stored here to save space.
message Constant {
  oneof const_value {
    // String value used throughout the circuit, such as for token values
    string string_value = 1;

    // Sub Circuit used for CircuitOperations
    Circuit circuit_value = 2;

    // Qubits used within the circuit (only populated in v2.5+)
    Qubit qubit = 3;
  }
}

// The quantum circuit, specified as a series of moments (abstract
// slices of times with gates acting on disjoint sets of qubits).
message Circuit {
  // How the circuit is scheduled.
  enum SchedulingStrategy {
    // The scheduling strategy is unspecified.
    SCHEDULING_STRATEGY_UNSPECIFIED = 0;

    // Each operation in a moment starts at the same time. The start of the
    // next moment is given by the duration of the longest operation in
    // the current moment.
    MOMENT_BY_MOMENT = 1;
  }

  SchedulingStrategy scheduling_strategy = 1;

  // The moments of the circuit, with the first element corresponding to the
  // first set of operations to apply, etc.
  repeated Moment moments = 2;
}

// A moment is a collection of operations and circuit operations that operate
// on a disjoint set of qubits. Conceptually, a moment represents operations
// that all occur in the same finite period of time.
message Moment {
  // All of the gate operations in the moment. Each operation and circuit
  // operation must act on different qubits.
  repeated Operation operations = 1;

  // All of the circuit operations in the moment. Each operation and circuit
  // operation must act on different qubits.
  repeated CircuitOperation circuit_operations = 2;
}

// The quantum circuit, specified as a series of operations at specific
// start times.
message Schedule {
  // A list of all the operations and their absolute start times.
  repeated ScheduledOperation scheduled_operations = 3;
}

// An operation occurring at a specific start time.
message ScheduledOperation {
  // Which operation is to be scheduled.
  Operation operation = 1;

  // The start time of the operation, with zero representing the absolute
  // start of the circuit.
  //
  // This must be consistent with the moment structure and must be positive.
  int64 start_time_picos = 2;
}

// The language in which the program is expressed.
message Language {
  // The name of the gate set being used.
  //
  // Valid names for the gate sets can be found in
  // cirq_google/serialization/gate_sets.py.
  //
  // Deprecated: A device now only supports a single gate set.
  // Previously, the value of this field also refers to the name of the
  // serializer for the program. Currently, the only serializer available is
  // CircuitSerializer in cirq_google/serialization/circuit_serializer.py.
  string gate_set = 1 [deprecated = true];

  // The language supported by ArgFunctions. These specifies what allowed
  // ArgFunction types there are.
  //
  // Valid names for the arg function language can be found in
  // cirq/google/arg_func_langs.py
  string arg_function_language = 2;
}

// Argument that is constrained to a float or symbolic expression
message FloatArg {
  oneof arg {
    float float_value = 1;
    string symbol = 2;
    ArgFunction func = 3;
  }
}

// Representation of cirq.XPowGate
message XPowGate {
  FloatArg exponent = 1;
}

// Representation of cirq.YPowGate
message YPowGate {
  FloatArg exponent = 1;
}

// Representation of cirq.ZPowGate
message ZPowGate {
  FloatArg exponent = 1;

  // If true, this is equivalent to:
  // cirq.ZPowGate(...).with_tags(cirq.google.PhysicalZTag)
  bool is_physical_z = 2;
}

// Representation of cirq.PhasedXPowGate
message PhasedXPowGate {
  FloatArg phase_exponent = 1;
  FloatArg exponent = 2;
}

// Representation of cirq.PhasedXZGate
message PhasedXZGate {
  FloatArg x_exponent = 1;
  FloatArg z_exponent = 2;
  FloatArg axis_phase_exponent = 3;
}

// Representation of cirq.CZPowGate
message CZPowGate {
  FloatArg exponent = 1;
}

// Representation of cirq.FSimGate
message FSimGate {
  FloatArg theta = 1;
  FloatArg phi = 2;
}

// Representation of cirq.ISwapPowGate
message ISwapPowGate {
  FloatArg exponent = 1;
}

// Representation of cirq.MeasurementGate
// i.e. cirq.measure
message MeasurementGate {
  Arg key = 1;
  Arg invert_mask = 2;
}

// Representation of cirq.WAitGate
message WaitGate {
  // Duration of the waiting period,
  // serialized to the number of nanoseconds
  FloatArg duration_nanos = 1;
}

// An operation acts on a set of qubits.
message Operation {
  // Which gate this operation corresponds to.
  // Populated pre-v2.5+.
  Gate gate = 1 [deprecated = true];

  // Each gate should populate one possible gate message
  // depending on the type desired.  Only populated in v2.5+.
  oneof gate_value {
    XPowGate xpowgate = 7;
    YPowGate ypowgate = 8;
    ZPowGate zpowgate = 9;
    PhasedXPowGate phasedxpowgate = 10;
    PhasedXZGate phasedxzgate = 11;
    CZPowGate czpowgate = 12;
    FSimGate fsimgate = 13;
    ISwapPowGate iswappowgate = 14;
    MeasurementGate measurementgate = 15;
    WaitGate waitgate = 16;
    InternalGate internalgate = 17;
    CouplerPulseGate couplerpulsegate = 18;
    IdentityGate identitygate = 19;
    HPowGate hpowgate = 20;
    SingleQubitCliffordGate singlequbitcliffordgate = 21;
  }

  // Map from the argument name to the Argument needed to fully specify
  // the gate. Only populated pre-v2.5+.
  map<string, Arg> args = 2 [deprecated = true];

  // Which qubits the operation acts on.
  // Operations should populate one of the following two
  // fields: either to specify the qubit directly or
  // to reference an index in the enclosing Program's
  // constant messages.  Note that qubit_constant_index
  // will only be populated in v2.5+
  repeated Qubit qubits = 3;
  repeated int32 qubit_constant_index = 6;

  // Token that can be used to specify a version of a gate.
  // For instance, a gate that has been calibrated for a circuit.
  //
  // The token can be specified as a string or as a reference to
  // the constant table of the circuit.
  oneof token {
    string token_value = 4;
    int32 token_constant_index = 5;
  }
}

// The instruction identifying the action taken on the quantum computer.
message Gate {
  // Name for the Gate.
  //
  // These names must match those specified in the gate set.  This is found
  // in cirq/google/gate_sets.py.
  string id = 1;
}

// An identifier for a qubit.
message Qubit {
  // Id of the qubit. These depend on the device being scheduled upon.
  //
  // Typically ids for qubits on a line are simple string versions of integers,
  // while for qubits on a square grid these are integers separated by a
  // underscore, i.e. '0_1', '1_2', etc.
  string id = 2;
}

// Arguments needed to specify a gate.
message Arg {
  // Arguments are either a number, a symbol, or an argument function
  // (which recursively depends on Arg).
  //
  // ArgValue is used to specify an argument that does not vary
  // depending on RunContext.
  //
  // Symbol is used when an argument will be resolved (supplied a value)
  // by a Run Context.
  //
  // Functions are used to define a simple s-expression tree describing
  // how to combine numbers and symbols mathematically.
  //
  // The argument can also be specified as a lookup in the Constant
  // table of the Circuit.
  oneof arg {
    ArgValue arg_value = 1;
    string symbol = 2;
    ArgFunction func = 3;
    int32 constant_index = 4;
  }
}

// Value that can be passed as an argument to a gate.
message ArgValue {
  oneof arg_value {
    float float_value = 1;
    RepeatedBoolean bool_values = 2;
    string string_value = 3;
    double double_value = 4;
    RepeatedInt64 int64_values = 5;
    RepeatedDouble double_values = 6;
    RepeatedString string_values = 7;
  }
}

// A repeated int value.
message RepeatedInt64 {
  repeated int64 values = 1;
}
// A repeated double value.
message RepeatedDouble {
  repeated double values = 1;
}
// A repeated string value.
message RepeatedString {
  repeated string values = 1;
}
// A repeated boolean value.
message RepeatedBoolean {
  repeated bool values = 1;
}

// A function of arguments. This is an s-expression tree representing
// mathematically the function being evaluated.
//
// What language is supported is specified by the arg_function_language
// in the language message.
message ArgFunction {
  // The name of the function. I.e. if the function is the sum of two symbols,
  // this could be '+', and the args would be two string symbol values.
  //
  // Valid values for the type are given in cirq/google/arg_func_langs.py
  // and must be consistent with the arg_function_language specified in the
  // language field of the program.
  string type = 1;

  // The arguments to the function.
  repeated Arg args = 2;
}

// An operation that applies a modified version of a reference circuit. The
// circuit is stored in the top-level Constants table; the mappings in this
// object specify how that circuit should be modified for this operation.
//
// Multiple CircuitOperations may reference the same base circuit even if their
// mappings of that circuit are different.
message CircuitOperation {
  // The index of the circuit in the top-level constant table.
  int32 circuit_constant_index = 1;

  // Specifier for repetitions of the circuit, which contains either a number
  // of repetitions or a list of repetition IDs.
  RepetitionSpecification repetition_specification = 2;

  // Map from qubits in the "inner" circuit (referenced by
  // circuit_constant_index) to qubits in the "outer" circuit (the one that
  // contains this operation).
  QubitMapping qubit_map = 3;

  // Map of measurement keys in the "inner" circuit (referenced by
  // circuit_constant_index) to measurement keys in the "outer" circuit (the
  // one that contains this operation).
  MeasurementKeyMapping measurement_key_map = 4;

  // Map of args in the "inner" circuit (referenced by circuit_constant_index)
  // to args in the "outer" circuit (the one that contains this operation).
  ArgMapping arg_map = 5;
}

// A description of the repetitions of a subcircuit. IDs are used as suffixes
// for measurements in the repeated subcircuit; if repetition_count is given
// instead, the IDs will simply be the integers [0..N-1].
message RepetitionSpecification {
  // An ordered list of IDs for a sequence of repetitions.
  message RepetitionIds {
    repeated string ids = 1;
  }

  oneof repetition_value {
    // A list of unique IDs, one per repetition of the subcircuit.
    RepetitionIds repetition_ids = 1;

    // An integer number of repetitions to perform.
    int32 repetition_count = 2;
  }
}

// A mapping of qubits from one value to another. All mappings are applied
// simultaneously and independently; for example, [(a, b), (b, a)] will swap
// qubits a and b.
message QubitMapping {
  // Indicates that qubit "key" should be replaced with "value".
  message QubitEntry {
    Qubit key = 1;
    Qubit value = 2;
  }

  // A list of qubit mappings to apply.
  repeated QubitEntry entries = 1;
}

// A key for matching a measurement event to its results.
message MeasurementKey {
  string string_key = 1;
}

// A mapping of measurement keys from one value to another. All mappings are
// applied simultaneously and independently; for example, [(a, b), (b, a)] will
// swap measurement keys a and b.
message MeasurementKeyMapping {
  // Indicates that measurement key "key" should be replaced with "value".
  message MeasurementKeyEntry {
    MeasurementKey key = 1;
    MeasurementKey value = 2;
  }

  // A list of measurement key mappings to apply.
  repeated MeasurementKeyEntry entries = 1;
}

// A mapping of args from one value to another. All mappings are applied
// simultaneously and independently; for example, [(a, b), (b, a)] will swap
// args a and b.
message ArgMapping {
  // Indicates that arg "key" should be replaced with "value".
  message ArgEntry {
    Arg key = 1;
    Arg value = 2;
  }

  // A list of arg mappings to apply.
  repeated ArgEntry entries = 1;
}

message InternalGate{
  string name = 1;  // Gate name.
  string module = 2;  // Gate module. 
  int32 num_qubits = 3;  // Number of qubits. Required during deserialization.
  map<string, Arg> gate_args = 4;  // Gate args.
}

message CouplerPulseGate{
  optional FloatArg hold_time_ps = 1;  // ps=picoseconds.
  optional FloatArg rise_time_ps = 2;  // ps=picoseconds.
  optional FloatArg padding_time_ps = 3;  // ps=picoseconds.
  optional FloatArg coupling_mhz = 4;
  optional FloatArg q0_detune_mhz = 5;
  optional FloatArg q1_detune_mhz = 6;
}

message CliffordTableau {
  optional int32 num_qubits = 1;  // Number of qubits the CliffordTableau acts on.
  optional int32 initial_state = 2;  // The initial state.
  repeated bool rs = 3;  // A flattened version of the `rs` array.
  repeated bool xs = 4;  // A flattened version of the `xs` array.
  repeated bool zs = 5;  // A flattened version of the `zs` array.
}

message SingleQubitCliffordGate {
  CliffordTableau tableau = 1;
}

message IdentityGate {
  repeated uint32 qid_shape = 1;
}

message HPowGate {
  FloatArg exponent = 1;
}