Removed deprecation of init_params + bump minor version (#355)

* removed deprecation of init_params and only allow the new initial_params

* bump minor version since change is breaking

* Fix some tests.  (#356)

* CompatHelper: add new compat entry for Statistics at version 1, (keep existing compat) (#354)

Co-authored-by: CompatHelper Julia <[email protected]>

* Update constructors.jl

* Update constructors.jl

* Update test/constructors.jl

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update Project.toml

* Update abstractmcmc.jl

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: CompatHelper Julia <[email protected]>

* Fix docs CI (#357)

* Update make.jl

* Update trajectory.jl

* Update integrator.jl

* Update metric.jl

* Update constructors.jl

* Update api.md

* Update constructors.jl

* Update Adaptation.jl

* Update abstractmcmc.jl

* Update Adaptation.jl

* Update Adaptation.jl

* Update api.md

* Update constructors.jl

* Update api.md

* Update make.jl

* Update docs/make.jl

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update docs/make.jl

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

---------

Co-authored-by: Hong Ge <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: CompatHelper Julia <[email protected]>

Author: 4 people

Project.toml

@@ -1,6 +1,6 @@
 name = "AdvancedHMC"
 uuid = "0bf59076-c3b1-5ca4-86bd-e02cd72cde3d"
-version = "0.5.6"
+version = "0.6.0"
 
 [deps]
 AbstractMCMC = "80f14c24-f653-4e6a-9b94-39d6b0f70001"
@@ -43,7 +43,7 @@ ProgressMeter = "1"
 Requires = "0.5, 1"
 Setfield = "0.7, 0.8, 1"
 SimpleUnPack = "1.1"
-Statistics = "1"
+Statistics = "1.6"
 StatsBase = "0.31, 0.32, 0.33, 0.34"
 StatsFuns = "0.8, 0.9, 1"
 julia = "1.6"

docs/make.jl

@@ -5,7 +5,11 @@ using AdvancedHMC
 
 # cp(joinpath(@__DIR__, "../README.md"), joinpath(@__DIR__, "src/index.md"))
 
-makedocs(sitename = "AdvancedHMC", format = Documenter.HTML(), modules = [AdvancedHMC])
+makedocs(
+    sitename = "AdvancedHMC",
+    format = Documenter.HTML(),
+    warnonly = [:cross_references],
+)
 
 deploydocs(
     repo = "github.com/TuringLang/AdvancedHMC.jl.git",

docs/src/api.md

@@ -5,7 +5,7 @@ Documentation for AdvancedHMC.jl
 ```@contents
 ```
 
-## Structs
+## Types
 ```@docs
 ClassicNoUTurn
 HMCSampler
@@ -18,4 +18,11 @@ HMCDA
 
 ```@docs
 sample
-```
+```
+
+## More types
+
+```@autodocs; canonical=false
+Modules = [AdvancedHMC, AdvancedHMC.Adaptation]
+Order   = [:type]
+```

src/abstractmcmc.jl

@@ -38,7 +38,7 @@ A convenient wrapper around `AbstractMCMC.sample` avoiding explicit construction
 
 function AbstractMCMC.sample(
     rng::Random.AbstractRNG,
-    model::LogDensityModel,
+    model::AbstractMCMC.LogDensityModel,
     sampler::AbstractHMCSampler,
     N::Integer;
     n_adapts::Int = min(div(N, 10), 1_000),
@@ -67,7 +67,7 @@ end
 
 function AbstractMCMC.sample(
     rng::Random.AbstractRNG,
-    model::LogDensityModel,
+    model::AbstractMCMC.LogDensityModel,
     sampler::AbstractHMCSampler,
     parallel::AbstractMCMC.AbstractMCMCEnsemble,
     N::Integer,
@@ -101,17 +101,11 @@ end
 
 function AbstractMCMC.step(
     rng::AbstractRNG,
-    model::LogDensityModel,
+    model::AbstractMCMC.LogDensityModel,
     spl::AbstractHMCSampler;
     initial_params = nothing,
-    init_params = initial_params,
     kwargs...,
 )
-    if init_params !== initial_params
-        Base.depwarn("`init_params` is deprecated, use `initial_params` instead", :step)
-        initial_params = init_params
-    end
-
     # Unpack model
     logdensity = model.logdensity
 
@@ -123,7 +117,7 @@ function AbstractMCMC.step(
 
     # Define integration algorithm
     # Find good eps if not provided one
-    initial_params = make_init_params(rng, spl, logdensity, initial_params)
+    initial_params = make_initial_params(rng, spl, logdensity, initial_params)
     ϵ = make_step_size(rng, spl, hamiltonian, initial_params)
     integrator = make_integrator(spl, ϵ)
 
@@ -144,7 +138,7 @@ end
 
 function AbstractMCMC.step(
     rng::AbstractRNG,
-    model::LogDensityModel,
+    model::AbstractMCMC.LogDensityModel,
     spl::AbstractHMCSampler,
     state::HMCState;
     kwargs...,
@@ -257,18 +251,18 @@ end
 #############
 ### Utils ###
 #############
-function make_init_params(
+function make_initial_params(
     rng::AbstractRNG,
     spl::AbstractHMCSampler,
     logdensity,
-    init_params,
+    initial_params,
 )
     T = sampler_eltype(spl)
-    if init_params == nothing
+    if initial_params == nothing
         d = LogDensityProblems.dimension(logdensity)
-        init_params = randn(rng, d)
+        initial_params = randn(rng, d)
     end
-    return T.(init_params)
+    return T.(initial_params)
 end
 
 #########
@@ -277,21 +271,21 @@ function make_step_size(
     rng::Random.AbstractRNG,
     spl::HMCSampler,
     hamiltonian::Hamiltonian,
-    init_params,
+    initial_params,
 )
     T = typeof(spl.κ.τ.integrator.ϵ)
-    ϵ = make_step_size(rng, spl.κ.τ.integrator, T, hamiltonian, init_params)
+    ϵ = make_step_size(rng, spl.κ.τ.integrator, T, hamiltonian, initial_params)
     return ϵ
 end
 
 function make_step_size(
     rng::Random.AbstractRNG,
     spl::AbstractHMCSampler,
     hamiltonian::Hamiltonian,
-    init_params,
+    initial_params,
 )
     T = sampler_eltype(spl)
-    return make_step_size(rng, spl.integrator, T, hamiltonian, init_params)
+    return make_step_size(rng, spl.integrator, T, hamiltonian, initial_params)
 
 end
 
@@ -300,12 +294,12 @@ function make_step_size(
     integrator::AbstractIntegrator,
     T::Type,
     hamiltonian::Hamiltonian,
-    init_params,
+    initial_params,
 )
     if integrator.ϵ > 0
         ϵ = integrator.ϵ
     else
-        ϵ = find_good_stepsize(rng, hamiltonian, init_params)
+        ϵ = find_good_stepsize(rng, hamiltonian, initial_params)
         @info string("Found initial step size ", ϵ)
     end
     return T(ϵ)
@@ -316,9 +310,9 @@ function make_step_size(
     integrator::Symbol,
     T::Type,
     hamiltonian::Hamiltonian,
-    init_params,
+    initial_params,
 )
-    ϵ = find_good_stepsize(rng, hamiltonian, init_params)
+    ϵ = find_good_stepsize(rng, hamiltonian, initial_params)
     @info string("Found initial step size ", ϵ)
     return T(ϵ)
 end

src/adaptation/Adaptation.jl

@@ -6,7 +6,13 @@ using Statistics: Statistics
 using SimpleUnPack: @unpack, @pack!
 
 using ..AdvancedHMC: DEBUG, AbstractScalarOrVec
+using DocStringExtensions
 
+"""
+$(TYPEDEF)
+
+Abstract type for HMC adaptors. 
+"""
 abstract type AbstractAdaptor end
 function getM⁻¹ end
 function getϵ end

src/constructors.jl

@@ -8,7 +8,7 @@ in favour of determined types from the other arguments.
 """
 determine_sampler_eltype(xs...) = float(_determine_sampler_eltype(xs...))
 # NOTE: We want to defer conversion to `float` until the very "end" of the
-# process, so as to allow `promote_type` to do it's job properly.
+# process to allow `promote_type` to do its job properly.
 # For example, in the scenario `determine_sampler_eltype(::Int64, ::Float32)`
 # we want to return `Float32`, not `Float64`. The latter would occur
 # if we did `float(eltype(x))` instead of just `eltype(x)`.
@@ -49,15 +49,15 @@ Note that all the fields have the prefix `initial_` to indicate
 that these will not necessarily correspond to the `kernel`, `metric`,
 and `adaptor` after sampling.
 
-To access the updated fields use the resulting [`HMCState`](@ref).
+To access the updated fields, use the resulting [`HMCState`](@ref).
 """
 struct HMCSampler{K<:AbstractMCMCKernel,M<:AbstractMetric,A<:AbstractAdaptor} <:
        AbstractHMCSampler
     "[`AbstractMCMCKernel`](@ref)."
     κ::K
     "Choice of initial metric [`AbstractMetric`](@ref). The metric type will be preserved during adaption."
     metric::M
-    "[`AbstractAdaptor`](@ref)."
+    "[`AdvancedHMC.Adaptation.AbstractAdaptor`](@ref)."
     adaptor::A
 end
 

src/integrator.jl

@@ -5,7 +5,7 @@
 # TODO: The type `<:Tuple{Integer,Bool}` is introduced to address
 # https://github.com/TuringLang/Turing.jl/pull/941#issuecomment-549191813
 # We might want to simplify it to `Tuple{Int,Bool}` when we figured out
-# why the it behaves unexpected on Windos 32.
+# why the it behaves unexpected on Windows 32.
 
 """
 $(TYPEDEF)

src/metric.jl

@@ -1,3 +1,8 @@
+"""
+$(TYPEDEF)
+
+Abstract type for preconditioning metrics. 
+"""
 abstract type AbstractMetric end
 
 _string_M⁻¹(mat::AbstractMatrix, n_chars::Int = 32) = _string_M⁻¹(diag(mat), n_chars)

src/trajectory.jl

@@ -25,12 +25,28 @@ end
 "Returns the statistics for transition `t`."
 stat(t::Transition) = t.stat
 
+"""
+$(TYPEDEF)
+Abstract type for HMC kernels. 
+"""
 abstract type AbstractMCMCKernel end
 
+"""
+$(TYPEDEF)
+Abstract type for termination criteria for Hamiltonian trajectories, e.g. no-U-turn and fixed number of leapfrog integration steps. 
+"""
 abstract type AbstractTerminationCriterion end
 
+"""
+$(TYPEDEF)
+Abstract type for a fixed number of leapfrog integration steps.
+"""
 abstract type StaticTerminationCriterion <: AbstractTerminationCriterion end
 
+"""
+$(TYPEDEF)
+Abstract type for dynamic Hamiltonian trajectory termination criteria. 
+"""
 abstract type DynamicTerminationCriterion <: AbstractTerminationCriterion end
 
 """

test/constructors.jl

@@ -131,9 +131,13 @@ get_kernel_hyperparamsT(spl::NUTS, state) = typeof(state.κ.τ.termination_crite
             @test AdvancedHMC.sampler_eltype(sampler) == T
 
             # Step.
-            transition, state =
-                AbstractMCMC.step(rng, model, sampler; n_adapts = 0, init_params = θ_init)
-
+            transition, state = AbstractMCMC.step(
+                rng,
+                model,
+                sampler;
+                n_adapts = 0,
+                initial_params = θ_init,
+            )
             # Verify that the types are preserved in the transition.
             @test eltype(transition.z.θ) == T
             @test eltype(transition.z.r) == T
@@ -159,7 +163,7 @@ get_kernel_hyperparamsT(spl::NUTS, state) = typeof(state.κ.τ.termination_crite
 end
 
 @testset "Utils" begin
-    @testset "init_params" begin
+    @testset "initial_params" begin
         d = 2
         θ_init = randn(d)
         rng = Random.default_rng()
@@ -171,10 +175,10 @@ end
         metric = AdvancedHMC.make_metric(spl, logdensity)
         hamiltonian = Hamiltonian(metric, model)
 
-        init_params1 = AdvancedHMC.make_init_params(rng, spl, logdensity, nothing)
-        @test typeof(init_params1) == Vector{T}
-        @test length(init_params1) == d
-        init_params2 = AdvancedHMC.make_init_params(rng, spl, logdensity, θ_init)
-        @test init_params2 == θ_init
+        initial_params1 = AdvancedHMC.make_initial_params(rng, spl, logdensity, nothing)
+        @test typeof(initial_params1) == Vector{T}
+        @test length(initial_params1) == d
+        initial_params2 = AdvancedHMC.make_initial_params(rng, spl, logdensity, θ_init)
+        @test initial_params2 == θ_init
     end
 end