carray 3.0.1 → 3.0.3

data/ext/ca_rng_normal.h

@@ -0,0 +1,42 @@
+/* ---------------------------------------------------------------------------
+
+   ca_rng_normal.h -- uniform to standard normal, as text
+
+   Read the two ways ca_rng_xoshiro256pp.h is read: compiled into this
+   extension, and handed out through CArray::Rng::COMMON_SOURCE for
+   another gem to paste.  The same rules apply -- no include guard,
+   nothing beyond <math.h>, `static inline` only.
+
+   Separate from any generator's file because it belongs to none of
+   them: it takes two uniforms and gives a normal, whichever generator
+   the uniforms came from.  Whoever pastes it pastes it once however
+   many generators are drawing, which is why it is not simply repeated
+   inside each generator's text.
+
+   --------------------------------------------------------------------------- */
+
+/* One standard normal from two uniforms in [0.0, 1.0), by Box-Muller.
+ *
+ * Exactly two, always.  The classical form takes two uniforms and gives
+ * two normals, and keeping the second would make the cost one uniform
+ * apiece -- but the spare has to live somewhere between calls, and the
+ * place it would live is the generator's state.  A kernel draws one
+ * number per cell and `CArray#random!` fills whole arrays, so a spare
+ * held across that boundary is a second kind of state to keep in step,
+ * on top of the one this design exists to keep in step.  Two uniforms
+ * and no spare costs an extra draw, at about a nanosecond, and buys a
+ * rule with nothing behind it: one normal is two draws, wherever it is
+ * taken.
+ *
+ * `1.0 - u1` rather than `u1`, so the argument to log is in (0.0, 1.0]
+ * and never zero.  Redrawing on a zero -- which is what the paired form
+ * does -- would make the number of uniforms per normal depend on the
+ * draw, and then "where is this generator" has no answer that can be
+ * worked out rather than run. */
+static inline double
+ca_rng_normal (double u1, double u2)
+{
+  const double radius = sqrt(-2.0 * log(1.0 - u1));
+  const double theta = 2.0 * M_PI * u2;
+  return radius * cos(theta);
+}

data/ext/ca_rng_xoshiro256pp.h

@@ -0,0 +1,105 @@
+/* ---------------------------------------------------------------------------
+
+   ca_rng_xoshiro256pp.h -- the xoshiro256++ generator, as text
+
+   This file is not a header in the usual sense.  It carries no include
+   guard and includes nothing, because it is read two ways:
+
+     - ext/carray_random.c #includes it, and the extension compiles it.
+       That is what `CArray#random!(rng: r)` runs.
+
+     - CArray::Rng::SOURCE[:xoshiro256pp] is this file's text, read at
+       runtime.  carray-jit pastes it into the translation unit it
+       generates for a kernel, beside its own `static inline` helpers.
+       That is what a kernel's `random(rng:)` runs.
+
+   One text, so the two cannot drift: a kernel that draws after
+   `random!` continues the same sequence because it is running the same
+   code, not because two implementations were checked against each
+   other.  Anything added here has to stay pasteable -- `static inline`,
+   no directives, and nothing beyond <stdint.h>, which both sides have.
+
+   xoshiro256++ 1.0 by David Blackman and Sebastiano Vigna, released to
+   the public domain (https://prng.di.unimi.it/xoshiro256plusplus.c).
+   The state is seeded through splitmix64, as its authors prescribe.
+
+   The state is held as int64_t[4] rather than uint64_t[4] so that it is
+   a plain CA_INT64 array a caller can look at.  C says an object may be
+   read through the corresponding signed or unsigned type, so the cast
+   below is the language's own allowance and not a reinterpretation.
+
+   --------------------------------------------------------------------------- */
+
+/* splitmix64: the state seeder.  A single 64-bit seed is a poor state
+   for xoshiro on its own -- an all-but-zero state takes many draws to
+   escape -- so the seed is stretched through a generator whose output
+   is well mixed from the first call. */
+static inline uint64_t
+ca_splitmix64_next (uint64_t *x)
+{
+  uint64_t z = (*x += 0x9E3779B97F4A7C15ULL);
+  z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9ULL;
+  z = (z ^ (z >> 27)) * 0x94D049BB133111EBULL;
+  return z ^ (z >> 31);
+}
+
+/* Fill a state from one seed. */
+static inline void
+ca_xoshiro256pp_seed (int64_t *s, uint64_t seed)
+{
+  uint64_t *u = (uint64_t *) s;
+  uint64_t x = seed;
+  u[0] = ca_splitmix64_next(&x);
+  u[1] = ca_splitmix64_next(&x);
+  u[2] = ca_splitmix64_next(&x);
+  u[3] = ca_splitmix64_next(&x);
+}
+
+static inline uint64_t
+ca_xoshiro256pp_rotl (uint64_t x, int k)
+{
+  return (x << k) | (x >> (64 - k));
+}
+
+/* One draw: 64 random bits, the state advanced. */
+static inline uint64_t
+ca_xoshiro256pp_next (int64_t *s)
+{
+  uint64_t *u = (uint64_t *) s;
+  const uint64_t result = ca_xoshiro256pp_rotl(u[0] + u[3], 23) + u[0];
+  const uint64_t t = u[1] << 17;
+
+  u[2] ^= u[0];
+  u[3] ^= u[1];
+  u[1] ^= u[2];
+  u[0] ^= u[3];
+  u[2] ^= t;
+  u[3] = ca_xoshiro256pp_rotl(u[3], 45);
+
+  return result;
+}
+
+/* A double in [0, 1).  The top 53 bits are the ones taken: that is the
+   whole mantissa, so no two draws collide merely because the generator
+   handed back fewer bits than a double can hold. */
+static inline double
+ca_xoshiro256pp_next_real (int64_t *s)
+{
+  return (double) (ca_xoshiro256pp_next(s) >> 11) * 0x1.0p-53;
+}
+
+/* One standard normal, which is two draws.  ca_rng_normal is what turns
+   them into one, and it is in a file of its own because it belongs to no
+   generator.
+
+   The two draws are taken into locals rather than written as two
+   arguments: C does not say which order a call's arguments are
+   evaluated in, and these two are not interchangeable -- they advance a
+   state. */
+static inline double
+ca_xoshiro256pp_next_normal (int64_t *s)
+{
+  const double u1 = ca_xoshiro256pp_next_real(s);
+  const double u2 = ca_xoshiro256pp_next_real(s);
+  return ca_rng_normal(u1, u2);
+}

data/ext/ca_sort_kernels.h

@@ -129,4 +129,74 @@ void ca_sort_merge_pair_u64 (ca_pair_u64 *a, ca_pair_u64 *aux, ca_size_t n);
 void ca_sort_merge_pair_f32 (ca_pair_f32 *a, ca_pair_f32 *aux, ca_size_t n);
 void ca_sort_merge_pair_f64 (ca_pair_f64 *a, ca_pair_f64 *aux, ca_size_t n);
 
+/* Runs of this many elements are insertion-sorted before the merge passes. */
+#define CA_SORT_INSERTION_THRESHOLD 16
+
+/* The body of a stable bottom-up mergesort over TYPE, ordered by cmp alone
+   (the element type has no `<`), for a function taking
+     (TYPE *a, TYPE *aux, ca_size_t n, int (*cmp)(const void *, const void *))
+   aux holds n elements.  cmp may raise -- an object comparator calls <=> --
+   and the raise unwinds through this code's frames, which hold nothing;
+   libc's qsort / mergesort would have to be unwound instead.
+
+   A comparison is costly here (a call into Ruby) and a move is cheap, so
+   the runs are insertion-sorted with each insertion point found by binary
+   search: log2(k) comparisons where a linear walk takes k/2.  Merge passes
+   ping-pong between a and aux and skip a pair of runs already in order.
+   Stable: an element lands after every one that does not compare greater,
+   and a merge takes from the right run only on a strictly smaller one. */
+#define CA_SORT_MERGE_BY_CMP(TYPE)                                            \
+{                                                                             \
+  if ( n <= 1 ) return;                                                       \
+  for ( ca_size_t lo = 0; lo < n; lo += CA_SORT_INSERTION_THRESHOLD ) {       \
+    ca_size_t hi = lo + CA_SORT_INSERTION_THRESHOLD;                          \
+    if ( hi > n ) hi = n;                                                     \
+    for ( ca_size_t k = lo + 1; k < hi; k++ ) {                               \
+      TYPE v = a[k];                                                          \
+      ca_size_t l = lo, r = k;                                                \
+      while ( l < r ) {                                                       \
+        ca_size_t mid = l + (r - l) / 2;                                      \
+        if ( cmp(&a[mid], &v) > 0 ) r = mid;                                  \
+        else                        l = mid + 1;                              \
+      }                                                                       \
+      if ( l < k ) {                                                          \
+        memmove(a + l + 1, a + l, (size_t)(k - l) * sizeof(TYPE));            \
+        a[l] = v;                                                             \
+      }                                                                       \
+    }                                                                         \
+  }                                                                           \
+  TYPE *cur  = a;                                                             \
+  TYPE *next = aux;                                                           \
+  for ( ca_size_t width = CA_SORT_INSERTION_THRESHOLD; width < n;             \
+        width <<= 1 ) {                                                       \
+    for ( ca_size_t lo = 0; lo < n; lo += (width << 1) ) {                    \
+      ca_size_t mid = lo + width;                                             \
+      ca_size_t hi  = lo + (width << 1);                                      \
+      if ( mid > n ) mid = n;                                                 \
+      if ( hi  > n ) hi  = n;                                                 \
+      if ( mid >= hi || cmp(&cur[mid - 1], &cur[mid]) <= 0 ) {               \
+        memcpy(next + lo, cur + lo, (size_t)(hi - lo) * sizeof(TYPE));        \
+        continue;                                                             \
+      }                                                                       \
+      ca_size_t i = lo, j = mid, k = lo;                                      \
+      while ( i < mid && j < hi ) {                                           \
+        if ( cmp(&cur[j], &cur[i]) < 0 ) next[k++] = cur[j++];                \
+        else                             next[k++] = cur[i++];                \
+      }                                                                       \
+      while ( i < mid ) next[k++] = cur[i++];                                 \
+      while ( j < hi  ) next[k++] = cur[j++];                                 \
+    }                                                                         \
+    { TYPE *t = cur; cur = next; next = t; }                                  \
+  }                                                                           \
+  if ( cur != a ) {                                                           \
+    memcpy(a, cur, (size_t) n * sizeof(TYPE));                                \
+  }                                                                           \
+}
+
+/* (VALUE, index) pairs, as the object lane of the sort kernels holds them. */
+typedef struct ca_pair_object { VALUE v; ca_size_t i; } ca_pair_object;
+void ca_sort_merge_pair_object (ca_pair_object *a, ca_pair_object *aux,
+                                ca_size_t n,
+                                int (*cmp)(const void *, const void *));
+
 #endif /* CA_SORT_KERNELS_H */