[WIP] Fast isValidCell

CMakeLists.txt

@@ -225,6 +225,7 @@ set(OTHER_SOURCE_FILES
     src/apps/benchmarks/benchmarkGridPathCells.c
     src/apps/benchmarks/benchmarkDirectedEdge.c
     src/apps/benchmarks/benchmarkVertex.c
+    src/apps/benchmarks/benchmarkIsValidCell.c
     src/apps/benchmarks/benchmarkH3Api.c)
 
 set(ALL_SOURCE_FILES
@@ -654,6 +655,7 @@ if(BUILD_BENCHMARKS)
     add_h3_benchmark(benchmarkGridPathCells src/apps/benchmarks/benchmarkGridPathCells.c)
     add_h3_benchmark(benchmarkDirectedEdge src/apps/benchmarks/benchmarkDirectedEdge.c)
     add_h3_benchmark(benchmarkVertex src/apps/benchmarks/benchmarkVertex.c)
+    add_h3_benchmark(benchmarkIsValidCell src/apps/benchmarks/benchmarkIsValidCell.c)
     add_h3_benchmark(benchmarkH3SetToLinkedGeo src/apps/benchmarks/benchmarkH3SetToLinkedGeo.c)
     add_h3_benchmark(benchmarkPolygonToCells src/apps/benchmarks/benchmarkPolygonToCells.c)
     if(ENABLE_REQUIRES_ALL_SYMBOLS)

src/apps/benchmarks/benchmarkIsValidCell.c

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2021 Uber Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+#include "benchmark.h"
+#include "h3api.h"
+
+H3Index p = 0x80c3fffffffffff;  // res 0 pentagon
+
+int parentRes;
+int childRes;
+
+int64_t N;
+H3Index *cells;
+
+BEGIN_BENCHMARKS();
+
+// pentagon 8->14
+parentRes = 8;
+childRes = 14;
+p = H3_EXPORT(cellToCenterChild)(p, parentRes);
+N = H3_EXPORT(cellToChildrenSize)(p, childRes);
+
+cells = calloc(N, sizeof(H3Index));
+H3_EXPORT(cellToChildren)(p, childRes, cells);
+
+BENCHMARK(pentagonChildren_8_14, 1000, {
+    for (int64_t i = 0; i < N; i++) {
+        H3_EXPORT(isValidCell)(cells[i]);
+    }
+});
+free(cells);
+
+// pentagon 2->8
+parentRes = 2;
+childRes = 8;
+p = H3_EXPORT(cellToCenterChild)(p, parentRes);
+N = H3_EXPORT(cellToChildrenSize)(p, childRes);
+
+cells = calloc(N, sizeof(H3Index));
+H3_EXPORT(cellToChildren)(p, childRes, cells);
+
+BENCHMARK(pentagonChildren_2_8, 1000, {
+    for (int64_t i = 0; i < N; i++) {
+        H3_EXPORT(isValidCell)(cells[i]);
+    }
+});
+free(cells);
+
+END_BENCHMARKS();

src/h3lib/lib/h3Index.c

@@ -78,49 +78,108 @@ void H3_EXPORT(h3ToString)(H3Index h, char *str, size_t sz) {
     sprintf(str, "%" PRIx64, h);
 }
 
+// Get Top t bits from h
+#define GT(h, t) ((h) >> (64 - (t)))
+
+static const bool isBaseCellPentagonArr[128] = {
+    [4] = 1,  [14] = 1, [24] = 1, [38] = 1, [49] = 1,  [58] = 1,
+    [63] = 1, [72] = 1, [83] = 1, [97] = 1, [107] = 1, [117] = 1};
+
 /**
- * Returns whether or not an H3 index is a valid cell (hexagon or pentagon).
- * @param h The H3 index to validate.
- * @return 1 if the H3 index if valid, and 0 if it is not.
+ * Determines whether an H3 index is a valid cell (hexagon or pentagon).
+ *
+ * @param   h  H3 index to test.
+ *
+ * @return     1 if the H3 index if valid, and 0 if it is not.
  */
 int H3_EXPORT(isValidCell)(H3Index h) {
-    if (H3_GET_HIGH_BIT(h) != 0) return 0;
-
-    if (H3_GET_MODE(h) != H3_HEXAGON_MODE) return 0;
-
-    if (H3_GET_RESERVED_BITS(h) != 0) return 0;
-
-    int baseCell = H3_GET_BASE_CELL(h);
-    if (baseCell < 0 || baseCell >= NUM_BASE_CELLS) {  // LCOV_EXCL_BR_LINE
-        // Base cells less than zero can not be represented in an index
-        return 0;
-    }
-
-    int res = H3_GET_RESOLUTION(h);
-    if (res < 0 || res > MAX_H3_RES) {  // LCOV_EXCL_BR_LINE
-        // Resolutions less than zero can not be represented in an index
-        return 0;
-    }
-
-    bool foundFirstNonZeroDigit = false;
-    for (int r = 1; r <= res; r++) {
-        Direction digit = H3_GET_INDEX_DIGIT(h, r);
-
-        if (!foundFirstNonZeroDigit && digit != CENTER_DIGIT) {
-            foundFirstNonZeroDigit = true;
-            if (_isBaseCellPentagon(baseCell) && digit == K_AXES_DIGIT) {
+    // Implementation strategy:
+    //
+    // Walk from high to low bits, checking validity of
+    // groups of bits as we go. After each check, shift bits off
+    // to the left, so that the next relevant group is at the
+    // highest bit location in the H3 Index, which we can
+    // easily read off with the `GT` macro. This strategy helps
+    // us avoid re-computing shifts and masks for each group.
+    //
+    // |   Region   | # bits |
+    // |------------|--------|
+    // | High       |      1 |
+    // | Mode       |      4 |
+    // | Reserved   |      3 |
+    // | Resolution |      4 |
+    // | Base Cell  |      7 |
+    // | Digit 1    |      3 |
+    // | Digit 2    |      3 |
+    // | ...        |    ... |
+    // | Digit 15   |      3 |
+    //
+    // Additionally, we try to group operations and void loops when possible.
+
+    // The 1 high bit should be 0b0
+    // The 4 mode bits should be 0b0001 (H3_CELL_MODE)
+    // The 3 reserved bits should be 0b000
+    // In total, the top 8 bits should be 0b00001000
+    if (GT(h, 8) != 0b00001000) return 0;
+    h <<= 8;
+
+    // Number of bits in each of the resolution, base cell, and digit regions.
+    const int nBitsRes = 4;
+    const int nBitsBaseCell = 7;
+    const int nBitsDigit = H3_PER_DIGIT_OFFSET;
+
+    // No need to check resolution; any 4-bit number is a valid resolution.
+    const int res = GT(h, nBitsRes);
+    h <<= nBitsRes;
+
+    // Check that base cell number is valid.
+    const int bc = GT(h, nBitsBaseCell);
+    if (bc >= NUM_BASE_CELLS) return 0;
+    h <<= nBitsBaseCell;
+
+    // Now check that each resolution digit is valid.
+    // Let `r` denote the resolution we're currently checking.
+    int r = 1;
+
+    // Pentagon cells start with a sequence of 0's (CENTER_DIGIT's).
+    // The first nonzero digit can't be a 1 (i.e., "deleted subsequence",
+    // PENTAGON_SKIPPED_DIGIT, or K_AXES_DIGIT).
+    // Test for pentagon base cell first to avoid this loop if possible.
+    if (isBaseCellPentagonArr[bc]) {
+        for (; r <= res; r++) {
+            int d = GT(h, nBitsDigit);
+            if (d == 0) {
+                h <<= nBitsDigit;
+            } else if (d == 1) {
                 return 0;
+            } else {
+                break;
+                // But don't increment `r`, since we still need to
+                // check that it isn't a 7.
             }
         }
-
-        if (digit < CENTER_DIGIT || digit >= NUM_DIGITS) return 0;
     }
 
-    for (int r = res + 1; r <= MAX_H3_RES; r++) {
-        Direction digit = H3_GET_INDEX_DIGIT(h, r);
-        if (digit != INVALID_DIGIT) return 0;
+    // After (possibly) taking care of pentagon logic, check that
+    // the remaining digits up to `res` are not 7 (INVALID_DIGIT).
+    // Don't see a way to avoid this loop :(
+    for (; r <= res; r++) {
+        if (GT(h, nBitsDigit) == 7) return 0;
+        h <<= nBitsDigit;
     }
 
+    // Now check that all the unused digits after `res` are
+    // set to 7 (INVALID_DIGIT).
+    // Bit shift operations allow us to avoid looping through digits;
+    // this saves time in benchmarks.
+    int shift = (15 - res) * 3;
+    uint64_t m = 0;
+    m = ~m;
+    m >>= shift;
+    m = ~m;
+    if (h != m) return 0;
+
+    // If no flaws were identified above, then the index is a valid H3 cell.
     return 1;
 }