[Vector API] Why to talk about lanes, shapes and species in the API doc?

[Paul Sandoz]

Hi Dietmar,

I think you have misunderstood the intent of the Vector API. 

The Vector API uses the term vector as in vector hardware register, whose size is a fixed number of bits (shape), and can be viewed as a fixed-sized array of primitive values (species). The API is specifically designed such that an instance of Vector compiles down to a value in a vector register, and operations compile down to one or a few vector hardware instructions. I sometimes refer to this API as a What You See Is What You Get (WYSIWYG) API.

What you desire, quite reasonably, is a higher level abstraction to operate over variable length arrays. The chosen parallel mechanism would be an implementation detail of such an abstraction. This kind of abstraction also makes sense for matrices or tensors. We do want to explore such APIs in the platform, but IMO we would first need to identify/propose enhancements to language so we can design the array-like API that we would be comfortable proposing and supporting. (Note some enhancements make come with Project Valhalla we likely require more.)

—

Providing a link to the relevant area of the release JavaDoc (once available) seems reasonable. It’s not something we have generally done with appropriate JEPs, but I think it’s useful. 

Paul.

> On Mar 29, 2022, at 11:41 AM, Dietmar Lippold <dietmar.lippold at mailbox.org> wrote:
> 
> Hi,
> 
> why is it necessary to talk about "lanes", "shapes" and "species" in the API doc?  From my point of view a Vector should be similar to an array, in particular it could have an arbitrary number of _elements_ (up to Integer.MAX_VALUE) and it should not be necessary to know something about the hardware (CPU or GPU).
> 
> On the page of JEP 417 (https://openjdk.java.net/jeps/417) there is the code:
> 
>  static final VectorSpecies<Float> SPECIES = FloatVector.SPECIES_PREFERRED;
> 
>  void vectorComputation(float[] a, float[] b, float[] c) {
>      int i = 0;
>      int upperBound = SPECIES.loopBound(a.length);
>      for (; i < upperBound; i += SPECIES.length()) {
>          // FloatVector va, vb, vc;
>          var va = FloatVector.fromArray(SPECIES, a, i);
>          var vb = FloatVector.fromArray(SPECIES, b, i);
>          var vc = va.mul(va)
>                     .add(vb.mul(vb))
>                     .neg();
>          vc.intoArray(c, i);
>      }
>      for (; i < a.length; i++) {
>          c[i] = (a[i] * a[i] + b[i] * b[i]) * -1.0f;
>      }
>  }
> 
> It should be possible to write instead:
> 
>  void vectorComputation(float[] a, float[] b, float[] c) {
>      // FloatVector va, vb, vc;
>      var va = FloatVector.fromArray(a);
>      var vb = FloatVector.fromArray(b);
>      var vc = va.mul(va)
>                 .add(vb.mul(vb))
>                 .neg();
>      vc.intoArray(c);
>  }
> 
> To make that possible the current class Vector (as well as its subclasses) could be converted into an inner class VectorHelp (or named similar) and that could handle all things of lanes, shapes and species.
> 
> Btw: Please add a link to the API doc of the Vector package (https://docs.oracle.com/en/java/javase/18/docs/api/jdk.incubator.vector/jdk/incubator/vector/package-summary.html) to the page of the JEP 417 (https://openjdk.java.net/jeps/417).
> 
> Dietmar