Package com.apple.foundationdb.linear

Class HalfRealVector

java.lang.Object
com.apple.foundationdb.linear.AbstractRealVector
com.apple.foundationdb.linear.HalfRealVector
All Implemented Interfaces:
RealVector
public class HalfRealVector extends AbstractRealVector
Immutable vector storing 16-bit Half-precision components. Internally the data is widened to a double[] for arithmetic compatibility with the rest of the RealVector hierarchy, but every value is first truncated through Half.valueOf(double) so storage cost and round-trip behaviour match a true half-precision vector. Conversions to the higher-precision FloatRealVector and DoubleRealVector are not memoized (each call wraps the already-widened backing array in a fresh instance — cheap enough that caching wouldn't pay off).

  • Constructor Details

    • HalfRealVector

      public HalfRealVector(@Nonnull Half[] halfData)
      Constructs a half-precision vector from a boxed Half[]. The input is unboxed and widened into a fresh double[] backing store; subsequent changes to halfData do not affect the returned vector.
      Parameters:
      halfData - the components of the new vector

    • HalfRealVector

      public HalfRealVector(@Nonnull double[] data)
      Constructs a half-precision vector from a primitive double[]. The input is truncated component-wise through Half.valueOf(double) (and re-widened to double) so round-trip behaviour matches a native half-precision vector. The original data array is read but not retained.
      Parameters:
      data - the components of the new vector, in double precision

    • HalfRealVector

      public HalfRealVector(@Nonnull int[] intData)
      Constructs a half-precision vector by widening each int component. The new vector owns its backing array — the input is read but not retained. int values outside the ~11-bit half-precision mantissa lose precision after the truncation in the constructor delegate.
      Parameters:
      intData - the components of the new vector

    • HalfRealVector

      public HalfRealVector(@Nonnull long[] longData)
      Constructs a half-precision vector by widening each long component. The new vector owns its backing array — the input is read but not retained. Same precision caveats as HalfRealVector(int[]).
      Parameters:
      longData - the components of the new vector

  • Method Details

    • toHalfRealVector

      @Nonnull public HalfRealVector toHalfRealVector()
      Returns this — already a half-precision vector, so no conversion is needed.
      Returns:
      a non-null HalfRealVector containing the Half precision floating-point representation of this object.

    • toFloatRealVector

      @Nonnull public FloatRealVector toFloatRealVector()
      Returns a fresh FloatRealVector carrying this vector's already-widened components. Note that the underlying values are still half-truncated; the conversion only changes the runtime type, not the precision of the data.
      Returns:
      a non-null FloatRealVector containing the single precision floating-point representation of this object.

    • toDoubleRealVector

      @Nonnull public DoubleRealVector toDoubleRealVector()
      Returns a fresh DoubleRealVector carrying this vector's already-widened components. Note that the underlying values are still half-truncated; the conversion only changes the runtime type, not the precision of the data.
      Returns:
      a non-null DoubleRealVector representation of this vector.

    • withData

      @Nonnull public HalfRealVector withData(@Nonnull double[] data)
      Returns a fresh HalfRealVector carrying data (after truncation to half precision inside the constructor).
      Parameters:
      data - the components of the new vector
      Returns:
      a fresh immutable half-precision vector

    • computeRawData

      @Nonnull protected byte[] computeRawData()
      Serializes this half-precision vector into a leading type byte followed by big-endian 16-bit Half-encoded components, one per dimension. The resulting byte array has length 1 + 2 * getNumDimensions() and round-trips through fromBytes(byte[]).
      Specified by:
      computeRawData in class AbstractRealVector
      Returns:
      a new byte array representing the serialized vector data; never null

    • normalize

      @Nonnull public HalfRealVector normalize()
      Returns a new vector pointing in the same direction as this vector but scaled to unit L2 norm. The receiver is not mutated; the result is a fresh allocation of the same precision type.

      Narrows the return type to HalfRealVector.

      Returns:
      a non-null unit-norm vector

    • add

      @Nonnull public HalfRealVector add(@Nonnull RealVector other)
      Returns a new vector whose components are the element-wise sum of this vector and other. The receiver is not mutated.

      Narrows the return type to HalfRealVector.

      Parameters:
      other - the right operand; must have the same dimensionality as this vector
      Returns:
      a non-null vector with result[i] = this[i] + other[i]

    • add

      @Nonnull public HalfRealVector add(double scalar)
      Returns a new vector with scalar added to every component of this vector. The receiver is not mutated.

      Narrows the return type to HalfRealVector.

      Parameters:
      scalar - the value to add to each component
      Returns:
      a non-null vector with result[i] = this[i] + scalar

    • subtract

      @Nonnull public HalfRealVector subtract(@Nonnull RealVector other)
      Returns a new vector whose components are the element-wise difference of this vector and other. The receiver is not mutated.

      Narrows the return type to HalfRealVector.

      Parameters:
      other - the right operand; must have the same dimensionality as this vector
      Returns:
      a non-null vector with result[i] = this[i] - other[i]

    • subtract

      @Nonnull public HalfRealVector subtract(double scalar)
      Returns a new vector with scalar subtracted from every component of this vector. The receiver is not mutated.

      Narrows the return type to HalfRealVector.

      Parameters:
      scalar - the value to subtract from each component
      Returns:
      a non-null vector with result[i] = this[i] - scalar

    • multiply

      @Nonnull public HalfRealVector multiply(double scalar)
      Returns a new vector with every component of this vector scaled by scalar. The receiver is not mutated.

      Narrows the return type to HalfRealVector.

      Parameters:
      scalar - the factor to scale each component by
      Returns:
      a non-null vector with result[i] = this[i] * scalar

    • zeroVector

      @Nonnull public static HalfRealVector zeroVector(int numDimensions)
      Returns a vector whose components are all zero.
      Parameters:
      numDimensions - number of dimensions
      Returns:
      a vector whose components are all zero

    • toImmutable

      @Nonnull public HalfRealVector toImmutable()
      Returns this — instances of this class are already immutable.
      Returns:
      a non-null immutable vector with the same components as this vector

    • fromBytes

      @Nonnull public static HalfRealVector fromBytes(@Nonnull byte[] vectorBytes)
      Creates a HalfRealVector from a byte array produced by AbstractRealVector.getRawData().

      The input is interpreted as a leading type byte (which must match VectorType.HALF) followed by a sequence of big-endian 16-bit Half-encoded components, one per dimension.

      Parameters:
      vectorBytes - the non-null byte array to convert
      Returns:
      a new HalfRealVector instance created from the byte array