[WIP: Do not review] NanoVDB: VoxelBlockManager CPU port of decodeInverseMaps

CLAUDE.md

@@ -0,0 +1,167 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build System
+
+OpenVDB uses CMake (minimum 3.24) and requires out-of-source builds.
+
+**Minimal core build:**
+```bash
+mkdir build && cd build
+cmake .. -DOPENVDB_BUILD_UNITTESTS=ON
+make -j$(nproc)
+```
+
+**Using the CI build script (recommended for full builds):**
+```bash
+./ci/build.sh --build-type=Release \
+  --components="core,test" \
+  --cargs="-DOPENVDB_ABI_VERSION_NUMBER=13"
+```
+
+Component flags for `--components`: `core`, `python`, `bin`, `view`, `render`, `test`, `hou`, `axcore`, `nano`, `nanotest`
+
+**Key CMake options:**
+| Option | Default | Description |
+|--------|---------|-------------|
+| `OPENVDB_BUILD_CORE` | ON | Core library |
+| `OPENVDB_BUILD_UNITTESTS` | OFF | Unit tests |
+| `OPENVDB_BUILD_NANOVDB` | OFF | NanoVDB |
+| `OPENVDB_BUILD_AX` | OFF | OpenVDB AX |
+| `OPENVDB_ABI_VERSION_NUMBER` | 13 | ABI version (6–13) |
+| `OPENVDB_CXX_STRICT` | OFF | Strict warnings |
+| `NANOVDB_USE_CUDA` | OFF | CUDA support for NanoVDB |
+
+## Running Tests
+
+```bash
+cd build
+ctest -V                          # all tests
+ctest -V -R TestGrid              # single test by name
+```
+
+To build only specific unit tests (avoids full rebuild):
+```bash
+cmake .. -DOPENVDB_TESTS="Grid;Tree;LeafNode"
+```
+
+Tests use Google Test (minimum 1.10). Test sources live in:
+- `openvdb/openvdb/unittest/` — core library tests (`TestFoo.cc` pattern)
+- `nanovdb/nanovdb/unittest/` — NanoVDB tests
+
+## Code Architecture
+
+### Repository Layout
+
+```
+openvdb/openvdb/        Core OpenVDB library
+  tree/                 Tree node hierarchy (RootNode, InternalNode, LeafNode)
+  tools/                Algorithm implementations (level sets, CSG, smoothing, etc.)
+  math/                 Math primitives (Vec, Mat, Quat, Transform, BBox)
+  io/                   VDB file format I/O
+  points/               Point data grids
+  python/               Python bindings (nanobind)
+  unittest/             Unit tests
+
+nanovdb/nanovdb/        NanoVDB — compact, GPU-friendly VDB subset
+  tools/                CPU algorithms
+  tools/cuda/           CUDA kernels
+  examples/             Standalone example programs
+
+openvdb_ax/openvdb_ax/  OpenVDB AX — JIT expression language for VDB operations
+  ast/                  Abstract syntax tree
+  codegen/              LLVM code generation
+  compiler/             Compilation pipeline
+
+openvdb_cmd/            Command-line tools (vdb_print, vdb_lod, vdb_tool, vdb_view, vdb_render)
+openvdb_houdini/        Houdini plugin
+openvdb_maya/           Maya plugin
+cmake/                  CMake find-modules and configuration
+ci/                     CI build/install scripts
+```
+
+### Core Data Model
+
+OpenVDB uses a **B+tree-like hierarchical sparse data structure**:
+- `Grid<TreeType>` — top-level container with transform and metadata
+- `Tree` — composed of `RootNode → InternalNode(s) → LeafNode`
+- Leaf nodes are 8×8×8 voxel blocks; internal nodes are 16³ and 32³ by default
+- `ValueAccessor` caches tree traversal paths for repeated access patterns
+- `GridBase` / `TypedGrid` provide the runtime-polymorphic/compile-time-typed split
+
+### NanoVDB vs OpenVDB
+
+NanoVDB is a read-optimized, single-allocation, GPU-portable subset of OpenVDB. It cannot be modified after construction. The `nanovdb/tools/CreateNanoGrid.h` and adjacent files handle conversion from OpenVDB grids to NanoVDB grids.
+
+### Topology Operators — CPU Port (this branch)
+
+The branch `vbm-cpu-port` back-ports the five CUDA-only NanoVDB topology operators (`DilateGrid`, `MergeGrids`, `PruneGrid`, `RefineGrid`, `CoarsenGrid`) from `nanovdb/tools/cuda/*.cuh` (namespace `nanovdb::tools::cuda`) to host-only headers at `nanovdb/tools/*.h` (namespace `nanovdb::tools`). The design plan is in `nanovdb/nanovdb/tools/TopologyCpuPortPlan.md`.
+
+**Key files:**
+- `nanovdb/tools/TopologyBuilder.h` — shared base class (in-progress port; still has CUDA includes during transition)
+- `nanovdb/tools/MergeGrids.h` — first operator being ported
+- `nanovdb/util/Morphology.h` — host-side morphology functors (parallel to `util/cuda/Morphology.cuh`)
+- `nanovdb/util/PrefixSum.h` — host `inclusiveScan` used in place of CUB scans
+- `nanovdb/tools/VoxelBlockManager.h` — VBM acceleration structure for active-voxel SIMT/SIMD access
+
+**CUDA → host transition pattern:**
+- Device-only scratch buffers use `ScratchBufferT = UnifiedBuffer` (transitional) → will become `HostBuffer`
+- `lambdaKernel` launches → `util::forEach` calls
+- CUB inclusive scans → `util::inclusiveScan`
+- Morphology functors move from `util/cuda/Morphology.cuh` (`__device__`) to `util/Morphology.h` (host `inline`)
+- CUDA stays on (`NANOVDB_USE_CUDA=ON`) throughout; host-only completion is signaled by renaming `.cu` → `.cpp` in examples
+
+**Build config for this branch** (build dir: `nanovdb/nanovdb/build/`):
+```bash
+cd nanovdb/nanovdb/build
+cmake -DCMAKE_BUILD_TYPE=Release \
+      -DNANOVDB_BUILD_EXAMPLES=ON \
+      -DNANOVDB_USE_CUDA=ON \
+      -DNANOVDB_USE_OPENVDB=ON \
+      -DNANOVDB_USE_TBB=ON \
+      -DCMAKE_CUDA_ARCHITECTURES=120 \
+      -DCMAKE_PREFIX_PATH=~/local \
+      -DOpenVDB_ROOT=~/local \
+      ..
+make -j$(nproc)
+```
+
+OpenVDB is installed at `~/local` (not `/usr/local`). The project's `cmake/FindOpenVDB.cmake` requires `-DOpenVDB_ROOT=~/local` explicitly — `CMAKE_PREFIX_PATH` alone is not enough because the finder is invoked from the repo's `cmake/` directory, not the installed `OpenVDB/` directory, so it doesn't auto-detect the prefix. Always clear `CMakeCache.txt` before re-running cmake if you change this path, as NOTFOUND results are cached.
+
+Always use a specific `-DCMAKE_CUDA_ARCHITECTURES=` value (here `120` for Blackwell). The default `=75` (Turing) causes silent kernel failures on non-sm_75 hardware, surfacing as misleading `cudaErrorInvalidDevice`.
+
+**Validation:**
+```bash
+./ex_merge_nanovdb_cpu  /path/to/dragon.vdb /path/to/torus.vdb 3
+./ex_dilate_nanovdb_cpu /path/to/dragon.vdb 3
+./ex_refine_nanovdb_cpu /path/to/dragon.vdb 3
+./ex_coarsen_nanovdb_cpu /path/to/dragon.vdb 3
+```
+Each should print `Result of <Op> check out CORRECT against reference`.
+
+**Only `OnIndexGrid` buildtypes are supported** (`static_assert(BuildTraits<BuildT>::is_onindex)`). Grids with tile values at any level cause the operator to throw.
+
+### OpenVDB AX
+
+AX compiles a domain-specific expression language to LLVM IR for execution over OpenVDB volumes and point grids. The pipeline is: source string → AST (`ast/`) → typed analysis → LLVM codegen (`codegen/`) → JIT execution via `compiler/`.
+
+## C++ Standard and ABI
+
+- Requires C++17 minimum
+- ABI version is set at compile time via `OPENVDB_ABI_VERSION_NUMBER`; the current version is 13
+- Headers are in `openvdb/openvdb/` and installed to `include/openvdb/`
+
+## Dependencies
+
+Core: Boost ≥ 1.82, TBB ≥ 2020.3, Blosc ≥ 1.17, OpenEXR/Imath ≥ 3.2, zlib ≥ 1.2.7
+Tests: GTest ≥ 1.10
+Python bindings: Python ≥ 3.11, nanobind ≥ 2.5.0
+NanoVDB GPU: CUDA toolkit
+AX: LLVM
+
+On Linux, ASWF Docker containers (used by CI) bundle most dependencies. See `ci/install_macos.sh` and `ci/install_windows.ps1` for platform-specific setup.
+
+## Coding Standards
+
+Follow the style guide at https://www.openvdb.org/documentation/doxygen/codingStyle.html. Contributions require a Developer Certificate of Origin sign-off (`git commit -s`) and a CLA on file — see CONTRIBUTING.md.

nanovdb/nanovdb/NanoVDB.h

@@ -4136,15 +4136,26 @@ struct NANOVDB_ALIGN(NANOVDB_DATA_ALIGNMENT) LeafData<ValueOnIndex, CoordT, Mask
     __hostdev__ uint64_t getMax() const { return this->hasStats() ? this->lastOffset() + 2u : 0u; }
     __hostdev__ uint64_t getAvg() const { return this->hasStats() ? this->lastOffset() + 3u : 0u; }
     __hostdev__ uint64_t getDev() const { return this->hasStats() ? this->lastOffset() + 4u : 0u; }
+    // Default branchless; define NANOVDB_USE_BRANCHY_GETVALUE to restore the
+    // pre-2026 branchy form.
     __hostdev__ uint64_t getValue(uint32_t i) const
     {
-        //return mValueMask.isOn(i) ? mOffset + mValueMask.countOn(i) : 0u;// for debugging
+#ifdef NANOVDB_USE_BRANCHY_GETVALUE
         uint32_t       n = i >> 6;
         const uint64_t w = BaseT::mValueMask.words()[n], mask = uint64_t(1) << (i & 63u);
-        if (!(w & mask)) return uint64_t(0); // if i'th value is inactive return offset to background value
+        if (!(w & mask)) return uint64_t(0);
         uint64_t sum  = BaseT::mOffset + util::countOn(w & (mask - 1u));
         if (n--) sum += BaseT::mPrefixSum >> (9u * n) & 511u;
         return sum;
+#else
+        const uint32_t n      = i >> 6;
+        const uint64_t w      = BaseT::mValueMask.words()[n];
+        const uint64_t bit    = uint64_t(1) << (i & 63u);
+        const uint64_t prefix = n == 0u ? uint64_t(0)
+                                        : (BaseT::mPrefixSum >> (9u * (n - 1u))) & 511u;
+        const uint64_t sum    = BaseT::mOffset + prefix + util::countOn(w & (bit - 1u));
+        return ((w & bit) ? ~uint64_t(0) : uint64_t(0)) & sum;
+#endif
     }
 }; // LeafData<ValueOnIndex>
 

nanovdb/nanovdb/examples/CMakeLists.txt

@@ -114,6 +114,30 @@ nanovdb_example(NAME "ex_merge_nanovdb_cuda" OPENVDB)
 nanovdb_example(NAME "ex_refine_nanovdb_cuda" OPENVDB)
 nanovdb_example(NAME "ex_coarsen_nanovdb_cuda" OPENVDB)
 
+# Host-side port of topology operators (in progress).
+# These examples start identical to their _cuda siblings (using nanovdb::tools::
+# instead of nanovdb::tools::cuda::) and progressively shed CUDA dependencies.
+nanovdb_example(NAME "ex_merge_nanovdb_cpu" OPENVDB)
+nanovdb_example(NAME "ex_dilate_nanovdb_cpu" OPENVDB)
+nanovdb_example(NAME "ex_coarsen_nanovdb_cpu" OPENVDB)
+nanovdb_example(NAME "ex_refine_nanovdb_cpu" OPENVDB)
+
+nanovdb_example(NAME "ex_voxelBlockManager_host_cuda")
+if(TARGET ex_voxelBlockManager_host_cuda)
+  target_compile_options(ex_voxelBlockManager_host_cuda PRIVATE
+    $<$<COMPILE_LANGUAGE:CUDA>:-Xcompiler=-mavx2,-fopenmp-simd>
+    $<$<COMPILE_LANGUAGE:CXX>:-mavx2 -fopenmp-simd>)
+endif()
+
+# End-to-end CPU WENO5 norm-square-gradient on a narrow-band level set,
+# with a scalar reference for correctness validation.
+nanovdb_example(NAME "ex_weno_nanovdb_cpu" OPENVDB)
+if(TARGET ex_weno_nanovdb_cpu)
+  target_compile_options(ex_weno_nanovdb_cpu PRIVATE -march=native -fopenmp-simd)
+  target_include_directories(ex_weno_nanovdb_cpu PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/../../..)
+endif()
+
 if(CUDAToolkit_FOUND)
   nanovdb_example(NAME "ex_make_mgpu_nanovdb") # requires cuRAND
   target_link_libraries(ex_make_mgpu_nanovdb PRIVATE CUDA::curand)

nanovdb/nanovdb/examples/ex_coarsen_nanovdb_cpu/coarsen_nanovdb_cpu.cpp

@@ -0,0 +1,138 @@
+// Copyright Contributors to the OpenVDB Project
+// SPDX-License-Identifier: Apache-2.0
+
+// the following files are from OpenVDB
+#include <openvdb/tree/LeafManager.h>
+#include <openvdb/util/CpuTimer.h>
+
+// the following files are from NanoVDB
+#include <nanovdb/NanoVDB.h>
+#include <nanovdb/tools/CreateNanoGrid.h>
+
+template<class CoordT>
+inline CoordT
+coarsenCoord(const CoordT& coord)
+{
+    auto coarsenComponent = [](const typename CoordT::ValueType n) {return (n>=0) ? (n>>1) : -((-n+1)>>1);};
+    CoordT result;
+    result[0] = coarsenComponent(coord[0]);
+    result[1] = coarsenComponent(coord[1]);
+    result[2] = coarsenComponent(coord[2]);
+    return result;
+}
+
+template<typename BuildT>
+void mainCoarsenGrid(
+    nanovdb::NanoGrid<BuildT> *srcGrid,           // original (un-coarsened) grid
+    nanovdb::NanoGrid<BuildT> *indexGridCoarsened,
+    uint32_t benchmark_iters
+);
+
+/// @brief This example depends on OpenVDB, NanoVDB, and CUDA
+int main(int argc, char *argv[])
+{
+    using GridT = openvdb::FloatGrid;
+    using BuildT = nanovdb::ValueOnIndex;
+
+    openvdb::util::CpuTimer cpuTimer;
+    const bool printGridDiagnostics = true;
+
+    try {
+        if (argc<2) OPENVDB_THROW(openvdb::ValueError, "usage: "+std::string(argv[0])+" input.vdb [<iterations>]\n");
+        int benchmark_iters = 10;
+        if (argc > 2) sscanf(argv[2], "%d", &benchmark_iters);
+
+        // Read the initial level set from file
+        cpuTimer.start("Read input VDB file");
+        openvdb::initialize();
+        openvdb::io::File inFile(argv[1]);
+        inFile.open(false); // disable delayed loading
+        auto baseGrids = inFile.getGrids();
+        inFile.close();
+        auto grid = openvdb::gridPtrCast<GridT>(baseGrids->at(0));
+        if (!grid) OPENVDB_THROW(openvdb::ValueError, "First grid is not a FloatGrid\n");
+        cpuTimer.stop();
+
+        // Convert to indexGrid (original, un-coarsened)
+        cpuTimer.start("Converting openVDB input to indexGrid (original version)");
+        auto handleOriginal = nanovdb::tools::openToIndexVDB<BuildT, nanovdb::HostBuffer>(
+            grid,
+            0u,    // Don't copy data channel
+            false, // No stats
+            false, // No tiles
+            1      // Verbose mode
+        );
+        auto *indexGridOriginal = handleOriginal.grid<BuildT>();
+        cpuTimer.stop();
+
+        if (printGridDiagnostics) {
+            std::cout << "============ Original Grid ===========" << std::endl;
+            std::cout << "Allocated values [valueCount()]       : " << indexGridOriginal->valueCount() << std::endl;
+            std::cout << "Active voxels    [activeVoxelCount()] : " << indexGridOriginal->activeVoxelCount() << std::endl;
+            auto minCorner = indexGridOriginal->indexBBox().min(), maxCorner = indexGridOriginal->indexBBox().max();
+            std::cout << "Index-space bounding box              : [" << minCorner.x() << "," << minCorner.y() << "," << minCorner.z()
+                      << "] -> [" << maxCorner.x() << "," << maxCorner.y() << "," << maxCorner.z() << "]" << std::endl;
+            std::cout << "Leaf nodes                            : " << indexGridOriginal->tree().nodeCount(0) << std::endl;
+            std::cout << "Lower internal nodes                  : " << indexGridOriginal->tree().nodeCount(1) << std::endl;
+            std::cout << "Upper internal nodes                  : " << indexGridOriginal->tree().nodeCount(2) << std::endl;
+            std::cout << "Leaf-level occupancy                  : "
+                      << 100.f * (float)(indexGridOriginal->activeVoxelCount())/(float)(indexGridOriginal->tree().nodeCount(0) * 512)
+                      << "%" << std::endl;
+            std::cout << "Memory usage                          : " << indexGridOriginal->gridSize() << " bytes" << std::endl;
+        }
+
+        // Coarsening (CPU/OpenVDB version), used as the correctness reference
+        cpuTimer.start("Coarsening OpenVDB (on CPU)");
+        using TreeT = GridT::TreeType;
+        using LeafManagerT = openvdb::tree::LeafManager<const TreeT>;
+        LeafManagerT leafMgr(grid->tree());
+        auto coarsenedGrid = openvdb::FloatGrid::create(grid->background());
+        coarsenedGrid->setTransform(grid->transform().copy());
+        coarsenedGrid->setName(grid->getName());
+        auto dstAcc = coarsenedGrid->getAccessor();
+        for (std::size_t leafID = 0; leafID < leafMgr.leafCount(); ++leafID) {
+            const auto& srcLeaf = leafMgr.leaf(leafID);
+            for (auto iter = srcLeaf.cbeginValueOn(); iter; ++iter) {
+                const auto dstCoord = coarsenCoord(iter.getCoord());
+                if (!dstAcc.isValueOn(dstCoord))
+                    dstAcc.setValue(dstCoord, iter.getValue());
+            }
+        }
+        cpuTimer.stop();
+
+        // Convert to indexGrid (coarsened reference)
+        cpuTimer.start("Converting openVDB input to indexGrid (coarsened version)");
+        auto handleCoarsened = nanovdb::tools::openToIndexVDB<BuildT, nanovdb::HostBuffer>(
+            coarsenedGrid,
+            0u,    // Don't copy data channel
+            false, // No stats
+            false, // No tiles
+            1      // Verbose mode
+        );
+        auto *indexGridCoarsened = handleCoarsened.grid<BuildT>();
+        cpuTimer.stop();
+
+        if (printGridDiagnostics) {
+            std::cout << "=========== Coarsened Grid ===========" << std::endl;
+            std::cout << "Allocated values [valueCount()]       : " << indexGridCoarsened->valueCount() << std::endl;
+            std::cout << "Active voxels    [activeVoxelCount()] : " << indexGridCoarsened->activeVoxelCount() << std::endl;
+            auto minCorner = indexGridCoarsened->indexBBox().min(), maxCorner = indexGridCoarsened->indexBBox().max();
+            std::cout << "Index-space bounding box              : [" << minCorner.x() << "," << minCorner.y() << "," << minCorner.z()
+                      << "] -> [" << maxCorner.x() << "," << maxCorner.y() << "," << maxCorner.z() << "]" << std::endl;
+            std::cout << "Leaf nodes                            : " << indexGridCoarsened->tree().nodeCount(0) << std::endl;
+            std::cout << "Lower internal nodes                  : " << indexGridCoarsened->tree().nodeCount(1) << std::endl;
+            std::cout << "Upper internal nodes                  : " << indexGridCoarsened->tree().nodeCount(2) << std::endl;
+            std::cout << "Leaf-level occupancy                  : "
+                      << 100.f * (float)(indexGridCoarsened->activeVoxelCount())/(float)(indexGridCoarsened->tree().nodeCount(0) * 512)
+                      << "%" << std::endl;
+            std::cout << "Memory usage                          : " << indexGridCoarsened->gridSize() << " bytes" << std::endl;
+        }
+
+        // All grids are host-resident (HostBuffer); the operators read them directly.
+        mainCoarsenGrid( indexGridOriginal, indexGridCoarsened, benchmark_iters );
+    }
+    catch (const std::exception& e) {
+        std::cerr << "An exception occurred: \"" << e.what() << "\"" << std::endl;
+    }
+    return 0;
+}