Directive Cheatsheet ==================== Summary:: assume symbol = expression observe expression = value predict expression forget directive_id freeze directive_id report directive_id force expression = value sample expression infer expression stop_continuous_inference continuous_inference_status define symbol = expression clear list_directives Directives ---------- The `assume`, `observe`, and `predict` operators, also called *directives*, make up the core modeling language of VentureScript. Each directive contains a modeling expression to be evaluated. At any time, the probabilistic execution trace consists of all directives that have been evaluated and not forgotten. VentureScript maintains an index of unique identifiers for directives so they can be referred to by other operations. - `assume symbol = expression`: declare and initialize a variable. Assume evaluates the `expression` and binds the result to ``symbol`` in the global environment. - `observe expression = value`: condition on observed data. The condition constrains the result of `expression` to be equal to `value`. An expression can only be constrained by an `observe` directive if its outermost procedure application is the result of a stochastic computation, rather than a deterministic one. For example, `observe normal(0, 1) = 0` is valid, but `observe normal(0, 1) + 1 = 0` is not, because `+` is a deterministic function of its arguments. `observe` has no effect on the distribution of other values (besides the one directly constrained) until the next time inference is invoked. - `predict expression`: register a persistent prediction. Predict tracks the `expression`, allowing its value to be reported before or after inference. A `predict` directive is persistent, in the sense that it becomes part of the program history and will be maintained and potentially resampled during inference. A `predict` ed expression may affect the evaluation of later expressions that are correlated or conditionally dependent. To evaluate an expression non-persistently, use `sample`. Directive manipulation ---------------------- In addition to the directives themselves, there are operators `forget`, `freeze`, and `report` which manipulate directives. - `forget directive_id`: remove a directive from the program history. Further inference will behave as if that directive had never been executed. Be careful `forget` ting an `assume` directive: any functions referring to the symbol that `assume` had bound will fail with "Symbol not found" errors if executed after the `forget`. - `freeze directive_id`: fix a directive's current value. Freeze removes the directive's random choices from the program history and fixes the directive to its current value. This operation is used to gain efficiency for inference strategies in the Sequential Monte Carlo style. - `report directive_id`: report the current value of a directive. Report does not re-evaluate the expression or otherwise change the program history. Pseudo-Directives ----------------- The `force` and `sample` operations are "pseudo-directives" which have temporary effects on the current program history. - `force expression = value`: set an expression to a value momentarily. Force is a temporary version of `observe` which is immediately forgotten after incorporating the observation. This has the effect of initializing `expression` to `value` without introducing a lasting constraint. In typical use, the expression is just a single variable, which sets that variable to the given value. - `sample expression`: make a transient prediction. Sample is a temporary version of `predict` which is immediately forgotten. This has the effect of evaluating `expression` once, without adding it to the program trace. Therefore, unlike `predict`, a `sample` d expression will not be maintained during inference, and `sample` d expressions will be independent of one another (conditioned on the rest of the program history). Inference --------- By themselves, the modeling directives do not perform any inference. When the directives are initially evaluated, their values will be drawn from the prior, ignoring any observations that have been made. To move from the prior to the posterior, it is necessary to invoke some inference operators. In simple cases, this will just amount to a transition count and some parameter settings for some generic inference strategy. For more complex cases, Venture supports user-programmable inference that can capture arbitrarily complex problem-specific insights. The inference expressions are described in the :ref:`Inference Syntax Reference `. Venture inference is also available in a continuous mode: - `infer loop(expression)`: execute continuous inference. The infer loop idiom evaluates an inference expression and starts repeatedly executing the specified inference strategy continuously in the background. Values can be queried (e.g. with `report`) while inference is in progress. See `loop`. - `endloop`: stop any ongoing continuous inference. endloop is safe to invoke even if continuous inference is not running. Definitions ----------- - `define symbol = expression`: define a reusable inference subroutine. A typical use case would be:: define frob = proc(a, b) { some(inference commmand); some(other inference commmand); ... }; whereupon ``frob`` can be invoked like any other inference procedure:: frob(1, 4); This is exactly analogous to definitions in other programming languages. Note: Model program expressions do not see symbols defined in the inference program, (and vice versa: inference expressions do not see symbols `assume` d in the model program, except via `sample`). Miscellaneous Instructions -------------------------- - `clear`: reset VentureScript to an empty state. - `list_directives`: print a description of all extant directives. - `ci_status`: report the status of continuous inference. The ci_status command reports whether continuous inference is currently running, and if so with what inference program.