tunits.proto

// Copyright 2024 The TUnits Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto2";

package tunits;

option java_multiple_files = true;

// Units supported for serialization.
enum UnitEnum {
  DECIBEL = 1;             // Power unit (dB).
  DECIBEL_MILLIWATTS = 2;  // Decibel-milliwatts (dBm).
  RADIANS = 3;             // Radians (rad).
  HERTZ = 4;               // Frequency unit (Hz).
  VOLT = 5;                // Electric potential Unit (V).
  SECOND = 6;              // Time unit (s).
}

enum Scale {
  // Enum value should be the associated exponent.
  YOTTA = 24;   // 10^24
  ZETTA = 21;   // 10^21
  EXA = 18;     // 10^18
  PETA = 15;    // 10^15
  TERA = 12;    // 10^12
  GIGA = 9;     // 10^9
  MEGA = 6;     // 10^6
  KILO = 3;     // 10^3
  HECTO = 2;    // 10^2
  DECAD = 1;    // 10^1
  UNITY = 0;    // 1
  DECI = -1;    // 10^-1
  CENTI = -2;   // 10^-2
  MILLI = -3;   // 10^-3
  MICRO = -6;   // 10^-6
  NANO = -9;    // 10^-9
  PICO = -12;   // 10^-12
  FEMTO = -15;  // 10^-15
  ATTO = -18;   // 10^-18
  ZEPTO = -21;  // 10^-21
  YOCTO = -24;  // 10^-24
}

// The exponent of a unit e.g.
// m^3 gives numerator=3, denominator=1.
// sqrt(Hz) gives numerator=1, denominator=2.
message Fraction {
  optional int64 numerator = 1;
  optional int64 denominator = 2;
}

// Unit message has a base unit, a scale and an exponent, e.g. 1/sqrt(ns)
// becomes unit=SECOND, scale=NANO, exponent.numerator=-1,
// exponent.denominator=2
message Unit {
  optional UnitEnum unit = 1;
  optional Scale scale = 2;
  optional Fraction exponent = 3;
}

message Complex {
  optional double real = 1;
  optional double imaginary = 2;
}

message Value {
  // Units are repeated to represent combinations of units (e.g. V*s and mV/us).
  // Units are combined through multiplication.
  repeated Unit units = 1;
  oneof value {
    double real_value = 2;
    Complex complex_value = 3;
  }
}

message DoubleArray {
  repeated double values = 1 [packed = true];
}

message ComplexArray {
  repeated Complex values = 1;
}

// Represents an array with associated units (a collection of values that share
// the same units).
message ValueArray {
  // Units are repeated to represent combinations of units (e.g. V*s and mV/us).
  // Units are combined through multiplication.
  repeated Unit units = 1;
  oneof values {
    // The flattened array.
    DoubleArray reals = 2;
    ComplexArray complexes = 3;
  }

  repeated uint32 shape = 4 [packed = true];  // The shape of the array.
}