TuringLang · penelopeysm · Jun 5, 2025 · May 21, 2025 · May 28, 2025 · Jun 2, 2025
diff --git a/HISTORY.md b/HISTORY.md
@@ -1,3 +1,28 @@
+# Release 0.39.0
+
+## Update to the AdvancedVI interface
+
+Turing's variational inference interface was updated to match version 0.4 version of AdvancedVI.jl.
+
+AdvancedVI v0.4 introduces various new features:
+
+  - location-scale families with dense scale matrices,
+  - parameter-free stochastic optimization algorithms like `DoG` and `DoWG`,
+  - proximal operators for stable optimization,
+  - the sticking-the-landing control variate for faster convergence, and
+  - the score gradient estimator for non-differentiable targets.
+
+Please see the [Turing API documentation](https://turinglang.org/Turing.jl/stable/api/#Variational-inference), and [AdvancedVI's documentation](https://turinglang.org/AdvancedVI.jl/stable/), for more details.
+
+## Removal of Turing.Essential
+
+The Turing.Essential module has been removed.
+Anything exported from there can be imported from either `Turing` or `DynamicPPL`.
+
+## `@addlogprob!`
+
+The `@addlogprob!` macro is now exported from Turing, making it officially part of the public interface.
+
 # Release 0.38.6
 
 Added compatibility with AdvancedHMC 0.8.

diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "Turing"
 uuid = "fce5fe82-541a-59a6-adf8-730c64b5f9a0"
-version = "0.38.6"
+version = "0.39.0"
 
 [deps]
 ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"
@@ -53,7 +53,7 @@ Accessors = "0.1"
 AdvancedHMC = "0.3.0, 0.4.0, 0.5.2, 0.6, 0.7, 0.8"
 AdvancedMH = "0.8"
 AdvancedPS = "0.6.0"
-AdvancedVI = "0.2"
+AdvancedVI = "0.4"
 BangBang = "0.4.2"
 Bijectors = "0.14, 0.15"
 Compat = "4.15.0"

diff --git a/docs/make.jl b/docs/make.jl
@@ -23,8 +23,11 @@ makedocs(;
     pages=[
         "Home" => "index.md",
         "API" => "api.md",
-        "Submodule APIs" =>
-            ["Inference" => "api/Inference.md", "Optimisation" => "api/Optimisation.md"],
+        "Submodule APIs" => [
+            "Inference" => "api/Inference.md",
+            "Optimisation" => "api/Optimisation.md",
+            "Variational " => "api/Variational.md",
+        ],
     ],
     checkdocs=:exports,
     doctest=false,

diff --git a/docs/src/api.md b/docs/src/api.md
@@ -42,6 +42,7 @@ even though [`Prior()`](@ref) is actually defined in the `Turing.Inference` modu
 | `to_submodel`        | [`DynamicPPL.to_submodel`](@extref)        | Define a submodel                                                                            |
 | `prefix`             | [`DynamicPPL.prefix`](@extref)             | Prefix all variable names in a model with a given VarName                                    |
 | `LogDensityFunction` | [`DynamicPPL.LogDensityFunction`](@extref) | A struct containing all information about how to evaluate a model. Mostly for advanced users |
+| `@addlogprob!`       | [`DynamicPPL.@addlogprob!`](@extref)       | Add arbitrary log-probability terms during model evaluation                                  |
 
 ### Inference
 
@@ -76,12 +77,14 @@ even though [`Prior()`](@ref) is actually defined in the `Turing.Inference` modu
 
 ### Variational inference
 
-See the [variational inference tutorial](https://turinglang.org/docs/tutorials/09-variational-inference/) for a walkthrough on how to use these.
+See the [docs of AdvancedVI.jl](https://turinglang.org/AdvancedVI.jl/stable/) for detailed usage and the [variational inference tutorial](https://turinglang.org/docs/tutorials/09-variational-inference/) for a basic walkthrough.
 
-| Exported symbol | Documentation                | Description                             |
-|:--------------- |:---------------------------- |:--------------------------------------- |
-| `vi`            | [`AdvancedVI.vi`](@extref)   | Perform variational inference           |
-| `ADVI`          | [`AdvancedVI.ADVI`](@extref) | Construct an instance of a VI algorithm |
+| Exported symbol        | Documentation                                     | Description                                                                              |
+|:---------------------- |:------------------------------------------------- |:---------------------------------------------------------------------------------------- |
+| `vi`                   | [`Turing.vi`](@ref)                               | Perform variational inference                                                            |
+| `q_locationscale`      | [`Turing.Variational.q_locationscale`](@ref)      | Find a numerically non-degenerate initialization for a location-scale variational family |
+| `q_meanfield_gaussian` | [`Turing.Variational.q_meanfield_gaussian`](@ref) | Find a numerically non-degenerate initialization for a mean-field Gaussian family        |
+| `q_fullrank_gaussian`  | [`Turing.Variational.q_fullrank_gaussian`](@ref)  | Find a numerically non-degenerate initialization for a full-rank Gaussian family         |
 
 ### Automatic differentiation types
 

diff --git a/docs/src/api/Variational.md b/docs/src/api/Variational.md
@@ -0,0 +1,6 @@
+# API: `Turing.Variational`
+
+```@autodocs
+Modules = [Turing.Variational]
+Order  = [:type, :function]
+```
diff --git a/src/Turing.jl b/src/Turing.jl
@@ -23,7 +23,7 @@ using Printf: Printf
 using Random: Random
 using LinearAlgebra: I
 
-using ADTypes: ADTypes
+using ADTypes: ADTypes, AutoForwardDiff, AutoReverseDiff, AutoMooncake
 
 const DEFAULT_ADTYPE = ADTypes.AutoForwardDiff()
 
@@ -39,16 +39,12 @@ function setprogress!(progress::Bool)
     @info "[Turing]: progress logging is $(progress ? "enabled" : "disabled") globally"
     PROGRESS[] = progress
     AbstractMCMC.setprogress!(progress; silent=true)
-    # TODO: `AdvancedVI.turnprogress` is removed in AdvancedVI v0.3
-    AdvancedVI.turnprogress(progress)
     return progress
 end
 
 # Random probability measures.
 include("stdlib/distributions.jl")
 include("stdlib/RandomMeasures.jl")
-include("essential/Essential.jl")
-using .Essential
 include("mcmc/Inference.jl")  # inference algorithms
 using .Inference
 include("variational/VariationalInference.jl")
@@ -57,13 +53,13 @@ using .Variational
 include("optimisation/Optimisation.jl")
 using .Optimisation
 
-include("deprecated.jl") # to be removed in the next minor version release
-
 ###########
 # Exports #
 ###########
 # `using` statements for stuff to re-export
 using DynamicPPL:
+    @model,
+    @varname,
     pointwise_loglikelihoods,
     generated_quantities,
     returned,
@@ -73,9 +69,12 @@ using DynamicPPL:
     decondition,
     fix,
     unfix,
+    prefix,
     conditioned,
+    @submodel,
     to_submodel,
-    LogDensityFunction
+    LogDensityFunction,
+    @addlogprob!
 using StatsBase: predict
 using OrderedCollections: OrderedDict
 
@@ -90,6 +89,7 @@ export
     to_submodel,
     prefix,
     LogDensityFunction,
+    @addlogprob!,
     # Sampling - AbstractMCMC
     sample,
     MCMCThreads,
@@ -116,6 +116,9 @@ export
     # Variational inference - AdvancedVI
     vi,
     ADVI,
+    q_locationscale,
+    q_meanfield_gaussian,
+    q_fullrank_gaussian,
     # ADTypes
     AutoForwardDiff,
     AutoReverseDiff,

diff --git a/src/deprecated.jl b/src/deprecated.jl
diff --git a/src/essential/Essential.jl b/src/essential/Essential.jl
diff --git a/src/essential/container.jl b/src/essential/container.jl
diff --git a/src/mcmc/Inference.jl b/src/mcmc/Inference.jl
@@ -1,7 +1,7 @@
 module Inference
 
-using ..Essential
 using DynamicPPL:
+    @model,
     Metadata,
     VarInfo,
     # TODO(mhauru) all_varnames_grouped_by_symbol isn't exported by DPPL, because it is only