DebugAccumulator (plus tiny bits and pieces)

HISTORY.md

@@ -2,7 +2,15 @@
 
 ## 0.37.0
 
-**Breaking changes**
+DynamicPPL 0.37 comes with a substantial reworking of its internals.
+Fundamentally, there is no change to the actual modelling syntax: if you are a Turing.jl user, for example, this release is unlikely to affect you much.
+However, if you are a package developer or someone who uses DynamicPPL's functionality directly, you will notice a number of changes.
+
+To avoid overwhelming the reader, we begin by listing the most important, user-facing changes, before explaining the changes to the internals in more detail.
+
+Note that virtually all changes listed here are breaking.
+
+**Public-facing changes**
 
 ### Submodel macro
 
@@ -19,6 +27,32 @@ There is now also an `rng` keyword argument to help seed parameter generation.
 Finally, instead of specifying `value_atol` and `grad_atol`, you can now specify `atol` and `rtol` which are used for both value and gradient.
 Their semantics are the same as in Julia's `isapprox`; two values are equal if they satisfy either `atol` or `rtol`.
 
+### `DynamicPPL.TestUtils.check_model`
+
+You now need to explicitly pass a `VarInfo` argument to `check_model` and `check_model_and_trace`.
+Previously, these functions would generate a new VarInfo for you (using an optionally provided `rng`).
+
+### Removal of `PriorContext` and `LikelihoodContext`
+
+A number of DynamicPPL's contexts have been removed, most notably `PriorContext` and `LikelihoodContext`.
+Although these are not the only _exported_ contexts, we consider unlikely that anyone was using _other_ contexts manually: if you have a question about contexts _other_ than these, please continue reading the 'Internals' section below.
+
+Previously, during evaluation of a model, DynamicPPL only had the capability to store a _single_ log probability (`logp`) field.
+`DefaultContext`, `PriorContext`, and `LikelihoodContext` were used to control what this field represented: they would accumulate the log joint, log prior, or log likelihood, respectively.
+
+Now, we have reworked DynamicPPL's `VarInfo` object such that it can track multiple log probabilities at once (see the 'Accumulators' section below).
+If you were evaluating a model with `PriorContext`, you can now just evaluate it with `DefaultContext`, and instead of calling `getlogp(varinfo)`, you can call `getlogprior(varinfo)` (and similarly for the likelihood).
+
+If you were constructing a `LogDensityFunction` with `PriorContext`, you can now stick to `DefaultContext`.
+`LogDensityFunction` now has an extra field, called `getlogdensity`, which represents a function that takes a `VarInfo` and returns the log density you want.
+Thus, if you pass `getlogprior` as the value of this parameter, you will get the same behaviour as with `PriorContext`.
+
+The other case where one might use `PriorContext` was to use `@addlogprob!` to add to the log prior.
+Previously, this was accomplished by manually checking `__context__ isa DynamicPPL.PriorContext`.
+Now, you can write `@addlogprob (; logprior=x, loglikelihood=y)` to add `x` to the log-prior and `y` to the log-likelihood.
+
+**Internals**
+
 ### Accumulators
 
 This release overhauls how VarInfo objects track variables such as the log joint probability. The new approach is to use what we call accumulators: Objects that the VarInfo carries on it that may change their state at each `tilde_assume!!` and `tilde_observe!!` call based on the value of the variable in question. They replace both variables that were previously hard-coded in the `VarInfo` object (`logp` and `num_produce`) and some contexts. This brings with it a number of breaking changes:

src/accumulators.jl

@@ -53,10 +53,11 @@ function accumulate_observe!! end
 
 Update `acc` in a `tilde_assume!!` call. Returns the updated `acc`.
 
-`vn` is the name of the variable being assumed, `val` is the value of the variable, and
-`right` is the distribution on the RHS of the tilde statement. `logjac` is the log
-determinant of the Jacobian of the transformation that was done to convert the value of `vn`
-as it was given (e.g. by sampler operating in linked space) to `val`.
+`vn` is the name of the variable being assumed, `val` is the value of the variable (in the
+original, unlinked space), and `right` is the distribution on the RHS of the tilde
+statement. `logjac` is the log determinant of the Jacobian of the transformation that was
+done to convert the value of `vn` as it was given to `val`: for example, if the sampler is
+operating in linked (Euclidean) space, then logjac will be nonzero.
 
 `accumulate_assume!!` may mutate `acc`, but not any of the other arguments.
 
@@ -71,7 +72,7 @@ Return a new accumulator like `acc` but empty.
 
 The precise meaning of "empty" is that that the returned value should be such that
 `combine(acc, split(acc))` is equal to `acc`. This is used in the context of multi-threading
-where different threads may accumulate independently and the results are the combined.
+where different threads may accumulate independently and the results are then combined.
 
 See also: [`combine`](@ref)
 """
@@ -80,7 +81,8 @@ function split end
 """
     combine(acc::AbstractAccumulator, acc2::AbstractAccumulator)
 
-Combine two accumulators of the same type. Returns a new accumulator.
+Combine two accumulators which have the same type (but may, in general, have different type
+parameters). Returns a new accumulator of the same type.
 
 See also: [`split`](@ref)
 """