LZGraphs 3.0.0__tar.gz → 3.0.2__tar.gz

{lzgraphs-3.0.0 → lzgraphs-3.0.2}/MANIFEST.in

@@ -4,4 +4,5 @@ include LICENSE
 include Makefile
 recursive-include include *.h
 recursive-include lib *.c
+recursive-include lib *.h
 recursive-include src/LZGraphs *.c

{lzgraphs-3.0.0 → lzgraphs-3.0.2}/Makefile

@@ -6,7 +6,7 @@ LDFLAGS = -lm
 SRCS = $(shell find lib -name '*.c')
 OBJS = $(patsubst lib/%.c, build/%.o, $(SRCS))
 
-.PHONY: all clean test
+.PHONY: all clean test bench_ops
 
 all: build/liblzgraph.a
 
@@ -123,3 +123,8 @@ build/test_walk_dict: tests/c_unit/test_walk_dict.c build/liblzgraph.a | build_d
 
 clean:
 	rm -rf build
+
+bench_ops: build/bench_ops
+
+build/bench_ops: tools/bench_ops.c build/liblzgraph.a | build_dirs
+	$(CC) $(CFLAGS) $< -Lbuild -llzgraph $(LDFLAGS) -o $@

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

@@ -1,22 +1,21 @@
 Metadata-Version: 2.4
 Name: LZGraphs
-Version: 3.0.0
+Version: 3.0.2
 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>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/MuteJester/LZGraphs
 Project-URL: Documentation, https://mutejester.github.io/LZGraphs/
 Project-URL: Repository, https://github.com/MuteJester/LZGraphs
 Project-URL: Issues, https://github.com/MuteJester/LZGraphs/issues
-Project-URL: Changelog, https://github.com/MuteJester/LZGraphs/blob/master/CHANGELOG.md
+Project-URL: Changelog, https://github.com/MuteJester/LZGraphs/blob/master/docs/resources/changelog.md
 Keywords: Graph Theory,Immunology,Analytics,Biology,T-cell,Repertoire,CDR3,Bioinformatics,LZ76,Lempel-Ziv
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10

{lzgraphs-3.0.0 → lzgraphs-3.0.2}/include/lzgraph/analytics.h

@@ -1,10 +1,16 @@
 /**
  * @file analytics.h
- * @brief Graph-level analytics computed via LZ-constrained forward DP.
+ * @brief Graph-level analytics computed via LZ-constrained Monte Carlo.
  *
- * Every function here uses lzg_forward_propagate() internally, meaning
- * all results respect LZ76 dictionary constraints — only valid walks
- * contribute to the computed quantities.
+ * All public analytics are Monte Carlo estimates, not exact graph invariants.
+ * They sample the accepted-walk model (same as simulate()/lzpgen()) and
+ * compute diversity/entropy/support statistics from the sampled log-probs.
+ *
+ * Default sample count is LZG_ANALYTICS_DEFAULT_MC_SAMPLES (10000).
+ * Functions with _mc suffixes accept a custom sample count.
+ *
+ * pgen_diagnostics() estimates absorbed/leaked mass of the raw structural
+ * walk law via a separate MC run — see its doc for caveats.
  */
 #ifndef LZGRAPH_ANALYTICS_H
 #define LZGRAPH_ANALYTICS_H
@@ -12,23 +18,46 @@
 #include "lzgraph/common.h"
 #include "lzgraph/graph.h"
 
+#define LZG_ANALYTICS_DEFAULT_MC_SAMPLES 10000u
+
 /* ── Simulation potential size ──────────────────────────────── */
 
 /**
- * Count the number of distinct LZ-valid walks (sequences) the graph
- * can produce from initial states to terminal states.
+ * Estimate the number of distinct completed LZ-valid walks (support size).
  */
 LZGError lzg_graph_path_count(const LZGGraph *g, double *out_count);
 
+/**
+ * Monte Carlo version of lzg_graph_path_count().
+ *
+ * @param n_samples Number of simulated walks. Use 0 for the default.
+ */
+LZGError lzg_graph_path_count_mc(const LZGGraph *g, uint32_t n_samples,
+                                  double *out_count);
+
 /* ── PGEN diagnostics ───────────────────────────────────────── */
 
 typedef struct {
-    double total_absorbed;          /* should be ≤ 1.0               */
-    double total_leaked;            /* mass at dead-end non-terminals */
-    double initial_prob_sum;        /* should be 1.0                 */
-    bool   is_proper;               /* |total_absorbed - 1.0| < atol */
+    double total_absorbed;          /* MC estimate of absorbed mass (≤ 1.0) */
+    double total_leaked;            /* 1 - total_absorbed                   */
+    double initial_prob_sum;        /* should be 1.0                        */
+    bool   is_proper;               /* |total_absorbed - 1.0| < atol       */
+    uint32_t mc_samples;            /* number of MC samples used            */
 } LZGPgenDiagnostics;
 
+/**
+ * Estimate absorption/leakage of the raw structural walk law via Monte Carlo.
+ *
+ * total_absorbed is a Monte Carlo estimate (not an exact proof): it reports
+ * the fraction of raw constrained walks that reached a sink node out of
+ * mc_samples trials. A value of 1.0 means "no leaks were observed," not
+ * "the graph is mathematically proven leak-free." Rare leakage events may
+ * be missed if mc_samples is too small relative to the leakage probability.
+ *
+ * @param g    The graph.
+ * @param atol Tolerance for is_proper check.
+ * @param out  Output diagnostics.
+ */
 LZGError lzg_pgen_diagnostics(const LZGGraph *g, double atol,
                                LZGPgenDiagnostics *out);
 
@@ -46,18 +75,26 @@ LZGError lzg_effective_diversity(const LZGGraph *g, LZGEffectiveDiversity *out);
 /* ── Hill numbers ───────────────────────────────────────────── */
 
 /**
- * Compute M(α) = Σ_{valid walks} π(s)^α via LZ-constrained DP.
- * The Hill number is D(α) = M(α)^{1/(1-α)}.
+ * Estimate the power sum M(α) = Σ_s π(s)^α of the public accepted-walk model.
+ * In particular, M(1) = 1 for every graph with at least one live completion.
  */
 LZGError lzg_power_sum(const LZGGraph *g, double alpha, double *out_m);
 
 /**
- * Compute D(α) = M(α)^{1/(1-α)} for a single order.
- * For α = 0: returns simulation_potential_size.
- * For α = 1: returns exp(Shannon entropy).
+ * Estimate the classical Hill number of the public accepted-walk law.
+ * For α = 0: returns support size.
+ * For α = 1: returns exp(Shannon entropy of the absorbed law).
  */
 LZGError lzg_hill_number(const LZGGraph *g, double alpha, double *out_d);
 
+/**
+ * Monte Carlo version of lzg_hill_number().
+ *
+ * @param n_samples Number of simulated walks. Use 0 for the default.
+ */
+LZGError lzg_hill_number_mc(const LZGGraph *g, double alpha,
+                             uint32_t n_samples, double *out_d);
+
 /**
  * Compute Hill numbers for multiple orders at once.
  *
@@ -69,6 +106,14 @@ LZGError lzg_hill_number(const LZGGraph *g, double alpha, double *out_d);
 LZGError lzg_hill_numbers(const LZGGraph *g, const double *orders,
                            uint32_t n, double *out);
 
+/**
+ * Monte Carlo version of lzg_hill_numbers().
+ *
+ * @param n_samples Number of simulated walks. Use 0 for the default.
+ */
+LZGError lzg_hill_numbers_mc(const LZGGraph *g, const double *orders,
+                              uint32_t n, uint32_t n_samples, double *out);
+
 /* ── PGEN dynamic range ─────────────────────────────────────── */
 
 typedef struct {

{lzgraphs-3.0.0 → lzgraphs-3.0.2}/include/lzgraph/diversity.h

@@ -2,9 +2,8 @@
  * @file diversity.h
  * @brief Diversity metrics: perplexity, entropy rate, K-diversity, saturation.
  *
- * All probability-based metrics use the LZ-constrained model
- * (via lzg_walk_log_prob), giving correct values under
- * the proper probability distribution.
+ * All probability-based metrics use the public constrained walk model
+ * exposed through lzg_walk_log_prob().
  *
  * Counting-based metrics (K-diversity, saturation) operate on
  * raw sequences without touching the probability model.

{lzgraphs-3.0.0 → lzgraphs-3.0.2}/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.2}/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.2}/include/lzgraph/graph.h

@@ -17,6 +17,8 @@
 #include "lzgraph/hash_map.h"
 #include "lzgraph/edge_builder.h"
 
+struct LZGExactModel_;
+
 /**
  * LZGraph — directed acyclic graph with sentinel-bounded walks.
  *
@@ -37,7 +39,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 +47,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 +61,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 +73,15 @@ 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 */
+    struct LZGExactModel_ *exact_model_cache; /* accepted-model normalizer cache */
 } LZGGraph;
 
 /** Allocate and initialize an empty graph. */
@@ -95,12 +106,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 +140,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 +156,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.2}/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.2}/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.2}/include/lzgraph/pgen_dist.h

@@ -2,14 +2,19 @@
  * @file pgen_dist.h
  * @brief LZPgen distribution: moments, analytical Gaussian mixture, pdf/cdf.
  *
- * The PGEN distribution characterizes the probability of generation
- * (log P(seq)) across all sequences producible by the graph.
+ * The PGEN distribution characterizes log-probability mass over graph walks.
  *
- * lzg_pgen_moments() computes exact mean, variance, skewness, kurtosis
- * via 5-dimensional moment propagation through the LZ-constrained DP.
+ * Important: the current implementation is powered by the unconstrained
+ * topological forward DP in forward.c. Its moments and Gaussian mixture
+ * therefore summarize the graph-topology walk law, not the exact
+ * LZ-constrained per-history walk law used by lzg_walk_log_prob().
+ *
+ * lzg_pgen_moments() computes mean, variance, skewness, kurtosis via
+ * 5-dimensional moment propagation through that unconstrained forward DP.
  *
  * lzg_pgen_analytical_distribution() produces a Gaussian mixture
- * (one component per walk length) for fast pdf/cdf/ppf evaluation.
+ * (one component per walk length) for fast pdf/cdf/ppf evaluation of
+ * the same unconstrained approximation.
  */
 #ifndef LZGRAPH_PGEN_DIST_H
 #define LZGRAPH_PGEN_DIST_H
@@ -21,12 +26,12 @@
 /* ── Moment results ────────────────────────────────────────── */
 
 typedef struct {
-    double mean;           /* E[log P]                     */
-    double variance;       /* Var[log P]                   */
+    double mean;           /* E[log P] under the unconstrained forward law */
+    double variance;       /* Var[log P] under the same law                */
     double std;            /* sqrt(variance)               */
     double skewness;       /* standardized 3rd cumulant    */
     double kurtosis;       /* standardized 4th cumulant    */
-    double total_mass;     /* Σ π(s) over valid walks      */
+    double total_mass;     /* total absorbed mass in the unconstrained forward DP */
 } LZGPgenMoments;
 
 LZGError lzg_pgen_moments(const LZGGraph *g, LZGPgenMoments *out);
@@ -47,8 +52,8 @@ typedef struct {
 } LZGPgenDist;
 
 /**
- * Compute the analytical PGEN distribution as a Gaussian mixture.
- * One component per walk length, with exact per-length (weight, mean, std).
+ * Compute the analytical PGEN distribution as a Gaussian mixture over the
+ * unconstrained forward-DP walk law. One component per walk length.
  */
 LZGError lzg_pgen_analytical(const LZGGraph *g, LZGPgenDist *out);
 

{lzgraphs-3.0.0 → lzgraphs-3.0.2}/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.0 → lzgraphs-3.0.2}/include/lzgraph/simulate.h

@@ -2,14 +2,14 @@
  * @file simulate.h
  * @brief LZ76-constrained sequence simulation and walk probability.
  *
- * simulate() generates sequences by random walks that respect LZ76
- * dictionary constraints at every step: single-char tokens must be
- * novel, multi-char tokens must extend a known prefix. Edge weights
- * are renormalized over the LZ-valid successor set at each step.
+ * simulate() generates sequences from a scalable accepted-sequence
+ * approximation: raw constrained walks are sampled forward until one
+ * reaches a terminal sink, and probabilities are normalized by a cached
+ * Monte Carlo estimate of the graph's absorption mass.
  *
- * walk_log_probability() computes the log-probability of a given
- * sequence under the same LZ-constrained model by re-encoding via
- * LZ76 and tracing the canonical walk with renormalized weights.
+ * walk_log_probability() uses that same cached normalization estimate, so
+ * its output stays consistent with simulate() without materializing the full
+ * history-expanded exact state space.
  */
 #ifndef LZGRAPH_SIMULATE_H
 #define LZGRAPH_SIMULATE_H
@@ -31,12 +31,12 @@ typedef struct {
 } LZGSimResult;
 
 /**
- * Simulate n sequences from the LZ-constrained generative model.
+ * Simulate n sequences from the public accepted-sequence model.
  *
- * Each walk enforces LZ76 dictionary constraints: at each step, only
- * successors whose subpattern is LZ76-valid given the accumulated
- * dictionary are eligible. Edge weights are renormalized over the
- * valid subset.
+ * Each trial walk enforces LZ76 dictionary constraints exactly, stops on
+ * dead ends, and retries until a completed sink-reaching walk is obtained.
+ * This keeps generation scalable on large graphs while still returning only
+ * completed accepted walks.
  *
  * @param g          The graph (must be finalized + topo-sorted).
  * @param n          Number of sequences to generate.
@@ -55,12 +55,12 @@ static inline void lzg_sim_result_free(LZGSimResult *r) {
 }
 
 /**
- * Compute the log-probability of a sequence under the LZ-constrained model.
+ * Compute the log-probability of a sequence under the public accepted model.
  *
- * The sequence is re-encoded via LZ76, producing its canonical walk.
- * At each step, the edge weight is renormalized by the sum of weights
- * of LZ-valid successors (given the accumulated LZ dictionary at that
- * point in the walk). This makes the result consistent with simulate().
+ * The sequence is re-encoded via LZ76, producing its canonical raw
+ * constrained walk, and then normalized by the same cached Monte Carlo
+ * absorption estimate used by simulate(). This keeps lzpgen() consistent
+ * with public generation semantics without the exact state explosion.
  *
  * @param g       The graph.
  * @param seq     Null-terminated amino acid sequence.
@@ -103,6 +103,11 @@ typedef struct {
  *   2. Walk with edges filtered by LZ + live + V/J gene presence
  *   3. Backtrack on dead ends (stack with blacklist)
  *
+ * The reported log_prob is the gene-conditional walk probability: the
+ * product of transition probabilities over gene-filtered, LZ-valid edges.
+ * This is a different probability law from the unconditional model returned
+ * by simulate() / lzg_walk_log_prob(). The two are not directly comparable.
+ *
  * @param g     Graph with gene_data != NULL.
  * @param n     Number of sequences to generate.
  * @param rng   RNG state.