Use lowercase functions, don't deprecate VarInfo

Author: penelopeysm

HISTORY.md

@@ -8,30 +8,20 @@
 
 `VarInfo(vi::VarInfo, values)` has been removed. You can replace this directly with `unflatten(vi, values)` instead.
 
-**The `VarInfo([rng, ]model[, sampler, context, metadata])` constructor has been replaced with the following methods:**
+The `metadata` argument to `VarInfo([rng, ]model[, sampler, context, metadata])` has been removed.
+If you were not using this argument (most likely), then there is no change needed.
+If you were using the `metadata` argument to specify a blank `VarNamedVector`, then you should replace calls to `VarInfo` with `DynamicPPL.typed_vector_varinfo` instead (see 'Other changes' below).
 
- 1. `UntypedVarInfo([rng, ]model[, sampler, context])`
- 2. `TypedVarInfo([rng, ]model[, sampler, context])`
- 3. `DynamicPPL.UntypedVectorVarInfo([rng, ]model[, sampler, context])`
- 4. `DynamicPPL.TypedVectorVarInfo([rng, ]model[, sampler, context])`
+The `UntypedVarInfo` constructor and type is no longer exported.
+If you needed to construct one, you should now use `DynamicPPL.untyped_varinfo` instead.
 
-**If you were not using the `metadata` argument (most likely), then you can directly replace calls to this constructor with `TypedVarInfo` instead.**
-That is to say, if you were using `VarInfo(model)`, you can replace this with `TypedVarInfo(model)`.
+The `TypedVarInfo` constructor and type is no longer exported.
+The _type_ has been replaced with `DynamicPPL.NTVarInfo`.
+The _constructor_ has been replaced with `DynamicPPL.typed_varinfo`.
 
-If you were using the `metadata` argument to specify a blank `VarNamedVector`, then you should replace calls to `VarInfo` with `TypedVectorVarInfo` instead.
-Note that the `VectorVarInfo` constructors (both `Untyped` and `Typed`) are not exported by default.
-
-If you were passing a non-empty metadata argument, you should use a different constructor of `VarInfo` instead.
-
-The reason for this change is that there were several flavours of VarInfo.
-Some, like TypedVarInfo, were easy to construct because we had convenience methods for them; however, the others were more difficult.
-This change makes it easier to access different VarInfo types, and also makes it more explicit which one you are constructing.
-
-The `untyped_varinfo` and `typed_varinfo` functions have also been removed; you can use `UntypedVarInfo` and `TypedVarInfo` as direct replacements.
-
-Finally, `TypedVarInfo` is no longer a type.
-It has been replaced with `NTVarInfo`.
-If you were dispatching on this, you should replace it with `NTVarInfo` instead.
+Note that the exact kind of VarInfo returned by `VarInfo(rng, model, ...)` is an implementation detail.
+Previously, it was guaranteed that this would always be a VarInfo whose metadata was a `NamedTuple` containing `Metadata` structs.
+Going forward, this is no longer the case, and you should only assume that the returned object obeys the `AbstractVarInfo` interface.
 
 ### VarName prefixing behaviour
 
@@ -78,6 +68,20 @@ outer() | (a.x=1.0,)
 If you are sampling from a model with submodels, this doesn't affect the way you interact with the `MCMCChains.Chains` object, because VarNames are converted into Symbols when stored in the chain.
 (This behaviour will likely be changed in the future, in that Chains should be indexable by VarNames and not just Symbols, but that has not been implemented yet.)
 
+**Other changes**
+
+While these are technically breaking, they are only internal changes and do not affect the public API.
+The following four functions have been added and/or reworked to make it easier to construct VarInfos with different types of metadata:
+
+ 1. `DynamicPPL.untyped_varinfo([rng, ]model[, sampler, context])`
+ 2. `DynamicPPL.typed_varinfo([rng, ]model[, sampler, context])`
+ 3. `DynamicPPL.untyped_vector_varinfo([rng, ]model[, sampler, context])`
+ 4. `DynamicPPL.typed_vector_varinfo([rng, ]model[, sampler, context])`
+
+The reason for this change is that there were several flavours of VarInfo.
+Some, like `typed_varinfo`, were easy to construct because we had convenience methods for them; however, the others were more difficult.
+This change makes it easier to access different VarInfo types, and also makes it more explicit which one you are constructing.
+
 ## 0.35.5
 
 Several internal methods have been removed:

benchmarks/src/DynamicPPLBenchmarks.jl

@@ -1,6 +1,6 @@
 module DynamicPPLBenchmarks
 
-using DynamicPPL: VarInfo, UntypedVarInfo, TypedVarInfo, SimpleVarInfo, VarName
+using DynamicPPL: VarInfo, SimpleVarInfo, VarName
 using BenchmarkTools: BenchmarkGroup, @benchmarkable
 using DynamicPPL: DynamicPPL
 using ADTypes: ADTypes
@@ -52,8 +52,8 @@ end
 
 Create a benchmark suite for `model` using the selected varinfo type and AD backend.
 Available varinfo choices:
-  • `:untyped`           → uses `UntypedVarInfo(model)`
-  • `:typed`             → uses `TypedVarInfo(model)`
+  • `:untyped`           → uses `DynamicPPL.untyped_varinfo(model)`
+  • `:typed`             → uses `DynamicPPL.typed_varinfo(model)`
   • `:simple_namedtuple` → uses `SimpleVarInfo{Float64}(model())`
   • `:simple_dict`       → builds a `SimpleVarInfo{Float64}` from a Dict (pre-populated with the model’s outputs)
 
@@ -67,9 +67,9 @@ function make_suite(model, varinfo_choice::Symbol, adbackend::Symbol, islinked::
     suite = BenchmarkGroup()
 
     vi = if varinfo_choice == :untyped
-        UntypedVarInfo(rng, model)
+        DynamicPPL.untyped_varinfo(rng, model)
     elseif varinfo_choice == :typed
-        TypedVarInfo(rng, model)
+        DynamicPPL.typed_varinfo(rng, model)
     elseif varinfo_choice == :simple_namedtuple
         SimpleVarInfo{Float64}(model(rng))
     elseif varinfo_choice == :simple_dict

docs/src/api.md

@@ -295,8 +295,13 @@ But exactly how a [`AbstractVarInfo`](@ref) stores this information can vary.
 
 ```@docs
 VarInfo
-UntypedVarInfo
-TypedVarInfo
+```
+
+```@docs
+DynamicPPL.untyped_varinfo
+DynamicPPL.typed_varinfo
+DynamicPPL.untyped_vector_varinfo
+DynamicPPL.typed_vector_varinfo
 ```
 
 One main characteristic of [`VarInfo`](@ref) is that samples are transformed to unconstrained Euclidean space and stored in a linearized form, as described in the [main Turing documentation](https://turinglang.org/docs/developers/transforms/dynamicppl/).
@@ -449,7 +454,7 @@ Finally, to specify which varinfo type a [`Sampler`](@ref) should use for a give
 DynamicPPL.default_varinfo
 ```
 
-There is also the _experimental_ [`DynamicPPL.Experimental.determine_suitable_varinfo`](@ref), which uses static checking via [JET.jl](https://github.com/aviatesk/JET.jl) to determine whether one should use [`DynamicPPL.TypedVarInfo`](@ref) or [`DynamicPPL.UntypedVarInfo`](@ref), depending on which supports the model:
+There is also the _experimental_ [`DynamicPPL.Experimental.determine_suitable_varinfo`](@ref), which uses static checking via [JET.jl](https://github.com/aviatesk/JET.jl) to determine whether one should use [`DynamicPPL.typed_varinfo`](@ref) or [`DynamicPPL.untyped_varinfo`](@ref), depending on which supports the model:
 
 ```@docs
 DynamicPPL.Experimental.determine_suitable_varinfo

docs/src/internals/varinfo.md

@@ -79,13 +79,13 @@ For example, with the model above we have
 
 ```@example varinfo-design
 # Type-unstable `VarInfo`
-varinfo_untyped = DynamicPPL.UntypedVarInfo(demo())
+varinfo_untyped = DynamicPPL.untyped_varinfo(demo())
 typeof(varinfo_untyped.metadata)
 ```
 
 ```@example varinfo-design
 # Type-stable `VarInfo`
-varinfo_typed = DynamicPPL.TypedVarInfo(demo())
+varinfo_typed = DynamicPPL.typed_varinfo(demo())
 typeof(varinfo_typed.metadata)
 ```
 
@@ -154,7 +154,7 @@ For example, we want to optimize code-paths which effectively boil down to inner
 
 ```julia
 # Construct a `VarInfo` with types inferred from `model`.
-varinfo = TypedVarInfo(model)
+varinfo = VarInfo(model)
 
 # Repeatedly sample from `model`.
 for _ in 1:num_samples
@@ -227,13 +227,13 @@ Continuing from the example from the previous section, we can use a `VarInfo` wi
 
 ```@example varinfo-design
 # Type-unstable
-varinfo_untyped_vnv = DynamicPPL.UntypedVectorVarInfo(varinfo_untyped)
+varinfo_untyped_vnv = DynamicPPL.untyped_vector_varinfo(varinfo_untyped)
 varinfo_untyped_vnv[@varname(x)], varinfo_untyped_vnv[@varname(y)]
 ```
 
 ```@example varinfo-design
 # Type-stable
-varinfo_typed_vnv = DynamicPPL.TypedVectorVarInfo(varinfo_typed)
+varinfo_typed_vnv = DynamicPPL.typed_vector_varinfo(varinfo_typed)
 varinfo_typed_vnv[@varname(x)], varinfo_typed_vnv[@varname(y)]
 ```
 

ext/DynamicPPLJETExt.jl

@@ -27,7 +27,7 @@ function DynamicPPL.Experimental._determine_varinfo_jet(
     model::DynamicPPL.Model, context::DynamicPPL.AbstractContext; only_ddpl::Bool=true
 )
     # First we try with the typed varinfo.
-    varinfo = DynamicPPL.TypedVarInfo(model, context)
+    varinfo = DynamicPPL.typed_varinfo(model, context)
 
     # Let's make sure that both evaluation and sampling doesn't result in type errors.
     issuccess, result = DynamicPPL.Experimental.is_suitable_varinfo(
@@ -46,7 +46,7 @@ function DynamicPPL.Experimental._determine_varinfo_jet(
     else
         # Warn the user that we can't use the type stable one.
         @warn "Model seems incompatible with typed varinfo. Falling back to untyped varinfo."
-        DynamicPPL.UntypedVarInfo(model, context)
+        DynamicPPL.untyped_varinfo(model, context)
     end
 end
 

ext/DynamicPPLMCMCChainsExt.jl

@@ -110,7 +110,7 @@ function DynamicPPL.predict(
     include_all=false,
 )
     parameter_only_chain = MCMCChains.get_sections(chain, :parameters)
-    varinfo = DynamicPPL.TypedVarInfo(model)
+    varinfo = DynamicPPL.VarInfo(model)
 
     iters = Iterators.product(1:size(chain, 1), 1:size(chain, 3))
     predictive_samples = map(iters) do (sample_idx, chain_idx)
@@ -245,7 +245,7 @@ julia> returned(model, chain)
 """
 function DynamicPPL.returned(model::DynamicPPL.Model, chain_full::MCMCChains.Chains)
     chain = MCMCChains.get_sections(chain_full, :parameters)
-    varinfo = DynamicPPL.TypedVarInfo(model)
+    varinfo = DynamicPPL.VarInfo(model)
     iters = Iterators.product(1:size(chain, 1), 1:size(chain, 3))
     return map(iters) do (sample_idx, chain_idx)
         # TODO: Use `fix` once we've addressed https://github.com/TuringLang/DynamicPPL.jl/issues/702.

src/DynamicPPL.jl

@@ -45,10 +45,7 @@ import Base:
 # VarInfo
 export AbstractVarInfo,
     VarInfo,
-    UntypedVarInfo,
-    TypedVarInfo,
     SimpleVarInfo,
-    NTVarInfo,
     push!!,
     empty!!,
     subset,

src/abstract_varinfo.jl

@@ -247,11 +247,11 @@ julia> values_as(SimpleVarInfo(data), Vector)
  2.0
 ```
 
-`TypedVarInfo`:
+`VarInfo` with `NamedTuple` of `Metadata`:
 
 ```jldoctest
 julia> # Just use an example model to construct the `VarInfo` because we're lazy.
-       vi = TypedVarInfo(DynamicPPL.TestUtils.demo_assume_dot_observe());
+       vi = DynamicPPL.typed_varinfo(DynamicPPL.TestUtils.demo_assume_dot_observe());
 
 julia> vi[@varname(s)] = 1.0; vi[@varname(m)] = 2.0;
 
@@ -273,11 +273,11 @@ julia> values_as(vi, Vector)
  2.0
 ```
 
-`UntypedVarInfo`:
+`VarInfo` with `Metadata`:
 
 ```jldoctest
 julia> # Just use an example model to construct the `VarInfo` because we're lazy.
-       vi = UntypedVarInfo(DynamicPPL.TestUtils.demo_assume_dot_observe());
+       vi = DynamicPPL.untyped_varinfo(DynamicPPL.TestUtils.demo_assume_dot_observe());
 
 julia> vi[@varname(s)] = 1.0; vi[@varname(m)] = 2.0;
 
@@ -354,7 +354,7 @@ demo (generic function with 2 methods)
 
 julia> model = demo();
 
-julia> varinfo = TypedVarInfo(model);
+julia> varinfo = VarInfo(model);
 
 julia> keys(varinfo)
 4-element Vector{VarName}:

src/deprecated.jl

@@ -1,14 +1 @@
 @deprecate generated_quantities(model, params) returned(model, params)
-
-Base.@deprecate VarInfo(
-    rng::Random.AbstractRNG,
-    model::Model,
-    sampler::AbstractSampler=SampleFromPrior(),
-    context::AbstractContext=DefaultContext(),
-) TypedVarInfo(rng, model, sampler, context)
-Base.@deprecate VarInfo(
-    model::Model,
-    sampler::AbstractSampler=SampleFromPrior(),
-    context::AbstractContext=DefaultContext(),
-) TypedVarInfo(model, sampler, context)
-Base.@deprecate VarInfo(model::Model, context::AbstractContext) TypedVarInfo(model, context)

src/experimental.jl

@@ -72,7 +72,7 @@ julia> # Typed varinfo cannot handle this random support model properly
 ┌ Warning: Model seems incompatible with typed varinfo. Falling back to untyped varinfo.
 └ @ DynamicPPLJETExt ~/.julia/dev/DynamicPPL.jl/ext/DynamicPPLJETExt.jl:48
 
-julia> vi isa typeof(DynamicPPL.UntypedVarInfo(model))
+julia> vi isa typeof(DynamicPPL.untyped_varinfo(model))
 true
 
 julia> # In contrast, a simple model with no random support can be handled by typed varinfo.
@@ -81,7 +81,7 @@ model_with_static_support (generic function with 2 methods)
 
 julia> vi = determine_suitable_varinfo(model_with_static_support());
 
-julia> vi isa typeof(DynamicPPL.TypedVarInfo(model_with_static_support()))
+julia> vi isa typeof(DynamicPPL.typed_varinfo(model_with_static_support()))
 true
 ```
 """
@@ -97,7 +97,7 @@ function determine_suitable_varinfo(
         # Warn the user.
         @warn "JET.jl is not loaded. Assumes the model is compatible with typed varinfo."
         # Otherwise, we use the, possibly incorrect, default typed varinfo (to stay backwards compat).
-        DynamicPPL.TypedVarInfo(model, context)
+        DynamicPPL.typed_varinfo(model, context)
     end
 end