Make: Separate StringCuZilla

Separate directory for parallel algorithms

Author: ashvardanian

include/stringzilla/features.h include/stringcuzilla/features.hppinclude/stringzilla/features.h renamed to include/stringcuzilla/features.hpp

@@ -355,7 +355,7 @@ status_t levenshtein_distances(
     cudaError_t error = cudaStreamSynchronize(stream);
     if (error != cudaSuccess) {
         if (error == cudaErrorMemoryAllocation) { return status_t::bad_alloc_k; }
-        else { return status_t::unknown_error_k; }
+        else { return status_t::unknown_k; }
     }
     return status_t::success_k;
 }
@@ -415,7 +415,7 @@ status_t needleman_wunsch_scores(
     cudaError_t error = cudaStreamSynchronize(stream);
     if (error != cudaSuccess) {
         if (error == cudaErrorMemoryAllocation) { return status_t::bad_alloc_k; }
-        else { return status_t::unknown_error_k; }
+        else { return status_t::unknown_k; }
     }
     return status_t::success_k;
 }

include/stringzilla/similarities.cuh include/stringcuzilla/similarities.cuhinclude/stringzilla/similarities.cuh renamed to include/stringcuzilla/similarities.cuh

@@ -319,7 +319,7 @@ SZ_INTERNAL sz_status_t _sz_levenshtein_distance_skewed_diagonals_serial( //
     previous_distances[0] = 0;
     current_distances[0] = current_distances[1] = 1;
 
-    // Progress through the upper triangle of the Levenshtein matrix.
+    // Progress through the upper-left triangle of the Levenshtein matrix.
     sz_size_t next_diagonal_index = 2;
     for (; next_diagonal_index != n; ++next_diagonal_index) {
         sz_size_t const next_diagonal_length = next_diagonal_index + 1;
@@ -338,7 +338,7 @@ SZ_INTERNAL sz_status_t _sz_levenshtein_distance_skewed_diagonals_serial( //
         next_distances = temporary;
     }
 
-    // By now we've scanned through the upper triangle of the matrix, where each subsequent iteration results in a
+    // By now we've scanned through the upper-left triangle of the matrix, where each subsequent iteration results in a
     // larger diagonal. From now onwards, we will be shrinking. Instead of adding value equal to the skewed diagonal
     // index on either side, we will be cropping those values out.
     sz_size_t diagonals_count = n + n - 1;
@@ -836,7 +836,7 @@ SZ_INTERNAL sz_size_t _sz_levenshtein_distance_skewed_diagonals_upto63_ice( //
     sz_size_t next_diagonal_index = 2;
     __mmask64 next_diagonal_mask = 0;
 
-    // Progress through the upper triangle of the Levenshtein matrix.
+    // Progress through the upper-left triangle of the Levenshtein matrix.
     for (; next_diagonal_index != shorter_dim; ++next_diagonal_index) {
         // After this iteration, the values at offset `0` and `next_diagonal_index` in the `next_vec`
         // should be set to `next_diagonal_index`, but it's easier to broadcast the value to the whole vector,
@@ -869,7 +869,7 @@ SZ_INTERNAL sz_size_t _sz_levenshtein_distance_skewed_diagonals_upto63_ice( //
         if (_ktestz_mask64_u8(within_bound_mask, next_diagonal_mask) == 1) return bound;
     }
 
-    // Now let's handle the anti-diagonal band of the matrix, between the top and bottom triangles.
+    // Now let's handle the anti-diagonal band of the matrix, between the top and bottom-right triangles.
     for (; next_diagonal_index != longer_dim; ++next_diagonal_index) {
         // After this iteration, the value `shorted_dim - 1` in the `next_vec`
         // should be set to `next_diagonal_index`, but it's easier to broadcast the value to the whole vector,
@@ -1072,7 +1072,7 @@ SZ_INTERNAL sz_status_t _sz_levenshtein_distance_skewed_diagonals_upto65k_ice( /
     // - 3 diagonals of decreasing length, at positions: 6, 7, 8.
     sz_size_t const diagonals_count = shorter_dim + longer_dim - 1;
 
-    // Progress through the upper triangle of the Levenshtein matrix.
+    // Progress through the upper-left triangle of the Levenshtein matrix.
     sz_size_t next_diagonal_index = 2;
     for (; next_diagonal_index != shorter_dim; ++next_diagonal_index) {
         sz_size_t const next_diagonal_length = next_diagonal_index + 1;
@@ -1118,7 +1118,7 @@ SZ_INTERNAL sz_status_t _sz_levenshtein_distance_skewed_diagonals_upto65k_ice( /
         next_distances = temporary;
     }
 
-    // By now we've scanned through the upper triangle of the matrix, where each subsequent iteration results in a
+    // By now we've scanned through the upper-left triangle of the matrix, where each subsequent iteration results in a
     // larger diagonal. From now onwards, we will be shrinking. Instead of adding value equal to the skewed diagonal
     // index on either side, we will be cropping those values out.
     for (; next_diagonal_index != diagonals_count; ++next_diagonal_index) {
@@ -1216,7 +1216,9 @@ SZ_PUBLIC sz_status_t sz_levenshtein_distance_ice( //
 }
 
 /**
- *  Computes the Needleman Wunsch alignment score between two strings.
+ *  @brief  Computes the Needleman-Wunsch alignment score between two strings. Uses the Wagner-Fischer algorithm
+ *          with the AVX-512VBMI extensions, vectorizing the substitution costs in each row.
+ *
  *  The method uses 32-bit integers to accumulate the running score for every cell in the matrix.
  *  Assuming the costs of substitutions can be arbitrary signed 8-bit integers, the method is expected to be used
  *  on strings not exceeding 2^24 length or 16.7 million characters.

include/stringzilla/similarities.hpp include/stringcuzilla/similarities.hppinclude/stringzilla/similarities.hpp renamed to include/stringcuzilla/similarities.hpp

@@ -0,0 +1,37 @@
+/**
+ *  @brief  StringZilla is a collection of advanced string algorithms, designed to be used in Big Data applications.
+ *          It is generally faster than LibC, and has a broader & cleaner interface for safer @b length-bounded strings.
+ *          On modern CPUs it uses AVX2, AVX-512, NEON, SVE, & SVE2 @b SIMD instructions & provides SWAR for older CPUs.
+ *          On @b CUDA-capable GPUs it also provides C++ kernels for bulk processing.
+ *
+ *  @file   stringzilla.cuh
+ *  @author Ash Vardanian
+ */
+#ifndef STRINGZILLA_CUH_
+#define STRINGZILLA_CUH_
+
+#include "stringzilla.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+SZ_DYNAMIC sz_status_t sz_levenshtein_distances_u32tape( //
+    sz_cptr_t a_data, sz_u32_t const *a_lengths,         //
+    sz_cptr_t b_data, sz_u32_t const *b_lengths,         //
+    sz_size_t count,                                     //
+    sz_size_t bound,                                     //
+    sz_memory_allocator_t *alloc, sz_size_t *results);
+
+SZ_DYNAMIC sz_status_t sz_needleman_wunsch_scores_u32tape( //
+    sz_cptr_t a_data, sz_u32_t const *a_lengths,           //
+    sz_cptr_t b_data, sz_u32_t const *b_lengths,           //
+    sz_size_t count,                                       //
+    sz_error_cost_t const *subs, sz_error_cost_t gap,      //
+    sz_memory_allocator_t *alloc, sz_ssize_t *results);
+
+#ifdef __cplusplus
+}
+#endif // __cplusplus
+
+#endif // STRINGZILLA_CUH_

include/stringzilla/similarity.h include/stringcuzilla/similarity.hinclude/stringzilla/similarity.h renamed to include/stringcuzilla/similarity.h

@@ -13,13 +13,13 @@
  *  Why the hell do we need a yet another hashing library?!
  *  Turns out, most existing libraries have noticeable constraints. Try finding a library that:
  *
- *  - Outputs 64-bit or 128-bit hashes and passes the SMHasher test suite.
- *  - Is fast for both short and long strings.
+ *  - Outputs 64-bit or 128-bit hashes and passes the @b SMHasher `--extra` tests.
+ *  - Is fast for both short @b (velocity) and long strings @b (throughput).
  *  - Supports incremental @b (streaming) hashing, when the data arrives in chunks.
- *  - Supports custom seeds hashes and secret strings for security.
- *  - Provides dynamic dispatch for different architectures to simplify deployment.
- *  - Uses modern SIMD, including not just AVX2 and NEON, but also AVX-512 and SVE2.
- *  - Documents its logic and guarantees the same output across different platforms.
+ *  - Supports custom @b seeds for hashes and have it affecting every bit of the output.
+ *  - Provides @b dynamic-dispatch for different architectures to simplify deployment.
+ *  - Uses @b SIMD, including not just AVX2 & NEON, but also masking AVX-512 & predicated SVE2.
+ *  - Documents its logic and @b guarantees the same output across different platforms.
  *
  *  This includes projects like "MurmurHash", "CityHash", "SpookyHash", "FarmHash", "MetroHash", "HighwayHash", etc.
  *  There are 2 libraries that are close to meeting these requirements: "xxHash" in C++ and "aHash" in Rust:

include/stringcuzilla/stringcuzilla.h

@@ -12,6 +12,24 @@
  *
  *  @section    Introduction
  *
+ *  StringZilla is multi-language project designed for high-throughput string processing, differentiating
+ *  the low-level "embeddable" mostly-C core implementation, containing:
+ *
+ *  - `compare.h` - byte-level comparison functions.
+ *  - `memory.h` - copying, moving, and filling raw memory.
+ *  - `hash.h` - hash functions and checksum algorithms.
+ *  - `find.h` - searching for substrings and byte sets.
+ *  - `sort.h` - single-threaded sorting algorithms.
+ *  - `intersect.h` - intersections of unordered string sets.
+ *  - `small_string.h` - "Small String Optimization" in C 99.
+ *  - `stringzilla.h` - umbrella header for the core C API.
+ *  - `stringzilla.hpp` - umbrella header for the core C++ API.
+ *
+ *  It also provides many higher-level algorithms, mostly implemented in C++ with OpenMP and CUDA,
+ *  also exposed via the stable C 99 ABI, but requiring C++17 and CUDA 17 compilers to build the shared libraries:
+ *
+ *  - `similarity.hpp` - similarity measures, like Levenshtein distance, Needleman-Wunsch, & Smith-Waterman alignment.
+ *  - `features.hpp` - feature extraction for TF-IDF and other Machine Learning algorithms.
  *
  *  @section    Compilation Settings
  *
@@ -36,6 +54,8 @@
  *  - `SZ_USE_NEON=?` - whether to use NEON instructions on ARM.
  *  - `SZ_USE_SVE=?` - whether to use SVE instructions on ARM.
  *  - `SZ_USE_SVE2=?` - whether to use SVE2 instructions on ARM.
+ *  - `SZ_USE_CUDA=?` -
+ *  - `SZ_USE_OPENMP=?` -
  */
 #ifndef STRINGZILLA_H_
 #define STRINGZILLA_H_

include/stringzilla/types.cuh include/stringcuzilla/types.cuhinclude/stringzilla/types.cuh renamed to include/stringcuzilla/types.cuh

@@ -411,6 +411,12 @@ typedef enum { sz_false_k = 0, sz_true_k = 1 } sz_bool_t;
  */
 typedef enum { sz_less_k = -1, sz_equal_k = 0, sz_greater_k = 1 } sz_ordering_t;
 
+/**
+ *  @brief Describes the alignment goal for string similarity algorithms.
+ *  @sa sz_align_global_k, sz_align_local_k
+ */
+typedef enum { sz_align_global_k = 0, sz_align_local_k = 1 } sz_alignment_locality_t;
+
 /**
  *  @brief A simple signed integer type describing the status of a faulty operation.
  *  @sa sz_success_k, sz_bad_alloc_k, sz_invalid_utf8_k, sz_contains_duplicates_k
@@ -424,6 +430,8 @@ typedef enum {
     sz_invalid_utf8_k = -2,
     /** For algorithms that take collections of unique elements, this status indicates presence of duplicates. */
     sz_contains_duplicates_k = -3,
+    /** A sink-hole status for unknown errors. */
+    sz_status_unknown_k = -4,
 } sz_status_t;
 
 /**

include/stringzilla/hash.h

@@ -115,7 +115,7 @@ enum class status_t {
     bad_alloc_k = sz_bad_alloc_k,
     invalid_utf8_k = sz_invalid_utf8_k,
     contains_duplicates_k = sz_contains_duplicates_k,
-    unknown_error_k = sz_unknown_error_k,
+    unknown_k = sz_status_unknown_k,
 };
 
 struct uniform_substitution_cost_t {