LZGraphs 3.0.0__tar.gz → 3.0.1__tar.gz

{lzgraphs-3.0.0 → lzgraphs-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: LZGraphs
-Version: 3.0.0
+Version: 3.0.1
 Summary: High-performance LZ76 compression graphs for immune receptor repertoire analysis
 Author-email: Thomas Konstantinovsky <thomaskon90@gmail.com>
 Maintainer-email: Thomas Konstantinovsky <thomaskon90@gmail.com>

{lzgraphs-3.0.0 → lzgraphs-3.0.1}/include/lzgraph/edge_builder.h

@@ -20,7 +20,7 @@ typedef struct LZGEdgeBuilder_ {
     LZGHashMap *edge_map;      /* key: pack(src,dst), value: edge index  */
     uint32_t   *src_ids;       /* [n_edges] source node IDs             */
     uint32_t   *dst_ids;       /* [n_edges] destination node IDs        */
-    uint32_t   *counts;        /* [n_edges] raw transition counts       */
+    uint64_t   *counts;        /* [n_edges] raw transition counts       */
     uint32_t    n_edges;
     uint32_t    capacity;
 } LZGEdgeBuilder;
@@ -34,10 +34,12 @@ void lzg_eb_destroy(LZGEdgeBuilder *eb);
 /**
  * Record a transition from src → dst with the given count.
  * If the edge already exists, increments its count.
+ * If `out_edge_idx` is non-NULL, returns the edge index that was updated.
  */
 LZGError lzg_eb_record(LZGEdgeBuilder *eb,
                         uint32_t src_id, uint32_t dst_id,
-                        uint32_t count);
+                        uint64_t count,
+                        uint32_t *out_edge_idx);
 
 /** Pack key from (src, dst) pair. */
 static inline uint64_t lzg_eb_pack_key(uint32_t src, uint32_t dst) {

{lzgraphs-3.0.0 → lzgraphs-3.0.1}/include/lzgraph/gene_data.h

@@ -26,13 +26,13 @@ typedef struct LZGGeneData_ {
     /* ── Per-edge V gene counts (CSR-within-CSR) ── */
     uint32_t *v_offsets;      /* [n_edges + 1]: range per edge         */
     uint32_t *v_gene_ids;     /* [total_v_entries]: interned gene IDs  */
-    uint32_t *v_gene_counts;  /* [total_v_entries]: raw counts         */
+    uint64_t *v_gene_counts;  /* [total_v_entries]: raw counts         */
     uint32_t  total_v_entries;
 
     /* ── Per-edge J gene counts (CSR-within-CSR) ── */
     uint32_t *j_offsets;
     uint32_t *j_gene_ids;
-    uint32_t *j_gene_counts;
+    uint64_t *j_gene_counts;
     uint32_t  total_j_entries;
 
     /* ── Graph-level marginal distributions ── */

{lzgraphs-3.0.0 → lzgraphs-3.0.1}/include/lzgraph/graph.h

@@ -37,7 +37,7 @@ typedef struct LZGGraph_ {
 
     /* ── Per-edge data (parallel to col_indices) ── */
     double   *edge_weights;    /* [n_edges]: normalized P(dst|src)         */
-    uint32_t *edge_counts;     /* [n_edges]: raw transition counts         */
+    uint64_t *edge_counts;     /* [n_edges]: raw transition counts         */
 
     /* ── Per-edge LZ constraint info ── */
     uint32_t *edge_sp_id;      /* [n_edges]: interned subpattern of dst    */
@@ -45,7 +45,7 @@ typedef struct LZGGraph_ {
     uint32_t *edge_prefix_id;  /* [n_edges]: interned prefix of dst sp     */
 
     /* ── Per-node data ── */
-    uint32_t *outgoing_counts; /* [n_nodes]: total raw outgoing count      */
+    uint64_t *outgoing_counts; /* [n_nodes]: total raw outgoing count      */
     uint32_t *node_sp_id;      /* [n_nodes]: interned subpattern string    */
     uint8_t  *node_sp_len;     /* [n_nodes]: subpattern character length   */
     uint32_t *node_pos;        /* [n_nodes]: cumulative position integer   */
@@ -59,7 +59,7 @@ typedef struct LZGGraph_ {
     bool      topo_valid;
 
     /* ── Length distribution ── */
-    uint32_t *length_counts;   /* indexed by sequence length               */
+    uint64_t *length_counts;   /* indexed by sequence length               */
     uint32_t  max_length;      /* largest observed sequence length         */
 
     /* ── String pool (owns all string data) ── */
@@ -71,6 +71,14 @@ typedef struct LZGGraph_ {
 
     /* ── Gene data (optional, NULL if no gene columns provided) ── */
     struct LZGGeneData_ *gene_data;
+
+    /* ── Transient query cache (not serialized) ── */
+    LZGHashMap *query_node_map; /* structural key -> node index */
+    uint64_t   *edge_sp_hash;   /* [n_edges]: hash of destination token     */
+    uint64_t   *edge_prefix_hash; /* [n_edges]: hash of prefix token or 0   */
+    uint64_t   *node_sp_hash;   /* [n_nodes]: hash of node token            */
+    uint8_t    *edge_single_char_idx; /* [n_edges]: aa bit index or UINT8_MAX */
+    uint8_t    *node_single_char_idx; /* [n_nodes]: aa bit index or UINT8_MAX */
 } LZGGraph;
 
 /** Allocate and initialize an empty graph. */
@@ -95,12 +103,25 @@ void lzg_graph_destroy(LZGGraph *g);
 LZGError lzg_graph_build(LZGGraph *g,
                           const char **sequences,
                           uint32_t n_seqs,
-                          const uint32_t *abundances,
+                          const uint64_t *abundances,
                           const char **v_genes,
                           const char **j_genes,
                           double smoothing,
                           uint32_t min_init);
 
+/**
+ * Build a graph from a plain text file without materializing all sequences in Python.
+ *
+ * Supported input formats:
+ * - one sequence per line
+ * - sequence<TAB>abundance
+ *
+ * Gene columns and headered tabular formats are not supported by this path.
+ */
+LZGError lzg_graph_build_plain_file(LZGGraph *g,
+                                     const char *path,
+                                     double smoothing);
+
 /** Compute topological sort (cached, invalidated on structural changes). */
 LZGError lzg_graph_topo_sort(LZGGraph *g);
 
@@ -116,7 +137,7 @@ LZGError lzg_graph_finalize_from_edges(
     LZGHashMap *initial_counts,
     LZGHashMap *terminal_counts,
     LZGHashMap *outgoing_counts,
-    uint32_t *len_counts, uint32_t max_len);
+    uint64_t *len_counts, uint32_t max_len);
 
 /* ── Recalculation flags ───────────────────────────────────── */
 
@@ -132,6 +153,12 @@ typedef enum {
  */
 LZGError lzg_graph_recalculate(LZGGraph *g, uint32_t flags);
 
+/**
+ * Internal: ensure transient query-side edge hash caches exist.
+ * These caches are derived from immutable edge metadata and are not serialized.
+ */
+LZGError lzg_graph_ensure_query_edge_hashes(LZGGraph *g);
+
 /** Get the number of successors for node `node_id`. */
 static inline uint32_t lzg_graph_out_degree(const LZGGraph *g, uint32_t node_id) {
     return g->row_offsets[node_id + 1] - g->row_offsets[node_id];

{lzgraphs-3.0.0 → lzgraphs-3.0.1}/include/lzgraph/hash_map.h

@@ -27,6 +27,22 @@ bool        lzg_hm_put(LZGHashMap *map, uint64_t key, uint64_t value);
 /** Lookup. Returns pointer to value or NULL. */
 uint64_t   *lzg_hm_get(const LZGHashMap *map, uint64_t key);
 
+/**
+ * Lookup or insert in a single probe walk. Returns a writable value slot.
+ * If the key is absent, inserts it with `initial_value`.
+ * If `inserted` is non-NULL, it is set to true iff a new entry was created.
+ */
+uint64_t   *lzg_hm_get_or_insert(LZGHashMap *map, uint64_t key,
+                                 uint64_t initial_value, bool *inserted);
+
+/**
+ * Add `delta` to the value stored at `key`, inserting `delta` if absent.
+ * Returns a writable value slot after the update.
+ * If `inserted` is non-NULL, it is set to true iff a new entry was created.
+ */
+uint64_t   *lzg_hm_add_u64(LZGHashMap *map, uint64_t key,
+                           uint64_t delta, bool *inserted);
+
 /** Delete. Returns true if found. */
 bool        lzg_hm_delete(LZGHashMap *map, uint64_t key);
 

{lzgraphs-3.0.0 → lzgraphs-3.0.1}/include/lzgraph/io.h

@@ -1,6 +1,6 @@
 /**
  * @file io.h
- * @brief LZG2 binary file format: section-based save/load with CRC-32C.
+ * @brief LZG binary file format: section-based save/load with CRC-32C.
  *
  * File extension: .lzg
  * See FILE_FORMAT.md for the complete specification.
@@ -14,7 +14,7 @@
 /* ── Format constants ──────────────────────────────────────── */
 
 #define LZG_IO_MAGIC           0x4C5A4732u  /* "LZG2" */
-#define LZG_IO_FORMAT_VERSION         2
+#define LZG_IO_FORMAT_VERSION         3
 #define LZG_IO_ENDIAN_LE       0x01
 #define LZG_IO_TRAILER_MAGIC   0x454E444Cu  /* "ENDL" */
 
@@ -50,8 +50,8 @@
 LZG_PACKED_BEGIN
 typedef struct LZG_PACKED_ATTR {
     uint32_t magic;               /* 0x4C5A4732 */
-    uint16_t format_version;      /* 2 */
-    uint16_t min_reader_version;  /* 2 */
+    uint16_t format_version;      /* current format version */
+    uint16_t min_reader_version;  /* minimum supported reader version */
     uint8_t  endian_tag;          /* 0x01 = LE */
     uint8_t  variant;             /* 0=AAP, 1=NDP, 2=Naive */
     uint8_t  compression;         /* 0=none, 1=zstd, 2=gzip */

{lzgraphs-3.0.0 → lzgraphs-3.0.1}/include/lzgraph/posterior.h

@@ -34,7 +34,7 @@
  */
 LZGError lzg_graph_posterior(const LZGGraph *prior,
                         const char **sequences, uint32_t n_seqs,
-                        const uint32_t *abundances,
+                        const uint64_t *abundances,
                         double kappa,
                         LZGGraph **out);
 

lzgraphs-3.0.1/include/lzgraph/walk_dict.h

@@ -0,0 +1,232 @@
+/**
+ * @file walk_dict.h
+ * @brief Per-walk LZ76 dictionary for dynamic constraint checking.
+ *
+ * Replaces the precomputed bitmask live index for simulation and walk
+ * probability. Each walk carries a lightweight hash dictionary that
+ * tracks which tokens have been emitted, enabling EXACT LZ76 constraint
+ * enforcement at O(degree) per step with no global precomputation.
+ *
+ * Correctness: The bitmask approach was an approximation —
+ *   - Single-char: tracked "character in ANY token" (too restrictive)
+ *   - Multi-char: tracked "first char of prefix seen" (too permissive)
+ *
+ * The walk dictionary checks the exact LZ76 conditions:
+ *   - Single-char token "X": X was NOT a previous standalone token
+ *   - Multi-char token "XY...Z": prefix "XY..." WAS a previous token
+ */
+#ifndef LZGRAPH_WALK_DICT_H
+#define LZGRAPH_WALK_DICT_H
+
+#include "lzgraph/common.h"
+#include "lzgraph/graph.h"
+#include "lzgraph/hash_map.h"
+#include "lzgraph/string_pool.h"
+#include <string.h>
+
+#define LZG_WD_INLINE_CAP 256u
+
+/**
+ * Per-walk LZ76 dictionary state.
+ *
+ * Uses a small exact fixed-capacity token set in the hot path.
+ * If an unexpected walk exceeds that bound, we promote once into an
+ * overflow hash map and keep exact behavior.
+ */
+typedef struct {
+    uint64_t    inline_keys[LZG_WD_INLINE_CAP];
+    uint8_t     inline_used[LZG_WD_INLINE_CAP];
+    uint16_t    inline_count;
+    uint32_t    single_char_bits; /* bitmask: chars emitted as single-char */
+    LZGHashMap *overflow;         /* exact fallback if inline set fills     */
+} LZGWalkDict;
+
+static inline bool lzg_wd_inline_contains(const LZGWalkDict *wd, uint64_t key) {
+    uint32_t mask = LZG_WD_INLINE_CAP - 1u;
+    uint32_t idx = (uint32_t)(key & mask);
+    while (wd->inline_used[idx]) {
+        if (wd->inline_keys[idx] == key) return true;
+        idx = (idx + 1u) & mask;
+    }
+    return false;
+}
+
+static inline bool lzg_wd_inline_insert(LZGWalkDict *wd, uint64_t key) {
+    /* Keep probe chains short; normal walks never approach this bound. */
+    if ((uint32_t)wd->inline_count * 4u >= LZG_WD_INLINE_CAP * 3u)
+        return false;
+
+    uint32_t mask = LZG_WD_INLINE_CAP - 1u;
+    uint32_t idx = (uint32_t)(key & mask);
+    while (wd->inline_used[idx]) {
+        if (wd->inline_keys[idx] == key) return true;
+        idx = (idx + 1u) & mask;
+    }
+    wd->inline_used[idx] = 1u;
+    wd->inline_keys[idx] = key;
+    wd->inline_count++;
+    return true;
+}
+
+static inline bool lzg_wd_promote_overflow(LZGWalkDict *wd) {
+    if (!wd->overflow) {
+        wd->overflow = lzg_hm_create(LZG_WD_INLINE_CAP * 2u);
+        if (!wd->overflow) return false;
+    } else {
+        lzg_hm_clear(wd->overflow);
+    }
+
+    for (uint32_t i = 0; i < LZG_WD_INLINE_CAP; i++) {
+        if (!wd->inline_used[i]) continue;
+        lzg_hm_put(wd->overflow, wd->inline_keys[i], 1u);
+    }
+
+    memset(wd->inline_used, 0, sizeof(wd->inline_used));
+    wd->inline_count = 0;
+    return true;
+}
+
+static inline bool lzg_wd_contains_hash(const LZGWalkDict *wd, uint64_t key) {
+    if (wd->overflow) return lzg_hm_get(wd->overflow, key) != NULL;
+    return lzg_wd_inline_contains(wd, key);
+}
+
+static inline bool lzg_wd_record_hash(LZGWalkDict *wd, uint64_t key) {
+    if (wd->overflow) {
+        lzg_hm_put(wd->overflow, key, 1u);
+        return true;
+    }
+    if (lzg_wd_inline_insert(wd, key)) return true;
+    if (!lzg_wd_promote_overflow(wd)) return false;
+    lzg_hm_put(wd->overflow, key, 1u);
+    return true;
+}
+
+static inline bool lzg_wd_record_prehashed(LZGWalkDict *wd, uint64_t key,
+                                           uint8_t single_char_idx) {
+    if (!lzg_wd_record_hash(wd, key)) return false;
+    if (single_char_idx != UINT8_MAX)
+        wd->single_char_bits |= (1u << single_char_idx);
+    return true;
+}
+
+/** Create a walk dictionary. */
+static inline LZGWalkDict lzg_wd_create(void) {
+    LZGWalkDict wd;
+    memset(&wd, 0, sizeof(wd));
+    return wd;
+}
+
+/** Reset a walk dictionary for reuse. */
+static inline void lzg_wd_reset(LZGWalkDict *wd) {
+    memset(wd->inline_used, 0, sizeof(wd->inline_used));
+    wd->inline_count = 0;
+    wd->single_char_bits = 0;
+    if (wd->overflow) lzg_hm_clear(wd->overflow);
+}
+
+/** Destroy a walk dictionary. */
+static inline void lzg_wd_destroy(LZGWalkDict *wd) {
+    if (wd->overflow) {
+        lzg_hm_destroy(wd->overflow);
+        wd->overflow = NULL;
+    }
+}
+
+/**
+ * Record a token in the walk dictionary.
+ *
+ * @param wd      Walk dictionary.
+ * @param pool    String pool containing the token.
+ * @param sp_id   Interned ID of the token string.
+ * @param sp_len  Length of the token.
+ */
+static inline void lzg_wd_record(LZGWalkDict *wd, const LZGStringPool *pool,
+                                  uint32_t sp_id, uint8_t sp_len) {
+    const char *sp = lzg_sp_get(pool, sp_id);
+    uint64_t h = lzg_hash_bytes(sp, sp_len);
+    uint8_t single_char_idx = (sp_len == 1) ? lzg_aa_to_bit(sp[0]) : UINT8_MAX;
+    (void)lzg_wd_record_prehashed(wd, h, single_char_idx);
+}
+
+/**
+ * Check if an edge is LZ76-valid given the current walk dictionary.
+ *
+ * @param g     The graph.
+ * @param edge  Edge index.
+ * @param wd    Current walk dictionary state.
+ * @return true if the edge's token is a valid next LZ76 token.
+ */
+/**
+ * Check if an edge is LZ76-valid for a CONTINUING walk (not the last step).
+ * Rules:
+ *   - Single-char "c": c must NOT be a previous standalone token
+ *   - Multi-char "wc": prefix "w" IN dictionary AND "wc" NOT in dictionary
+ */
+static inline bool lzg_wd_edge_valid(const LZGGraph *g, uint32_t edge,
+                                      const LZGWalkDict *wd) {
+    uint8_t sp_len = g->edge_sp_len[edge];
+
+    if (sp_len == 1) {
+        uint8_t idx = g->edge_single_char_idx ? g->edge_single_char_idx[edge] : UINT8_MAX;
+        if (idx != UINT8_MAX)
+            return !(wd->single_char_bits & (1u << idx));
+        const char *sp = lzg_sp_get(g->pool, g->edge_sp_id[edge]);
+        return !(wd->single_char_bits & (1u << lzg_aa_to_bit(sp[0])));
+    } else {
+        uint64_t prefix_h;
+        if (g->edge_prefix_hash) {
+            prefix_h = g->edge_prefix_hash[edge];
+        } else {
+            const char *prefix = lzg_sp_get(g->pool, g->edge_prefix_id[edge]);
+            uint32_t prefix_len = sp_len - 1;
+            prefix_h = lzg_hash_bytes(prefix, prefix_len);
+        }
+        if (!lzg_wd_contains_hash(wd, prefix_h))
+            return false;
+
+        uint64_t token_h;
+        if (g->edge_sp_hash) {
+            token_h = g->edge_sp_hash[edge];
+        } else {
+            const char *sp = lzg_sp_get(g->pool, g->edge_sp_id[edge]);
+            token_h = lzg_hash_bytes(sp, sp_len);
+        }
+        if (lzg_wd_contains_hash(wd, token_h))
+            return false;
+
+        return true;
+    }
+}
+
+/* lzg_wd_edge_valid_terminal removed: with $ sentinels, every last token
+ * is guaranteed novel (contains $), so case-3 exception is eliminated. */
+
+/**
+ * Record a node's subpattern into the walk dictionary.
+ * Convenience for recording the initial node of a walk.
+ */
+static inline void lzg_wd_record_node(LZGWalkDict *wd, const LZGGraph *g,
+                                       uint32_t node_id) {
+    if (g->node_sp_hash && g->node_single_char_idx) {
+        (void)lzg_wd_record_prehashed(wd, g->node_sp_hash[node_id],
+                                      g->node_single_char_idx[node_id]);
+    } else {
+        lzg_wd_record(wd, g->pool, g->node_sp_id[node_id], g->node_sp_len[node_id]);
+    }
+}
+
+/**
+ * Record an edge's destination subpattern into the walk dictionary.
+ */
+static inline void lzg_wd_record_edge(LZGWalkDict *wd, const LZGGraph *g,
+                                       uint32_t edge) {
+    if (g->edge_sp_hash && g->edge_single_char_idx) {
+        (void)lzg_wd_record_prehashed(wd, g->edge_sp_hash[edge],
+                                      g->edge_single_char_idx[edge]);
+    } else {
+        lzg_wd_record(wd, g->pool, g->edge_sp_id[edge], g->edge_sp_len[edge]);
+    }
+}
+
+#endif /* LZGRAPH_WALK_DICT_H */

{lzgraphs-3.0.0 → lzgraphs-3.0.1}/lib/core/hash_map.c

@@ -11,6 +11,45 @@ static uint32_t next_pow2(uint32_t v) {
     v |= v >> 8; v |= v >> 16; return v + 1;
 }
 
+static inline uint64_t hm_mix64(uint64_t x) {
+    x ^= x >> 33;
+    x *= 0xff51afd7ed558ccdULL;
+    x ^= x >> 33;
+    x *= 0xc4ceb9fe1a85ec53ULL;
+    x ^= x >> 33;
+    return x;
+}
+
+static uint32_t hm_find_existing(const LZGHashMap *m, uint64_t key) {
+    uint32_t mask = m->capacity - 1;
+    uint32_t idx = (uint32_t)(hm_mix64(key) & mask);
+    while (1) {
+        uint64_t k = m->keys[idx];
+        if (k == key) return idx;
+        if (k == LZG_HM_EMPTY) return UINT32_MAX;
+        idx = (idx + 1) & mask;
+    }
+}
+
+static uint32_t hm_find_insert_slot(const LZGHashMap *m, uint64_t key, bool *found) {
+    uint32_t mask = m->capacity - 1;
+    uint32_t idx = (uint32_t)(hm_mix64(key) & mask);
+    uint32_t tomb = UINT32_MAX;
+    while (1) {
+        uint64_t k = m->keys[idx];
+        if (k == key) {
+            *found = true;
+            return idx;
+        }
+        if (k == LZG_HM_EMPTY) {
+            *found = false;
+            return (tomb != UINT32_MAX) ? tomb : idx;
+        }
+        if (k == LZG_HM_DELETED && tomb == UINT32_MAX) tomb = idx;
+        idx = (idx + 1) & mask;
+    }
+}
+
 LZGHashMap *lzg_hm_create(uint32_t initial_capacity) {
     if (initial_capacity < 16) initial_capacity = 16;
     initial_capacity = next_pow2(initial_capacity);
@@ -42,10 +81,10 @@ static void hm_resize(LZGHashMap *m, uint32_t new_cap) {
     m->capacity = new_cap;
     m->count = m->tombstones = 0;
     memset(m->keys, 0xFF, new_cap * sizeof(uint64_t));
-    uint32_t mask = new_cap - 1;
     for (uint32_t i = 0; i < oc; i++) {
         if (ok[i] != LZG_HM_EMPTY && ok[i] != LZG_HM_DELETED) {
-            uint32_t idx = (uint32_t)(ok[i] & mask);
+            uint32_t mask = new_cap - 1;
+            uint32_t idx = (uint32_t)(hm_mix64(ok[i]) & mask);
             while (m->keys[idx] != LZG_HM_EMPTY) idx = (idx + 1) & mask;
             m->keys[idx] = ok[i];
             m->values[idx] = ov[i];
@@ -58,46 +97,61 @@ static void hm_resize(LZGHashMap *m, uint32_t new_cap) {
 bool lzg_hm_put(LZGHashMap *m, uint64_t key, uint64_t value) {
     if ((m->count + m->tombstones) * 5 > m->capacity * 3)
         hm_resize(m, m->capacity * 2);
-    uint32_t mask = m->capacity - 1;
-    uint32_t idx = (uint32_t)(key & mask);
-    uint32_t tomb = UINT32_MAX;
-    while (1) {
-        uint64_t k = m->keys[idx];
-        if (k == key)       { m->values[idx] = value; return false; }
-        if (k == LZG_HM_EMPTY) {
-            if (tomb != UINT32_MAX) { idx = tomb; m->tombstones--; }
-            m->keys[idx] = key; m->values[idx] = value; m->count++;
-            return true;
-        }
-        if (k == LZG_HM_DELETED && tomb == UINT32_MAX) tomb = idx;
-        idx = (idx + 1) & mask;
+    bool found = false;
+    uint32_t idx = hm_find_insert_slot(m, key, &found);
+    if (found) {
+        m->values[idx] = value;
+        return false;
     }
+    if (m->keys[idx] == LZG_HM_DELETED) m->tombstones--;
+    m->keys[idx] = key;
+    m->values[idx] = value;
+    m->count++;
+    return true;
 }
 
 uint64_t *lzg_hm_get(const LZGHashMap *m, uint64_t key) {
-    uint32_t mask = m->capacity - 1;
-    uint32_t idx = (uint32_t)(key & mask);
-    while (1) {
-        uint64_t k = m->keys[idx];
-        if (k == key)       return (uint64_t *)&m->values[idx];
-        if (k == LZG_HM_EMPTY) return NULL;
-        idx = (idx + 1) & mask;
+    uint32_t idx = hm_find_existing(m, key);
+    if (idx == UINT32_MAX) return NULL;
+    return (uint64_t *)&m->values[idx];
+}
+
+uint64_t *lzg_hm_get_or_insert(LZGHashMap *m, uint64_t key,
+                               uint64_t initial_value, bool *inserted) {
+    if ((m->count + m->tombstones) * 5 > m->capacity * 3)
+        hm_resize(m, m->capacity * 2);
+
+    bool found = false;
+    uint32_t idx = hm_find_insert_slot(m, key, &found);
+    if (found) {
+        if (inserted) *inserted = false;
+        return &m->values[idx];
     }
+
+    if (m->keys[idx] == LZG_HM_DELETED) m->tombstones--;
+    m->keys[idx] = key;
+    m->values[idx] = initial_value;
+    m->count++;
+    if (inserted) *inserted = true;
+    return &m->values[idx];
+}
+
+uint64_t *lzg_hm_add_u64(LZGHashMap *m, uint64_t key,
+                         uint64_t delta, bool *inserted) {
+    bool created = false;
+    uint64_t *slot = lzg_hm_get_or_insert(m, key, delta, &created);
+    if (!created) *slot += delta;
+    if (inserted) *inserted = created;
+    return slot;
 }
 
 bool lzg_hm_delete(LZGHashMap *m, uint64_t key) {
-    uint32_t mask = m->capacity - 1;
-    uint32_t idx = (uint32_t)(key & mask);
-    while (1) {
-        uint64_t k = m->keys[idx];
-        if (k == key) {
-            m->keys[idx] = LZG_HM_DELETED;
-            m->count--; m->tombstones++;
-            return true;
-        }
-        if (k == LZG_HM_EMPTY) return false;
-        idx = (idx + 1) & mask;
-    }
+    uint32_t idx = hm_find_existing(m, key);
+    if (idx == UINT32_MAX) return false;
+    m->keys[idx] = LZG_HM_DELETED;
+    m->count--;
+    m->tombstones++;
+    return true;
 }
 
 void lzg_hm_clear(LZGHashMap *m) {