C++ Improvements - API enhancement and increase testing

[stephen29xie]

Changes Made

C++

• Add overloaded Index::addItems and Index::query methods that accept 2D vector of floats (std::vector<std::vector<float>>) instead of an NDArray.
  • When the Java and Python bindings add items or query, they convert the Python and Java objects to a 2-D NDArray. The NDArray is abstracted. We should have an option to abstract that in the C++ interface too to maintain ease-of-use and intuitiveness, especially If Voyager is used as a standalone C++ library (cpp wrappers are using default namespace #52).
  • This is used in the unit test when we add items or query the index
• Add C++ tests
  • A C++ test framework was added recently in C++ improvements #63 but there is only some basic Index property checking
  • These additional tests generate random vectors and add them to an index. Each of these vectors is then used as a target vector in a query. We expect to see that the ANN distance is ~0 (allowing for some precision error based on storage type), and that the ANN is itself.
  • We technically still one have only one test. We don't have support for test parameterization yet. As a workaround we use nested loops to enumerate and test different combinations of parameters.
  • By nature of HNSW, the test is nondeterministic. Even with considerations for lower precision data storage types, it is possible that a test run will fail because we are testing that the true NN is equal to the ANN.

Testing

Added C++ tests

Related Issues

In these tests, we query with k = 1 (single nearest neighbour). If you change it or add an additional test with k = num_vectors_in_index, you can sporadically reproduce this issue: #38

Checklist

• My code follows the code style of this project.
• I have added and/or updated appropriate documentation (if applicable).
• All new and existing tests pass locally with these changes.
• I have run static code analysis (if available) and resolved any issues.
• I have considered backward compatibility (if applicable).
• I have confirmed that this PR does not introduce any security vulnerabilities.

Additional Comments

[stephen29xie]

-g flag builds executable with debugging symbols to use with a debugger

[stephen29xie]

Is there a more memory-efficient way of doing this?

[psobot]

Not memory-efficient, but time-efficient, yes: we should pre-allocate the space in flatArray by calculating numVectors * dimensions, then doing std::memcpy into that buffer for each vector.

What we have here will resize (and potentially reallocate) the vector on each .insert, which makes this O(n²) as .insert is O(n) rather than O(1).

[stephen29xie]

From meeting:

add conditional statement
if storageType = float32, then randomVectors
if storageType = float8 or e4m3, then randomQuantizedVectors

[markkohdev]

Looking good! Left some comments but nice work on this so far :)

[markkohdev]

Let's add an explicit unit test for this

[markkohdev]

I think we can remove these functions and instead just use the randomQuantizedVectors and randomVectors methods

[markkohdev]

Rather than iterating over the outer and inner vectors, we should try to utilize the underlying data access that std::vector provides. Be careful with this though as there may be caveats around vector memory allocation boundaries and actual vector item counts

[stephen29xie]

I am still iterating over each vector because I added a check to validate that each vector size is identical. But now I am preallocating the space I need in the flattened array to avoid resizing, and using std::memcpy to do the copying

[markkohdev]

👍 Thanks for fixing this up! Looks good to me
🤠 🐴 🏇