On this page
Vector
The Vector object represents a real dense vector that is backed by a primitive double Java array. Because the vector is backed by a Java array, the elements of the vector are stored contiguously in memory and uses zero-based indexing. The maximum number of entries in a vector is limited by the maximum Java array size of 2,147,483,647.
A Vector is essentially a rank 1 Tensor. However, the vector objects in Flag4j have specialized algorithms and operations which may yield additional performance and ease of use over a 1D tensor.
Vector objects in Flag4j do not have an inherent notion of orientation (e.g., row or column vector). However, some methods will treat the vector as if it were a row or column vector. For example, the matrix-vector multiplication method provided in the Matrix class operates as if the vector is a column vector.
Initialization
The Vector class contain several constructors that can be used to initialize an instance. The most basic constructor takes a single Java double[] array which will be used as the data of the vector. Note that when using this constructor, the double[] array backing the vector will be the same instance passed as a parameter to the constructor. This means manipulating entries in the original array will be reflected in the Vector object instance.
Passing a sequence of doubles will also initialize a vector in the same manner as a passing a Java double[] array because the values will be implicitly wrapped as an array. It is similar when passing a primitive Java int[] array as well but in this case the original array will not be the same instance as the data array of the Vector so changes made in the original array will not be reflected in the vector object instance.
There are a few possible gotchas with the available constructors we will discuss. The Vector class also offers some constructors to initialize zero vectors or single value vectors of a specified size. Passing a single integer will create a zero vector of that size while passing a single double (or float) will result in a vector with a single entry with that value. Passing an integer followed by a single double (or float) will result in a vector of size equal to the integer with all values set to the passed double value. However, passing two doubles (or floats) will result in a vector of length 2 with those two entries. Users should be carful and note the difference between the constructor which accepts an integer then a double and the varargs double constructor.
The snippet below provides examples of using all major constructors available in Flag4j's Vector class.
As with all array objects in Flag4j, you may create a copy of a Vector using the copy() method.
This will be a deep copy in the sense that changing the elements in the copy vector will have no effect on the elements of the original vector.
Core Attributes
The Vector object maintains its most important properties as public final fields. This includes size/shape and data (i.e. the entries) of the vector as well as the rank which will trivially be 1 for any vector. The rank is provided to be consistent with Flag4j's array API.
There are also several getters provided as part of Flag4j's array API. For vectors, the totalEntries() getter will always be equal to the length/size of the vector.
Element Access &
Slicing
There are several methods available in the Vector object for setting and accessing data.
Users can get a single element, get a slice (i.e., a continuous range of values), or get items at a specific list of indices. Getting a slice or multiple items will return a Vector object containing all of the specified items.
Similarly, users may set a single item, set a slice, or set multiple items at specific indices. When setting a slice or multiple items, the new values may be specified in an array or as another vector. All set methods take the new value(s) to set first, then the index/indices to be set second. This is done to allow for varargs to be used when setting values in Tensors while maintaining a consistent API across all array objects in Flag4j.
Reshaping & Manipulating
Because vectors are 1D arrays they cannot be reshaped (and remain a 1D array). However, the reshape and flatten methods are still supported as part of Flag4j's array API. These methods are effectively just a copy and only support the shape/size parameter to be exactly the same as the shape/size of the vector exactly.
It is still possible to convert the Vector to a Matrix or Tensor which can be reshaped. See the section on interoperability for examples.
Attributes & Comparisons
Vectors support the basic element-wise comparisons defined by Flag4j's array API including equality and approximate equality: equals(...) and allClose(...) respectively. Vector objects also support checking for parallelism and perpendicularity.
As with any real dense array object in Flag4j, users can check if a Vector contains only finite values, contains a NaN, or if all entries are all positive, negative, zeros, or ones.
Standard Operations
As part of Flag4j's array API, Vectors support all basic arithmetic operations. Users can compute element-wise addition, subtraction, multiplication and division with two vector objects or with a scalar value.
For all operations in the example code snippet below, the vectors `a` and `b` may contain arbitrary elements provided they are the same size. Each operation may also be done in-place using the accompanying [operation]Eq() method.
For any of the binary element-wise operations, if the two vectors are not the same size, an error will be thrown.
Linear Algebra &
Tensor Operations
There are a few "vector-specific" operations supported by the Vector object. Specifically, vector products, and vector norms/magnitudes.
Vector Products
For real vectors, the inner and dot products are equivalent.
The outer product will return a Matrix.
The cross product is only defined for vectors of length 3. If vectors of a different length are used, an exception will be thrown. It will return a Vector of length 3.
Vector Norms
Flag4j supports the standard norms such as L1, L2, Lp, and maximum norms. Arbitrary p-values may be specified when computing the Lp norm, even negative values. Strictly speaking, p-values less than 1 are not true norms in the sense that they may not satisfy all formal requirements of a norm. However, they can still be useful for numerical purposes and are supported by Flag4j. Computing the magnitude of a vector is equivalent to the L2 (Euclidian) norm.
Passing a p-value of Double.POSITIVE_INFINITY will result in the maximum norm while Double.NEGATIVE_INFINITY will return in the minimum "norm" (which is not a true norm).
Note: While p-values less than 1 are supported, setting p equal to exactly zero will raise an error to avoid division by zero.
Reductions &
Aggregations
Interoperability
Array objects in Flag4j are very flexible and support a wide range of overloaded operations and conversions. For instance, a real dense vector may be converted to/from a complex dense vector or a real sparse COO vector. Most binary operations also support passing other vector types such as complex dense vectors, real sparse vectors, and complex sparse vectors.
Conversions
Vectors can be converted to sparse COO vectors if desired. This should be done with some caution as sparse vectors are only more efficient if the vector is very sparse.
Vectors may also be converted to matrices or tensors with optionally specified shapes. If a shape is specified, then the total number of entries specified by the shape (i.e., the product of each dimension) must exactly equal the number of elements in the vector.
Overloaded Operations
Most binary operations support passing other vector types as arguments. For instance, the Vector class has several overloaded methods for vector addition supporting complex dense vectors, real sparse vectors, and complex sparse vectors. Most other basic binary operations also implement similar overloaded methods. An exception is element-wise division which does not support passing a sparse vector as the denominator since it would almost certainly result in division by zero.
The code snippet below demonstrates some of these overloaded methods as well as their return type.
For a full list of overloaded methods see the API reference.