Corrections to GFI doc

docs/README.md

@@ -10,7 +10,7 @@ The docs are divided in roughly four sections:
 
 
 # Developing
-To build the docs, run `julia --make.jl` or alternatively startup the Julia REPL and include `make.jl`. For debugging, consider setting `draft=true` in the `makedocs` function found in `make.jl`.
+To build the docs, run `julia -- make.jl` or alternatively startup the Julia REPL and include `make.jl`. For debugging, consider setting `draft=true` in the `makedocs` function found in `make.jl`.
 Currently you must write the tutorial directly in the docs rather than a source file (e.g. Quarto). See `getting_started` or `tutorials` for examples.
 
 Code snippets must use the triple backtick with a label to run. The environment carries over so long as the labels match. Example:

docs/src/tutorials/basics/gfi.md

@@ -62,6 +62,8 @@ And we denote the conditional distribution on non-addressable randomness ``r``,
 p(r | t; x) := p(t, r; x) / p(t; x)
 ```
 
+We require that the marginal distribution on choice maps be **structured** in the sense that if both ``p(t; x) > 0`` and ``p(t'; x) > 0`` and if ``t != t'`` then for some address ``a`` common to the domains of ``t`` and ``t'`` one has ``t(a) != t'(a)``.  In particular, if ``t'`` extends ``t`` (so ``t`` is the restriction of ``t'`` to a subset of the latter's addresses), and both ``p(t; x) > 0`` and ``p(t'; x) > 0``, then ``t = t'``.
+
 ### Return value function
 A (deterministic) function ``f`` that maps the tuple ``(x, t)`` of the arguments and the choice map to the return value of the function (which we denote by ``y``).
 Note that the return value cannot depend on the non-addressable randomness.
@@ -81,11 +83,10 @@ It must satisfy the following conditions:
 \sum_{t} q(t; x, u) = 1 \;\; \text{for all} \;\; x \in X, u
 ```
 ```math
-p(t; x) > 0 \text{ if and only if } q(t; x, u) > 0 \text{ for all } u \text{ where } u \text{ and } t \text{ agree }
-```
-```math
-q(t; x, u) > 0 \text{ implies that } u \text{ and } t \text{ agree }.
+q(t; x, u) > 0 \text{ if and only if } p(t; x) > 0 \text{ and } u \text{ and } t \text{ agree}
 ```
+The structuredness requirement on ``p(t; x)`` implies that if ``p(t; x) > 0`` then ``q(t; x, t) = 1``.
+
 There is also a family of probability distributions ``q(r; x, t)`` on non-addressable randomness, that satisfies:
 ```math
 q(r; x, t) > 0 \text{ if and only if } p(r | t, x) > 0

src/gen_fn_interface.jl

@@ -54,7 +54,7 @@ function get_choices end
 
 Return:
 ```math
-\\log \\frac{p(r, t; x)}{q(r; x, t)}
+\\log \\frac{p(t, r; x)}{q(r; x, t)}
 ```
 
 When there is no non-addressed randomness, this simplifies to the log probability \$\\log p(t; x)\$.
@@ -139,7 +139,7 @@ get_params(::GenerativeFunction) = ()
 
 Execute the generative function and return the trace.
 
-Given arguments (`args`), sample \$(r, t) \\sim p(\\cdot; x)\$ and return a trace with choice map \$t\$.
+Given arguments (`args`), sample \$(t, r) \\sim p(\\cdot; x)\$ and return the trace \$(x, t, r)\$.
 
 If `gen_fn` has optional trailing arguments (i.e., default values are provided),
 the optional arguments can be omitted from the `args` tuple. The generated trace
@@ -161,10 +161,10 @@ Return a trace of a generative function that is consistent with the given
 constraints on the random choices.
 
 Given arguments \$x\$ (`args`) and assignment \$u\$ (`constraints`) (which is empty for the first form), sample \$t \\sim
-q(\\cdot; u, x)\$ and \$r \\sim q(\\cdot; x, t)\$, and return the trace \$(x, r, t)\$ (`trace`).
+q(\\cdot; x, u)\$ and \$r \\sim q(\\cdot; x, t)\$, and return the trace \$(x, t, r)\$ (`trace`).
 Also return the weight (`weight`):
 ```math
-\\log \\frac{p(r, t; x)}{q(t; u, x) q(r; x, t)}
+\\log \\frac{p(t, r; x)}{q(t; x, u) q(r; x, t)}
 ```
 
 If `gen_fn` has optional trailing arguments (i.e., default values are provided),
@@ -195,11 +195,11 @@ end
 Estimate the probability that the selected choices take the values they do in a
 trace.
 
-Given a trace \$(x, r, t)\$ (`trace`) and a set of addresses \$A\$ (`selection`),
+Given a trace \$(x, t, r)\$ (`trace`) and a set of addresses \$A\$ (`selection`),
 let \$u\$ denote the restriction of \$t\$ to \$A\$. Return the weight
 (`weight`):
 ```math
-\\log \\frac{p(r, t; x)}{q(t; u, x) q(r; x, t)}
+\\log \\frac{p(t, r; x)}{q(t; x, u) q(r; x, t)}
 ```
 """
 function project(trace, selection::Selection)
@@ -215,7 +215,7 @@ Given arguments (`args`), sample \$t \\sim p(\\cdot; x)\$ and \$r \\sim p(\\cdot
 t)\$, and return \$t\$
 (`choices`) and the weight (`weight`):
 ```math
-\\log \\frac{p(r, t; x)}{q(r; x, t)}
+\\log \\frac{p(t, r; x)}{q(r; x, t)}
 ```
 """
 function propose(gen_fn::GenerativeFunction, args::Tuple)
@@ -233,7 +233,7 @@ Given arguments \$x\$ (`args`) and an assignment \$t\$ (`choices`) such that
 \$p(t; x) > 0\$, sample \$r \\sim q(\\cdot; x, t)\$ and
 return the weight (`weight`):
 ```math
-\\log \\frac{p(r, t; x)}{q(r; x, t)}
+\\log \\frac{p(t, r; x)}{q(r; x, t)}
 ```
 It is an error if \$p(t; x) = 0\$.
 """
@@ -249,8 +249,8 @@ end
 Update a trace by changing the arguments and/or providing new values for some
 existing random choice(s) and values for some newly introduced random choice(s).
 
-Given a previous trace \$(x, r, t)\$ (`trace`), new arguments \$x'\$ (`args`), and
-a map \$u\$ (`constraints`), return a new trace \$(x', r', t')\$ (`new_trace`)
+Given a previous trace \$(x, t, r)\$ (`trace`), new arguments \$x'\$ (`args`), and
+a map \$u\$ (`constraints`), return a new trace \$(x', t', r')\$ (`new_trace`)
 that is consistent with \$u\$.  The values of choices in \$t'\$ are
 either copied from \$t\$ or from \$u\$ (with \$u\$ taking
 precedence) or are sampled from the internal proposal distribution.  All choices in \$u\$ must appear in \$t'\$.  Also return an
@@ -261,8 +261,8 @@ q(\\cdot; x', t')\$, where \$t + u\$ is the choice map obtained by merging
 \$t\$ and \$u\$ with \$u\$ taking precedence for overlapping addresses.  Also
 return a weight (`weight`):
 ```math
-\\log \\frac{p(r', t'; x')}{q(r'; x', t') q(t'; x', t + u)}
-- \\log \\frac{p(r, t; x)}{q(r; x, t)}
+\\log \\frac{p(t', r'; x')}{q(r'; x', t') q(t'; x', t + u)}
+- \\log \\frac{p(t, r; x)}{q(r; x, t)}
 ```
 
 Note that `argdiffs` is expected to be the same length as `args`. If the
@@ -296,17 +296,17 @@ end
 Update a trace by changing the arguments and/or randomly sampling new values
 for selected random choices using the internal proposal distribution family.
 
-Given a previous trace \$(x, r, t)\$ (`trace`), new arguments \$x'\$ (`args`), and
-a set of addresses \$A\$ (`selection`), return a new trace \$(x', t')\$
+Given a previous trace \$(x, t, r)\$ (`trace`), new arguments \$x'\$ (`args`), and
+a set of addresses \$A\$ (`selection`), return a new trace \$(x', t', r')\$
 (`new_trace`) such that \$t'\$ agrees with \$t\$ on all addresses not in \$A\$
 (\$t\$ and \$t'\$ may have different sets of addresses).  Let \$u\$ denote the
-restriction of \$t\$ to the complement of \$A\$.  Sample \$t' \\sim Q(\\cdot;
-u, x')\$ and sample \$r' \\sim Q(\\cdot; x', t')\$.
-Return the new trace \$(x', r', t')\$ (`new_trace`) and the weight
+restriction of \$t\$ to the complement of \$A\$.  Sample \$t' \\sim q(\\cdot;
+x', u)\$ and sample \$r' \\sim q(\\cdot; x', t')\$.
+Return the new trace \$(x', t', r')\$ (`new_trace`) and the weight
 (`weight`):
 ```math
-\\log \\frac{p(r', t'; x')}{q(t'; u, x') q(r'; x', t')}
-- \\log \\frac{p(r, t; x)}{q(t; u', x) q(r; x, t)}
+\\log \\frac{p(t', r'; x')}{q(t'; x', u) q(r'; x', t')}
+- \\log \\frac{p(t, r; x)}{q(t; x, u') q(r; x, t)}
 ```
 where \$u'\$ is the restriction of \$t'\$ to the complement of \$A\$.