Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -296,6 +296,8 @@ set(OTHER_SOURCE_FILES
src/apps/testapps/testConformanceTraversal.c
src/apps/testapps/testConformanceUnsafe.c
src/apps/testapps/testConformanceLocalIj.c
src/apps/testapps/testConformanceHierarchy.c
src/apps/testapps/testConformanceSets.c
src/apps/testapps/testConformanceManifest.c
src/apps/testapps/mkConformance.c
src/apps/miscapps/cellToBoundaryHier.c
Expand Down
13 changes: 13 additions & 0 deletions CMakeTests.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -228,6 +228,19 @@ foreach(file ${conformance_files})
File)
endforeach()

file(GLOB conformance_files tests/inputfiles/hierarchy/*.jsonl)
foreach(file ${conformance_files})
add_h3_test_with_arg(testConformanceHierarchy
src/apps/testapps/testConformanceHierarchy.c ${file}
File)
endforeach()

file(GLOB conformance_files tests/inputfiles/sets/*.jsonl)
foreach(file ${conformance_files})
add_h3_test_with_arg(testConformanceSets
src/apps/testapps/testConformanceSets.c ${file} File)
endforeach()

add_h3_test_with_arg(testConformanceFloatsCells
src/apps/testapps/testConformanceFloatsCells.c
${CMAKE_CURRENT_SOURCE_DIR}/tests/inputfiles/floats/cells.jsonl
Expand Down
120 changes: 117 additions & 3 deletions dev-docs/conformance.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,11 +115,14 @@ tests/inputfiles/
unsafe/cells.jsonl
localij/pairs.jsonl
localij/curated.jsonl
hierarchy/cells.jsonl
hierarchy/curated.jsonl
sets/sets.jsonl
sets/curated.jsonl
```

The remaining groups of the suite (`hierarchy`, `edges`, `vertexes`,
`sets`, `regions`, the other `floats` files and `digests`) are added group
by group; the generator already writes all
The remaining groups of the suite (`edges`, `vertexes`, `regions`, the
other `floats` files and `digests`) are added group by group; the generator already writes all
of them, and each is specified here when its files land.

`manifest.json` is the only file a consumer opens by name. Every record file
Expand Down Expand Up @@ -376,6 +379,79 @@ Example:
{"index":"8003fffffffffff","target":"8001fffffffffff","ij":{"i":1,"j":0},"cell":"8001fffffffffff"}
```

### `hierarchy`

One line per **valid cell**. Resolution bounds are the only source of errors:
a resolution-0 cell has no parents, and a resolution-15 cell has no children.

| Key | Function | Type |
|---|---|---|
| `index` | the subject cell | index string |
| `parents` | `cellToParent(index, r)` for `r` from 0 to `res - 1`, in that order | sequence of index strings |
| `centerChild` | `cellToCenterChild(index, res + 1)` | index string, or error |
| `children` | `cellToChildren(index, res + 1)`, with `0` padding removed | set of index strings, or error |
| `childPos` | `cellToChildPos(index, 0)` | integer, or error |

A consumer must also check the round trip `childPosToCell(childPos, parents[0],
res) == index` (using `index` itself as the parent when `res` is 0) whenever
`childPos` succeeded.

Example:

```json
{"index":"8100bffffffffff","parents":["8001fffffffffff"],"centerChild":"820087fffffffff","children":["820087fffffffff","82008ffffffffff","820097fffffffff","82009ffffffffff","8200a7fffffffff","8200affffffffff","8200b7fffffffff"],"childPos":2}
```

### `sets`

One line per **input set**, built from a subject cell in one of six kinds.
The `id` is the kind and the cell, joined by `:`. `input` is a sequence
because duplicates and invalid entries are part of the test; the two
function outputs are sets.

| Key | Function | Type |
|---|---|---|
| `id` | `<kind>:<cell>` | string |
| `input` | the cells passed to both functions, in order | sequence of index strings |
| `compact` | `compactCells(input)` | set of index strings, or error |
| `uncompactRes` | the resolution passed to `uncompactCells` | integer |
| `uncompact` | `uncompactCells(input, uncompactRes)` | set of index strings, or `true` when that set is `input` as a set, or error |

When `uncompactRes` is the resolution of `input`, `uncompactCells` returns
the input itself, and the file writes `true` rather than repeating it. A
consumer that reads `true` compares against `input` with padding removed,
sorted and deduplicated.

The kinds, for a subject at resolution `res`:

| Kind | `input` | `uncompactRes` |
|---|---|---|
| `children` | `cellToChildren(cell, min(res + 2, 15))` | `min(res + 2, 15)` |
| `disk` | `gridDisk(cell, 2)` in slot order | `res + 1` |
| `holes` | `gridDisk(cell, 3)` in slot order with one to three slots cleared (see Sampling) | `res` |
| `duplicate` | `cellToChildren(p, res(p) + 1)` followed by its first entry again, where `p` is the cell, or its parent when `res` is 15 | `res(p) + 1` |
| `invalid` | `gridDisk(cell, 1)` in slot order followed by the cell with reserved bits 56-58 set to `001` | `res` |
| `coarse` | `gridDisk(cell, 1)` in slot order | `res - 1` |

Padding is removed from every input. `duplicate` fails `compactCells` with
`E_DUPLICATE_INPUT`; `invalid` fails it with `E_CELL_INVALID` except at
resolution 0, where the reference copies the input through unchecked;
`coarse` fails `uncompactCells` with `E_RES_MISMATCH`, as does `disk` at
resolution 15. Mixed-resolution input to `compactCells` is outside its
contract and is not sampled.

A consumer must also check the round trip `uncompactCells(compact, r) ==
input` as sets, where `r` is the finest resolution in `input`, whenever
`compact` succeeded and every entry of `input` is a valid cell.

Example:

```json
{"id":"coarse:8009fffffffffff","input":["8007fffffffffff","8009fffffffffff","8019fffffffffff","8001fffffffffff","801ffffffffffff","8011fffffffffff"],"compact":["8001fffffffffff","8007fffffffffff","8009fffffffffff","8011fffffffffff","8019fffffffffff","801ffffffffffff"],"uncompactRes":-1,"uncompact":{"err":"E_RES_MISMATCH"}}
{"id":"children:8f0800000000000","input":["8f0800000000000"],"compact":["8f0800000000000"],"uncompactRes":15,"uncompact":true}
{"id":"duplicate:81083ffffffffff","input":["820807fffffffff","820817fffffffff","82081ffffffffff","820827fffffffff","82082ffffffffff","820837fffffffff","820807fffffffff"],"compact":{"err":"E_DUPLICATE_INPUT"},"uncompactRes":2,"uncompact":["820807fffffffff","820817fffffffff","82081ffffffffff","820827fffffffff","82082ffffffffff","820837fffffffff"]}
```

## Curated files

Seeded sampling gives coverage density but is blind to the particular inputs
Expand Down Expand Up @@ -449,6 +525,26 @@ input directory (`tests/inputfiles/`), and *hand* a choice made here.
| `85283473fffffff` | `85283472fffffff` | cli | an invalid target |
| `200f202020202020` | `85283473fffffff` | tests | an invalid origin |

### `hierarchy/curated.jsonl`

`88283080ddfffff`, `8f283080dcb0ae2`, `81083ffffffffff`, `820807fffffffff`,
`85283473fffffff`, `80c3fffffffffff`, `8928342e20fffff`, `8029fffffffffff`:
the `cellToChildren` fixtures, a res 15 cell, a res 1 pentagon and its
res 2 center child, the command-line cells, and res 0 cells.

### `sets/curated.jsonl`

The `id` is `curated:<name>`; the `input` is in the record, in this order.

| Name | `input` | `uncompactRes` | Source |
|---|---|---|---|
| `compact_test1` | the 19 res 5 cells of `compact_test1.txt`, which include all seven children of `8428347ffffffff` | 6 | inputfiles |
| `multipolygon_test3` | the 6 res 5 cells of `multipolygon_test3.txt`, a ring without its center | 6 | inputfiles |
| `multipolygon_test4` | the 7 cells of `multipolygon_test4.txt`, that ring and a distant cell | 6 | inputfiles |
| `multipolygon_test5` | the 128 res 5 cells of `multipolygon_test5.txt` | 6 | inputfiles |
| `pentagon_children` | the six children of the res 1 pentagon `81083ffffffffff` | 3 | hand |
| `res0` | `getRes0Cells` in the reference's order | 1 | hand |

## Sampling

Inputs are chosen by a deterministic procedure from `generator.seed`, so that
Expand Down Expand Up @@ -567,6 +663,24 @@ cells at the origin's resolution until `isValidCell` accepts one. The origin
is written with the near target, then with the far target unless the two
targets are the same cell.

### `hierarchy/cells.jsonl`

Valid-cell subjects with `n` = 32. No further draws.

### `sets/sets.jsonl`

Subjects:

1. `getPentagons(res)` for `res` 0 through 15, in the order the reference
returns them. No draws.
2. For `res` 0 through 15, twice: draw cells at `res` until `isValidCell`
accepts one, and emit it.

Sorted ascending and deduplicated as above. Then for each subject, the six
kinds are written in the order of the kinds table. Only `holes` draws: draw 3
to get a count from 1 to 3, then that many times draw 37 and clear that slot
of the `gridDisk(cell, 3)` array; a slot that is already zero stays zero.

### Curated files

No draws. The subjects are the tables under Curated files, written in the
Expand Down
90 changes: 90 additions & 0 deletions src/apps/testapps/testConformanceHierarchy.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
/*
* Copyright 2026 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.
*/
/** @file
* @brief Conformance runner for the `hierarchy` group
* (dev-docs/conformance.md).
*
* usage: `testConformanceHierarchy <record-file>`
*
* Each line holds one valid cell with its parents at every coarser
* resolution, its center child and children one resolution finer, and its
* position among the children of its resolution 0 ancestor.
*/

#include <stdlib.h>

#include "conformance.h"
#include "h3api.h"

static void checkHierarchy(const cJSON *record) {
H3Index h = jsonIndex(record, "index");
int res = H3_EXPORT(getResolution)(h);

const cJSON *parents = jsonArray(record, "parents");
c_assert(cJSON_GetArraySize(parents) == res,
"parents: expected one per coarser resolution");
int parentRes = 0;
const cJSON *item;
cJSON_ArrayForEach(item, parents) {
H3Index parent;
c_assert(!H3_EXPORT(cellToParent)(h, parentRes, &parent),
"cellToParent");
assertIndex(item, parent, "parents");
parentRes++;
}

const cJSON *centerChildItem = jsonItem(record, "centerChild");
H3Index centerChild;
H3Error err = H3_EXPORT(cellToCenterChild)(h, res + 1, &centerChild);
if (!expectResult(centerChildItem, err, "centerChild")) {
assertIndex(centerChildItem, centerChild, "centerChild");
}

const cJSON *childrenItem = jsonItem(record, "children");
int64_t childCount = 0;
err = H3_EXPORT(cellToChildrenSize)(h, res + 1, &childCount);
if (!expectResult(childrenItem, err, "children")) {
H3Index *children = calloc((size_t)childCount, sizeof *children);
c_assert(children, "out of memory");
c_assert(!H3_EXPORT(cellToChildren)(h, res + 1, children),
"cellToChildren");
assertIndexSet(childrenItem, children, childCount, "children");
free(children);
}

const cJSON *childPosItem = jsonItem(record, "childPos");
int64_t childPos;
err = H3_EXPORT(cellToChildPos)(h, 0, &childPos);
if (!expectResult(childPosItem, err, "childPos")) {
c_assert(cJSON_IsNumber(childPosItem), "childPos: not a number");
c_assert(childPos == (int64_t)childPosItem->valuedouble, "childPos");

// The round trip through the resolution 0 ancestor.
H3Index ancestor = h;
if (res > 0) {
ancestor = parseIndex(cJSON_GetArrayItem(parents, 0)->valuestring);
}
H3Index roundTrip;
c_assert(
!H3_EXPORT(childPosToCell)(childPos, ancestor, res, &roundTrip),
"childPosToCell");
c_assert(roundTrip == h, "childPosToCell does not round trip");
}
}

int main(int argc, char *argv[]) {
return conformanceMain(argc, argv, checkHierarchy);
}
127 changes: 127 additions & 0 deletions src/apps/testapps/testConformanceSets.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
/*
* Copyright 2026 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.
*/
/** @file
* @brief Conformance runner for the `sets` group (dev-docs/conformance.md).
*
* usage: `testConformanceSets <record-file>`
*
* Each line holds one input set, which may contain duplicates and invalid
* cells, with `compactCells` of it and `uncompactCells` of it at a given
* resolution. When every input is valid and compaction succeeded,
* uncompacting the result at the input's finest resolution must give the
* input back as a set.
*/

#include <stdlib.h>
#include <string.h>

#include "conformance.h"
#include "h3api.h"

/** Uncompacts `cells` to `res`, returning the error or filling `out` and
* `count` with a malloc'd result. */
static H3Error uncompact(const H3Index *cells, int64_t numCells, int res,
H3Index **out, int64_t *count) {
*out = NULL;
*count = 0;
H3Error err = H3_EXPORT(uncompactCellsSize)(cells, numCells, res, count);
if (err) {
return err;
}
*out = calloc(*count ? (size_t)*count : 1, sizeof **out);
c_assert(*out, "out of memory");
err = H3_EXPORT(uncompactCells)(cells, numCells, *out, *count, res);
if (err) {
free(*out);
*out = NULL;
}
return err;
}

/** Checks that two buffers hold the same set of indexes; both are
* reordered. */
static void assertSameSet(H3Index *got, int64_t gotCount, H3Index *want,
int64_t wantCount, const char *what) {
gotCount = normalizeIndexSet(got, gotCount);
wantCount = normalizeIndexSet(want, wantCount);
c_assert(gotCount == wantCount &&
!memcmp(got, want, (size_t)gotCount * sizeof *got),
what);
}

static void checkSets(const cJSON *record) {
int64_t numInput;
H3Index *input = parseIndexArray(jsonArray(record, "input"), &numInput);
bool allValid = true;
int finest = 0;
for (int64_t i = 0; i < numInput; i++) {
allValid = allValid && H3_EXPORT(isValidCell)(input[i]);
int res = H3_EXPORT(getResolution)(input[i]);
finest = res > finest ? res : finest;
}

const cJSON *compactItem = jsonItem(record, "compact");
H3Index *compacted =
calloc(numInput ? (size_t)numInput : 1, sizeof *compacted);
c_assert(compacted, "out of memory");
H3Error compactErr = H3_EXPORT(compactCells)(input, compacted, numInput);
if (!expectResult(compactItem, compactErr, "compact")) {
H3Index *copy = malloc((size_t)numInput * sizeof *copy + 1);
c_assert(copy, "out of memory");
memcpy(copy, compacted, (size_t)numInput * sizeof *copy);
assertIndexSet(compactItem, copy, numInput, "compact");
free(copy);
}

int uncompactRes = jsonInt(record, "uncompactRes");
const cJSON *uncompactItem = jsonItem(record, "uncompact");
H3Index *uncompacted;
int64_t numUncompacted;
H3Error err =
uncompact(input, numInput, uncompactRes, &uncompacted, &numUncompacted);
if (!expectResult(uncompactItem, err, "uncompact")) {
if (cJSON_IsTrue(uncompactItem)) {
// true means the input as a set.
H3Index *want = malloc((size_t)numInput * sizeof *want + 1);
c_assert(want, "out of memory");
memcpy(want, input, (size_t)numInput * sizeof *want);
assertSameSet(uncompacted, numUncompacted, want, numInput,
"uncompact: not the input as a set");
free(want);
} else {
assertIndexSet(uncompactItem, uncompacted, numUncompacted,
"uncompact");
}
}
free(uncompacted);

if (!compactErr && allValid) {
H3Index *roundTrip;
int64_t numRoundTrip;
c_assert(
!uncompact(compacted, numInput, finest, &roundTrip, &numRoundTrip),
"uncompactCells of the compacted set");
assertSameSet(roundTrip, numRoundTrip, input, numInput,
"uncompactCells(compact) does not round trip");
free(roundTrip);
}
free(compacted);
free(input);
}

int main(int argc, char *argv[]) {
return conformanceMain(argc, argv, checkSets);
}
Loading
Loading