ProvSQL C/C++ API
Adding support for provenance and uncertainty management to PostgreSQL databases
Loading...
Searching...
No Matches
CircuitFromMMap.h
Go to the documentation of this file.
1/**
2 * @file CircuitFromMMap.h
3 * @brief Build in-memory circuits from the mmap-backed persistent store.
4 *
5 * Declares two free functions that traverse the memory-mapped circuit
6 * storage starting from a given root UUID and construct the corresponding
7 * in-memory circuit representation. These functions are the primary
8 * bridge between the persistent @c MMappedCircuit and the evaluation
9 * algorithms that operate on @c BooleanCircuit or @c GenericCircuit.
10 */
11#ifndef BOOLEAN_CIRCUIT_FROM_MMAP_H
12#define BOOLEAN_CIRCUIT_FROM_MMAP_H
13
14extern "C" {
15#include "provsql_utils.h"
16}
17
18#include "BooleanCircuit.h"
19#include "GenericCircuit.h"
20#include "FormulaRegions.h"
21
22/**
23 * @brief Build a @c BooleanCircuit from the mmap store rooted at @p token.
24 *
25 * Performs a depth-first traversal of the persistent circuit starting at
26 * @p token, translating each @c gate_type to the corresponding
27 * @c BooleanGate and copying probabilities and info integers.
28 *
29 * On return, @p gate is set to the @c gate_t identifier within the
30 * returned circuit that corresponds to @p token.
31 *
32 * @param token UUID of the root gate.
33 * @param gate Output: @c gate_t of the root within the returned circuit.
34 * @return An in-memory @c BooleanCircuit.
35 */
37
38/**
39 * @brief Build a @c BooleanCircuit from an already-loaded @c GenericCircuit.
40 *
41 * Variant of @c getBooleanCircuit() that reuses an existing
42 * @c GenericCircuit (typically obtained via @c getGenericCircuit()) and
43 * additionally exposes the @c GenericCircuit-to-@c BooleanCircuit gate
44 * mapping, so that callers can translate input-side annotations
45 * (e.g., user-supplied leaf labels) from @p gc to the constructed
46 * @c BooleanCircuit.
47 *
48 * @param gc Source generic circuit (mutated through HAVING
49 * evaluation).
50 * @param token UUID of the root gate.
51 * @param gate Output: @c gate_t of the root within the returned circuit.
52 * @param gc_to_bc Output: mapping from @c gc input/mulinput gates to the
53 * corresponding gates in the returned @c BooleanCircuit.
54 * @return An in-memory @c BooleanCircuit.
55 */
58 pg_uuid_t token,
59 gate_t &gate,
60 std::unordered_map<gate_t, gate_t> &gc_to_bc);
61
62/**
63 * @brief Build a @c GenericCircuit from the mmap store rooted at @p token.
64 *
65 * Equivalent to @c createGenericCircuit() declared in @c MMappedCircuit.h.
66 * Performs a depth-first traversal and copies all gate metadata
67 * (type, info1/info2, extra strings, probabilities) into the returned
68 * @c GenericCircuit.
69 *
70 * @param token UUID of the root gate.
71 * @return An in-memory @c GenericCircuit.
72 */
74
75/**
76 * @brief The regions of @p requests, for @c sr_formula_rows (see
77 * @c FormulaRegions), with the load-time simplification applied.
78 *
79 * @param requests The gates, or ranges of their children, asked for.
80 * @param cap Size, in symbols, past which a gate is named.
81 * @param wide_cap Size past which a named gate's row is split into one
82 * row per child.
83 */
84FormulaRegions getFormulaRegions(const std::vector<FormulaRequest> &requests,
85 unsigned long cap, unsigned long wide_cap);
86
87/**
88 * @brief Simplify a loaded circuit for a probability readout.
89 *
90 * The load-time passes of @c getGenericCircuit / @c getJointCircuit read
91 * no probability, so the circuit they return keeps every tuple token and
92 * serves every consumer, the displayed circuit included. A readout of a
93 * probability or of a distribution (expectation, moments, quantiles,
94 * samples, histograms, information measures, event probabilities) may
95 * further read a mixture whose selector is certain by the probabilities
96 * of its inputs as its surviving arm; this applies that rewrite
97 * (@c foldDegenerateMixtures with @c read_probabilities) and the
98 * constant folding it enables. Gated, like the load-time passes, by
99 * @c provsql.simplify_on_load. Call it right after loading, before any
100 * evaluation.
101 *
102 * @param gc Circuit, rewritten in place.
103 */
105
106/**
107 * @brief Propagate the per-gate d-DNNF certificate from @p gc to @p c.
108 *
109 * For every @c gate_plus / @c gate_times of @p gc carrying the
110 * @c DNNF_CERT_INFO mark whose BoolExpr image in @p c is an OR / AND
111 * gate (the zero/one shortcuts of @c GenericCircuit::evaluate may map a
112 * gate to a constant instead, in which case the mark is moot), set the
113 * mark on the image, so @c independentEvaluation() and
114 * @c interpretAsDD() can exploit determinism / decomposability.
115 * Requires @p gc_to_bc to cover internal gates, which
116 * @c GenericCircuit::evaluate guarantees (it memoises every visited
117 * gate).
118 *
119 * @param gc Source generic circuit.
120 * @param gc_to_bc Gate mapping produced by the BoolExpr evaluation.
121 * @param c Target Boolean circuit.
122 */
124 const GenericCircuit &gc,
125 const std::unordered_map<gate_t, gate_t> &gc_to_bc,
126 BooleanCircuit &c);
127
128class dDNNF;
129/**
130 * @brief Compile a query certified inversion-free to its structured d-DNNF.
131 *
132 * Builds the same structured d-DNNF the @c 'inversion-free' probability method
133 * uses (over the query-derived Prop. 4.5 order carried on the circuit's
134 * annotation markers), for the knowledge-compilation surface (DOT / NNF /
135 * stats). Throws @c CircuitException if @p token's root carries no
136 * inversion-free certificate. Defined in @c probability_evaluate.cpp.
137 */
139
140/**
141 * @brief Build a @c GenericCircuit containing the closures of two
142 * roots, with shared subgraphs unified.
143 *
144 * Loads the union of every gate reachable from @p root_token and
145 * every gate reachable from @p event_token in a single in-memory
146 * @c GenericCircuit. Because @c GenericCircuit's UUID-to-gate
147 * mapping is idempotent, a @c gate_rv (or any other gate) reachable
148 * from both roots gets exactly one @c gate_t -- the property the
149 * conditional MC sampler needs to couple the indicator's draw with
150 * the value's draw through @c Sampler's per-iteration cache.
151 *
152 * The on-load simplification passes that @c getGenericCircuit runs
153 * (gated by @c provsql.simplify_on_load) are applied to the joint
154 * circuit too, followed by @c applyProbabilisticSimplification: every
155 * caller of this loader is a probability or distribution readout. The
156 * passes are in-place: gate types may change, but UUID-to-gate_t
157 * mappings stay valid, so callers can resolve their two roots via
158 * @c getGate after the call returns.
159 *
160 * Output parameters @p root_gate and @p event_gate are the resolved
161 * @c gate_t for the two input UUIDs.
162 *
163 * @param root_token First root UUID (e.g. an RV's gate).
164 * @param event_token Second root UUID (e.g. the conditioning gate).
165 * @param root_gate Output: @c gate_t for @p root_token in the
166 * returned circuit.
167 * @param event_gate Output: @c gate_t for @p event_token in the
168 * returned circuit.
169 * @return An in-memory @c GenericCircuit.
170 */
172 pg_uuid_t root_token,
173 pg_uuid_t event_token,
174 gate_t &root_gate,
175 gate_t &event_gate);
176
177/**
178 * @brief Multi-root variant of @c getJointCircuit.
179 *
180 * Loads the union of the closures of @p tokens in a single in-memory
181 * @c GenericCircuit, with the same shared-subgraph unification and
182 * load-time simplification guarantees as the two-root form. On return
183 * @p gates holds the resolved @c gate_t of each input UUID, in the
184 * order of @p tokens.
185 *
186 * @param tokens Root UUIDs (at least one).
187 * @param gates Output: resolved @c gate_t per token.
188 * @return An in-memory @c GenericCircuit.
189 */
191 const std::vector<pg_uuid_t> &tokens,
192 std::vector<gate_t> &gates);
193
194#endif /* BOOLEAN_CIRCUIT_FROM_MMAP_H */
Boolean provenance circuit with support for knowledge compilation.
FormulaRegions getFormulaRegions(const std::vector< FormulaRequest > &requests, unsigned long cap, unsigned long wide_cap)
The regions of requests, for sr_formula_rows (see FormulaRegions), with the load-time simplification ...
void applyProbabilisticSimplification(GenericCircuit &gc)
Simplify a loaded circuit for a probability readout.
void propagateDNNFCertificate(const GenericCircuit &gc, const std::unordered_map< gate_t, gate_t > &gc_to_bc, BooleanCircuit &c)
Propagate the per-gate d-DNNF certificate from gc to c.
BooleanCircuit getBooleanCircuit(pg_uuid_t token, gate_t &gate)
Build a BooleanCircuit from the mmap store rooted at token.
GenericCircuit getJointCircuit(pg_uuid_t root_token, pg_uuid_t event_token, gate_t &root_gate, gate_t &event_gate)
Build a GenericCircuit containing the closures of two roots, with shared subgraphs unified.
dDNNF buildInversionFreeDDNNF(pg_uuid_t token)
Compile a query certified inversion-free to its structured d-DNNF.
GenericCircuit getGenericCircuit(pg_uuid_t token)
Build a GenericCircuit from the mmap store rooted at token.
gate_t
Strongly-typed gate identifier.
Definition Circuit.h:53
The parts of a circuit sr_formula_rows renders a few rows from.
Semiring-agnostic in-memory provenance circuit.
Boolean circuit for provenance formula evaluation.
std::vector< BooleanGate > gates
Definition Circuit.h:215
A d-DNNF circuit supporting exact probabilistic and game-theoretic evaluation.
Definition dDNNF.h:71
Core types, constants, and utilities shared across ProvSQL.
The regions of a few requests, in one circuit.