Package com.apple.foundationdb.linear

Class DoubleRealVector

java.lang.Object
com.apple.foundationdb.linear.AbstractRealVector
com.apple.foundationdb.linear.DoubleRealVector
All Implemented Interfaces:
RealVector
Direct Known Subclasses:
MutableDoubleRealVector
public class DoubleRealVector extends AbstractRealVector
Immutable vector storing 64-bit double-precision components. Conversions to the lower-precision HalfRealVector and FloatRealVector representations are memoized, so callers that round-trip a vector through several precisions repeatedly only pay the conversion cost once per direction. The mutable counterpart with the same storage layout is MutableDoubleRealVector.

  • Constructor Details

    • DoubleRealVector

      public DoubleRealVector(@Nonnull Double[] doubleData)
      Constructs a double-precision vector from a boxed Double[]. The input is defensively copied into a fresh primitive array, so subsequent changes to doubleData do not affect the returned vector.
      Parameters:
      doubleData - the components of the new vector

    • DoubleRealVector

      public DoubleRealVector(@Nonnull double[] data)
      Constructs a double-precision vector over the given primitive array. The array is stored by reference per the base contract — callers must not mutate data after construction. Use data.clone() at the call site if you need an independent backing store.
      Parameters:
      data - the components of the new vector; ownership transfers to this vector

    • DoubleRealVector

      public DoubleRealVector(@Nonnull int[] intData)
      Constructs a double-precision vector by widening each int component to a double. The new vector owns its backing array — the input is read but not retained.
      Parameters:
      intData - the components of the new vector

    • DoubleRealVector

      public DoubleRealVector(@Nonnull long[] longData)
      Constructs a double-precision vector by widening each long component to a double. The new vector owns its backing array — the input is read but not retained. long values outside the 53-bit double mantissa may lose precision.
      Parameters:
      longData - the components of the new vector

  • Method Details

    • toHalfRealVector

      @Nonnull public HalfRealVector toHalfRealVector()
      Returns the memoized half-precision projection of this vector.
      Returns:
      a non-null HalfRealVector containing the Half precision floating-point representation of this object.

    • computeHalfRealVector

      @Nonnull protected HalfRealVector computeHalfRealVector()
      Builds a fresh half-precision view of this vector by truncating each component into a HalfRealVector. Used as the supplier behind toHalfRealVector(); subclasses may override to plug in alternative half-precision representations.
      Returns:
      a new HalfRealVector with this vector's components

    • toFloatRealVector

      @Nonnull public FloatRealVector toFloatRealVector()
      Returns the memoized single-precision projection of this vector.
      Returns:
      a non-null FloatRealVector containing the single precision floating-point representation of this object.

    • computeFloatRealVector

      @Nonnull protected FloatRealVector computeFloatRealVector()
      Builds a fresh single-precision view of this vector by truncating each component into a FloatRealVector. Used as the supplier behind toFloatRealVector(); subclasses may override to plug in alternative single-precision representations.
      Returns:
      a new FloatRealVector with this vector's components

    • toDoubleRealVector

      @Nonnull public DoubleRealVector toDoubleRealVector()
      Returns this — already a double-precision vector, so no conversion is needed.
      Returns:
      a non-null DoubleRealVector representation of this vector.

    • withData

      @Nonnull public DoubleRealVector withData(@Nonnull double[] data)
      Returns a fresh DoubleRealVector backed by data. Like the array-by-reference constructor, ownership of data transfers to the returned vector.
      Parameters:
      data - the components of the new vector
      Returns:
      a fresh immutable double-precision vector

    • toImmutable

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

    • computeRawData

      @Nonnull protected byte[] computeRawData()
      Serializes this double-precision vector into a leading type byte followed by big-endian 64-bit IEEE-754 doubles, one per component. The resulting byte array has length 1 + 8 * 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 DoubleRealVector 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 DoubleRealVector.

      Returns:
      a non-null unit-norm vector

    • add

      @Nonnull public DoubleRealVector 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 DoubleRealVector.

      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 DoubleRealVector 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 DoubleRealVector.

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

    • subtract

      @Nonnull public DoubleRealVector 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 DoubleRealVector.

      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 DoubleRealVector 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 DoubleRealVector.

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

    • multiply

      @Nonnull public DoubleRealVector 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 DoubleRealVector.

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

    • zeroVector

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

    • computeDoubleData

      @Nonnull protected static double[] computeDoubleData(@Nonnull Double[] doubleData)
      Unboxes a Double[] into a freshly allocated double[] suitable for handing to the array-by-reference constructor. Shared between this class and MutableDoubleRealVector's boxed-array constructor.
      Parameters:
      doubleData - the boxed components
      Returns:
      a new primitive array of the same length and values

    • fromBytes

      @Nonnull public static DoubleRealVector fromBytes(@Nonnull byte[] vectorBytes)
      Creates a DoubleRealVector from a byte array.

      This method interprets the input byte array as a sequence of 64-bit double-precision floating-point numbers. Each run of eight bytes is converted into a double value, which then becomes a component of the resulting vector.

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

    • decodeDoubleBytes

      @Nonnull protected static double[] decodeDoubleBytes(@Nonnull byte[] vectorBytes)
      Decodes a serialized double-precision vector byte array into its raw double[] components, shared between fromBytes(byte[]) and MutableDoubleRealVector.fromBytes(byte[]). The first byte must be the VectorType.DOUBLE ordinal; the remainder is read as big-endian 64-bit doubles.
      Parameters:
      vectorBytes - the non-null byte array to decode
      Returns:
      a freshly allocated double[] with the decoded components