TuringLang · penelopeysm · Mar 5, 2026 · Dec 5, 2025 · Jan 7, 2026 · Jan 8, 2026
diff --git a/HISTORY.md b/HISTORY.md
@@ -1,3 +1,161 @@
+# 0.43.0
+
+## DynamicPPL 0.40 and `VarNamedTuple`
+
+DynamicPPL v0.40 includes a major overhaul of Turing's internal data structures.
+Most notably, cases where we might once have used `Dict{VarName}` or `NamedTuple` have all been replaced with a single data structure, called `VarNamedTuple`.
+
+This provides substantial benefits in terms of robustness and performance.
+
+However, it does place some constraints on Turing models.
+Specifically, the types of **containers that can include random variables** are now more limited:
+if `x[i] ~ dist` is a random variable, then `x` must obey the following criteria:
+
+  - They must be arrays. Dicts and other containers are currently unsupported (we have [an issue to track this](https://github.com/TuringLang/DynamicPPL.jl/issues/1263)). If you really need this functionality, please open an issue and let us know; we can try to make it a priority.
+
+    ```julia
+    @model function f()
+        # Allowed
+        x = Array{Float64}(undef, 1)
+        x[1] ~ Normal()
+
+        # Forbidden
+        x = Dict{Int,Float64}()
+        return x[1] ~ Normal()
+    end
+    ```
+
+  - They must not be resized between calls to `~`. The following is forbidden (you should initialise `x` to the correct size before the loop):
+
+    ```julia
+    x = Float64[]
+    for i in 1:10
+        push!(x, 0.0)
+        x[i] ~ Normal()
+    end
+    ```
+
+However, please note that this only applies to **containers that contain random variables on the left-hand side of tilde-statements.**
+In general, there are no restrictions on containers of *observed* data, or containers that are not used in tilde-statements.
+
+  - Likewise, arrays of random variables should ideally have a constant size from iteration to iteration. That means a model like this will fail sometimes (*but* see below):
+
+    ```julia
+    n ~ Poisson(2.0)
+    x = Vector{Float64}(undef, n)
+    for i in 1:n
+        x[i] ~ Normal()
+    end
+    ```
+
+    *Technically speaking*: Inference (e.g. MCMC sampling) on this model will still work, but if you want to use `returned` or `predict`, both of the following conditions must hold true: (1) you must use FlexiChains.jl; (2) all elements of `x` must be random variables, i.e., you cannot have a mixture of `x[i]`'s being random variables and observed.
+
+`VarNamedTuple` and `@vnt` are now re-exported from Turing directly.
+There is a docs page explaining how to use and create `VarNamedTuple`s, which [can be found here](https://turinglang.org/docs/usage/varnamedtuple/).
+
+## Optimisation interface
+
+Turing.jl's optimisation interface has been completely overhauled in this release.
+The aim of this has been to provide users with a more consistent and principled way of specifying constraints.
+
+The crux of the issue is that Optimization.jl expects vectorised inputs, whereas Turing models are more high-level: they have named variables which may be scalars, vectors, or in general anything.
+Prior to this version, Turing's interface required the user to provide the vectorised inputs 'raw', which is both unintuitive and error-prone (especially when considering that optimisation may run in linked or unlinked space).
+
+Going forward, initial parameters for optimisation are specified using `AbstractInitStrategy` (for more information about this, please see [the docs on MCMC sampling](https://turinglang.org/docs/usage/sampling-options/#specifying-initial-parameters)).
+If specific parameters are provided (via `InitFromParams`), these must be in model space (i.e. untransformed).
+This directly mimics the interface for MCMC sampling that has been in place since v0.41.
+
+Furthermore, lower and upper bounds (if desired) can be specified as `VarNamedTuple`s using the `lb` and `ub` keyword arguments.
+Bounds are always provided in model space; Turing will handle the transformation of these bounds to linked space if necessary.
+Constraints are respected when creating initial parameters for optimisation: if the `AbstractInitStrategy` provided is incompatible with the constraints (for example `InitFromParams((; x = 2.0))` but `x` is constrained to be between `[0, 1]`), an error will be raised.
+
+Here is a (very simplified) example of the new interface:
+
+```julia
+using Turing
+@model f() = x ~ Beta(2, 2)
+maximum_a_posteriori(
+    f();
+    # All of the following are in unlinked space.
+    # We use NamedTuples here for simplicity, but you can use
+    # VarNamedTuple or Dict{<:VarName} as well (internally they
+    # will be converted to VarNamedTuple).
+    initial_params=InitFromParams((; x=0.3)),
+    lb=(; x=0.1),
+    ub=(; x=0.4),
+)
+```
+
+For more information, please see the docstring of `estimate_mode`.
+
+Note that in some cases, the translation of bounds to linked space may not be well-defined.
+This is especially true for distributions where the samples have elements that are not independent (for example, Dirichlet, or LKJCholesky).
+**In these cases, Turing will raise an error if bounds are provided.**
+Users who wish to perform optimisation with such constraints should directly use `LogDensityFunction` and Optimization.jl.
+Documentation on this matter will be forthcoming.
+
+### Other changes to the optimisation interface
+
+  - `estimate_mode`, `maximum_a_posteriori`, and `maximum_likelihood` now accept an optional `rng` first argument for reproducible initialisation.
+  - New keyword argument `link::Bool=true` controls whether to optimise in linked (transformed) space.
+  - New keyword argument `check_constraints_at_runtime::Bool=true` enables runtime constraint checking during model evaluation.
+  - Generic (non-box) constraints via `cons`, `lcons`, `ucons` are no longer supported. Users who need these should use `LogDensityFunction` and Optimization.jl directly.
+
+### `ModeResult` changes
+
+The return type from an optimisation procedure, `ModeResult`, has been substantially reworked:
+
+  - `ModeResult.params` is now a `VarNamedTuple` (previously an `AbstractDict{<:VarName}`). Parameters can be accessed via e.g. `m.params[@varname(x)]`.
+  - The `values::NamedArray` field has been removed. Use `vector_names_and_params(m)` (newly exported) to obtain `(Vector{VarName}, Vector{values})`.
+  - `Base.get(m::ModeResult, ...)` has been removed; use `m.params[@varname(x)]` instead.
+  - `StatsBase.coef` now returns a plain `Vector` (not a `NamedArray`).
+  - `StatsBase.coefnames` now returns a `Vector{VarName}` (not strings or symbols).
+  - `StatsBase.informationmatrix`: the `hessian_function` keyword argument has been replaced by `adtype::ADTypes.AbstractADType` (default `AutoForwardDiff()`). Hessian computation uses DifferentiationInterface under the hood.
+
+## `IS` sampler
+
+The `IS` sampler has been removed (its behaviour was in fact exactly the same as `Prior`).
+To see an example of importance sampling (via `Prior()` and then subsequent reweighting), see e.g. [this issue](https://github.com/TuringLang/Turing.jl/issues/2767).
+
+## `MH` sampler
+
+The interface of the MH sampler is slightly different.
+It no longer accepts `AdvancedMH` proposals, and is now more flexible: you can specify proposals for individual `VarName`s (not just top-level symbols), and any unspecified `VarName`s will be drawn from the prior, instead of being silently ignored.
+It is also faster than before (by around 30% on simple models).
+
+Additional changes:
+
+  - A new type `LinkedRW` allows specifying random-walk proposals in linked (unconstrained) space, e.g. `MH(@varname(x) => LinkedRW(cov_matrix))`.
+
+  - Callable (conditional) proposals now receive a `VarNamedTuple` of the full parameter state, rather than a single scalar. For example:
+
+    ```julia
+    # Old
+    MH(:m => x -> Normal(x, 1))
+    # New
+    MH(@varname(m) => (vnt -> Normal(vnt[@varname(m)], 1)))
+    ```
+  - MH now reports whether each proposal was `accepted` in the chain stats.
+  - At the start of sampling, MH logs `@info` messages showing which proposal is used for each variable (disable with `verbose=false`). This helps detect misspecified proposals.
+  - MH validates initial parameters against the proposal distribution; if they have zero or NaN probability, a clear error is thrown.
+
+## HMC / NUTS
+
+HMC-family samplers now check for discrete variables before sampling begins.
+If a model contains discrete variables (e.g. `x ~ Categorical(...)`) and an HMC sampler is used, an `ArgumentError` is thrown immediately.
+Previously, this would silently proceed.
+
+## `GibbsConditional`
+
+When defining a conditional posterior, instead of being provided with a Dict of values, the function must now take a `VarNamedTuple` containing the values.
+Note that indexing into a `VarNamedTuple` is very similar to indexing into a `Dict`; however, it is more flexible since you can use syntax such as `x[1:2]` even if `x[1]` and `x[2]` are separate variables in the model.
+
+## `filldist` and `arraydist`
+
+These two convenience functions are now imported and re-exported from DynamicPPL, rather than DistributionsAD.jl.
+They are now just wrappers around `Distributions.product_distribution`, instead of the specialised implementations that were in DistributionsAD.jl.
+DistributionsAD.jl is for all intents and purposes deprecated: it is no longer a dependency in the Turing stack.
+
 # 0.42.9
 
 Improve handling of model evaluator functions with Libtask.

diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "Turing"
 uuid = "fce5fe82-541a-59a6-adf8-730c64b5f9a0"
-version = "0.42.9"
+version = "0.43.0"
 
 [deps]
 ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"
@@ -15,8 +15,8 @@ BangBang = "198e06fe-97b7-11e9-32a5-e1d131e6ad66"
 Bijectors = "76274a88-744f-5084-9051-94815aaf08c4"
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+DifferentiationInterface = "a0c0ee7d-e4b9-4e03-894e-1c5f64a51d63"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
-DistributionsAD = "ced4e74d-a319-5a8a-b0ac-84af2272839c"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 DynamicPPL = "366bfd00-2699-11ea-058f-f148b4cae6d8"
 EllipticalSliceSampling = "cad2338a-1db2-11e9-3401-43bc07c9ede2"
@@ -25,7 +25,6 @@ Libtask = "6f1fad26-d15e-5dc8-ae53-837a1d7b8c9f"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 LogDensityProblems = "6fdf6af0-433a-55f7-b3ed-c6c6e0b8df7c"
 MCMCChains = "c7f686f2-ff18-58e9-bc7b-31028e88f75d"
-NamedArrays = "86f7a689-2022-50b4-a561-43c23ac3c673"
 Optimization = "7f7a1694-90dd-40f0-9382-eb1efda571ba"
 OptimizationOptimJL = "36348300-93cb-4f02-beb5-3c3902f8871e"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
@@ -48,30 +47,29 @@ TuringDynamicHMCExt = "DynamicHMC"
 [compat]
 ADTypes = "1.9"
 AbstractMCMC = "5.13"
-AbstractPPL = "0.11, 0.12, 0.13"
+AbstractPPL = "0.14"
 Accessors = "0.1"
 AdvancedHMC = "0.8.3"
 AdvancedMH = "0.8.9"
 AdvancedPS = "0.7.2"
 AdvancedVI = "0.6"
 BangBang = "0.4.2"
-Bijectors = "0.14, 0.15"
+Bijectors = "0.15.17"
 Compat = "4.15.0"
 DataStructures = "0.18, 0.19"
+DifferentiationInterface = "0.7"
 Distributions = "0.25.77"
-DistributionsAD = "0.6"
 DocStringExtensions = "0.8, 0.9"
 DynamicHMC = "3.4"
-DynamicPPL = "0.39.1"
+DynamicPPL = "0.40.6"
 EllipticalSliceSampling = "0.5, 1, 2"
 ForwardDiff = "0.10.3, 1"
 Libtask = "0.9.14"
 LinearAlgebra = "1"
 LogDensityProblems = "2"
 MCMCChains = "5, 6, 7"
-NamedArrays = "0.9, 0.10"
 Optimization = "3, 4, 5"
-OptimizationOptimJL = "0.1, 0.2, 0.3, 0.4"
+OptimizationOptimJL = "0.1 - 0.4"
 OrderedCollections = "1"
 Printf = "1"
 Random = "1"

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,4 +1,10 @@
 [deps]
+Bijectors = "76274a88-744f-5084-9051-94815aaf08c4"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
+DynamicPPL = "366bfd00-2699-11ea-058f-f148b4cae6d8"
+Mooncake = "da2b9cff-9c12-43a0-ae48-6db2b0edb7d6"
+OptimizationOptimJL = "36348300-93cb-4f02-beb5-3c3902f8871e"
+ReverseDiff = "37e2e3b7-166d-5795-8a7a-e32c996b4267"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 Turing = "fce5fe82-541a-59a6-adf8-730c64b5f9a0"
diff --git a/docs/make.jl b/docs/make.jl
@@ -11,7 +11,6 @@ links = InterLinks(
     "AbstractMCMC" => "https://turinglang.org/AbstractMCMC.jl/stable/",
     "ADTypes" => "https://sciml.github.io/ADTypes.jl/stable/",
     "AdvancedVI" => "https://turinglang.org/AdvancedVI.jl/stable/",
-    "DistributionsAD" => "https://turinglang.org/DistributionsAD.jl/stable/",
     "OrderedCollections" => "https://juliacollections.github.io/OrderedCollections.jl/stable/",
     "Distributions" => "https://juliastats.org/Distributions.jl/stable/",
 )
@@ -31,6 +30,7 @@ makedocs(;
             "Variational " => "api/Variational.md",
             "RandomMeasures " => "api/RandomMeasures.md",
         ],
+        "Optimisation" => "optim.md",
     ],
     checkdocs=:exports,
     doctest=false,

diff --git a/docs/src/api.md b/docs/src/api.md
@@ -73,7 +73,6 @@ even though [`Prior()`](@ref) is actually defined in the `Turing.Inference` modu
 | `PolynomialStepsize` | [`Turing.Inference.PolynomialStepsize`](@ref) | Returns a function which generates polynomially decaying step sizes |
 | `HMCDA`              | [`Turing.Inference.HMCDA`](@ref)              | Hamiltonian Monte Carlo with dual averaging                         |
 | `NUTS`               | [`Turing.Inference.NUTS`](@ref)               | No-U-Turn Sampler                                                   |
-| `IS`                 | [`Turing.Inference.IS`](@ref)                 | Importance sampling                                                 |
 | `SMC`                | [`Turing.Inference.SMC`](@ref)                | Sequential Monte Carlo                                              |
 | `PG`                 | [`Turing.Inference.PG`](@ref)                 | Particle Gibbs                                                      |
 | `CSMC`               | [`Turing.Inference.CSMC`](@ref)               | The same as PG                                                      |
@@ -158,20 +157,21 @@ LogPoisson
 
 ### Tools to work with distributions
 
-| Exported symbol | Documentation                          | Description                                                    |
-|:--------------- |:-------------------------------------- |:-------------------------------------------------------------- |
-| `I`             | [`LinearAlgebra.I`](@extref)           | Identity matrix                                                |
-| `filldist`      | [`DistributionsAD.filldist`](@extref)  | Create a product distribution from a distribution and integers |
-| `arraydist`     | [`DistributionsAD.arraydist`](@extref) | Create a product distribution from an array of distributions   |
-| `NamedDist`     | [`DynamicPPL.NamedDist`](@extref)      | A distribution that carries the name of the variable           |
+| Exported symbol | Documentation                     | Description                                                    |
+|:--------------- |:--------------------------------- |:-------------------------------------------------------------- |
+| `I`             | [`LinearAlgebra.I`](@extref)      | Identity matrix                                                |
+| `filldist`      | [`DynamicPPL.filldist`](@extref)  | Create a product distribution from a distribution and integers |
+| `arraydist`     | [`DynamicPPL.arraydist`](@extref) | Create a product distribution from an array of distributions   |
+| `NamedDist`     | [`DynamicPPL.NamedDist`](@extref) | A distribution that carries the name of the variable           |
 
 ### Point estimates
 
 See the [mode estimation tutorial](https://turinglang.org/docs/tutorials/docs-17-mode-estimation/) for more information.
 
-| Exported symbol        | Documentation                                      | Description                                  |
-|:---------------------- |:-------------------------------------------------- |:-------------------------------------------- |
-| `maximum_a_posteriori` | [`Turing.Optimisation.maximum_a_posteriori`](@ref) | Find a MAP estimate for a model              |
-| `maximum_likelihood`   | [`Turing.Optimisation.maximum_likelihood`](@ref)   | Find a MLE estimate for a model              |
-| `MAP`                  | [`Turing.Optimisation.MAP`](@ref)                  | Type to use with Optim.jl for MAP estimation |
-| `MLE`                  | [`Turing.Optimisation.MLE`](@ref)                  | Type to use with Optim.jl for MLE estimation |
+| Exported symbol           | Documentation                                         | Description                                   |
+|:------------------------- |:----------------------------------------------------- |:--------------------------------------------- |
+| `maximum_a_posteriori`    | [`Turing.Optimisation.maximum_a_posteriori`](@ref)    | Find a MAP estimate for a model               |
+| `maximum_likelihood`      | [`Turing.Optimisation.maximum_likelihood`](@ref)      | Find a MLE estimate for a model               |
+| `MAP`                     | [`Turing.Optimisation.MAP`](@ref)                     | Type to use with Optim.jl for MAP estimation  |
+| `MLE`                     | [`Turing.Optimisation.MLE`](@ref)                     | Type to use with Optim.jl for MLE estimation  |
+| `vector_names_and_params` | [`Turing.Optimisation.vector_names_and_params`](@ref) | Extract parameter names and values as vectors |